"May your worlds be procedurally perfect, your builds eternally green, and your development chair supremely comfortable."

TWG-MetVanDamn is an advanced Unity project that combines procedural MetroidVania world generation with Entity Component System (ECS/DOTS) architecture to create dynamic, interconnected game worlds. The project features a sophisticated Living Dev Agent workflow that integrates comprehensive development tooling, documentation practices, and the sacred "Save The Butts!" philosophy.

• 🗺️ Procedural MetroidVania Generation: Wave Function Collapse (WFC) algorithms create interconnected districts with proper gating and biome distribution
• ⚡ High-Performance ECS/DOTS: Unity's Data-Oriented Technology Stack for scalable, performance-optimized game systems
• 🧬 Living Dev Agent Workflow: Comprehensive development environment with automated documentation, validation, and collaboration tools
• 🍑 Developer Comfort Focus: Sustainable development practices prioritizing developer well-being and code quality

• District System: Modular world areas with unique characteristics and connections
• Wave Function Collapse (WFC): Constraint-solving algorithm for coherent world layout
• Biome Field System: Dynamic environmental influences across the world
• Gate Condition System: MetroidVania-style progression gating with configurable unlock conditions
• AI Navigation System: Runtime pathfinding with polarized gate handling for intelligent agent movement

• Navigation Graph: Runtime graph built from districts, connections, and gates
• Agent Capabilities: Polarity and ability-based agent configuration system
• Polarized Gate Handling: Dual-mode support for hard blocking vs. soft cost-based gating
• Reachability Validation: Automated detection of unreachable areas and connectivity issues
• Editor Visualization: Interactive navigation graph debugging with cost overlays

• Pure ECS Architecture: All game logic implemented as performant, data-oriented systems
• Burst-Compiled Systems: Maximum performance through Unity's Burst compiler
• Job System Integration: Efficient multi-threaded processing for complex world generation
• Authoring Layer: Scene-based setup tools for designers without requiring code

com.tinywalnutgames.metvd.core     # Core components, IDs, math utilities
com.tinywalnutgames.metvd.biome    # Biome field system and polarity rules
com.tinywalnutgames.metvd.graph    # District WFC and sector refinement
com.tinywalnutgames.metvd.authoring # Scene authoring tools and bakers
com.tinywalnutgames.metvd.utility  # Generic utilities and aggregation systems
com.tinywalnutgames.metvd.samples  # Example scenes and configurations

• Unity 6000.2+ (Unity 6 with DOTS 1.2.0)
• Git with LFS support for large assets
• Visual Studio or JetBrains Rider (recommended)
• Python 3.11+ for Living Dev Agent tools

# Clone the repository
git clone https://github.com/jmeyer1980/TWG-MetVanDamn.git
cd TWG-MetVanDamn

# Initialize Living Dev Agent environment
mkdir -p .github/workflows
chmod +x scripts/init_agent_context.sh scripts/clone-and-clean.sh
scripts/init_agent_context.sh

# Open project in Unity 6000.2+
# Unity will automatically resolve package dependencies
# Import any required 2D packages if working with sprites

# Verify DOTS packages are properly installed:
# - com.unity.entities 1.2.0+
# - com.unity.collections 1.2.4+
# - com.unity.mathematics 1.2.6+

# Install development dependencies
pip install -r scripts/requirements.txt

# Run validation to ensure setup is correct
python3 src/SymbolicLinter/validate_docs.py --tldl-path docs/
python3 src/DebugOverlayValidation/debug_overlay_validator.py --path src/
python3 src/SymbolicLinter/symbolic_linter.py --path src/

1. Follow the Complete Setup Guide - The ultimate "clone to working world" experience
2. Navigate to Assets/Scenes/ for example scenes
3. Check Documentation Hub for comprehensive guides
4. Review MANIFESTO.md for project philosophy and development practices
5. Create your first TLDL entry: scripts/init_agent_context.sh --create-tldl "MyFirstAdventure"

• Dynamic District Creation: Each playthrough generates unique interconnected areas
• Intelligent Gate Placement: Progression barriers placed according to MetroidVania design principles
• Biome Consistency: Environmental themes flow naturally across connected regions
• Configurable Complexity: Adjust world size, density, and challenge progression

• Scalable Architecture: Handle thousands of entities without performance degradation
• Burst-Compiled Systems: Critical paths optimized for maximum throughput
• Data-Oriented Design: Memory layout optimized for cache efficiency
• Job System Parallelization: Multi-threaded processing for complex algorithms

