Skip to content

Latest commit

 

History

History
419 lines (305 loc) · 12.2 KB

TEXTURE_GUIDES_README.md

File metadata and controls

419 lines (305 loc) · 12.2 KB

Drill Down Texture System - Complete Documentation

Master index for all texture packing guides. Start here to find the guide you need.

📚 Available Guides

1. TEXTURE_PACKING_GUIDE.md - Complete Reference Manual

Best for: Understanding the complete system, troubleshooting issues, learning how everything works

Contents:

  • System overview and workflow
  • Key concepts (texture atlas, TexturePacker, TextureRegion)
  • All files involved (atlas-settings.json, tex.atlas, etc.)
  • Texture naming conventions
  • Step-by-step: Adding new textures
  • Comprehensive troubleshooting section
  • Common mistakes and how to avoid them
  • Advanced: Atlas file format explanation

When to read:

  • First time learning the system
  • Debugging texture issues
  • Understanding why something doesn't work
  • Need comprehensive reference

Read time: 20-30 minutes for full understanding

2. TEXTURE_IMPLEMENTATION_CHECKLIST.md - Quick Action Guide

Best for: Rapid implementation, following a checklist, avoiding mistakes during implementation

Contents:

  • Pre-implementation checklist
  • Step-by-step instructions with checkboxes
  • Code examples for each type (items, structures, science)
  • TexturePacker invocation options
  • Atlas verification steps
  • Testing procedures
  • Git commands for committing
  • Troubleshooting quick reference

When to read:

  • Adding textures to the game right now
  • Want a step-by-step checklist format
  • Need quick reference during implementation
  • First-time implementation

Read time: 5-10 minutes during implementation

3. TEXTURE_SYSTEM_ARCHITECTURE.md - Visual Explanation

Best for: Visual learners, understanding data flow, system architecture, performance

Contents:

  • System architecture diagrams (ASCII art)
  • Data flow visualizations
  • Component relationship diagrams
  • Naming convention system
  • Atlas file format explained visually
  • Common issues & breakdown points
  • Performance characteristics
  • Complete data flow verification checklist

When to read:

  • Want to understand HOW the system works
  • Learning the architecture
  • Understanding data flow
  • Visual learners
  • Explaining system to others

Read time: 10-15 minutes

4. TEXTURE_PATTERNS_AND_TIPS.md - Advanced Techniques

Best for: Real-world patterns, optimization, debugging, best practices

Contents:

  • Common implementation patterns (items, buildings, science, variants)
  • Advanced techniques (large atlases, compression, dynamic loading, replacement systems)
  • Performance tips and optimization
  • Debugging techniques
  • Common pitfalls and how to avoid them
  • Workflow optimization
  • Best practices checklist

When to read:

  • After basic implementation works
  • Optimizing performance
  • Debugging complex issues
  • Learning advanced techniques
  • Implementing multiple textures

Read time: 15-20 minutes (or reference as needed)

🎯 Quick Navigation

"I need to add a texture right now!"

→ Read TEXTURE_IMPLEMENTATION_CHECKLIST.md

Step-by-step guide with checkboxes and code examples. You'll be done in 10 minutes.

"I don't understand why my texture isn't showing"

→ Read TEXTURE_PACKING_GUIDE.md (Troubleshooting section)

Comprehensive troubleshooting for all common issues.

"I want to understand how the entire system works"

→ Read TEXTURE_SYSTEM_ARCHITECTURE.md then TEXTURE_PACKING_GUIDE.md

First get the visual overview, then dive into complete details.

"My textures disappeared after regeneration"

→ Read TEXTURE_PACKING_GUIDE.md (Problem 2: Textures Missing After Regenerating Atlas)

Specific diagnosis and solutions for this common issue.

"I want to optimize and improve my texture workflow"

→ Read TEXTURE_PATTERNS_AND_TIPS.md

Real-world patterns, best practices, and workflow optimization tips.

"I'm debugging a complex texture issue"

→ Read TEXTURE_PATTERNS_AND_TIPS.md (Debugging Texture Issues section)

Multiple debugging techniques and visual debugging tools.

📋 Decision Tree

