appiq-solution 1.3.3 → 1.4.3

package/#Tools/APPIQ-METHOD/deployment/build/expansion-packs/bmad-2d-phaser-game-dev/data/development-guidelines.md

@@ -1,651 +0,0 @@
-# Game Development Guidelines
-
-## Overview
-
-This document establishes coding standards, architectural patterns, and development practices for 2D game development using Phaser 3 and TypeScript. These guidelines ensure consistency, performance, and maintainability across all game development stories.
-
-## TypeScript Standards
-
-### Strict Mode Configuration
-
-**Required tsconfig.json settings:**
-
-```json
-{
-  "compilerOptions": {
-    "strict": true,
-    "noImplicitAny": true,
-    "strictNullChecks": true,
-    "strictFunctionTypes": true,
-    "noImplicitReturns": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "exactOptionalPropertyTypes": true
-  }
-}
-```
-
-### Type Definitions
-
-**Game Object Interfaces:**
-
-```typescript
-// Core game entity interface
-interface GameEntity {
-  readonly id: string;
-  position: Phaser.Math.Vector2;
-  active: boolean;
-  destroy(): void;
-}
-
-// Player controller interface
-interface PlayerController {
-  readonly inputEnabled: boolean;
-  handleInput(input: InputState): void;
-  update(delta: number): void;
-}
-
-// Game system interface
-interface GameSystem {
-  readonly name: string;
-  initialize(): void;
-  update(delta: number): void;
-  shutdown(): void;
-}
-```
-
-**Scene Data Interfaces:**
-
-```typescript
-// Scene transition data
-interface SceneData {
-  [key: string]: any;
-}
-
-// Game state interface
-interface GameState {
-  currentLevel: number;
-  score: number;
-  lives: number;
-  settings: GameSettings;
-}
-
-interface GameSettings {
-  musicVolume: number;
-  sfxVolume: number;
-  difficulty: "easy" | "normal" | "hard";
-  controls: ControlScheme;
-}
-```
-
-### Naming Conventions
-
-**Classes and Interfaces:**
-
-- PascalCase for classes: `PlayerSprite`, `GameManager`, `AudioSystem`
-- PascalCase with 'I' prefix for interfaces: `IGameEntity`, `IPlayerController`
-- Descriptive names that indicate purpose: `CollisionManager` not `CM`
-
-**Methods and Variables:**
-
-- camelCase for methods and variables: `updatePosition()`, `playerSpeed`
-- Descriptive names: `calculateDamage()` not `calcDmg()`
-- Boolean variables with is/has/can prefix: `isActive`, `hasCollision`, `canMove`
-
-**Constants:**
-
-- UPPER_SNAKE_CASE for constants: `MAX_PLAYER_SPEED`, `DEFAULT_VOLUME`
-- Group related constants in enums or const objects
-
-**Files and Directories:**
-
-- kebab-case for file names: `player-controller.ts`, `audio-manager.ts`
-- PascalCase for scene files: `MenuScene.ts`, `GameScene.ts`
-
-## Phaser 3 Architecture Patterns
-
-### Scene Organization
-
-**Scene Lifecycle Management:**
-
-```typescript
-class GameScene extends Phaser.Scene {
-  private gameManager!: GameManager;
-  private inputManager!: InputManager;
-
-  constructor() {
-    super({ key: "GameScene" });
-  }
-
-  preload(): void {
-    // Load only scene-specific assets
-    this.load.image("player", "assets/player.png");
-  }
-
-  create(data: SceneData): void {
-    // Initialize game systems
-    this.gameManager = new GameManager(this);
-    this.inputManager = new InputManager(this);
-
-    // Set up scene-specific logic
-    this.setupGameObjects();
-    this.setupEventListeners();
-  }
-
-  update(time: number, delta: number): void {
-    // Update all game systems
-    this.gameManager.update(delta);
-    this.inputManager.update(delta);
-  }
-
-  shutdown(): void {
-    // Clean up resources
-    this.gameManager.destroy();
-    this.inputManager.destroy();
-
-    // Remove event listeners
-    this.events.off("*");
-  }
-}
-```
-
-**Scene Transitions:**
-
-```typescript
-// Proper scene transitions with data
-this.scene.start("NextScene", {
-  playerScore: this.playerScore,
-  currentLevel: this.currentLevel + 1,
-});
-
-// Scene overlays for UI
-this.scene.launch("PauseMenuScene");
-this.scene.pause();
-```
-
-### Game Object Patterns
-
-**Component-Based Architecture:**
-
-```typescript
-// Base game entity
-abstract class GameEntity extends Phaser.GameObjects.Sprite {
-  protected components: Map<string, GameComponent> = new Map();
-
-  constructor(scene: Phaser.Scene, x: number, y: number, texture: string) {
-    super(scene, x, y, texture);
-    scene.add.existing(this);
-  }
-
-  addComponent<T extends GameComponent>(component: T): T {
-    this.components.set(component.name, component);
-    return component;
-  }
-
-  getComponent<T extends GameComponent>(name: string): T | undefined {
-    return this.components.get(name) as T;
-  }
-
-  update(delta: number): void {
-    this.components.forEach((component) => component.update(delta));
-  }
-
-  destroy(): void {
-    this.components.forEach((component) => component.destroy());
-    this.components.clear();
-    super.destroy();
-  }
-}
-
-// Example player implementation
-class Player extends GameEntity {
-  private movement!: MovementComponent;
-  private health!: HealthComponent;
-
-  constructor(scene: Phaser.Scene, x: number, y: number) {
-    super(scene, x, y, "player");
-
-    this.movement = this.addComponent(new MovementComponent(this));
-    this.health = this.addComponent(new HealthComponent(this, 100));
-  }
-}
-```
-
-### System Management
-
-**Singleton Managers:**
-
-```typescript
-class GameManager {
-  private static instance: GameManager;
-  private scene: Phaser.Scene;
-  private gameState: GameState;
-
-  constructor(scene: Phaser.Scene) {
-    if (GameManager.instance) {
-      throw new Error("GameManager already exists!");
-    }
-
-    this.scene = scene;
-    this.gameState = this.loadGameState();
-    GameManager.instance = this;
-  }
-
-  static getInstance(): GameManager {
-    if (!GameManager.instance) {
-      throw new Error("GameManager not initialized!");
-    }
-    return GameManager.instance;
-  }
-
-  update(delta: number): void {
-    // Update game logic
-  }
-
-  destroy(): void {
-    GameManager.instance = null!;
-  }
-}
-```
-
-## Performance Optimization
-
-### Object Pooling
-
-**Required for High-Frequency Objects:**
-
-```typescript
-class BulletPool {
-  private pool: Bullet[] = [];
-  private scene: Phaser.Scene;
-
-  constructor(scene: Phaser.Scene, initialSize: number = 50) {
-    this.scene = scene;
-
-    // Pre-create bullets
-    for (let i = 0; i < initialSize; i++) {
-      const bullet = new Bullet(scene, 0, 0);
-      bullet.setActive(false);
-      bullet.setVisible(false);
-      this.pool.push(bullet);
-    }
-  }
-
-  getBullet(): Bullet | null {
-    const bullet = this.pool.find((b) => !b.active);
-    if (bullet) {
-      bullet.setActive(true);
-      bullet.setVisible(true);
-      return bullet;
-    }
-
-    // Pool exhausted - create new bullet
-    console.warn("Bullet pool exhausted, creating new bullet");
-    return new Bullet(this.scene, 0, 0);
-  }
-
-  releaseBullet(bullet: Bullet): void {
-    bullet.setActive(false);
-    bullet.setVisible(false);
-    bullet.setPosition(0, 0);
-  }
-}
-```
-
-### Frame Rate Optimization
-
-**Performance Monitoring:**
-
-```typescript
-class PerformanceMonitor {
-  private frameCount: number = 0;
-  private lastTime: number = 0;
-  private frameRate: number = 60;
-
-  update(time: number): void {
-    this.frameCount++;
-
-    if (time - this.lastTime >= 1000) {
-      this.frameRate = this.frameCount;
-      this.frameCount = 0;
-      this.lastTime = time;
-
-      if (this.frameRate < 55) {
-        console.warn(`Low frame rate detected: ${this.frameRate} FPS`);
-        this.optimizePerformance();
-      }
-    }
-  }
-
-  private optimizePerformance(): void {
-    // Reduce particle counts, disable effects, etc.
-  }
-}
-```
-
-**Update Loop Optimization:**
-
-```typescript
-// Avoid expensive operations in update loops
-class GameScene extends Phaser.Scene {
-  private updateTimer: number = 0;
-  private readonly UPDATE_INTERVAL = 100; // ms
-
-  update(time: number, delta: number): void {
-    // High-frequency updates (every frame)
-    this.updatePlayer(delta);
-    this.updatePhysics(delta);
-
-    // Low-frequency updates (10 times per second)
-    this.updateTimer += delta;
-    if (this.updateTimer >= this.UPDATE_INTERVAL) {
-      this.updateUI();
-      this.updateAI();
-      this.updateTimer = 0;
-    }
-  }
-}
-```
-
-## Input Handling
-
-### Cross-Platform Input
-
-**Input Abstraction:**
-
-```typescript
-interface InputState {
-  moveLeft: boolean;
-  moveRight: boolean;
-  jump: boolean;
-  action: boolean;
-  pause: boolean;
-}
-
-class InputManager {
-  private inputState: InputState = {
-    moveLeft: false,
-    moveRight: false,
-    jump: false,
-    action: false,
-    pause: false,
-  };
-
-  private keys!: { [key: string]: Phaser.Input.Keyboard.Key };
-  private pointer!: Phaser.Input.Pointer;
-
-  constructor(private scene: Phaser.Scene) {
-    this.setupKeyboard();
-    this.setupTouch();
-  }
-
-  private setupKeyboard(): void {
-    this.keys = this.scene.input.keyboard.addKeys("W,A,S,D,SPACE,ESC,UP,DOWN,LEFT,RIGHT");
-  }
-
-  private setupTouch(): void {
-    this.scene.input.on("pointerdown", this.handlePointerDown, this);
-    this.scene.input.on("pointerup", this.handlePointerUp, this);
-  }
-
-  update(): void {
-    // Update input state from multiple sources
-    this.inputState.moveLeft = this.keys.A.isDown || this.keys.LEFT.isDown;
-    this.inputState.moveRight = this.keys.D.isDown || this.keys.RIGHT.isDown;
-    this.inputState.jump = Phaser.Input.Keyboard.JustDown(this.keys.SPACE);
-    // ... handle touch input
-  }
-
-  getInputState(): InputState {
-    return { ...this.inputState };
-  }
-}
-```
-
-## Error Handling
-
-### Graceful Degradation
-
-**Asset Loading Error Handling:**
-
-```typescript
-class AssetManager {
-  loadAssets(): Promise<void> {
-    return new Promise((resolve, reject) => {
-      this.scene.load.on("filecomplete", this.handleFileComplete, this);
-      this.scene.load.on("loaderror", this.handleLoadError, this);
-      this.scene.load.on("complete", () => resolve());
-
-      this.scene.load.start();
-    });
-  }
-
-  private handleLoadError(file: Phaser.Loader.File): void {
-    console.error(`Failed to load asset: ${file.key}`);
-
-    // Use fallback assets
-    this.loadFallbackAsset(file.key);
-  }
-
-  private loadFallbackAsset(key: string): void {
-    // Load placeholder or default assets
-    switch (key) {
-      case "player":
-        this.scene.load.image("player", "assets/defaults/default-player.png");
-        break;
-      default:
-        console.warn(`No fallback for asset: ${key}`);
-    }
-  }
-}
-```
-
-### Runtime Error Recovery
-
-**System Error Handling:**
-
-```typescript
-class GameSystem {
-  protected handleError(error: Error, context: string): void {
-    console.error(`Error in ${context}:`, error);
-
-    // Report to analytics/logging service
-    this.reportError(error, context);
-
-    // Attempt recovery
-    this.attemptRecovery(context);
-  }
-
-  private attemptRecovery(context: string): void {
-    switch (context) {
-      case "update":
-        // Reset system state
-        this.reset();
-        break;
-      case "render":
-        // Disable visual effects
-        this.disableEffects();
-        break;
-      default:
-        // Generic recovery
-        this.safeShutdown();
-    }
-  }
-}
-```
-
-## Testing Standards
-
-### Unit Testing
-
-**Game Logic Testing:**
-
-```typescript
-// Example test for game mechanics
-describe("HealthComponent", () => {
-  let healthComponent: HealthComponent;
-
-  beforeEach(() => {
-    const mockEntity = {} as GameEntity;
-    healthComponent = new HealthComponent(mockEntity, 100);
-  });
-
-  test("should initialize with correct health", () => {
-    expect(healthComponent.currentHealth).toBe(100);
-    expect(healthComponent.maxHealth).toBe(100);
-  });
-
-  test("should handle damage correctly", () => {
-    healthComponent.takeDamage(25);
-    expect(healthComponent.currentHealth).toBe(75);
-    expect(healthComponent.isAlive()).toBe(true);
-  });
-
-  test("should handle death correctly", () => {
-    healthComponent.takeDamage(150);
-    expect(healthComponent.currentHealth).toBe(0);
-    expect(healthComponent.isAlive()).toBe(false);
-  });
-});
-```
-
-### Integration Testing
-
-**Scene Testing:**
-
-```typescript
-describe("GameScene Integration", () => {
-  let scene: GameScene;
-  let mockGame: Phaser.Game;
-
-  beforeEach(() => {
-    // Mock Phaser game instance
-    mockGame = createMockGame();
-    scene = new GameScene();
-  });
-
-  test("should initialize all systems", () => {
-    scene.create({});
-
-    expect(scene.gameManager).toBeDefined();
-    expect(scene.inputManager).toBeDefined();
-  });
-});
-```
-
-## File Organization
-
-### Project Structure
-
-```
-src/
-├── scenes/
-│   ├── BootScene.ts          # Initial loading and setup
-│   ├── PreloadScene.ts       # Asset loading with progress
-│   ├── MenuScene.ts          # Main menu and navigation
-│   ├── GameScene.ts          # Core gameplay
-│   └── UIScene.ts            # Overlay UI elements
-├── gameObjects/
-│   ├── entities/
-│   │   ├── Player.ts         # Player game object
-│   │   ├── Enemy.ts          # Enemy base class
-│   │   └── Collectible.ts    # Collectible items
-│   ├── components/
-│   │   ├── MovementComponent.ts
-│   │   ├── HealthComponent.ts
-│   │   └── CollisionComponent.ts
-│   └── ui/
-│       ├── Button.ts         # Interactive buttons
-│       ├── HealthBar.ts      # Health display
-│       └── ScoreDisplay.ts   # Score UI
-├── systems/
-│   ├── GameManager.ts        # Core game state management
-│   ├── InputManager.ts       # Cross-platform input handling
-│   ├── AudioManager.ts       # Sound and music system
-│   ├── SaveManager.ts        # Save/load functionality
-│   └── PerformanceMonitor.ts # Performance tracking
-├── utils/
-│   ├── ObjectPool.ts         # Generic object pooling
-│   ├── MathUtils.ts          # Game math helpers
-│   ├── AssetLoader.ts        # Asset management utilities
-│   └── EventBus.ts           # Global event system
-├── types/
-│   ├── GameTypes.ts          # Core game type definitions
-│   ├── UITypes.ts            # UI-related types
-│   └── SystemTypes.ts        # System interface definitions
-├── config/
-│   ├── GameConfig.ts         # Phaser game configuration
-│   ├── GameBalance.ts        # Game balance parameters
-│   └── AssetConfig.ts        # Asset loading configuration
-└── main.ts                   # Application entry point
-```
-
-## Development Workflow
-
-### Story Implementation Process
-
-1. **Read Story Requirements:**
-
-   - Understand acceptance criteria
-   - Identify technical requirements
-   - Review performance constraints
-
-2. **Plan Implementation:**
-
-   - Identify files to create/modify
-   - Consider component architecture
-   - Plan testing approach
-
-3. **Implement Feature:**
-
-   - Follow TypeScript strict mode
-   - Use established patterns
-   - Maintain 60 FPS performance
-
-4. **Test Implementation:**
-
-   - Write unit tests for game logic
-   - Test cross-platform functionality
-   - Validate performance targets
-
-5. **Update Documentation:**
-   - Mark story checkboxes complete
-   - Document any deviations
-   - Update architecture if needed
-
-### Code Review Checklist
-
-**Before Committing:**
-
-- [ ] TypeScript compiles without errors
-- [ ] All tests pass
-- [ ] Performance targets met (60 FPS)
-- [ ] No console errors or warnings
-- [ ] Cross-platform compatibility verified
-- [ ] Memory usage within bounds
-- [ ] Code follows naming conventions
-- [ ] Error handling implemented
-- [ ] Documentation updated
-
-## Performance Targets
-
-### Frame Rate Requirements
-
-- **Desktop**: Maintain 60 FPS at 1080p
-- **Mobile**: Maintain 60 FPS on mid-range devices, minimum 30 FPS on low-end
-- **Optimization**: Implement dynamic quality scaling when performance drops
-
-### Memory Management
-
-- **Total Memory**: Under 100MB for full game
-- **Per Scene**: Under 50MB per gameplay scene
-- **Asset Loading**: Progressive loading to stay under limits
-- **Garbage Collection**: Minimize object creation in update loops
-
-### Loading Performance
-
-- **Initial Load**: Under 5 seconds for game start
-- **Scene Transitions**: Under 2 seconds between scenes
-- **Asset Streaming**: Background loading for upcoming content
-
-These guidelines ensure consistent, high-quality game development that meets performance targets and maintains code quality across all implementation stories.