warfactoryracine/TODO.md

Warfactory - Implementation Roadmap

Current Status

✅ Documentation Phase Complete (51,335 words, 9.5/10 quality) 🚀 Next Phase: Core Implementation & Module System

---

Phase 1: Core Interfaces 🏗️

Interface Definitions

• IEngine.h - Engine orchestration interface

  • initialize(), update(deltaTime), shutdown()
  • setModuleSystem(std::unique_ptr<IModuleSystem>)

• IModuleSystem.h - Module execution strategy interface

  • registerModule(name, std::unique_ptr<IModule>)
  • processModules(deltaTime), setIOLayer(std::unique_ptr<IIO>)
  • queryModule(name, json input) -> json

• IModule.h - Pure business logic interface

  • json process(const json& input) // PURE FUNCTION
  • initialize(const json& config), shutdown()
  • getState(), setState(const json& state) // Hot-reload support

• IIO.h - Communication transport interface

  • json send(target, message), json receive(source)
  • broadcast(const json& message)

---

Phase 2: Initial Implementations ⚙️

Core Engine Components

• DebugEngine - Development/testing engine

  • Step-by-step execution, verbose logging
  • Module isolation for debugging

• SequentialModuleSystem - Simple execution strategy

  • Process modules one at a time (debug/test mode)
  • Perfect for initial development

• IntraIO - Direct communication layer

  • Same-process direct function calls
  • Zero network overhead for local development

Configuration System Setup (PREREQUISITE)

• Basic configuration framework - BEFORE FIRST MODULE
  • JSON-based configuration loading
  • Module-specific config files in config/ directory
  • Configuration validation and error handling
  • Essential for module parameterization

Coordination System (CRITICAL FOUNDATION)

• Module coordination framework - AFTER CONFIG, BEFORE MODULES

  • Inter-module communication orchestration
  • Message routing and delivery system
  • Module dependency management and ordering
  • Event system for module coordination

• JSON coordination interface

  • Input: {"type": "coordinate", "source": "ModuleA", "target": "ModuleB", "message": {...}}
  • Output: {"status": "delivered", "response": {...}, "timing": "5ms"}

• Coordination services

  • Module discovery and registration
  • Health monitoring and failure detection
  • Load balancing for module requests
  • Debugging and logging coordination activities

Logging & Monitoring System (DEVELOPMENT ESSENTIAL)

• Basic logging infrastructure - WITH COORDINATION SYSTEM

  • Module-specific log channels
  • Configurable log levels (DEBUG, INFO, WARN, ERROR)
  • JSON-structured logging for parsing
  • Log file rotation and management

• Performance monitoring

  • Module execution time tracking
  • JSON message processing metrics
  • Memory usage per module (basic)
  • Hot-reload performance measurement

• Development debugging

  • Real-time log streaming to ImGUI
  • Module communication visualization
  • Performance dashboard integration
  • Error alerting and notification

First Module Implementation

• DebugWorldGenModule.cpp - FIRST MODULE (200-300 lines max)
  • Critical: No world exists without this module
  • Uses configuration system for world parameters
  • Minimal world generation for development/testing
  • JSON input/output validation
  • State preservation testing
  • Hot-reload capability verification

---

Phase 3: Fixes & Infrastructure Setup 🛠️

Legacy System Repairs

• Fix defense mode - Adapt from engines → modules
  • Update apply_defenses_to_all_engines.sh
  • Migrate defense configurations to modular system
  • Verify sanitizer compatibility with new architecture

Project Structure Setup

• Setup modules/ directory structure

  modules/
  ├── test/              # TestModule for validation
  ├── tank/              # TankModule (future)
  ├── economy/           # EconomyModule (future)
  ├── factory/           # FactoryModule (future)
  └── shared/            # Common interfaces
  

• CMake per-module autonomous builds

  • cd modules/X/ && cmake . builds independently
  • No parent directory dependencies
  • Module-specific CMakeLists.txt files

---

Phase 4: Module System Implementation 🚀

Hot-Reload System

• Module loader - Dynamic library loading (.so files)

  • File change detection
  • Safe unload/reload with state preservation
  • Error handling and rollback

• State preservation system

  • Implement getState()/setState() pattern
  • JSON state serialization
  • Seamless hot-reload without game interruption

Communication & Validation

• JSON communication pipeline

  • Message format standardization
  • Input/output validation
  • Error handling and logging

• Module integration testing

  • End-to-end communication tests
  • Performance validation (target <5s iteration cycle)
  • Hot-reload stress testing

---

Phase 5: World Generation System 🌍

DebugWorldGenModule (IMPLEMENTED IN PHASE 2)

• Already implemented as FIRST MODULE - See Phase 2 above
• Enhanced features (if needed after Phase 2 implementation)
  • Performance optimization
  • Extended terrain types
  • Resource balancing tweaks

Working World Generation

• Procedural terrain generation (based on docs/02-systems/map-system.md)

  • 218+ terrain elements implementation
  • Budget system (-10 to +10) for biome balance
  • Realistic geographical features

• Advanced resource placement

  • Geological realism for deposits
  • Economic balance considerations
  • Strategic resource distribution

• Infrastructure generation

  • Road networks and transport routes
  • Initial settlements and facilities
  • Regional specialization setup

