bmad-method 5.1.3 → 6.0.0-alpha.0

package/src/modules/bmm/workflows/3-solutioning/templates/game-engine-web-guide.md

@@ -0,0 +1,528 @@
+# Web Game Engine Architecture Guide
+
+This guide provides web game engine-specific guidance (Phaser, PixiJS, Three.js, Babylon.js) for solution architecture generation.
+
+---
+
+## Web Game-Specific Questions
+
+### 1. Engine & Technology Selection
+
+**Ask:**
+
+- Which engine? (Phaser 3, PixiJS, Three.js, Babylon.js, custom Canvas/WebGL)
+- TypeScript or JavaScript?
+- Build tool? (Vite, Webpack, Rollup, Parcel)
+- Target platform(s)? (Desktop web, mobile web, PWA, Cordova/Capacitor wrapper)
+
+**Guidance:**
+
+- **Phaser 3**: Full-featured 2D game framework, great for beginners
+- **PixiJS**: 2D rendering library, more low-level than Phaser
+- **Three.js**: 3D graphics library, mature ecosystem
+- **Babylon.js**: Complete 3D game engine, WebXR support
+- **TypeScript**: Recommended for all web games (type safety, better tooling)
+- **Vite**: Modern, fast, HMR - best for development
+
+**Record ADR:** Engine selection and build tooling
+
+---
+
+### 2. Architecture Pattern
+
+**Ask:**
+
+- Scene-based architecture? (Phaser scenes, custom scene manager)
+- ECS (Entity Component System)? (Libraries: bitECS, ecsy)
+- State management? (Redux, Zustand, custom FSM)
+
+**Guidance:**
+
+- **Scene-based**: Natural for Phaser, good for level-based games
+- **ECS**: Better performance for large entity counts (100s+)
+- **FSM**: Good for simple state transitions (menu → game → gameover)
+
+**Phaser Pattern:**
+
+```typescript
+// MainMenuScene.ts
+export class MainMenuScene extends Phaser.Scene {
+  constructor() {
+    super({ key: 'MainMenu' });
+  }
+
+  create() {
+    this.add.text(400, 300, 'Main Menu', { fontSize: '32px' });
+
+    const startButton = this.add
+      .text(400, 400, 'Start Game', { fontSize: '24px' })
+      .setInteractive()
+      .on('pointerdown', () => {
+        this.scene.start('GameScene');
+      });
+  }
+}
+```
+
+**Record ADR:** Architecture pattern and scene management
+
+---
+
+### 3. Asset Management
+
+**Ask:**
+
+- Asset loading strategy? (Preload all, lazy load, progressive)
+- Texture atlas usage? (TexturePacker, built-in tools)
+- Audio format strategy? (MP3, OGG, WebM)
+
+**Guidance:**
+
+- **Preload**: Load all assets at start (simple, small games)
+- **Lazy load**: Load per-level (better for larger games)
+- **Texture atlases**: Essential for performance (reduce draw calls)
+- **Audio**: MP3 for compatibility, OGG for smaller size, use both
+
+**Phaser loading:**
+
+```typescript
+class PreloadScene extends Phaser.Scene {
+  preload() {
+    // Show progress bar
+    this.load.on('progress', (value: number) => {
+      console.log('Loading: ' + Math.round(value * 100) + '%');
+    });
+
+    // Load assets
+    this.load.atlas('sprites', 'assets/sprites.png', 'assets/sprites.json');
+    this.load.audio('music', ['assets/music.mp3', 'assets/music.ogg']);
+    this.load.audio('jump', ['assets/sfx/jump.mp3', 'assets/sfx/jump.ogg']);
+  }
+
+  create() {
+    this.scene.start('MainMenu');
+  }
+}
+```
+
+**Record ADR:** Asset loading and management strategy
+
+---
+
+## Web Game-Specific Architecture Sections
+
+### Performance Optimization
+
+**Web-specific considerations:**
+
+- **Object Pooling**: Mandatory for bullets, particles, enemies (avoid GC pauses)
+- **Sprite Batching**: Use texture atlases, minimize state changes
+- **Canvas vs WebGL**: WebGL for better performance (most games)
+- **Draw Call Reduction**: Batch similar sprites, use sprite sheets
+- **Memory Management**: Watch heap size, profile with Chrome DevTools
+
+**Object Pooling Pattern:**
+
+```typescript
+class BulletPool {
+  private pool: Bullet[] = [];
+  private scene: Phaser.Scene;
+
+  constructor(scene: Phaser.Scene, size: number) {
+    this.scene = scene;
+    for (let i = 0; i < size; i++) {
+      const bullet = new Bullet(scene);
+      bullet.setActive(false).setVisible(false);
+      this.pool.push(bullet);
+    }
+  }
+
+  spawn(x: number, y: number, velocityX: number, velocityY: number): Bullet | null {
+    const bullet = this.pool.find((b) => !b.active);
+    if (bullet) {
+      bullet.spawn(x, y, velocityX, velocityY);
+    }
+    return bullet || null;
+  }
+}
+```
+
+**Target Performance:**
+
+- **Desktop**: 60 FPS minimum
+- **Mobile**: 60 FPS (high-end), 30 FPS (low-end)
+- **Profile with**: Chrome DevTools Performance tab, Phaser Debug plugin
+
+---
+
+### Input Handling
+
+**Multi-input support:**
+
+```typescript
+class GameScene extends Phaser.Scene {
+  private cursors?: Phaser.Types.Input.Keyboard.CursorKeys;
+  private wasd?: { [key: string]: Phaser.Input.Keyboard.Key };
+
+  create() {
+    // Keyboard
+    this.cursors = this.input.keyboard?.createCursorKeys();
+    this.wasd = this.input.keyboard?.addKeys('W,S,A,D') as any;
+
+    // Mouse/Touch
+    this.input.on('pointerdown', (pointer: Phaser.Input.Pointer) => {
+      this.handleClick(pointer.x, pointer.y);
+    });
+
+    // Gamepad (optional)
+    this.input.gamepad?.on('down', (pad, button, index) => {
+      this.handleGamepadButton(button);
+    });
+  }
+
+  update() {
+    // Handle keyboard input
+    if (this.cursors?.left.isDown || this.wasd?.A.isDown) {
+      this.player.moveLeft();
+    }
+  }
+}
+```
+
+---
+
+### State Persistence
+
+**LocalStorage pattern:**
+
+```typescript
+interface GameSaveData {
+  level: number;
+  score: number;
+  playerStats: {
+    health: number;
+    lives: number;
+  };
+}
+
+class SaveManager {
+  private static SAVE_KEY = 'game_save_data';
+
+  static save(data: GameSaveData): void {
+    localStorage.setItem(this.SAVE_KEY, JSON.stringify(data));
+  }
+
+  static load(): GameSaveData | null {
+    const data = localStorage.getItem(this.SAVE_KEY);
+    return data ? JSON.parse(data) : null;
+  }
+
+  static clear(): void {
+    localStorage.removeItem(this.SAVE_KEY);
+  }
+}
+```
+
+---
+
+### Source Tree Structure
+
+**Phaser + TypeScript + Vite:**
+
+```
+project/
+├── public/              # Static assets
+│   ├── assets/
+│   │   ├── sprites/
+│   │   ├── audio/
+│   │   │   ├── music/
+│   │   │   └── sfx/
+│   │   └── fonts/
+│   └── index.html
+├── src/
+│   ├── main.ts         # Game initialization
+│   ├── config.ts       # Phaser config
+│   ├── scenes/         # Game scenes
+│   │   ├── PreloadScene.ts
+│   │   ├── MainMenuScene.ts
+│   │   ├── GameScene.ts
+│   │   └── GameOverScene.ts
+│   ├── entities/       # Game objects
+│   │   ├── Player.ts
+│   │   ├── Enemy.ts
+│   │   └── Bullet.ts
+│   ├── systems/        # Game systems
+│   │   ├── InputManager.ts
+│   │   ├── AudioManager.ts
+│   │   └── SaveManager.ts
+│   ├── utils/          # Utilities
+│   │   ├── ObjectPool.ts
+│   │   └── Constants.ts
+│   └── types/          # TypeScript types
+│       └── index.d.ts
+├── tests/              # Unit tests
+├── package.json
+├── tsconfig.json
+├── vite.config.ts
+└── README.md
+```
+
+---
+
+### Testing Strategy
+
+**Jest + TypeScript:**
+
+```typescript
+// Player.test.ts
+import { Player } from '../entities/Player';
+
+describe('Player', () => {
+  let player: Player;
+
+  beforeEach(() => {
+    // Mock Phaser scene
+    const mockScene = {
+      add: { sprite: jest.fn() },
+      physics: { add: { sprite: jest.fn() } },
+    } as any;
+
+    player = new Player(mockScene, 0, 0);
+  });
+
+  test('takes damage correctly', () => {
+    player.health = 100;
+    player.takeDamage(20);
+    expect(player.health).toBe(80);
+  });
+
+  test('dies when health reaches zero', () => {
+    player.health = 10;
+    player.takeDamage(20);
+    expect(player.alive).toBe(false);
+  });
+});
+```
+
+**E2E Testing:**
+
+- Playwright for browser automation
+- Cypress for interactive testing
+- Test game states, not individual frames
+
+---
+
+### Deployment & Build
+
+**Build for production:**
+
+```json
+// package.json scripts
+{
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "test": "jest"
+  }
+}
+```
+
+**Deployment targets:**
+
+- **Static hosting**: Netlify, Vercel, GitHub Pages, AWS S3
+- **CDN**: Cloudflare, Fastly for global distribution
+- **PWA**: Service worker for offline play
+- **Mobile wrapper**: Cordova or Capacitor for app stores
+
+**Optimization:**
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  build: {
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          phaser: ['phaser'], // Separate Phaser bundle
+        },
+      },
+    },
+    minify: 'terser',
+    terserOptions: {
+      compress: {
+        drop_console: true, // Remove console.log in prod
+      },
+    },
+  },
+});
+```
+
+---
+
+## Specialist Recommendations
+
+### Audio Designer
+
+**When needed:** Games with music, sound effects, ambience
+**Responsibilities:**
+
+- Web Audio API architecture
+- Audio sprite creation (combine sounds into one file)
+- Music loop management
+- Sound effect implementation
+- Audio performance on web (decode strategy)
+
+### Performance Optimizer
+
+**When needed:** Mobile web games, complex games
+**Responsibilities:**
+
+- Chrome DevTools profiling
+- Object pooling implementation
+- Draw call optimization
+- Memory management
+- Bundle size optimization
+- Network performance (asset loading)
+
+### Monetization Specialist
+
+**When needed:** F2P web games
+**Responsibilities:**
+
+- Ad network integration (Google AdSense, AdMob for web)
+- In-game purchases (Stripe, PayPal)
+- Analytics (Google Analytics, custom events)
+- A/B testing frameworks
+- Economy design
+
+### Platform Specialist
+
+**When needed:** Mobile wrapper apps (Cordova/Capacitor)
+**Responsibilities:**
+
+- Native plugin integration
+- Platform-specific performance tuning
+- App store submission
+- Device compatibility testing
+- Push notification setup
+
+---
+
+## Common Pitfalls
+
+1. **Not using object pooling** - Frequent instantiation causes GC pauses
+2. **Too many draw calls** - Use texture atlases and sprite batching
+3. **Loading all assets at once** - Causes long initial load times
+4. **Not testing on mobile** - Performance vastly different on phones
+5. **Ignoring bundle size** - Large bundles = slow load times
+6. **Not handling window resize** - Web games run in resizable windows
+7. **Forgetting audio autoplay restrictions** - Browsers block auto-play without user interaction
+
+---
+
+## Engine-Specific Patterns
+
+### Phaser 3
+
+```typescript
+const config: Phaser.Types.Core.GameConfig = {
+  type: Phaser.AUTO, // WebGL with Canvas fallback
+  width: 800,
+  height: 600,
+  physics: {
+    default: 'arcade',
+    arcade: { gravity: { y: 300 }, debug: false },
+  },
+  scene: [PreloadScene, MainMenuScene, GameScene, GameOverScene],
+};
+
+const game = new Phaser.Game(config);
+```
+
+### PixiJS
+
+```typescript
+const app = new PIXI.Application({
+  width: 800,
+  height: 600,
+  backgroundColor: 0x1099bb,
+});
+
+document.body.appendChild(app.view);
+
+const sprite = PIXI.Sprite.from('assets/player.png');
+app.stage.addChild(sprite);
+
+app.ticker.add((delta) => {
+  sprite.rotation += 0.01 * delta;
+});
+```
+
+### Three.js
+
+```typescript
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
+const renderer = new THREE.WebGLRenderer();
+
+renderer.setSize(window.innerWidth, window.innerHeight);
+document.body.appendChild(renderer.domElement);
+
+const geometry = new THREE.BoxGeometry();
+const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 });
+const cube = new THREE.Mesh(geometry, material);
+scene.add(cube);
+
+function animate() {
+  requestAnimationFrame(animate);
+  cube.rotation.x += 0.01;
+  renderer.render(scene, camera);
+}
+animate();
+```
+
+---
+
+## Key Architecture Decision Records
+
+### ADR Template for Web Games
+
+**ADR-XXX: [Title]**
+
+**Context:**
+What web game-specific issue are we solving?
+
+**Options:**
+
+1. Phaser 3 (full framework)
+2. PixiJS (rendering library)
+3. Three.js/Babylon.js (3D)
+4. Custom Canvas/WebGL
+
+**Decision:**
+We chose [Option X]
+
+**Web-specific Rationale:**
+
+- Engine features vs bundle size
+- Community and plugin ecosystem
+- TypeScript support
+- Performance on target devices (mobile web)
+- Browser compatibility
+- Development velocity
+
+**Consequences:**
+
+- Impact on bundle size (Phaser ~1.2MB gzipped)
+- Learning curve
+- Platform limitations
+- Plugin availability
+
+---
+
+_This guide is specific to web game engines. For native engines, see:_
+
+- game-engine-unity-guide.md
+- game-engine-godot-guide.md
+- game-engine-unreal-guide.md

package/src/modules/bmm/workflows/3-solutioning/templates/infrastructure-architecture.md

@@ -0,0 +1,66 @@
+# {{TITLE}} Architecture Document
+
+**Project:** {{project_name}}
+**Date:** {{date}}
+**Author:** {{user_name}}
+
+## Executive Summary
+
+{{executive_summary}}
+
+## 1. Technology Stack & Decisions
+
+### 1.1 Technology & Library Decision Table
+
+{{technology_table}}
+
+## 2. Architecture Overview
+
+{{architecture_overview}}
+
+## 3. Data Architecture
+
+{{data_architecture}}
+
+## 4. Component & Integration Overview
+
+{{component_overview}}
+
+## 5. Architecture Decision Records
+
+{{architecture_decisions}}
+
+## 6. Implementation Guidance
+
+{{implementation_guidance}}
+
+## 7. Proposed Source Tree
+
+```
+{{source_tree}}
+```
+
+## 8. Testing Strategy
+
+{{testing_strategy}}
+{{testing_specialist_section}}
+
+## 9. Deployment & Operations
+
+{{deployment_operations}}
+{{devops_specialist_section}}
+
+## 10. Security
+
+{{security}}
+{{security_specialist_section}}
+
+---
+
+## Specialist Sections
+
+{{specialist_sections_summary}}
+
+---
+
+_Generated using BMad Method Solution Architecture workflow_

package/src/modules/bmm/workflows/3-solutioning/templates/library-package-architecture.md

@@ -0,0 +1,66 @@
+# {{TITLE}} Architecture Document
+
+**Project:** {{project_name}}
+**Date:** {{date}}
+**Author:** {{user_name}}
+
+## Executive Summary
+
+{{executive_summary}}
+
+## 1. Technology Stack & Decisions
+
+### 1.1 Technology & Library Decision Table
+
+{{technology_table}}
+
+## 2. Architecture Overview
+
+{{architecture_overview}}
+
+## 3. Data Architecture
+
+{{data_architecture}}
+
+## 4. Component & Integration Overview
+
+{{component_overview}}
+
+## 5. Architecture Decision Records
+
+{{architecture_decisions}}
+
+## 6. Implementation Guidance
+
+{{implementation_guidance}}
+
+## 7. Proposed Source Tree
+
+```
+{{source_tree}}
+```
+
+## 8. Testing Strategy
+
+{{testing_strategy}}
+{{testing_specialist_section}}
+
+## 9. Deployment & Operations
+
+{{deployment_operations}}
+{{devops_specialist_section}}
+
+## 10. Security
+
+{{security}}
+{{security_specialist_section}}
+
+---
+
+## Specialist Sections
+
+{{specialist_sections_summary}}
+
+---
+
+_Generated using BMad Method Solution Architecture workflow_

package/src/modules/bmm/workflows/3-solutioning/templates/mobile-app-architecture.md

@@ -0,0 +1,66 @@
+# {{TITLE}} Architecture Document
+
+**Project:** {{project_name}}
+**Date:** {{date}}
+**Author:** {{user_name}}
+
+## Executive Summary
+
+{{executive_summary}}
+
+## 1. Technology Stack & Decisions
+
+### 1.1 Technology & Library Decision Table
+
+{{technology_table}}
+
+## 2. Architecture Overview
+
+{{architecture_overview}}
+
+## 3. Data Architecture
+
+{{data_architecture}}
+
+## 4. Component & Integration Overview
+
+{{component_overview}}
+
+## 5. Architecture Decision Records
+
+{{architecture_decisions}}
+
+## 6. Implementation Guidance
+
+{{implementation_guidance}}
+
+## 7. Proposed Source Tree
+
+```
+{{source_tree}}
+```
+
+## 8. Testing Strategy
+
+{{testing_strategy}}
+{{testing_specialist_section}}
+
+## 9. Deployment & Operations
+
+{{deployment_operations}}
+{{devops_specialist_section}}
+
+## 10. Security
+
+{{security}}
+{{security_specialist_section}}
+
+---
+
+## Specialist Sections
+
+{{specialist_sections_summary}}
+
+---
+
+_Generated using BMad Method Solution Architecture workflow_