START: "I need to work with textures"
    ↓
    Are you adding textures for the first time?
    ├─ YES → Read TEXTURE_IMPLEMENTATION_CHECKLIST.md (5-10 min)
    │        Then keep TEXTURE_PACKING_GUIDE.md as reference
    │
    └─ NO → Do you have a specific problem?
            ├─ YES, I don't know why textures aren't working
            │   → Read TEXTURE_PACKING_GUIDE.md (Troubleshooting)
            │
            ├─ YES, I want to optimize
            │   → Read TEXTURE_PATTERNS_AND_TIPS.md
            │
            ├─ YES, I'm debugging
            │   → Read TEXTURE_PATTERNS_AND_TIPS.md (Debugging section)
            │
            └─ NO, I want to understand everything
                → Read all guides in order:
                   1. TEXTURE_SYSTEM_ARCHITECTURE.md
                   2. TEXTURE_PACKING_GUIDE.md
                   3. TEXTURE_PATTERNS_AND_TIPS.md

🚀 Getting Started Paths

Path 1: "I'm New and Need to Add Textures Now" (15 minutes)

  1. Read: TEXTURE_IMPLEMENTATION_CHECKLIST.md (Steps 1-5)
  2. Do: Create texture PNG and add code
  3. Do: Run TexturePacker
  4. Do: Test in game
  5. Bookmark: TEXTURE_PACKING_GUIDE.md for future reference

Path 2: "I Want to Fully Understand the System" (60 minutes)

  1. Read: TEXTURE_SYSTEM_ARCHITECTURE.md (understand overview)
  2. Read: TEXTURE_PACKING_GUIDE.md (understand details)
  3. Skim: TEXTURE_PATTERNS_AND_TIPS.md (aware of patterns)
  4. Practice: Add a test texture following CHECKLIST.md
  5. Result: Complete mastery of system

Path 3: "I Have a Problem to Solve" (5-30 minutes)

  1. Identify your problem in TEXTURE_PACKING_GUIDE.md (Troubleshooting section)
  2. Read: The specific problem section
  3. Apply: The suggested fix
  4. Verify: Test that it works
  5. Learn: Read the explanation to understand why

📖 Complete Reading Order (for deep understanding)

For developers who want comprehensive mastery:

  1. TEXTURE_SYSTEM_ARCHITECTURE.md (15 min)

    • Understand high-level system
    • See visual data flow
    • Learn key components

  2. TEXTURE_PACKING_GUIDE.md (30 min)

    • Understand detailed mechanisms
    • Learn all configuration options
    • Study naming conventions
    • Learn troubleshooting

  3. TEXTURE_IMPLEMENTATION_CHECKLIST.md (5 min)

    • Internalize the workflow
    • Keep as quick reference

  4. TEXTURE_PATTERNS_AND_TIPS.md (20 min)

    • Learn real-world patterns
    • Understand advanced techniques
    • Learn best practices

  5. Practice: Add 3-5 test textures following the checklist

Total time: ~70 minutes for complete mastery

🔑 Key Concepts Quick Reference

These concepts appear throughout all guides:

Texture Atlas

A single large image (tex.png) containing many smaller textures packed efficiently together.

  • Current size: 4096×2048 pixels
  • Contains: All game textures (structures, items, tiles, UI, etc.)
  • Format: RGBA PNG

TexturePacker

LibGDX tool that combines individual PNGs into an atlas.

  • Input: Hundreds of individual PNG files
  • Output: tex.png + tex.atlas
  • Command: ./gradlew.bat desktop:run -Pargs=textures

tex.atlas

Text descriptor file mapping texture names to coordinates in tex.png.

  • Purpose: Tells game where each texture is located
  • Auto-generated: Do NOT edit manually
  • Format: Human-readable text file with coordinates

TextureRegion

LibGDX object representing a portion of the atlas.

  • Created by: Quarry.Q.atlas.findRegion("name")
  • Contains: Pointers to specific pixel coordinates in tex.png
  • Used by: Game rendering code

Naming Convention

Strict naming system matching files to code references.

  • Items: item_[name].png ↔ Code: "item_[name]"
  • Structures: structure_[name].png ↔ Code: "structure_[name]"
  • Science: icon_[name].png ↔ Code: "icon_[name]"
  • Critical: Name match must be EXACT

✅ Verification Checklist (Before Committing)

Use this checklist before committing any texture changes:

