Node 20, installer improvements, agent improvements and Expansion Pack for game dev (#232)
* feat: add expansion pack installation system with game dev and infrastructure expansion packs - Added expansion pack discovery and installation to BMAD installer - Supports interactive and CLI installation of expansion packs - Expansion pack files install to destination root (.bmad-core) - Added game development expansion pack (.bmad-2d-phaser-game-dev) - Game designer, developer, and scrum master agents - Game-specific templates, tasks, workflows, and guidelines - Specialized for Phaser 3 + TypeScript development - Added infrastructure devops expansion pack (.bmad-infrastructure-devops) - Platform engineering agent and infrastructure templates - Expansion pack agents automatically integrate with IDE rules - Added list:expansions command and --expansion-packs CLI option 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com> * alpha expansion packs and installer update to support installing expansion packs optionally * node20 --------- Co-authored-by: Brian Madison <brianmadison@Brians-MacBook-Pro.local> Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Brian
@@ -0,0 +1,560 @@
|
||||
# {{Game Title}} Game Architecture Document
|
||||
|
||||
[[LLM: This template creates a comprehensive game architecture document specifically for Phaser 3 + TypeScript projects. This should provide the technical foundation for all game development stories and epics.
|
||||
|
||||
If available, review any provided documents: Game Design Document (GDD), Technical Preferences. This architecture should support all game mechanics defined in the GDD.]]
|
||||
|
||||
## Introduction
|
||||
|
||||
[[LLM: Establish the document's purpose and scope for game development]]
|
||||
|
||||
This document outlines the complete technical architecture for {{Game Title}}, a 2D game built with Phaser 3 and TypeScript. 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 60 FPS performance and cross-platform compatibility.
|
||||
|
||||
### Change Log
|
||||
|
||||
[[LLM: Track document versions and changes]]
|
||||
|
||||
| Date | Version | Description | Author |
|
||||
| :--- | :------ | :---------- | :----- |
|
||||
|
||||
## Technical Overview
|
||||
|
||||
[[LLM: Present all subsections together, then apply `tasks#advanced-elicitation` protocol to the complete section.]]
|
||||
|
||||
### Architecture Summary
|
||||
|
||||
[[LLM: Provide a comprehensive overview covering:
|
||||
|
||||
- Game engine choice and configuration
|
||||
- Project structure and organization
|
||||
- Key systems and their interactions
|
||||
- Performance and optimization strategy
|
||||
- How this architecture achieves GDD requirements]]
|
||||
|
||||
### Platform Targets
|
||||
|
||||
[[LLM: Based on GDD requirements, confirm platform support]]
|
||||
|
||||
**Primary Platform:** {{primary_platform}}
|
||||
**Secondary Platforms:** {{secondary_platforms}}
|
||||
**Minimum Requirements:** {{min_specs}}
|
||||
**Target Performance:** 60 FPS on {{target_device}}
|
||||
|
||||
### Technology Stack
|
||||
|
||||
**Core Engine:** Phaser 3.70+
|
||||
**Language:** TypeScript 5.0+ (Strict Mode)
|
||||
**Build Tool:** {{build_tool}} (Webpack/Vite/Parcel)
|
||||
**Package Manager:** {{package_manager}}
|
||||
**Testing:** {{test_framework}}
|
||||
**Deployment:** {{deployment_platform}}
|
||||
|
||||
## Project Structure
|
||||
|
||||
[[LLM: Define the complete project organization that developers will follow]]
|
||||
|
||||
### Repository Organization
|
||||
|
||||
[[LLM: Design a clear folder structure for game development]]
|
||||
|
||||
```text
|
||||
{{game_name}}/
|
||||
├── src/
|
||||
│ ├── scenes/ # Game scenes
|
||||
│ ├── gameObjects/ # Custom game objects
|
||||
│ ├── systems/ # Core game systems
|
||||
│ ├── utils/ # Utility functions
|
||||
│ ├── types/ # TypeScript type definitions
|
||||
│ ├── config/ # Game configuration
|
||||
│ └── main.ts # Entry point
|
||||
├── assets/
|
||||
│ ├── images/ # Sprite assets
|
||||
│ ├── audio/ # Sound files
|
||||
│ ├── data/ # JSON data files
|
||||
│ └── fonts/ # Font files
|
||||
├── public/ # Static web assets
|
||||
├── tests/ # Test files
|
||||
├── docs/ # Documentation
|
||||
│ ├── stories/ # Development stories
|
||||
│ └── architecture/ # Technical docs
|
||||
└── dist/ # Built game files
|
||||
```text
|
||||
|
||||
### Module Organization
|
||||
|
||||
[[LLM: Define how TypeScript modules should be organized]]
|
||||
|
||||
**Scene Structure:**
|
||||
|
||||
- Each scene in separate file
|
||||
- Scene-specific logic contained
|
||||
- Clear data passing between scenes
|
||||
|
||||
**Game Object Pattern:**
|
||||
|
||||
- Component-based architecture
|
||||
- Reusable game object classes
|
||||
- Type-safe property definitions
|
||||
|
||||
**System Architecture:**
|
||||
|
||||
- Singleton managers for global systems
|
||||
- Event-driven communication
|
||||
- Clear separation of concerns
|
||||
|
||||
## Core Game Systems
|
||||
|
||||
[[LLM: Detail each major system that needs to be implemented. Each system should be specific enough for developers to create implementation stories.]]
|
||||
|
||||
### Scene Management System
|
||||
|
||||
**Purpose:** Handle game flow and scene transitions
|
||||
|
||||
**Key Components:**
|
||||
|
||||
- Scene loading and unloading
|
||||
- Data passing between scenes
|
||||
- Transition effects
|
||||
- Memory management
|
||||
|
||||
**Implementation Requirements:**
|
||||
|
||||
- Preload scene for asset loading
|
||||
- Menu system with navigation
|
||||
- Gameplay scenes with state management
|
||||
- Pause/resume functionality
|
||||
|
||||
**Files to Create:**
|
||||
|
||||
- `src/scenes/BootScene.ts`
|
||||
- `src/scenes/PreloadScene.ts`
|
||||
- `src/scenes/MenuScene.ts`
|
||||
- `src/scenes/GameScene.ts`
|
||||
- `src/systems/SceneManager.ts`
|
||||
|
||||
### Game State Management
|
||||
|
||||
**Purpose:** Track player progress and game status
|
||||
|
||||
**State Categories:**
|
||||
|
||||
- Player progress (levels, unlocks)
|
||||
- Game settings (audio, controls)
|
||||
- Session data (current level, score)
|
||||
- Persistent data (achievements, statistics)
|
||||
|
||||
**Implementation Requirements:**
|
||||
|
||||
- Save/load system with localStorage
|
||||
- State validation and error recovery
|
||||
- Cross-session data persistence
|
||||
- Settings management
|
||||
|
||||
**Files to Create:**
|
||||
|
||||
- `src/systems/GameState.ts`
|
||||
- `src/systems/SaveManager.ts`
|
||||
- `src/types/GameData.ts`
|
||||
|
||||
### Asset Management System
|
||||
|
||||
**Purpose:** Efficient loading and management of game assets
|
||||
|
||||
**Asset Categories:**
|
||||
|
||||
- Sprite sheets and animations
|
||||
- Audio files and music
|
||||
- Level data and configurations
|
||||
- UI assets and fonts
|
||||
|
||||
**Implementation Requirements:**
|
||||
|
||||
- Progressive loading strategy
|
||||
- Asset caching and optimization
|
||||
- Error handling for failed loads
|
||||
- Memory management for large assets
|
||||
|
||||
**Files to Create:**
|
||||
|
||||
- `src/systems/AssetManager.ts`
|
||||
- `src/config/AssetConfig.ts`
|
||||
- `src/utils/AssetLoader.ts`
|
||||
|
||||
### Input Management System
|
||||
|
||||
**Purpose:** Handle all player input across platforms
|
||||
|
||||
**Input Types:**
|
||||
|
||||
- Keyboard controls
|
||||
- Mouse/pointer interaction
|
||||
- Touch gestures (mobile)
|
||||
- Gamepad support (optional)
|
||||
|
||||
**Implementation Requirements:**
|
||||
|
||||
- Input mapping and configuration
|
||||
- Touch-friendly mobile controls
|
||||
- Input buffering for responsive gameplay
|
||||
- Customizable control schemes
|
||||
|
||||
**Files to Create:**
|
||||
|
||||
- `src/systems/InputManager.ts`
|
||||
- `src/utils/TouchControls.ts`
|
||||
- `src/types/InputTypes.ts`
|
||||
|
||||
### Game Mechanics Systems
|
||||
|
||||
[[LLM: For each major mechanic defined in the GDD, create a system specification]]
|
||||
|
||||
<<REPEAT section="mechanic_system" count="based_on_gdd">>
|
||||
|
||||
#### {{mechanic_name}} System
|
||||
|
||||
**Purpose:** {{system_purpose}}
|
||||
|
||||
**Core Functionality:**
|
||||
|
||||
- {{feature_1}}
|
||||
- {{feature_2}}
|
||||
- {{feature_3}}
|
||||
|
||||
**Dependencies:** {{required_systems}}
|
||||
|
||||
**Performance Considerations:** {{optimization_notes}}
|
||||
|
||||
**Files to Create:**
|
||||
|
||||
- `src/systems/{{SystemName}}.ts`
|
||||
- `src/gameObjects/{{RelatedObject}}.ts`
|
||||
- `src/types/{{SystemTypes}}.ts`
|
||||
|
||||
<</REPEAT>>
|
||||
|
||||
### Physics & Collision System
|
||||
|
||||
**Physics Engine:** {{physics_choice}} (Arcade Physics/Matter.js)
|
||||
|
||||
**Collision Categories:**
|
||||
|
||||
- Player collision
|
||||
- Enemy interactions
|
||||
- Environmental objects
|
||||
- Collectibles and items
|
||||
|
||||
**Implementation Requirements:**
|
||||
|
||||
- Optimized collision detection
|
||||
- Physics body management
|
||||
- Collision callbacks and events
|
||||
- Performance monitoring
|
||||
|
||||
**Files to Create:**
|
||||
|
||||
- `src/systems/PhysicsManager.ts`
|
||||
- `src/utils/CollisionGroups.ts`
|
||||
|
||||
### Audio System
|
||||
|
||||
**Audio Requirements:**
|
||||
|
||||
- Background music with looping
|
||||
- Sound effects for actions
|
||||
- Audio settings and volume control
|
||||
- Mobile audio optimization
|
||||
|
||||
**Implementation Features:**
|
||||
|
||||
- Audio sprite management
|
||||
- Dynamic music system
|
||||
- Spatial audio (if applicable)
|
||||
- Audio pooling for performance
|
||||
|
||||
**Files to Create:**
|
||||
|
||||
- `src/systems/AudioManager.ts`
|
||||
- `src/config/AudioConfig.ts`
|
||||
|
||||
### UI System
|
||||
|
||||
**UI Components:**
|
||||
|
||||
- HUD elements (score, health, etc.)
|
||||
- Menu navigation
|
||||
- Modal dialogs
|
||||
- Settings screens
|
||||
|
||||
**Implementation Requirements:**
|
||||
|
||||
- Responsive layout system
|
||||
- Touch-friendly interface
|
||||
- Keyboard navigation support
|
||||
- Animation and transitions
|
||||
|
||||
**Files to Create:**
|
||||
|
||||
- `src/systems/UIManager.ts`
|
||||
- `src/gameObjects/UI/`
|
||||
- `src/types/UITypes.ts`
|
||||
|
||||
## Performance Architecture
|
||||
|
||||
[[LLM: Define performance requirements and optimization strategies]]
|
||||
|
||||
### Performance Targets
|
||||
|
||||
**Frame Rate:** 60 FPS sustained, 30 FPS minimum
|
||||
**Memory Usage:** <{{memory_limit}}MB total
|
||||
**Load Times:** <{{initial_load}}s initial, <{{level_load}}s per level
|
||||
**Battery Optimization:** Reduced updates when not visible
|
||||
|
||||
### Optimization Strategies
|
||||
|
||||
**Object Pooling:**
|
||||
|
||||
- Bullets and projectiles
|
||||
- Particle effects
|
||||
- Enemy objects
|
||||
- UI elements
|
||||
|
||||
**Asset Optimization:**
|
||||
|
||||
- Texture atlases for sprites
|
||||
- Audio compression
|
||||
- Lazy loading for large assets
|
||||
- Progressive enhancement
|
||||
|
||||
**Rendering Optimization:**
|
||||
|
||||
- Sprite batching
|
||||
- Culling off-screen objects
|
||||
- Reduced particle counts on mobile
|
||||
- Texture resolution scaling
|
||||
|
||||
**Files to Create:**
|
||||
|
||||
- `src/utils/ObjectPool.ts`
|
||||
- `src/utils/PerformanceMonitor.ts`
|
||||
- `src/config/OptimizationConfig.ts`
|
||||
|
||||
## Game Configuration
|
||||
|
||||
[[LLM: Define all configurable aspects of the game]]
|
||||
|
||||
### Phaser Configuration
|
||||
|
||||
```typescript
|
||||
// src/config/GameConfig.ts
|
||||
const gameConfig: Phaser.Types.Core.GameConfig = {
|
||||
type: Phaser.AUTO,
|
||||
width: {{game_width}},
|
||||
height: {{game_height}},
|
||||
scale: {
|
||||
mode: {{scale_mode}},
|
||||
autoCenter: Phaser.Scale.CENTER_BOTH
|
||||
},
|
||||
physics: {
|
||||
default: '{{physics_system}}',
|
||||
{{physics_system}}: {
|
||||
gravity: { y: {{gravity}} },
|
||||
debug: false
|
||||
}
|
||||
},
|
||||
// Additional configuration...
|
||||
};
|
||||
```text
|
||||
|
||||
### Game Balance Configuration
|
||||
|
||||
[[LLM: Based on GDD, define configurable game parameters]]
|
||||
|
||||
```typescript
|
||||
// src/config/GameBalance.ts
|
||||
export const GameBalance = {
|
||||
player: {
|
||||
speed: {{player_speed}},
|
||||
health: {{player_health}},
|
||||
// Additional player parameters...
|
||||
},
|
||||
difficulty: {
|
||||
easy: {{easy_params}},
|
||||
normal: {{normal_params}},
|
||||
hard: {{hard_params}}
|
||||
},
|
||||
// Additional balance parameters...
|
||||
};
|
||||
```
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
[[LLM: Provide coding standards specific to game development]]
|
||||
|
||||
### TypeScript Standards
|
||||
|
||||
**Type Safety:**
|
||||
|
||||
- Use strict mode
|
||||
- Define interfaces for all data structures
|
||||
- Avoid `any` type usage
|
||||
- Use enums for game states
|
||||
|
||||
**Code Organization:**
|
||||
|
||||
- One class per file
|
||||
- Clear naming conventions
|
||||
- Proper error handling
|
||||
- Comprehensive documentation
|
||||
|
||||
### Phaser 3 Best Practices
|
||||
|
||||
**Scene Management:**
|
||||
|
||||
- Clean up resources in shutdown()
|
||||
- Use scene data for communication
|
||||
- Implement proper event handling
|
||||
- Avoid memory leaks
|
||||
|
||||
**Game Object Design:**
|
||||
|
||||
- Extend Phaser classes appropriately
|
||||
- Use component-based architecture
|
||||
- Implement object pooling where needed
|
||||
- Follow consistent update patterns
|
||||
|
||||
### Testing Strategy
|
||||
|
||||
**Unit Testing:**
|
||||
|
||||
- Test game logic separately from Phaser
|
||||
- Mock Phaser dependencies
|
||||
- Test utility functions
|
||||
- Validate game balance calculations
|
||||
|
||||
**Integration Testing:**
|
||||
|
||||
- Scene loading and transitions
|
||||
- Save/load functionality
|
||||
- Input handling
|
||||
- Performance benchmarks
|
||||
|
||||
**Files to Create:**
|
||||
|
||||
- `tests/utils/GameLogic.test.ts`
|
||||
- `tests/systems/SaveManager.test.ts`
|
||||
- `tests/performance/FrameRate.test.ts`
|
||||
|
||||
## Deployment Architecture
|
||||
|
||||
[[LLM: Define how the game will be built and deployed]]
|
||||
|
||||
### Build Process
|
||||
|
||||
**Development Build:**
|
||||
|
||||
- Fast compilation
|
||||
- Source maps enabled
|
||||
- Debug logging active
|
||||
- Hot reload support
|
||||
|
||||
**Production Build:**
|
||||
|
||||
- Minified and optimized
|
||||
- Asset compression
|
||||
- Performance monitoring
|
||||
- Error tracking
|
||||
|
||||
### Deployment Strategy
|
||||
|
||||
**Web Deployment:**
|
||||
|
||||
- Static hosting ({{hosting_platform}})
|
||||
- CDN for assets
|
||||
- Progressive loading
|
||||
- Browser compatibility
|
||||
|
||||
**Mobile Packaging:**
|
||||
|
||||
- Cordova/Capacitor wrapper
|
||||
- Platform-specific optimization
|
||||
- App store requirements
|
||||
- Performance testing
|
||||
|
||||
## Implementation Roadmap
|
||||
|
||||
[[LLM: Break down the architecture implementation into phases that align with the GDD development phases]]
|
||||
|
||||
### Phase 1: Foundation ({{duration}})
|
||||
|
||||
**Core Systems:**
|
||||
|
||||
- Project setup and configuration
|
||||
- Basic scene management
|
||||
- Asset loading pipeline
|
||||
- Input handling framework
|
||||
|
||||
**Story Epics:**
|
||||
|
||||
- "Engine Setup and Configuration"
|
||||
- "Basic Scene Management System"
|
||||
- "Asset Loading Foundation"
|
||||
|
||||
### Phase 2: Game Systems ({{duration}})
|
||||
|
||||
**Gameplay Systems:**
|
||||
|
||||
- {{primary_mechanic}} implementation
|
||||
- Physics and collision system
|
||||
- Game state management
|
||||
- UI framework
|
||||
|
||||
**Story Epics:**
|
||||
|
||||
- "{{Primary_Mechanic}} System Implementation"
|
||||
- "Physics and Collision Framework"
|
||||
- "Game State Management System"
|
||||
|
||||
### Phase 3: Content & Polish ({{duration}})
|
||||
|
||||
**Content Systems:**
|
||||
|
||||
- Level loading and management
|
||||
- Audio system integration
|
||||
- Performance optimization
|
||||
- Final polish and testing
|
||||
|
||||
**Story Epics:**
|
||||
|
||||
- "Level Management System"
|
||||
- "Audio Integration and Optimization"
|
||||
- "Performance Optimization and Testing"
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
[[LLM: Identify potential technical risks and mitigation strategies]]
|
||||
|
||||
| Risk | Probability | Impact | Mitigation Strategy |
|
||||
| ---------------------------- | ----------- | ---------- | ------------------- |
|
||||
| Performance issues on mobile | {{prob}} | {{impact}} | {{mitigation}} |
|
||||
| Asset loading bottlenecks | {{prob}} | {{impact}} | {{mitigation}} |
|
||||
| Cross-platform compatibility | {{prob}} | {{impact}} | {{mitigation}} |
|
||||
|
||||
## Success Criteria
|
||||
|
||||
[[LLM: Define measurable technical success criteria]]
|
||||
|
||||
**Technical Metrics:**
|
||||
|
||||
- All systems implemented per specification
|
||||
- Performance targets met consistently
|
||||
- Zero critical bugs in core systems
|
||||
- Successful deployment across target platforms
|
||||
|
||||
**Code Quality:**
|
||||
|
||||
- 90%+ test coverage on game logic
|
||||
- Zero TypeScript errors in strict mode
|
||||
- Consistent adherence to coding standards
|
||||
- Comprehensive documentation coverage
|
||||
Reference in New Issue
Block a user