template: id: game-architecture-template-v3 name: Game Architecture Document version: 3.0 output: format: markdown filename: docs/game-architecture.md title: "{{project_name}} Game Architecture Document" workflow: mode: interactive elicitation: advanced-elicitation sections: - id: introduction title: Introduction instruction: | If available, review any provided relevant documents to gather all relevant context before beginning. At a minimum you should locate and review: Game Design Document (GDD), Technical Preferences. If these are not available, ask the user what docs will provide the basis for the game architecture. sections: - id: intro-content content: | This document outlines the complete technical architecture for {{project_name}}, a game built with Godot Engine and GDScript. It serves as the technical foundation for AI-driven game development, ensuring consistency and scalability across all game systems. This architecture is designed to support the gameplay mechanics defined in the Game Design Document while maintaining stable performance and cross-platform compatibility, whether the game is developed in 2D or 3D. - id: starter-template title: Starter Template or Existing Project instruction: | Before proceeding further with game architecture design, check if the project is based on a Godot template or existing codebase: 1. Review the GDD and brainstorming brief for any mentions of: - Godot project templates or demo projects - Existing Godot projects being used as a foundation - Asset Library packages or game development frameworks - Previous game projects to be cloned or adapted 2. If a starter template or existing project is mentioned: - Ask the user to provide access via one of these methods: - Link to the Godot demo project - Upload/attach the project files (for small projects) - Share a link to the project repository (GitHub, GitLab, etc.) - Analyze the starter/existing project to understand: - Pre-configured Godot version and renderer settings - Project structure and scene organization patterns - Built-in plugins and dependencies - Existing architectural patterns and conventions - Any limitations or constraints imposed by the starter - Use this analysis to inform and align your architecture decisions 3. If no starter template is mentioned but this is a greenfield project: - Suggest appropriate Godot project structure based on the target platform - Recommend relevant demo projects or learning resources - Consider Godot Asset Library resources for common game mechanics - id: target-platforms title: Target Platforms and Performance Requirements instruction: Analyze the GDD's platform requirements and establish technical baselines sections: - id: platform-overview title: Platform Overview instruction: | Based on the GDD, identify all target platforms for this game. For each platform, document: - Primary target devices (e.g., PC, Mobile, Web) - Minimum and recommended system specifications - Input methods (keyboard/mouse, touch, gamepad) - Distribution platforms (Steam, itch.io, mobile app stores, web) - Platform-specific requirements or constraints - id: performance-targets title: Performance Targets instruction: | Establish performance baselines for each target platform: - Frame rate targets (30fps minimum, 60fps target, etc.) - Memory usage limits per platform - Loading time requirements - Battery life considerations (mobile) - Network requirements (if multiplayer/online features) - id: godot-setup title: Godot Project Setup instruction: Define the foundational Godot project configuration sections: - id: godot-version title: Godot Version and Configuration instruction: | Document the Godot setup: - Godot version (recommend 4.4 for stability) - Renderer selection (Forward+ for desktop, Mobile for mobile/web) - Project settings configuration - Input map setup for target platforms - id: godot-project-structure title: Project Structure instruction: | Design a scalable project folder structure supporting both C# and GDScript: ``` project/ ├── scenes/ # Game scenes (.tscn files) │ ├── main/ # Main menu, settings, etc. │ ├── levels/ # Game levels and gameplay scenes │ ├── ui/ # UI components and HUD │ └── components/ # Reusable scene components ├── scripts/ # Script files (both languages) │ ├── gdscript/ # GDScript files (.gd) │ │ ├── autoload/ # GDScript singletons │ │ ├── components/ # Reusable components │ │ ├── player/ # Player-related scripts │ │ ├── enemies/ # Enemy behaviors │ │ ├── ui/ # UI controllers │ │ └── utils/ # Utility functions │ └── csharp/ # C# files (.cs) │ ├── Core/ # Core game systems │ ├── Managers/ # Singleton managers │ ├── Components/ # Reusable components │ ├── Player/ # Player systems │ ├── Enemies/ # Enemy systems │ ├── UI/ # UI controllers │ └── Utils/ # Utility classes ├── assets/ # Game assets │ ├── art/ # Visual assets for 2D games │ │ ├── sprites/ # Sprite sheets and images │ │ ├── animations/ # Animation resources │ │ ├── tilemaps/ # Tilemap resources │ │ ├── ui/ # UI graphics and icons │ │ ├── backgrounds/ # Background images │ │ ├── particles/ # Particle textures │ │ └── shaders/ # 2D shader files │ ├── audio/ # Music and sound effects │ │ ├── music/ # Background music │ │ ├── sfx/ # Sound effects │ │ └── ambient/ # Ambient sounds │ └── fonts/ # Font files ├── data/ # Game data files │ ├── resources/ # .tres resource files │ │ ├── items/ # Item definitions │ │ ├── enemies/ # Enemy data │ │ └── levels/ # Level data │ └── config/ # Configuration files ├── addons/ # Godot plugins and addons ├── tests/ # Unit and integration tests │ ├── unit/ # Unit tests │ │ ├── gdscript/ # GDScript tests (GUT) │ │ └── csharp/ # C# tests (GoDotTest) │ └── integration/ # Integration tests └── builds/ # Export templates and builds ├── windows/ # Windows builds ├── linux/ # Linux builds ├── macos/ # macOS builds ├── android/ # Android builds └── web/ # Web builds Additional files in root: - project.godot # Godot project file - .csproj # C# project file (if using C#) - .gitignore # Version control ignore file - README.md # Project documentation ``` Language Organization Guidelines: - Keep GDScript and C# code separated in their respective folders - Use consistent folder structure patterns within each language directory - GDScript follows snake_case for folder names - C# follows PascalCase for folder names - Scene files can reference scripts from either language - Prefer one language per system/feature for maintainability - id: core-architecture title: Core Game Architecture instruction: Design the fundamental system architecture following Godot best practices sections: - id: scene-architecture title: Scene Architecture instruction: | Design the scene hierarchy and organization: - Main scene structure and autoloads - Scene transition management - UI layer organization (CanvasLayer usage) - Scene instancing patterns for reusable components - id: node-patterns title: Node and Component Patterns instruction: | Establish patterns for game object architecture: - Component composition using child nodes - Signal-based communication patterns - Node group usage for categorization - Scene inheritance and variation patterns - id: singleton-systems title: Singleton Systems (AutoLoad) instruction: | Design singleton managers for global systems: - GameManager: Game state, scoring, level management - AudioManager: Music and sound effect management - SaveManager: Save/load game data - SceneManager: Scene transition handling - InputManager: Input handling and action management - id: gameplay-systems-architecture title: Gameplay Systems Architecture (2D) instruction: Design specific 2D game mechanics based on the GDD using Godot's 2D systems sections: - id: player-system-2d title: Player System (2D) instruction: | Design the 2D player character architecture: Scene Structure: ``` Player (CharacterBody2D or RigidBody2D) ├── CollisionShape2D (capsule or rectangle for character) ├── Sprite2D or AnimatedSprite2D │ └── AnimationPlayer (for complex animations) ├── Area2D (for interaction detection) │ └── CollisionShape2D (interaction radius) ├── StateMachine (Node) │ ├── IdleState │ ├── MoveState │ ├── JumpState │ └── AttackState ├── HealthComponent (Node) ├── AudioStreamPlayer2D (for player sounds) └── Marker2D nodes (for spawn points, weapon positions) ``` Movement Types (based on game genre): - Platformer: CharacterBody2D with move_and_slide() - Top-down: CharacterBody2D with velocity-based movement - Physics-based: RigidBody2D with forces/impulses - Grid-based: Position snapping with tweening Input Handling: - Input mapping configuration in Project Settings - Action-based input (jump, move_left, attack) - Analog stick support with dead zones - Touch input for mobile (virtual joystick/buttons) - id: camera-system-2d title: Camera System (2D) instruction: | Design the 2D camera system: Camera Setup: ``` Camera2D ├── Properties to configure: │ ├── enabled = true │ ├── anchor_mode = DRAG_CENTER │ ├── process_callback = PHYSICS │ ├── position_smoothing_enabled = true │ ├── position_smoothing_speed = 5.0 │ └── rotation_smoothing_enabled = false ├── Limits (for world boundaries) │ ├── limit_left │ ├── limit_top │ ├── limit_right │ └── limit_bottom └── Drag margins (for delayed following) ``` Camera Behaviors: - Follow player with smoothing - Look-ahead based on velocity/input - Screen shake for impacts/explosions - Zoom in/out for dramatic effects - Multi-target following (average position) - Room-based cameras (Metroidvania style) - Parallax background scrolling support - id: collision-system-2d title: Collision and Physics (2D) instruction: | Design the 2D collision system: Collision Layers and Masks: - Layer 1: Player - Layer 2: Enemies - Layer 3: Player projectiles - Layer 4: Enemy projectiles - Layer 5: Environment - Layer 6: Pickups - Layer 7: Triggers - Layer 8: One-way platforms Collision Detection Patterns: - Continuous collision detection for fast objects - Area2D for triggers and overlap detection - RayCast2D for line-of-sight and ground detection - ShapeCast2D for wide collision queries Physics Optimization: - Use simple shapes (rectangles, circles) when possible - Compound shapes only when necessary - Disable collision for off-screen objects - Use physics layers effectively to minimize checks - id: enemy-system-2d title: Enemy and AI System (2D) instruction: | Design 2D enemy architecture: Enemy Scene Structure: ``` Enemy (CharacterBody2D or RigidBody2D) ├── CollisionShape2D ├── Sprite2D or AnimatedSprite2D ├── Area2D (detection range) │ └── CollisionShape2D ├── NavigationAgent2D (for pathfinding) ├── StateMachine │ ├── PatrolState │ ├── ChaseState │ ├── AttackState │ └── StunnedState ├── HealthComponent ├── RayCast2D (for vision) └── AudioStreamPlayer2D ``` AI Patterns: - State-based behavior (FSM or behavior tree) - Navigation2D for pathfinding - Line-of-sight detection with RayCast2D - Steering behaviors (seek, flee, wander) - Group behaviors (flocking, formations) Performance Considerations: - LOD system for AI complexity - Disable AI for off-screen enemies - Object pooling for spawning - Batch AI updates across frames - id: combat-system-2d title: Combat System (2D) instruction: | Design 2D combat mechanics: Melee Combat: - Hitbox activation with Area2D - Attack animation timing - Combo system with input buffering - Knockback and hitstun - Invincibility frames (i-frames) Ranged Combat: - Projectile pooling system - Bullet patterns (for bullet-hell games) - Hitscan vs projectile physics - Ammunition management - id: level-system-2d title: Level and Environment System (2D) instruction: | Design 2D level architecture: TileMap System: ``` Level (Node2D) ├── TileMapLayer (terrain) ├── TileMapLayer (decorations) ├── TileMapLayer (collision) ├── Navigation2D │ └── NavigationRegion2D ├── Spawners (Node2D) │ ├── EnemySpawners │ └── ItemSpawners ├── Triggers (Node2D) │ └── Area2D nodes └── ParallaxBackground └── ParallaxLayer nodes ``` Level Features: - Autotiling for terrain - Collision layers from tilemap - Navigation mesh generation - Destructible terrain - Moving platforms - Environmental hazards - Interactive objects Level Loading: - Scene-based levels - Procedural generation - Chunk-based streaming - Level transitions and doors - id: particle-effects-2d title: Particle and Effects System (2D) instruction: | Design comprehensive 2D particle effects system using Godot best practices: Particle System Selection: ``` CPUParticles2D: - Best for: Simple effects, < 1000 particles - Advantages: No GPU requirement, per-particle collision - Use cases: Hit sparks, small explosions, pickups GPUParticles2D: - Best for: Complex effects, > 1000 particles - Advantages: GPU acceleration, better performance - Use cases: Rain, snow, large explosions, magic effects ``` Performance Best Practices: - Pool all particle systems - Disable particles outside camera view - Use LOD system for particle density - Batch similar effects together - Limit maximum concurrent effects - Use SubViewport for complex effects - Pre-warm particles with preprocess - Cache ParticleProcessMaterial resources - id: shader-guidelines title: Shader Guidelines for 2D Games instruction: | Design shader architecture following Godot best practices for 2D games: Shader Types and Usage: ``` CanvasItem Shaders (2D): - Used for: Sprite2D, Control nodes, TileMap - Features: vertex(), fragment(), light() - Best for: Most 2D effects Visual Shaders: - Node-based shader creation - Good for: Artists, prototyping - Limitation: Less optimized than code ``` Shader Performance Guidelines: - Minimize texture samples - Avoid branching (if/else) in shaders - Use hint_range for uniforms - Precompute values in vertex shader - Cache materials when possible - Batch draw calls with same shader - Use GPU-friendly math (avoid sin/cos when possible) - Profile with RenderingServer.get_rendering_info() - id: sprite-management title: Sprite Management and Optimization instruction: | Design sprite management system for 2D games in Godot: Sprite Organization: ``` assets/art/sprites/ ├── characters/ │ ├── player/ │ │ ├── idle.png (sprite sheet) │ │ ├── run.png │ │ └── player.tres (SpriteFrames resource) │ └── enemies/ │ └── enemy_sprites.png (atlas) ├── environment/ │ ├── tileset.png │ └── props_atlas.png └── ui/ └── ui_atlas.png ``` Sprite Optimization Techniques: - Use texture atlases to reduce draw calls - Enable texture filtering appropriately (nearest for pixel art) - Batch sprites with same material/shader - Use sprite pooling for frequently created/destroyed sprites - Implement LOD system for distant sprites - Disable sprites outside camera view - Use region_rect for atlas sprites - Compress textures appropriately (lossless for pixel art) - Power-of-two texture dimensions when possible - Z-index sorting for proper layering - Modulate instead of separate colored sprites - Cache SpriteFrames resources - id: ui-system-2d title: User Interface System (2D) instruction: | Design the 2D UI architecture: UI Scene Structure: ``` UI (CanvasLayer) ├── HUD (Control) │ ├── HealthBar (ProgressBar) │ ├── ScoreLabel (Label) │ ├── AmmoCounter (HBoxContainer) │ └── Minimap (SubViewport) ├── Menus (Control) │ ├── PauseMenu (PopupPanel) │ ├── InventoryMenu (Panel) │ └── DialogueBox (NinePatchRect) └── TouchControls (Control) ├── VirtualJoystick └── ActionButtons ``` UI Components: - Health/mana bars with tweening - Score and combo counters - Inventory grids - Dialogue system - Quest tracker - Notification system - Virtual controls for mobile UI Patterns: - Theme resources for consistent styling - Signal-based UI updates - UI animation with Tween - Responsive scaling for different resolutions - Input handling priority with mouse_filter - id: audio-system-2d title: Audio System (2D) instruction: | Design comprehensive 2D audio architecture using Godot best practices: Audio Bus Layout: ``` Master ├── Music (volume: -6db) │ ├── Reverb effect │ └── Compressor ├── SFX (volume: 0db) │ ├── Environment │ ├── Combat │ └── UI ├── Voice (volume: 0db) │ └── Compressor └── Ambient (volume: -12db) └── Low-pass filter ``` Best Practices: - Pool audio players to avoid allocations - Limit simultaneous sounds for performance - Use audio buses for organized mixing - Implement LOD for distant sounds - Crossfade music for smooth transitions - Pre-load frequently used sounds - Use .ogg for music, .wav for short SFX - Keep sample rates consistent (44.1kHz or 48kHz) - Compress audio appropriately - Disable audio players when not in use - id: game-mechanics-implementation title: Core Game Mechanics Implementation instruction: | Implement comprehensive game mechanics using Godot best practices. Best Practices: - Use object pooling for all spawnable mechanics - Pre-allocate arrays to avoid runtime allocations - Implement frame-spreading for expensive operations - Use Resources for data-driven design - Emit signals for loose coupling - Cache node references - Use groups for efficient queries - Implement proper cleanup methods - Profile performance regularly - Document complex mechanics thoroughly - id: data-management title: Data Management and Resources instruction: Design data architecture for game content and state using JSON serialization sections: - id: json-data-architecture title: JSON Data Architecture instruction: | Design JSON-based data management system: File Structure: ``` data/ ├── json/ # JSON data files │ ├── items/ # Item definitions │ │ ├── weapons.json │ │ ├── armor.json │ │ └── consumables.json │ ├── enemies/ # Enemy configurations │ │ └── enemy_data.json │ ├── levels/ # Level definitions │ │ ├── level_1.json │ │ └── level_metadata.json │ └── config/ # Game configuration │ ├── settings.json │ └── difficulty.json └── saves/ # Save game files ├── save_slot_1.json ├── save_slot_2.json └── save_slot_3.json ``` Performance Considerations: - Pre-parse JSON at startup for read-only data - Cache frequently accessed data in memory - Use streaming for large JSON files - Compress save files for smaller storage - Implement autosave with configurable intervals - Keep backup of previous save before overwriting - id: analytics-integration title: Analytics and Telemetry Integration instruction: Design analytics system for player behavior tracking and game metrics sections: - id: analytics-architecture title: Analytics Architecture Overview instruction: | Design comprehensive analytics system: Analytics Categories: - Player Behavior: Movement patterns, choices, playtime - Game Performance: FPS, load times, crashes - Monetization: Purchase events, ad views, conversion rates - Progression: Level completion, difficulty spikes, drop-off points - Social: Sharing, multiplayer engagement, friend invites Privacy Considerations: - GDPR compliance (EU) - COPPA compliance (children) - User consent management - Data anonymization - Opt-out mechanisms Recommended Services: - GameAnalytics (free tier available) - Unity Analytics (works with Godot via REST API) - Custom backend with Supabase/Firebase - Open-source: Matomo, Plausible - Steam Stats API (for Steam releases) Implementation guidelines: Event Naming Conventions: - Use snake_case for event names - Be consistent and descriptive - Group related events with prefixes - Examples: level_start, level_complete, ui_button_click Essential Events to Track: ``` // Core gameplay - session_start / session_end - level_start / level_complete / level_fail - tutorial_start / tutorial_complete / tutorial_skip // Monetization - purchase_initiated / purchase_complete / purchase_failed - ad_requested / ad_shown / ad_clicked / ad_skipped // Player progression - achievement_unlocked - level_up - item_acquired / item_used // Technical - error / crash - low_fps - long_load_time // Social - share_initiated / share_complete - friend_invited - multiplayer_match_start / multiplayer_match_end ``` Performance Considerations: - Batch events to reduce network calls - Use background threads for sending - Implement retry logic with exponential backoff - Store events locally if offline - Limit event properties size - Sample high-frequency events Privacy Requirements: - Always get user consent before tracking - Provide clear opt-out mechanism - Anonymize user data - Don't track PII without explicit consent - Implement data retention policies - Support data deletion requests (GDPR) - id: multiplayer-architecture title: Multiplayer and Networking Architecture instruction: Design multiplayer systems for networked gameplay sections: - id: multiplayer-overview title: Multiplayer Architecture Overview instruction: | Design networking architecture: Network Topologies: - Peer-to-Peer (P2P): Direct connections, good for small groups - Client-Server: Authoritative server, prevents cheating - Relay-based: Using services like Steam Relay, Photon - Hybrid: P2P with relay fallback Godot Networking Options: - Built-in MultiplayerAPI (ENet-based) - WebRTC for browser-based multiplayer - WebSocket for real-time communication - Steam Networking (via GodotSteam) - Third-party: Nakama, Photon, Mirror Architecture Patterns: - Authoritative server with client prediction - Lag compensation and interpolation - State synchronization - Rollback netcode (for fighting games) - Deterministic lockstep (for RTS) Network Optimization: - Use unreliable for frequent updates (position) - Use reliable for important events (damage, items) - Implement delta compression - Send only changed values - Use bit packing for booleans - Implement interest management (culling) Anti-Cheat Measures: - Server authoritative gameplay - Validate all client inputs - Implement speed hack detection - Use server-side physics - Encrypt sensitive data - Implement rate limiting Lag Compensation: - Client-side prediction - Server reconciliation - Interpolation for smooth movement - Extrapolation for high latency - Lag compensation for hit detection - Rollback and replay for fighting games Scalability: - Use dedicated servers for competitive games - Implement matchmaking and lobbies - Regional server distribution - Load balancing - Database for persistent data - Consider cloud services (AWS GameLift, Google Cloud Game Servers) Testing Strategies: - Simulate network conditions (latency, packet loss) - Bot players for testing - Stress testing with multiple clients - Cross-platform testing - Network profiling tools - id: performance-optimization title: Performance Optimization Strategy instruction: Plan for performance from the architecture level sections: - id: rendering-optimization title: Rendering and Graphics Optimization instruction: | Design for optimal rendering performance: - Texture management and compression - Sprite batching and draw call optimization - Particle system usage and limits - Camera and viewport optimization - id: memory-management title: Memory Management instruction: | Plan memory usage and optimization: - Object pooling for frequently created objects - Resource loading and unloading strategies - Garbage collection optimization - Memory profiling and monitoring - id: cpu-optimization title: CPU Optimization instruction: | Design for CPU performance: - Process scheduling (_process vs _physics_process) - Signal vs polling patterns - Multithreading considerations - Performance profiling integration - id: platform-specific title: Platform-Specific Considerations instruction: Address platform-specific requirements and optimizations sections: - id: mobile-optimization title: Mobile Platform Optimization instruction: | If targeting mobile platforms: - Touch input handling and UI scaling - Battery life optimization - Performance scaling for different devices - App lifecycle management (pause/resume) - id: web-deployment title: Web Platform Considerations instruction: | If targeting web deployment: - File size optimization and streaming - Browser compatibility considerations - Input handling for web browsers - Loading screen and progress indicators - id: testing-architecture title: Testing and Quality Assurance instruction: Design comprehensive TDD-driven testing architecture sections: - id: tdd-philosophy title: Test-Driven Development Approach instruction: | Establish TDD as the core development methodology: - Write tests BEFORE implementation code - Red-Green-Refactor cycle for all features - Tests define the specification and API design - Maintain test coverage goals: - Core game logic: 90% minimum - Utility functions: 100% coverage - UI: Critical path automation tests - Performance: All hot paths tested Test Pyramid Structure: 1. Unit Tests (70%) - Fast, isolated logic tests 2. Integration Tests (20%) - System interaction tests 3. UI/E2E Tests (10%) - Critical user path validation - id: testing-structure title: Test Organization and Structure instruction: | Define dual testing strategy for both languages: For C# Projects: ``` tests/ ├── unit/ # Pure C# unit tests │ ├── Core/ # Core game logic tests │ ├── Utils/ # Utility function tests │ └── Performance/ # Zero-allocation tests ├── integration/ # Godot integration tests │ ├── Systems/ # Game system tests │ ├── UI/ # UI automation tests │ └── Scenes/ # Scene loading tests └── fixtures/ # Test data and mocks └── TestData.cs # Pre-allocated test buffers ``` For GDScript Projects: ``` tests/ ├── unit/ # GUT unit tests │ ├── core/ # Core game logic tests │ ├── utils/ # Utility function tests │ └── components/ # Component tests ├── integration/ # Scene integration tests │ ├── systems/ # Game system tests │ ├── ui/ # UI automation tests │ └── scenes/ # Scene loading tests └── fixtures/ # Test data and resources └── test_data.gd # Test resource files ``` - id: unit-testing-strategy title: Unit Testing Strategy instruction: | Design unit testing approach for both languages: C# Unit Testing (Performance-First): - Use custom test runner (avoid standard dotnet test) - Zero-allocation testing patterns: ```csharp // Pre-allocated buffers for tests private readonly Vector2I[] _neighborBuffer = new Vector2I[6]; private readonly Unit[] _unitBuffer = new Unit[100]; [Test] public void TestHexNeighbors_ZeroAllocation() { HexUtils.GetNeighbors(hex, _neighborBuffer); Assert.AreEqual(expected, _neighborBuffer[0]); } ``` - Performance requirements: - Zero allocations during test execution - Test execution < 10ms per test - No LINQ, reflection, or dynamic allocations - Use stackalloc for temporary buffers GDScript Unit Testing (GUT Framework): - Test file naming: test_*.gd - Test method naming: test_*() - Pre-allocated test data: ```gdscript var _test_buffer := [] var _unit_pool := [] func before_all(): # Pre-allocate test resources _test_buffer.resize(100) for i in 100: _unit_pool.append(Unit.new()) func test_hex_distance(): var hex1 = Vector2i(10, 10) var hex2 = Vector2i(12, 11) assert_eq(HexUtils.get_distance(hex1, hex2), 2) ``` - id: integration-testing title: Integration Testing Strategy instruction: | Design Godot integration testing for C# (GoDotTest + GodotTestDriver) or GDScript (GUT Scene Testing). - id: performance-testing title: Performance and Allocation Testing instruction: | Design performance validation tests in preferred language. - id: ui-automation title: UI Automation Testing instruction: | Design UI testing strategy: For C# (GodotTestDriver): - Button interactions - Text input simulation - Tab/menu navigation - Mouse/touch input - Drag and drop testing For GDScript (Input Simulation): - Create input events programmatically - Test signal emissions - Verify UI state changes - Test scene transitions - id: test-runners title: Test Execution and Runners instruction: | Configure test execution: C# Test Execution: ```bash # Unit tests (custom runner for zero-allocation) ./run_tests.sh --unit # Integration tests (Godot headless) godot --headless --script tests/TestRunner.cs # Performance tests ./run_tests.sh --performance --release ``` GDScript Test Execution: ```bash # Run all GUT tests godot --headless -s addons/gut/gut_cmdln.gd # Run specific test suite godot --headless -s addons/gut/gut_cmdln.gd -gtest=tests/unit/test_*.gd # Run with coverage godot --headless -s addons/gut/gut_cmdln.gd -gcoverage ``` - id: ci-integration title: Continuous Integration Pipeline instruction: | Design automated testing pipeline using GitHub CI/CD. - id: test-data-management title: Test Data and Fixtures instruction: | Design test data strategy: - Pre-allocated buffers for zero-allocation testing - Reusable test scenes and resources - Mock data generators - Test-specific Resource files (.tres) - Deterministic random seeds for reproducible tests - id: debugging-tools title: Debugging and Development Tools instruction: | Plan development and debugging support: - Debug overlay UI showing: - FPS and frame time - Memory allocation tracking - Active object counts - Performance metrics - Console commands for testing: - Spawn test entities - Trigger game states - Load test scenarios - Logging system: - Structured logging with levels - Performance event tracking - Error aggregation - Development cheats: - God mode - Resource manipulation - Time control - State inspection - id: deployment-architecture title: Deployment and Distribution instruction: Plan build and deployment strategy sections: - id: build-pipeline title: Build Pipeline instruction: | Design the build and export process: - Export templates and configurations - Asset optimization pipeline - Platform-specific build settings - Version management and tagging - id: distribution-strategy title: Distribution Strategy instruction: | Plan distribution approach: - Target distribution platforms - Update and patching strategy - Analytics and telemetry integration - User feedback collection systems - id: development-standards title: Development Standards and Guidelines instruction: Establish coding and development standards sections: - id: coding-standards title: Coding Standards instruction: | These standards are MANDATORY for AI agents. Work with user to define ONLY the critical rules needed to prevent bad code. Explain that: 1. This section directly controls AI developer behavior 2. Keep it minimal - assume AI knows general best practices 3. Focus on project-specific conventions and gotchas 4. Overly detailed standards bloat context and slow development 5. Standards will be extracted to separate file for dev agent use For each standard, get explicit user confirmation it's necessary. elicit: true sections: - id: core-standards title: Core Standards template: | - **Languages & Runtimes:** {{languages_and_versions}} - **Style & Linting:** {{linter_config}} - **Test Organization:** {{test_file_convention}} - id: naming-conventions title: Naming Conventions type: table columns: [Element, Convention (C#), Convention (GDScript), Example] instruction: | Define naming conventions for both C# and GDScript. Default conventions: C# Naming: - Methods: PascalCase - Public Properties: PascalCase - Private Fields: _camelCase (underscore prefix) - Local Variables: camelCase - Constants: PascalCase - Interfaces: IPascalCase (avoid unless necessary) GDScript Naming (Godot style guide): - Functions: snake_case - Properties/Variables: snake_case - Private members: _snake_case (underscore prefix) - Constants: UPPER_SNAKE_CASE - Signals: snake_case - Enums: PascalCase, members: UPPER_SNAKE_CASE - id: critical-rules title: Critical Rules instruction: | List ONLY rules that AI might violate or project-specific requirements. Examples: - "Never use console.log in production code - use logger" - "All API responses must use ApiResponse wrapper type" - "Database queries must use repository pattern, never direct ORM" Avoid obvious rules like "use SOLID principles" or "write clean code" repeatable: true template: "- **{{rule_name}}:** {{rule_description}}" - id: performance-patterns title: Performance-Critical Patterns instruction: | Define performance requirements if this is a performance-sensitive game: For C#: - Pre-allocate all buffers and arrays - Reuse collections with Clear() instead of new - Pass arrays as parameters to fill, don't return new ones - Use stackalloc for small temporary buffers - AVOID: LINQ (causes allocations), var for collections, unnecessary interfaces, reflection For GDScript: - Pre-allocate arrays when size is known - Reuse objects from object pools for frequently created/destroyed items - Use typed arrays when possible (Array[Type]) - Cache node references instead of repeated get_node() calls - Prefer signals over polling in _process() - Use _physics_process() for physics-related code condition: Performance-sensitive game - id: language-specifics title: Language-Specific Guidelines condition: Critical language-specific rules needed instruction: Add ONLY if critical for preventing AI mistakes. Most teams don't need this section. sections: - id: csharp-rules title: C# Specific Rules condition: Using C# for scripting instruction: | Critical C# patterns for Godot development: - Use Godot types (Vector2I, Color) instead of System types - Prefer GD.Print for logging - Handle signals with direct connections, not C# events - Use [Export] for editor-visible properties - Always use explicit types, never var for collections - Mark allocation points with // ALLOC: comment if unavoidable - Use // PERF: comments for performance-sensitive sections repeatable: true template: "- **{{rule_topic}}:** {{rule_detail}}" - id: gdscript-rules title: GDScript Specific Rules condition: Using GDScript instruction: | Critical GDScript patterns: - Use @export for editor-visible properties - Prefer typed variables (var name: Type) for better performance - Use @onready for node references - Avoid creating nodes in _process() or _physics_process() - Use match statements instead of long if-elif chains - Prefer Resource classes for data structures - Use await for coroutines instead of yield (Godot 4.x) repeatable: true template: "- **{{rule_topic}}:** {{rule_detail}}" - id: scene-standards title: Scene Organization Standards instruction: | Define scene creation standards: - Node naming conventions - Scene composition patterns - Signal connection standards - Resource usage guidelines - id: risk-assessment title: Risk Assessment and Mitigation instruction: Identify and plan for potential technical risks sections: - id: technical-risks title: Technical Risk Analysis instruction: | Identify potential risks: - Performance bottlenecks and scalability limits - Platform compatibility issues - Third-party dependency risks - Team skill gaps and learning curves - id: mitigation-strategies title: Risk Mitigation Strategies instruction: | Plan mitigation approaches: - Prototype critical systems early - Performance testing milestones - Fallback plans for complex features - Knowledge sharing and documentation - id: implementation-roadmap title: Implementation Roadmap instruction: Create development phases and priorities sections: - id: development-phases title: Development Phase Planning instruction: | Break down implementation into phases: - Phase 1: Core systems and foundation - Phase 2: Gameplay mechanics implementation - Phase 3: Content creation and level building - Phase 4: Polish, optimization, and testing - id: story-breakdown title: Story Breakdown Guidance instruction: | Provide guidance for breaking this architecture into implementation stories: - Recommended story size and scope - Dependencies between architectural components - Testing requirements for each story - Integration points and validation criteria