From eebc222d7351b85c95a9e99a1df70fc176741750 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 24 Dec 2025 13:25:52 +0000 Subject: [PATCH 1/5] Initial plan From 4bc062cebd88e5cbf2594fe697146a0f457f32b4 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 24 Dec 2025 13:29:03 +0000 Subject: [PATCH 2/5] Document UE5 procedural generation approach with unit testing Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com> --- DESIGN_BRIEF.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 14 ++++++++- 2 files changed, 95 insertions(+), 1 deletion(-) 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 From f70ac68d2fec7469d742f933463db1d145356811 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 24 Dec 2025 13:30:06 +0000 Subject: [PATCH 3/5] Add quick navigation to design brief for easy reference Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com> --- DESIGN_BRIEF.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/DESIGN_BRIEF.md b/DESIGN_BRIEF.md index fe20a17..022b5fe 100644 --- a/DESIGN_BRIEF.md +++ b/DESIGN_BRIEF.md @@ -1,5 +1,13 @@ # BlockWar Design Brief +**Quick Navigation:** +- [Procedural Generation Strategy](#procedural-generation-strategy) - **Key Technical Decision**: UE5-native procedural generation with unit testing +- [Project Overview](#project-overview) - Game concept and goals +- [Core Game Concept](#core-game-concept) - Gameplay mechanics +- [CI/CD Pipeline](#cicd-pipeline) - Automated testing and deployment + +--- + ## Project Naming Recommendations ### Current Name Analysis From 2fc355dbd526c9f90c1988dbef4bf7bb8ace6d30 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 24 Dec 2025 13:31:26 +0000 Subject: [PATCH 4/5] Use placeholders in quick start guide for better maintainability Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com> --- DESIGN_BRIEF.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/DESIGN_BRIEF.md b/DESIGN_BRIEF.md index 022b5fe..1a1ba2f 100644 --- a/DESIGN_BRIEF.md +++ b/DESIGN_BRIEF.md @@ -1342,7 +1342,7 @@ class TestMapGeneration(unittest.TestCase): **Development Environment Setup:** ```bash # Clone repository -git clone https://github.com/yourorg/BlockWar.git +git clone cd BlockWar # Install Python dependencies @@ -1356,7 +1356,7 @@ pytest tests/unit/ -v python scripts/generate_all_content.py # Run UE5 automation tests (requires UE5 editor) -UnrealEditor.exe BlockWar.uproject -ExecCmds="Automation RunTests;Quit" +UnrealEditor.exe .uproject -ExecCmds="Automation RunTests;Quit" ``` **Running Tests in CI/CD:** From 0bf0c5dfa0a6bd6fa320dc2a7c0ac07e6e26ff1c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 24 Dec 2025 13:32:36 +0000 Subject: [PATCH 5/5] Clarify that quick start guide describes planned implementation Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com> --- DESIGN_BRIEF.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/DESIGN_BRIEF.md b/DESIGN_BRIEF.md index 1a1ba2f..c19ce4e 100644 --- a/DESIGN_BRIEF.md +++ b/DESIGN_BRIEF.md @@ -1339,13 +1339,15 @@ class TestMapGeneration(unittest.TestCase): #### 5. Quick Start: Setting Up Testing +**Note**: This section describes the planned development environment setup. These files and directories will be created during project implementation. + **Development Environment Setup:** ```bash # Clone repository git clone cd BlockWar -# Install Python dependencies +# Install Python dependencies (files to be created) pip install -r requirements.txt pip install -r requirements-test.txt @@ -1356,6 +1358,7 @@ pytest tests/unit/ -v python scripts/generate_all_content.py # Run UE5 automation tests (requires UE5 editor) +# Replace with actual UE5 project name (e.g., BlockWar) UnrealEditor.exe .uproject -ExecCmds="Automation RunTests;Quit" ``` @@ -1363,7 +1366,7 @@ UnrealEditor.exe .uproject -ExecCmds="Automation RunTests;Quit" - 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 +- See `.github/workflows/ci.yml` for complete pipeline (to be implemented) **Test-Driven Development Workflow:** 1. Write Python unit test for generation logic