File Organization

  • All PNG files in Development/Textures/
  • PNG naming follows convention (type_name.png)
  • PNG format is RGBA with transparency
  • No source files (PSD, XCF) in Development/Textures/
  • No backup or temp files in Development/Textures/

Code References

  • Code texture names match PNG filenames exactly
  • Code changes in appropriate enums (ItemType, StructureType, etc.)
  • All texture references are consistent

Atlas Generation

  • TexturePacker was run after all changes
  • android/assets/tex.png was updated
  • android/assets/tex.atlas was updated
  • Only tex.png and tex.atlas exist (no tex2.png)
  • android/assets/atlas-settings.json checked (maxWidth/Height = 4096)

Testing

  • Game compiles without errors
  • Game launches without "texture not found" errors
  • New textures visible and display correctly
  • Existing textures still work (no regression)
  • Texture appearance matches expectations

Localization

  • English strings added to TheQuarry_en.properties
  • Game displays proper names in menus

Git Commit

  • Development/Textures/ files staged
  • android/assets/tex.png staged
  • android/assets/tex.atlas staged
  • Code changes staged
  • Commit message is descriptive

🆘 When Things Go Wrong

Quick Troubleshooting Decision Tree

Game won't start / crashes
├─ "could not find texture" error?
│  └─ → TEXTURE_PACKING_GUIDE.md: Problem 1
│
├─ "multiple atlas pages created" warning?
│  └─ → TEXTURE_PACKING_GUIDE.md: Problem 2 (Cause A)
│
├─ Textures missing or wrong?
│  ├─ After packing? → Problem 2 (Causes A, B, C)
│  ├─ After restart? → Problem 4 (Old textures)
│  └─ Wrong appearance? → Problem 3
│
└─ Something else?
   └─ → Search TEXTURE_PACKING_GUIDE.md for your symptom

📞 Need Help?

  1. Check the guides - Most issues are documented
  2. Search for symptoms - Use Ctrl+F to search relevant guide
  3. Follow troubleshooting - TEXTURE_PACKING_GUIDE.md has comprehensive troubleshooting
  4. Try a test - Add a simple texture following CHECKLIST.md to verify workflow
  5. Review patterns - TEXTURE_PATTERNS_AND_TIPS.md shows real working examples

📝 Document Information

Guide Sizes

  • TEXTURE_PACKING_GUIDE.md: ~6,000 words (comprehensive reference)
  • TEXTURE_IMPLEMENTATION_CHECKLIST.md: ~2,000 words (quick action)
  • TEXTURE_SYSTEM_ARCHITECTURE.md: ~4,000 words (visual explanation)
  • TEXTURE_PATTERNS_AND_TIPS.md: ~5,000 words (patterns & advanced)
  • TEXTURE_GUIDES_README.md: This file (navigation)

Total Learning Material

  • Complete reading: ~60-70 minutes
  • Quick reference during work: 5-10 minutes per session
  • Future lookups: 2-5 minutes per issue

💾 File Reference

All guides are markdown files in the project root:

D:\Projects\DrillDown\
├── TEXTURE_GUIDES_README.md          ← You are here
├── TEXTURE_PACKING_GUIDE.md
├── TEXTURE_IMPLEMENTATION_CHECKLIST.md
├── TEXTURE_SYSTEM_ARCHITECTURE.md
└── TEXTURE_PATTERNS_AND_TIPS.md

🎓 Learning Outcomes

After reading these guides, you will understand:

✅ How the texture packing system works
✅ Why TexturePacker is necessary
✅ What tex.atlas does and why it's important
✅ How to add new textures correctly
✅ What naming conventions to follow
✅ How to run TexturePacker
✅ How to verify textures are packed correctly
✅ How to troubleshoot common issues
✅ Best practices for texture management
✅ Advanced techniques and optimizations
✅ Performance implications
✅ Debugging strategies

🚀 Ready to Get Started?

  1. Beginner? → Start with TEXTURE_IMPLEMENTATION_CHECKLIST.md
  2. Want full understanding? → Start with TEXTURE_SYSTEM_ARCHITECTURE.md
  3. Have a problem? → Go to TEXTURE_PACKING_GUIDE.md > Troubleshooting
  4. Want optimization? → Read TEXTURE_PATTERNS_AND_TIPS.md

Good luck! 🎮

Created for the Drill Down development team. These guides document the tried-and-tested texture packing workflow for LibGDX games.