• Scene-Based Authoring: Set up worlds visually without code
• Real-Time Preview: See generation results instantly during development
• Validation Systems: Catch configuration errors before runtime
• Debug Overlays: Visualize generation algorithms in action

TWG-MetVanDamn/
├── Assets/
│   ├── MetVanDAMN/                    # Core game systems
│   │   ├── Authoring/                 # Scene authoring tools
│   │   ├── Docs/                      # **NEW** - Consolidated MetVanDAMN documentation hub
│   │   └── Utility/                   # Generic ECS utilities
│   ├── Plugins/TLDA/                  # Living Dev Agent Unity integration
│   │   ├── Editor/                    # TLDL editor tools
│   │   ├── Runtime/                   # Runtime TLDA components
│   │   └── docs/                      # TLDA-specific documentation
│   ├── Scenes/                        # Example and test scenes
│   └── Settings/                      # Unity project settings
├── Packages/                          # Custom packages
│   ├── com.tinywalnutgames.metvd.core/      # Core systems
│   ├── com.tinywalnutgames.metvd.biome/     # Biome management
│   ├── com.tinywalnutgames.metvd.graph/     # Graph generation
│   ├── com.tinywalnutgames.metvd.authoring/ # Authoring tools
│   ├── com.tinywalnutgames.metvd.utility/   # Utility systems
│   └── com.tinywalnutgames.metvd.samples/   # Example content
├── scripts/                           # Development automation
│   ├── init_agent_context.sh         # Environment initialization
│   ├── clone-and-clean.sh           # Template setup
│   └── cid-faculty/                  # CI/CD automation
├── src/                              # Validation and linting tools
├── docs/                             # Legacy documentation (being phased out)
├── TLDL/                             # Living Dev Log entries
├── MANIFESTO.md                      # Project philosophy
├── CONTRIBUTING.md                   # Contribution guidelines
└── CHANGELOG.md                      # Release history

This project follows the Save The Butts! manifesto, prioritizing:

• Developer Comfort: Ergonomic practices and sustainable development
• Documentation Excellence: Comprehensive TLDL (Living Dev Log) entries
• Collaborative Spirit: Mentoring, knowledge sharing, and inclusive practices
• Quality Focus: Automated validation, testing, and continuous improvement

# Create new development entry
scripts/init_agent_context.sh --create-tldl "FeatureName"

# Document discoveries, decisions, and learnings
# Follow template in docs/tldl_template.yaml

# Validate documentation integrity
python3 src/SymbolicLinter/validate_docs.py --tldl-path docs/

# Environment initialization
scripts/init_agent_context.sh                    # Setup and validate environment
scripts/init_agent_context.sh --create-tldl "Title"  # Create new TLDL entry

# Quality assurance
python3 src/SymbolicLinter/validate_docs.py --tldl-path docs/    # ~60ms
python3 src/DebugOverlayValidation/debug_overlay_validator.py    # ~56ms
python3 src/SymbolicLinter/symbolic_linter.py --path src/        # ~68ms

# Project maintenance
scripts/directory_lint.py                        # Validate project structure
python3 scripts/cid-faculty/overlord-sentinel.js # Security validation

• Use Assets/MetVanDAMN/Authoring/BiomeArtProfileLibrary to define available BiomeArtProfile assets.
• Populate a global profiles list and optional perTypeBuckets for specific BiomeType values.
• Runtime selection order in BiomeArtAutoAssignmentSystem:
  1. Prefer matching perTypeBuckets[type].profiles when present and non-empty
  2. Fallback to the global profiles list
• Selection is deterministic per biome entity: seeded by world seed, biome type, and NodeId.
• Editor tools (Biome Color Legend, Sector Room Hierarchy) use the same preference order for names/colors.

Set up and query world configuration data via a single ECS aspect.

• Authoring: Add WorldAuthoring to any GameObject in your scene and configure Seed, World Size (Extents), Target Sector Count, Biome Transition Radius, and toggles for debug/logging. The baker adds WorldSeedData, WorldBoundsData, and WorldGenerationConfigData to an entity.
• Query: Use WorldConfigAspect to read/write the values from systems.

using Unity.Burst;
using Unity.Entities;
using TinyWalnutGames.MetVD.Core; // WorldConfigAspect and Data components

[BurstCompile]
[UpdateInGroup(typeof(InitializationSystemGroup))]
public partial struct WorldConfigAspectQuickstartSystem : ISystem
{
    public void OnCreate(ref SystemState state) {}

