diff --git a/DESIGN_BRIEF.md b/DESIGN_BRIEF.md index 7552bad..fe20a17 100644 --- a/DESIGN_BRIEF.md +++ b/DESIGN_BRIEF.md @@ -843,6 +843,17 @@ BlockWar embraces a **near-future industrial military aesthetic** that balances ## Procedural Generation Strategy +### Decision: UE5-Native Procedural Generation with Unit Testing + +**Confirmed Approach:** BlockWar will implement procedural generation **directly within Unreal Engine 5** using its native tools (PCG Framework, Blueprints, C++, Python, and Geometry Script). This approach enables comprehensive unit testing while maintaining tight integration with the engine. + +**Key Benefits:** +- ✅ **Unit testable**: Python scripts and C++ code can be unit tested outside the editor +- ✅ **Editor integration**: Content generation happens in UE5 using native tools +- ✅ **Performance**: Generated content uses UE5's optimized systems +- ✅ **Maintainable**: Changes to generation logic are automatically tested via CI/CD +- ✅ **Flexible**: Mix of editor-time and runtime generation as needed + ### Overview BlockWar will leverage procedural generation extensively to create a maintainable, testable, and scalable codebase. By generating content programmatically rather than manually creating assets, we gain several key advantages: @@ -1318,6 +1329,42 @@ class TestMapGeneration(unittest.TestCase): - Localization strings - Documentation generation +#### 5. Quick Start: Setting Up Testing + +**Development Environment Setup:** +```bash +# Clone repository +git clone https://github.com/yourorg/BlockWar.git +cd BlockWar + +# Install Python dependencies +pip install -r requirements.txt +pip install -r requirements-test.txt + +# Run unit tests (no UE5 required) +pytest tests/unit/ -v + +# Generate procedural content (requires UE5) +python scripts/generate_all_content.py + +# Run UE5 automation tests (requires UE5 editor) +UnrealEditor.exe BlockWar.uproject -ExecCmds="Automation RunTests;Quit" +``` + +**Running Tests in CI/CD:** +- Unit tests run on every commit (GitHub Actions) +- Integration tests run on pull requests +- Full UE5 build tests run on main branch merges +- See `.github/workflows/ci.yml` for complete pipeline + +**Test-Driven Development Workflow:** +1. Write Python unit test for generation logic +2. Implement generation algorithm in Python +3. Run `pytest` to verify (fast, no UE5 needed) +4. Integrate with UE5 APIs +5. Run UE5 automation tests to verify integration +6. Commit and push (CI/CD runs full test suite) + --- ### Testing Strategy @@ -1395,6 +1442,41 @@ tests/ - Ensure performance targets - Document expected behavior +#### How UE5 Procedural Generation Enables Unit Testing + +**Testing Architecture:** + +1. **Python Scripts**: Core generation logic lives in Python scripts that can be tested independently + ```python + # scripts/generators/block_generator.py - Testable outside UE5 + def generate_block_parameters(block_type, size): + # Pure Python logic, fully unit testable + return BlockParams(...) + ``` + +2. **UE5 Integration**: Python scripts call UE5 APIs to create actual assets + ```python + # Only executed in UE5 editor + import unreal + block_params = generate_block_parameters('cube', 1.0) # Tested + unreal.EditorAssetLibrary.create_asset(...) # UE5 integration + ``` + +3. **C++ Systems**: Game logic in C++ with dedicated test targets + ```cpp + // Can be compiled and tested separately from editor + class BlockPhysicsSystem { + bool IsStable(const BlockConfig& config); // Unit testable + }; + ``` + +**This approach provides:** +- ✅ Fast unit tests (Python/C++) without launching UE5 editor +- ✅ Integration tests within UE5 automation framework +- ✅ CI/CD pipeline compatibility +- ✅ Code coverage metrics +- ✅ Rapid iteration cycles + --- ### Benefits Summary diff --git a/README.md b/README.md index a47fc4e..bfc67d1 100644 --- a/README.md +++ b/README.md @@ -6,5 +6,17 @@ BlockWar is an innovative multiplayer FPS that combines tactical base constructi Built in Unreal Engine 5, inspired by classic community mods. +## Technical Approach + +**Procedural Generation + Unit Testing**: BlockWar uses UE5's native procedural generation tools (PCG Framework, Blueprints, C++, Python, Geometry Script) to create game content. This approach enables comprehensive unit testing while maintaining tight engine integration. + +**Key Technologies:** +- **UE5 PCG Framework**: Level and content generation +- **Geometry Script**: Procedural mesh generation +- **Python**: Editor automation and unit testing +- **C++**: Performance-critical systems and testing +- **Blueprints**: Gameplay logic and procedural workflows + ## Documentation -See [DESIGN_BRIEF.md](DESIGN_BRIEF.md) for comprehensive game design documentation. +- [DESIGN_BRIEF.md](DESIGN_BRIEF.md) - Comprehensive game design documentation +- See "Procedural Generation Strategy" section for detailed technical approach and testing methodology