Getting Started
Creating Your First Project
1. Click "Choose Projects Folder" to select where your projects will be stored
2. Click "New Project" to create your first project
3. Give your project a name and click "Create"
Adding Project Details
Enhance your projects with detailed information that helps organize and identify your games:
- Project Description: Add a brief description of your game concept
- Game Type: Select from Card Game, Board Game, Dice Game, Puzzle Game, Party Game, Strategy Game, Role-Playing Game, or Other
- Players: Specify player count (e.g., "2-4 players", "1-6 players")
- Playtime: Indicate game duration (e.g., "30-60 minutes", "15-30 minutes")
- Ages: Set age recommendations (e.g., "8+", "12+", "All ages")
- Game Logo: Upload a logo image for your game
How to Add Details: Click on any project label (e.g., "Project: My Game") in the Components or Cards screens to open the project details editor. You can also add details when creating a new project.
Project Cards: All your project details are displayed on the main projects screen, making it easy to identify and organize your games at a glance.
Creating Your First Deck
1. Open a project to see the decks screen
2. Click "New Deck" to create a new deck
3. Enter a deck name and optionally add a background image
4. Add deck text, choose fonts, colors, and alignment
5. Click "Save Deck" to create your deck
Creating Your First Card
1. Open a deck to see the cards screen
2. Click "New Card" to create a new card
3. Add card text and answer text
4. Customize fonts, colors, alignment, and positioning
5. Click "Save Card" to create your card
Components & Project Organization
Understanding Components
Components are the building blocks of your projects. They help you organize different types of content within your project. Currently, BlackBox supports Card Decks as a component type, with more component types planned for future updates.
Adding Components to Your Project
Step 1: Open a project to access the Components screen
Step 2: Click "Create Component" to open the component creation menu
Step 3: Choose "Add Card Deck To Project" to create a new deck
Step 4: The deck creator will open automatically - configure your deck settings and click "Create Deck"
Note: You can also access existing decks by clicking "View Decks" in the Components screen
Managing Card Decks
Card decks are the primary component type in BlackBox. Each deck can contain multiple cards and has its own visual identity:
- Deck Back Image: Each deck can have a custom back image that appears as a thumbnail preview in the deck list
- Card Count Display: The Components screen shows how many cards are in each deck
- Visual Previews: Deck cards display a thumbnail of the deck back image for easy identification
- Organized Storage: Each deck is stored as a separate folder within your project
Component Screen Features
The Components screen provides an organized view of all components in your project:
- Component Tables: Each component type (like Decks) is displayed in its own table
- Conditional Display: Component tables only appear if you have components of that type
- Quick Actions: Use "View Decks" to access all decks in your project
- Project Context: The screen shows which project you're currently working in
Custom Components (MISC)
Custom components allow you to track miscellaneous items that don't require design work but are part of your project:
- Creating Custom Components: Click "Create Component" → "Add Custom Component" → Enter name and quantity
- Common Uses: Sand timers, dice sets, game tokens, score pads, rule books, or any physical components
- Quantity Tracking: Specify how many of each component you have (1-999)
- MISC Table: Custom components appear in a dedicated "MISC" table that only shows when you have custom components
- Management: Each custom component has a delete button for easy removal
- Storage: Custom components are saved in your project folder as
custom_components.json
Custom Component Examples
Here are some examples of custom components you might add to your projects:
Game Components:
• Sand Timer (Qty: 1)
• Turn Tracker Token (Qty: 1)
• Score Pads (Qty: 4)
• Storage Box (Qty: 1)
• Reference Cards (Qty: 8)
Tip: Use custom components to create a complete inventory of everything needed for your game or project!
Bulk Card Generator & Import Tutorial
Getting Started with Bulk Card Generation
Step 1: Design your first card with the desired styling, fonts, colors, and layout
Step 2: Click "Use as Template" to open the bulk card generator
Step 3: Add card text and answer text for each card you want to create
Step 4: Click "Generate Cards" to create all cards with the same design
Importing Data from Files
Supported Formats: CSV (.csv) and Excel (.xlsx) files are supported for importing bulk card data
File Structure: Your file should have two columns: Column A for card text and Column B for answer text
Headers: Include a header row in your Excel file (e.g., "Question" and "Answer") - the import will automatically skip the first row
CSV Format: Use commas, tabs, or semicolons to separate columns in CSV files
Excel File Format (.xlsx)
Recommended Format: Excel files are the most reliable for importing bulk card data
Structure: Create a spreadsheet with headers in row 1, then add your card data starting from row 2
Example:
A1: Question | B1: Answer
A2: What is 2+2? | B2: 4
A3: What is the capital of France? | B3: Paris
A4: What color is the sky? | B4: Blue
Benefits: Excel files maintain data structure better and are less prone to parsing errors
CSV File Format (.csv)
⚠️ Important Note: CSV files may not import correctly if there are no clear column separators or if the data contains commas within the text
Common Issues:
- Text containing commas can break the column structure
- Quotes and special characters may not parse correctly
- Inconsistent separators can cause data misalignment
- Empty cells may shift column positions
Best Practices for CSV:
- Use Excel to create your data, then export as CSV
- Avoid commas within your card text or answer text
- Use simple text without special characters
- Test with a small sample first
Alternative: Consider using Excel (.xlsx) format instead of CSV for more reliable imports
Text File Format (.txt)
Supported Separators: Text files can use tabs, pipes (|), or dashes (-) as separators
Example:
What is 2+2? 4
What is the capital of France? Paris
What color is the sky? Blue
Note: Text files are less structured than Excel files and may have similar parsing issues to CSV
Troubleshooting Import Issues
No Data Imported: Check that your file has data in the first column and that the file format is supported
Wrong Data in Columns: Ensure your file has card text in column A and answer text in column B
CSV Parsing Errors: Try converting your CSV to Excel format for more reliable imports
Empty Rows: The import will skip completely empty rows automatically
Special Characters: Some special characters may not import correctly - use simple text when possible
Tips for Successful Bulk Card Generation
Design First: Always design your first card completely before using it as a template
Test Import: Import a small sample of data first to ensure everything works correctly
Review Data: Check the imported data in the table before generating cards
File Organization: Keep your data files organized and use consistent formatting
Backup Data: Keep backups of your original data files before importing
PDF Generation
Generate PDFs of your decks from the "View Cards" screen. PDFs include the deck back image followed by all cards, perfect for printing or sharing.
Card Dimensions
Choose from standard card sizes (Poker, Bridge, Tarot, etc.) or create custom dimensions. Supports pixels, inches, millimeters, and centimeters with automatic conversion.
Dark Theme
Toggle between light and dark themes using the settings menu. Your preference is automatically saved.
Font Importer Tutorial
How to Import Custom Fonts
Step 1: Open the Font Importer from the Projects screen settings menu (gear icon → Tools → Font Importer)
Step 2: Click "Import new font" to open the file picker
Step 3: Select your font file (TTF, OTF, WOFF, or WOFF2 format)
Step 4: The font will be imported and appear in the font list with a preview
Step 5: Your custom font will now be available in all font dropdowns throughout the app
Managing Custom Fonts
Viewing: All imported fonts appear in the Font Importer with a full character preview
Deleting: Click the red "✖" button next to any custom font to remove it
Duplicates: The app prevents importing fonts with the same name to avoid conflicts
Persistence: Custom fonts are saved and will be available when you reload the app
Custom Font Compatibility Issues
Browser Limitations: Different browsers handle custom fonts differently. Some may not load certain font formats or may fall back to system fonts.
Font Format Support: While we support TTF, OTF, WOFF, and WOFF2 formats, not all browsers support all formats equally well.
Character Set Issues: Some custom fonts may not include all characters (numbers, symbols, special characters) which could cause display problems.
Rendering Differences: Fonts may render slightly differently across different operating systems and devices.
Performance Impact: Large font files can slow down the app, especially when many custom fonts are loaded.
Best Practices for Custom Fonts
Test Thoroughly: Always preview your cards with custom fonts before finalizing
Use Web-Optimized Fonts: WOFF and WOFF2 formats are generally more reliable for web use
Keep File Sizes Small: Large font files can impact performance
Have Fallbacks: Consider using system fonts as backup options
Check Character Support: Ensure your font includes all characters you plan to use
Troubleshooting Font Issues
Font Not Loading: Try a different font format (WOFF2 is most reliable)
Characters Missing: The font may not include those characters - try a different font
Slow Performance: Remove unused custom fonts to improve speed
Display Issues: Some fonts may not render properly - test with system fonts first
Import Errors: Ensure the font file is not corrupted and is in a supported format
Card Design Tips
Choosing Card Dimensions
Standard Poker (2.5" × 3.5"): Most common card size, great for traditional card games
Bridge (2.25" × 3.5"): Slightly narrower, good for games with lots of text
Tarot (2.75" × 4.75"): Larger cards, perfect for games with detailed artwork
Custom Sizes: Create unique dimensions for your specific game needs
Design Best Practices
Safe Areas: Keep important text and images within the green dashed lines to avoid trimming
Bleed Margins: Background images should extend to the red dashed lines for professional printing
Text Readability: Use high contrast colors and appropriate font sizes for easy reading
Consistent Spacing: Use the line height and offset controls for uniform text positioning
Working with Images
High Resolution: Use images with at least 300 DPI for best print quality
Background Images: Will automatically scale to cover the entire card area
Text Over Images: Ensure sufficient contrast between text and background for readability
File Formats: PNG and JPG work best for card backgrounds
Image Quality & PPI Settings
Understanding PPI (Pixels Per Inch)
What is PPI? PPI (Pixels Per Inch) determines the resolution and quality of your exported card images. Higher PPI values create sharper, more detailed images suitable for professional printing.
PPI vs DPI: While often used interchangeably, PPI refers to digital image resolution, while DPI refers to printer output. For our purposes, PPI controls the quality of your exported images.
Card Size Preservation: Increasing PPI does NOT change the physical size of your cards - it only increases the image quality and file size.
Recommended PPI Settings
72 PPI: Minimum quality, suitable for web display only
150 PPI: Good quality for home printing and basic card games
300 PPI: Professional quality, recommended for most printing services and high-quality cards
600 PPI: Ultra-high quality for premium printing and detailed artwork
1000 PPI: Maximum quality for archival prints and professional publishing
Setting PPI for Your Project
Deck Creation: Set PPI when creating a new deck using the "Pixels Per Inch (PPI)" input field
Default Value: New decks default to 300 PPI for optimal quality
Range: PPI can be set from 72 to 1000 depending on your quality needs
Editing: You can change PPI settings by editing an existing deck
High-Quality Preview Toggle
What it does: The "High-Quality Preview" toggle shows your cards at export quality in the preview area
When to use: Enable this when you want to see exactly how your cards will look when exported
Performance: High-quality previews may be slower to update, so disable for faster editing
PPI Integration: The preview uses your deck's PPI setting to show accurate export quality
File Size Considerations
Higher PPI = Larger Files: Each doubling of PPI increases file size by approximately 4x
Storage Impact: High PPI images take more storage space in your project folder
Loading Times: Higher quality images may take longer to load in the app
Printing Costs: Higher PPI images may cost more to print professionally
Quality vs Performance Tips
For Development: Use 150-300 PPI while designing to speed up preview updates
For Final Export: Use 300-600 PPI for professional-quality cards
For Web Use: 72-150 PPI is sufficient and will load faster
For Printing: Check with your print service for their recommended PPI requirements
Print & Play Prototype Creator
What is Print & Play?
The Print & Play Prototype Creator is a powerful tool that generates professional card sheets for printing and sharing your card games. It creates PDF files with multiple cards per page, perfect for testing prototypes or creating print-ready materials.
Getting Started with Print & Play
Step 1: Access Print & Play from the settings menu (gear icon → Print & Play Prototype Creator)
Step 2: Select a project from the list of available projects
Step 3: Choose "Create Card Sheets" from the available tools
Step 4: Select which decks you want to include in your card sheets
Step 5: Configure layout options and generate your PDFs
Layout Options
Cards per Page: Choose from 2x2 (4 cards), 3x3 (9 cards), 4x4 (16 cards), 2x3 (6 cards), or 3x4 (12 cards) layouts
Page Size: Select Letter (8.5" x 11"), A4 (210mm x 297mm), or Legal (8.5" x 14") paper sizes
Output Format: Currently supports PDF format (PNG option coming soon)
Include Card Backs: Toggle to include deck back images in your sheets (enabled by default)
Card Sheet Layout
Alternating Pages: Card sheets alternate between card backs and card fronts for easy double-sided printing
Page 1: Card backs (deck back images)
Page 2: Card fronts (individual cards)
Page 3: Card backs (for next set of cards)
And so on... This pattern continues for all cards in the selected decks
Smart Card Back Generation
Exact Count: Card backs are only generated for the actual number of cards, not for empty slots on a page
Efficient Printing: No wasted paper or ink on unnecessary card backs
Professional Layout: Perfect for creating print-ready prototypes
Output Organization
Print and Play Folder: All generated PDFs are saved in a "Print and Play" folder within your project
Individual PDFs: Each selected deck gets its own PDF file named "{DeckName}_CardSheet.pdf"
Easy Access: Find your generated files in your project folder for printing or sharing
Printing Tips
Double-Sided Printing: For best results, print double-sided with the alternating back/front layout
Paper Quality: Use cardstock or heavy paper for professional-looking cards
Cutting Guides: The card layouts include proper spacing for easy cutting
Test Print: Print a single page first to ensure your printer settings are correct
Use Cases
Prototype Testing: Quickly create physical prototypes for playtesting
Game Sharing: Share your card games with friends and family
Event Materials: Create materials for game nights or conventions
Professional Presentation: Show physical prototypes to publishers or investors
Troubleshooting Print & Play
No Decks Available: Ensure your project has decks with cards in the "Finished" folder
PDF Generation Fails: Check that your browser supports PDF generation and has sufficient memory
Missing Card Backs: Verify that your decks have back images configured
Layout Issues: Try different "Cards per Page" settings for better fit
Drag & Drop Organization
Reordering Components
BlackBox includes powerful drag-and-drop functionality that allows you to easily reorganize your components and decks to match your preferred workflow.
Deck Reordering (Decks Screen)
Horizontal Reordering: On the decks screen, you can drag decks left and right to reorder them
Drag Handle: Look for the four-dot icon (⋮⋮) in the top-left corner of each deck card
Visual Feedback: While dragging, you'll see drop indicators showing where the deck will be placed
Persistent Order: Your deck order is automatically saved and will be remembered between sessions
Deck Reordering (Components Screen)
Vertical Reordering: In the components screen, decks can be reordered up and down
Same Functionality: Uses the same drag handles and visual feedback as the decks screen
Cross-Screen Consistency: Reordering in either screen updates the order everywhere
Custom Component Reordering
MISC Section: Custom components in the MISC section can be reordered vertically
Drag Handles: Each custom component has a four-dot drag handle on the left side
Smart Interaction: Buttons (edit/delete) temporarily disable dragging when clicked
Persistent Storage: Component order is saved to your project file
Drag & Drop Tips
Look for Drag Handles: The four-dot icon (⋮⋮) indicates items can be reordered
Visual Feedback: Pay attention to drop indicators and hover effects
Smooth Animations: Items smoothly animate to their new positions
Automatic Saving: Changes are saved automatically - no need to manually save
Organization Benefits
Workflow Optimization: Arrange components in the order you use them most
Project Management: Keep related decks together for easier navigation
Visual Hierarchy: Put important components at the top for quick access
Team Collaboration: Organize components in a way that makes sense for your team
Tips & Shortcuts
Keyboard Shortcuts
Tab Navigation: Use Tab to move between form fields and Enter to activate buttons
Slider Controls: Use arrow keys when focused on sliders for precise adjustments
Quick Access: Use the gear icon (⚙️) in the top right for quick access to settings
Workflow Tips
Design First: Set up your deck design (background, fonts, colors) before creating individual cards
Use Templates: Create one card with your design, then use "Use As Template" for bulk generation
Preview Often: Check your card previews frequently to ensure text fits and looks good
Save Regularly: Your work is automatically saved, but it's good practice to check your project folder
Performance Tips
Image Optimization: Use compressed images to improve loading times
Font Management: Remove unused custom fonts to improve performance
Browser Compatibility: Use modern browsers (Chrome, Firefox, Safari, Edge) for best performance
Rulebook Editor
What is the Rulebook Editor?
The Rulebook Editor is a powerful tool for creating professional game rulebooks and documentation. It allows you to design multi-page documents with various content blocks, custom layouts, and styling options.
Getting Started with Rulebooks
Step 1: Access the Rulebook Editor from the "Add Document" section in the main menu
Step 2: Give your rulebook a name in the "Rulebook Name" field
Step 3: Configure page settings (size, margins, bleed) in the "Bleed & Margins" panel
Step 4: Start adding content blocks to your pages using the tools panel
Step 5: Save your work regularly using the save button or Ctrl+S
Content Blocks
H1 & H2 Headers: Create main section headers and subheaders with customizable fonts and colors
Paragraph: Add body text with full formatting options including bold, italic, and alignment
Lists: Create bulleted or numbered lists with custom styling
Images: Insert images from your project or upload new ones
Game Logo: Automatically insert your project's game logo into the rulebook. The logo is pulled directly from your project details, ensuring consistency across all your documents. Click the logo block to change the image or drag and drop a new logo file.
Spacers: Add vertical spacing between content sections
Columns: Create multi-column layouts for complex page designs
Components List: Automatically generate lists of your project's components (decks, dice, custom items)
Page Management
Adding Pages: Click the "+" button in the page thumbnails panel to add new pages
Deleting Pages: Click the trash icon on any page thumbnail to delete it
Duplicating Pages: Click the duplicate icon to copy a page and all its content
Page Navigation: Click any page thumbnail to jump to that page
Page Thumbnails: The right panel shows live previews of all your pages
Components List Feature
Automatic Generation: The Components List block automatically displays all components from your current project
Smart Formatting: Shows deck card counts, custom component quantities, and proper pluralization
Customizable Layout: Choose between single, two, or three-column layouts
Sorting Options: Sort components alphabetically, by quantity, by type, or in custom order
Drag & Drop Reordering: Rearrange components by dragging them in the edit menu
Live Updates: Changes to layout, sorting, and colors update in real-time
Font Customization: Change the text color to match your rulebook's design
Page Settings & Layout
Page Size: Choose from standard sizes (Letter, A4, Legal) or set custom dimensions
Units: Work in pixels, inches, centimeters, or millimeters
Bleed & Margins: Set up proper margins and bleed areas for professional printing
Show Guides: Toggle visual guides to see margin and bleed boundaries
Page Color: Set custom background colors for your pages
Font Color: Customize the default text color for your rulebook
Editing & Formatting
Click to Edit: Click any content block to start editing it
Drag & Drop: Drag content blocks from the tools panel onto pages
Block Actions: Each block has refresh, duplicate, and delete buttons
Text Formatting: Use the formatting toolbar for bold, italic, alignment, and more
Auto-Save: Your work is automatically saved as you make changes
Saving & Loading
Auto-Save: Rulebooks are automatically saved to your browser's local storage
Named Documents: Give your rulebooks descriptive names for easy identification
Documents Table: View all saved rulebooks in the Components screen under "Documents"
Edit Existing: Click "Edit" on any saved document to continue working on it
Delete Documents: Remove unwanted rulebooks using the delete button in the Documents table
Tips for Great Rulebooks
Start with Structure: Plan your rulebook sections before adding content
Use Components Lists: Automatically keep your component lists up-to-date
Consistent Styling: Use the same fonts and colors throughout your document
Visual Hierarchy: Use H1 for main sections, H2 for subsections
Page Breaks: Use spacers to control where content appears on pages
Test Layout: Check the page thumbnails to see how your content flows
Box Creator
What is the Box Creator?
The Box Creator is a sophisticated 3D box design and template generation tool that allows you to create custom game boxes with realistic 3D previews, generate 2D templates for printing, and preview your 2D artwork on 3D box models. It's perfect for designing boxes for card games, board games, or any other tabletop game components.
Getting Started with Box Creation
Step 1: Access the Box Creator from the "Add Component" section in the main menu
Step 2: Choose "Add Box To Project" to open the box creator
Step 3: Set your box dimensions (width, height, depth) in the settings panel
Step 4: Customize the box appearance with colors, textures, and artwork
Step 5: Use the 3D preview to see your box from all angles
Box Dimensions & Settings
Width, Height, Depth: Set the internal dimensions of your box in your preferred units
Wall Thickness: Control how thick the box walls are (affects external dimensions)
Units: Work in inches, centimeters, or millimeters
Real-time Updates: Changes to dimensions instantly update the 3D preview
External Dimensions: The tool automatically calculates external dimensions based on wall thickness
3D Preview & Navigation
Mouse Controls: Left-click and drag to rotate the box view
Zoom: Use mouse wheel to zoom in and out
Pan: Right-click and drag to move the view around
Reset View: Use the reset button to return to the default viewing angle
Real-time Rendering: See changes to your box design instantly in 3D
Box Appearance & Styling
Base Color: Set the primary color for your box material
Texture Options: Choose from various material textures (matte, glossy, wood, etc.)
Artwork Upload: Add custom images for box sides, top, and bottom
Label Placement: Position text and graphics on different box faces
Finish Options: Adjust glossiness, roughness, and other material properties
2D Template Generation
Print-Ready Templates: Generate precise 2D templates that can be printed and assembled into physical boxes
Multiple Box Types: Create different box styles (standard, tuck box, magnetic closure, custom designs)
Template Layouts: Generate flat templates with proper fold lines, cut lines, and assembly guides
Artwork Integration: Place your 2D artwork directly onto the template with proper scaling and positioning
Export Options: Save templates as high-resolution images or PDFs for professional printing
Assembly Instructions: Generate step-by-step assembly guides for complex box designs
3D Preview & Artwork Testing
Real-Time 3D Preview: See your 2D artwork applied to a 3D box model instantly
Artwork Positioning: Test how your graphics look on different box faces and adjust positioning
Lighting & Materials: Preview how your artwork appears under different lighting conditions and material finishes
Perspective Views: View your box from multiple angles to ensure artwork looks good from all sides
Scale Testing: Verify that text and graphics are readable at the final box size
Color Accuracy: Preview how colors will appear on different materials and finishes
Advanced Design Features
Insert Design: Design custom inserts to hold your game components securely
Lid Options: Choose between hinged lids, removable tops, sliding covers, or magnetic closures
Handle Cutouts: Add finger holes, handle cutouts, or ergonomic grips for easy opening
Reinforcement Areas: Add extra material thickness in high-stress areas for durability
Custom Geometry: Create unique box shapes and designs beyond standard rectangular boxes
Multi-Piece Assembly: Design boxes that require multiple pieces for complex structures
Integration with Projects
Component Integration: Boxes appear in your project's Components screen
Size Optimization: Design boxes to perfectly fit your card decks and components
Project Organization: Keep all your game components (cards, boxes, rulebooks) in one project
Export Options: Save box designs as images or 3D files for sharing
Template Generation Workflow
Design Phase: Start with the 3D preview to visualize your box design and test artwork placement
Artwork Testing: Use the 3D preview to ensure your graphics look good from all angles and at the final size
Template Generation: Once satisfied with the 3D design, generate the 2D template for printing
Print Testing: Print a test template on regular paper first to check dimensions and assembly
Final Production: Print the final template on cardstock or your chosen material
Assembly: Follow the generated assembly instructions to create your physical box
Box Creation Tips
Measure Your Components: Know the dimensions of your cards and other components before designing
Add Extra Space: Include a small amount of extra space for easy insertion and removal
Test Artwork in 3D: Always preview your artwork on the 3D model before generating templates
Consider Accessibility: Make sure the box is easy to open and close
Test Different Angles: Use the 3D preview to check your box from all perspectives
Prototype First: Create a test version before finalizing your design
Print Considerations: Design with your printing method in mind (home printer vs. professional)
Material Testing: Test how your artwork looks on different materials and finishes
Troubleshooting Box Creator
3D Preview Not Loading: Ensure your browser supports WebGL and has hardware acceleration enabled
Slow Performance: Try reducing the complexity of textures or artwork
Dimension Issues: Double-check your measurements and units
Artwork Not Appearing: Verify image file formats and sizes are supported
Template Generation Fails: Check that your box dimensions are valid and artwork is properly positioned
Print Quality Issues: Ensure you're using high-resolution artwork and appropriate print settings
Assembly Problems: Verify that fold lines and cut lines are clearly marked on your template
Save Problems: Make sure you're working within a project and have given your box a name