    public void OnUpdate(ref SystemState state)
    {
        foreach (var world in SystemAPI.Query<WorldConfigAspect>())
        {
            // Read authored values
            var seed = world.WorldSeed;
            var center = world.Center;   // float3
            var extents = world.Extents; // float3

            // Adjust generation config at runtime
            world.TargetSectors = math.max(1, world.TargetSectors);
            world.BiomeTransitionRadius = math.max(1f, world.BiomeTransitionRadius);

            if (world.LogSteps)
            {
                UnityEngine.Debug.Log($"World seed {seed} @ center {center} extents {extents}");
            }
        }
    }
}

Files and references:

• Assets/MetVanDAMN/Authoring/WorldAuthoring.cs (authoring + baker)
• Packages/com.tinywalnutgames.metvd.core/Runtime/WorldConfigAspect.cs (aspect)
• Packages/com.tinywalnutgames.metvd.core/Runtime/WorldConfigAspectSampleSystem.cs (example system)
• Assets/MetVanDAMN/Authoring/Tests/WorldConfigAspectPlayModeTests.cs (PlayMode test)

The world generation system uses a constraint-solving approach where:

1. District Templates: Pre-defined room types with connection rules
2. Constraint Propagation: Ensures valid connections between adjacent areas
3. Backtracking Algorithm: Resolves conflicts through systematic exploration
4. Biome Coherence: Environmental rules guide theme distribution

// Example: Biome field processing
[BurstCompile]
[UpdateInGroup(typeof(SimulationSystemGroup))]
public partial struct BiomeFieldSystem : ISystem
{
    // High-performance biome influence calculation
    // Processes thousands of entities per frame
}

• World Generation: ~200ms for medium complexity worlds
• Biome Processing: 60fps with 10,000+ entities
• Memory Usage: <100MB for typical game worlds
• Build Time: ~30s for incremental builds

We welcome contributions! Please see our Contributing Guidelines for detailed information about:

• Development Workflow: TLDL documentation, code review process
• Code Standards: ECS best practices, naming conventions
• Issue Reporting: Bug reports, feature requests
• Community Guidelines: Inclusive, respectful collaboration

• Read the MANIFESTO.md and embrace the Save The Butts! philosophy
• NEW: Follow the Complete MetVanDAMN Setup Guide for immediate success
• Browse the MetVanDAMN Documentation Hub for comprehensive guides and references
• Create TLDL entries documenting your work
• Follow ECS/DOTS best practices
• Add tests for new functionality
• Update documentation as needed
• Run validation tools before submitting PRs

• 📚 MetVanDAMN Documentation Hub: NEW - Complete consolidated documentation hub with GitBook structure
• 🗺️ Complete Setup Guide: From clone to full playable demo in 25 minutes
• ⚡ Quick Start Guide: Rapid developer introduction
• 🏛️ Project Overview: Complete system architecture overview
• 📋 Technical Specification: Comprehensive API and system documentation
• MANIFESTO.md: Project philosophy and "Save The Butts!" doctrine
• CONTRIBUTING.md: Comprehensive contribution guidelines
• CHANGELOG.md: Release history and feature evolution

• MetVanDAMN TLDL Chronicles: Development chronicles and technical discoveries
• TLDL/entries/: General development chronicles
• Legacy docs/: Legacy documentation (being phased out)

• Unity DOTS Documentation: Official ECS/DOTS guides
• Wave Function Collapse: Algorithm reference implementation
• MetroidVania Design Patterns: Genre design principles

• 🛡️ Buttsafe Certified™: Comprehensive developer comfort and code quality standards
• ⚡ DOTS Optimized: High-performance ECS architecture with Burst compilation
• 🧬 Living Documentation: Self-documenting codebase with comprehensive TLDL integration
• 🤖 AI Collaboration Ready: GitHub Copilot integration with ping-and-fix workflows

This project is licensed under the GNU General Public License v3.0. See LICENSE for details.

Created by: Tiny Walnut Games Development Team Template System: Living Dev Agent workflow Philosophy: Save The Butts! Manifesto Powered by: Unity DOTS, ECS architecture, and developer comfort principles

Special thanks to:

• The Living Dev Agent Community: For innovative development workflows
• Unity DOTS Team: For powerful ECS framework and performance tools
• MetroidVania Designers: For establishing genre conventions we lovingly subvert
• Every Developer: Who has suffered through uncomfortable chairs and poor documentation

"May your worlds be procedurally perfect, your builds eternally green, and your development chair supremely comfortable."

🍑 ✨ Happy Coding! ✨ 🍑