Phase 6: Map System & Basic Client 🗺️

MapModule Implementation (ESSENTIAL SECOND MODULE)

• Map management system (200-300 lines max)

  • Terrain data management and chunk loading
  • Coordinate system and spatial queries
  • Resource location tracking
  • Map state persistence and hot-reload

• JSON interface for map operations

  • Input: {"type": "get_chunk", "coords": [x, y]}
  • Output: {"chunk_data": [...], "resources": [...], "terrain": [...]}

Basic Client Implementation

• Minimal rendering client

  • Display generated world from WorldGenModule
  • Show terrain and resource data from MapModule
  • Basic camera movement and zoom
  • Connection to module system via JSON

• ImGUI integration

  • ImGUI interface for development tools
  • Module status display and controls
  • Hot-reload visualization interface
  • Debug information panels
  • Performance metrics dashboard

Phase 7: Core Gameplay Modules 🎯

MacroEntityModule Implementation (THIRD MODULE)

• Macro entity management (200-300 lines max)

  • High-level entity tracking and coordination
  • Company/state/faction entity management
  • Macro-scale interactions and behaviors
  • Entity lifecycle and evolution

• JSON interface for macro entities

  • Input: {"type": "create_entity", "entity_type": "company", "config": {...}}
  • Output: {"entity_id": "comp_001", "status": "created", "properties": {...}}

• Integration with map system

  • Entity positioning and territorial control
  • Resource access and territorial claims
  • Influence zones and interaction ranges

Phase 8: Economic Systems 💰

EconomyModule Implementation (FOURTH MODULE - BAREBONE)

• Basic market system (200-300 lines max)

  • Simple supply/demand tracking
  • Basic price calculation (no complex dynamics initially)
  • Essential resource trading only
  • Foundation for future expansion

• JSON interface for basic operations

  • Input: {"type": "trade", "item": "steel", "quantity": 100, "action": "buy"}
  • Output: {"status": "executed", "price": 5.0, "total": 500.0}

• Minimal integration

  • Basic resource flow between entities
  • Simple trading mechanics
  • Foundation for complex features (Points 272-296 for later phases)

Phase 9: Player Systems 🎮

PlayerModule Implementation (FIFTH MODULE)

• Player entity management (200-300 lines max)

  • Player state tracking and persistence
  • Player actions and command processing
  • Inventory and resource management
  • Player-world interaction systems

• JSON interface for player operations

  • Input: {"type": "player_action", "action": "move", "target": [x, y]}
  • Output: {"status": "success", "new_position": [x, y], "resources_gathered": {...}}

• Integration with existing modules

  • Player interaction with map system
  • Player participation in economy
  • Player entity registration with MacroEntityModule

Phase 10: Local Map & Client Enhancement 🗺️🖥️

LocalMap Loading System

• Local map management (200-300 lines max)

  • Detailed local area loading around player
  • Higher resolution terrain and object data
  • Local resource and entity tracking
  • Smooth transitions between local and global map

• JSON interface for local map operations

  • Input: {"type": "load_local_area", "center": [x, y], "radius": 50}
  • Output: {"local_data": {...}, "entities": [...], "detailed_terrain": [...]}

Enhanced Client Features

• Local map rendering

  • Detailed local area visualization
  • Zoom levels and level-of-detail management
  • Local entity rendering and animation
  • Smooth camera transitions

• Advanced ImGUI interfaces

  • Local map debug tools
  • Entity inspection panels
  • Local area performance metrics
  • Map loading/unloading controls

• Client-Map integration

  • Efficient local data streaming
  • Background loading of adjacent areas
  • Memory management for map data
  • Performance optimization for rendering

Phase 11: Advanced Configuration ⚙️

Enhanced Configuration Features (POST-BASIC MODULES)

• Advanced configuration management

  • Hot-reload configuration changes during runtime
  • Configuration versioning and migration
  • Environment-specific configurations (dev/prod)
  • Configuration inheritance and overrides

• Configuration tooling

  • Configuration validation tools
  • Configuration documentation generation
  • Configuration diff and merge utilities
  • Configuration backup and restore

---

Development Guidelines

Module Constraints (CRITICAL)

• NEVER #include "../" or cmake ..
• JSON only communication between modules
• Build autonome: cd modules/X/ && cmake .
• 200-300 lines max per module (except ProductionModule: 500-800 lines)
• Hot-reload ready: Always implement getState()/setState()

Performance Targets

• V1 Client: 30+ fps
• V2 Client: 60+ fps
• V1 Server: 10+ players
• V2 Server: 100+ players
• Iteration cycle: <5 seconds (edit → reload → test)

Testing Strategy

• #ifdef TESTING validation in modules
• Standalone testing: Test modules without full engine
• AI-optimized: Simple tests for Claude Code development

---

Notes

• Architecture Status: Transitioning from 10 engines to modular system
• Documentation: See docs/01-architecture/architecture-modulaire.md for complete specification
• Claude Code Optimization: Each module = micro-context for AI development
• Exception: ProductionModule (Belt+Inserter+Factory) requires 500-800 lines for performance
• World Generation: Critical for testing - no initial world exists without DebugWorldGenModule
• World Gen Reference: Complete procedural generation system documented in docs/02-systems/map-system.md