fix: dist bundles updated

This commit is contained in:
Brian Madison
2025-06-19 17:12:38 -05:00
parent bbcc30ac29
commit d9a989dbe5
17 changed files with 761 additions and 386 deletions

View File

@@ -290,7 +290,7 @@ This architecture is designed to support the gameplay mechanics defined in the G
│ ├── stories/ # Development stories
│ └── architecture/ # Technical docs
└── dist/ # Built game files
```text
```
### Module Organization
@@ -575,7 +575,7 @@ const gameConfig: Phaser.Types.Core.GameConfig = {
},
// Additional configuration...
};
```text
```
### Game Balance Configuration
@@ -776,6 +776,7 @@ export const GameBalance = {
## Story Completeness
### Basic Story Elements
- [ ] **Story Title** - Clear, descriptive title that identifies the feature
- [ ] **Epic Assignment** - Story is properly assigned to relevant epic
- [ ] **Priority Level** - Appropriate priority assigned (High/Medium/Low)
@@ -783,6 +784,7 @@ export const GameBalance = {
- [ ] **Description** - Clear, concise description of what needs to be implemented
### Game Design Alignment
- [ ] **GDD Reference** - Specific Game Design Document section referenced
- [ ] **Game Mechanic Context** - Clear connection to game mechanics defined in GDD
- [ ] **Player Experience Goal** - Describes the intended player experience
@@ -792,6 +794,7 @@ export const GameBalance = {
## Technical Specifications
### Architecture Compliance
- [ ] **File Organization** - Follows game architecture document structure
- [ ] **Class Definitions** - TypeScript interfaces and classes are properly defined
- [ ] **Integration Points** - Clear specification of how feature integrates with existing systems
@@ -799,6 +802,7 @@ export const GameBalance = {
- [ ] **Dependencies** - All system dependencies clearly identified
### Phaser 3 Requirements
- [ ] **Scene Integration** - Specifies which scenes are affected and how
- [ ] **Game Object Usage** - Proper use of Phaser 3 game objects and components
- [ ] **Physics Integration** - Physics requirements specified if applicable
@@ -806,6 +810,7 @@ export const GameBalance = {
- [ ] **Performance Considerations** - 60 FPS target and optimization requirements
### Code Quality Standards
- [ ] **TypeScript Strict Mode** - All code must comply with strict TypeScript
- [ ] **Error Handling** - Error scenarios and handling requirements specified
- [ ] **Memory Management** - Object pooling and cleanup requirements where needed
@@ -815,6 +820,7 @@ export const GameBalance = {
## Implementation Readiness
### Acceptance Criteria
- [ ] **Functional Requirements** - All functional acceptance criteria are specific and testable
- [ ] **Technical Requirements** - Technical acceptance criteria are complete and verifiable
- [ ] **Game Design Requirements** - Game-specific requirements match GDD specifications
@@ -822,6 +828,7 @@ export const GameBalance = {
- [ ] **Completeness** - No acceptance criteria are vague or unmeasurable
### Implementation Tasks
- [ ] **Task Breakdown** - Story broken into specific, ordered implementation tasks
- [ ] **Task Scope** - Each task is completable in 1-4 hours
- [ ] **Task Clarity** - Each task has clear, actionable instructions
@@ -829,6 +836,7 @@ export const GameBalance = {
- [ ] **Development Flow** - Tasks follow logical implementation order
### Dependencies
- [ ] **Story Dependencies** - All prerequisite stories identified with IDs
- [ ] **Technical Dependencies** - Required systems and files identified
- [ ] **Asset Dependencies** - All needed assets specified with locations
@@ -838,6 +846,7 @@ export const GameBalance = {
## Testing Requirements
### Test Coverage
- [ ] **Unit Test Requirements** - Specific unit test files and scenarios defined
- [ ] **Integration Test Cases** - Integration testing with other game systems specified
- [ ] **Manual Test Cases** - Game-specific manual testing procedures defined
@@ -845,6 +854,7 @@ export const GameBalance = {
- [ ] **Edge Case Testing** - Edge cases and error conditions covered
### Test Implementation
- [ ] **Test File Paths** - Exact test file locations specified
- [ ] **Test Scenarios** - All test scenarios are complete and executable
- [ ] **Expected Behaviors** - Clear expected outcomes for all tests defined
@@ -854,6 +864,7 @@ export const GameBalance = {
## Game-Specific Quality
### Gameplay Implementation
- [ ] **Mechanic Accuracy** - Implementation matches GDD mechanic specifications
- [ ] **Player Controls** - Input handling requirements are complete
- [ ] **Game Feel** - Requirements for juice, feedback, and responsiveness specified
@@ -861,6 +872,7 @@ export const GameBalance = {
- [ ] **State Management** - Game state changes and persistence requirements defined
### User Experience
- [ ] **UI Requirements** - User interface elements and behaviors specified
- [ ] **Audio Integration** - Sound effect and music requirements defined
- [ ] **Visual Feedback** - Animation and visual effect requirements specified
@@ -868,6 +880,7 @@ export const GameBalance = {
- [ ] **Error Recovery** - User-facing error handling and recovery specified
### Performance Optimization
- [ ] **Frame Rate Targets** - Specific FPS requirements for different platforms
- [ ] **Memory Usage** - Memory consumption limits and monitoring requirements
- [ ] **Asset Optimization** - Texture, audio, and data optimization requirements
@@ -877,6 +890,7 @@ export const GameBalance = {
## Documentation and Communication
### Story Documentation
- [ ] **Implementation Notes** - Additional context and implementation guidance provided
- [ ] **Design Decisions** - Key design choices documented with rationale
- [ ] **Future Considerations** - Potential future enhancements or modifications noted
@@ -884,6 +898,7 @@ export const GameBalance = {
- [ ] **Reference Materials** - Links to relevant GDD sections and architecture docs
### Developer Handoff
- [ ] **Immediate Actionability** - Developer can start implementation without additional questions
- [ ] **Complete Context** - All necessary context provided within the story
- [ ] **Clear Boundaries** - What is and isn't included in the story scope is clear
@@ -893,6 +908,7 @@ export const GameBalance = {
## Final Validation
### Story Readiness
- [ ] **No Ambiguity** - No sections require interpretation or additional design decisions
- [ ] **Technical Completeness** - All technical requirements are specified and actionable
- [ ] **Scope Appropriateness** - Story scope matches assigned story points
@@ -900,6 +916,7 @@ export const GameBalance = {
- [ ] **Review Completion** - Story has been reviewed for completeness and accuracy
### Implementation Preparedness
- [ ] **Environment Ready** - Development environment requirements specified
- [ ] **Resources Available** - All required resources (assets, docs, dependencies) accessible
- [ ] **Testing Prepared** - Testing environment and data requirements specified
@@ -928,6 +945,7 @@ This document establishes coding standards, architectural patterns, and developm
### Strict Mode Configuration
**Required tsconfig.json settings:**
```json
{
"compilerOptions": {
@@ -941,11 +959,12 @@ This document establishes coding standards, architectural patterns, and developm
"exactOptionalPropertyTypes": true
}
}
```text
```
### Type Definitions
**Game Object Interfaces:**
```typescript
// Core game entity interface
interface GameEntity {
@@ -969,9 +988,10 @@ interface GameSystem {
update(delta: number): void;
shutdown(): void;
}
```text
```
**Scene Data Interfaces:**
```typescript
// Scene transition data
interface SceneData {
@@ -989,28 +1009,32 @@ interface GameState {
interface GameSettings {
musicVolume: number;
sfxVolume: number;
difficulty: 'easy' | 'normal' | 'hard';
difficulty: "easy" | "normal" | "hard";
controls: ControlScheme;
}
```text
```
### 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`
@@ -1019,88 +1043,91 @@ interface GameSettings {
### Scene Organization
**Scene Lifecycle Management:**
```typescript
class GameScene extends Phaser.Scene {
private gameManager!: GameManager;
private inputManager!: InputManager;
constructor() {
super({ key: 'GameScene' });
super({ key: "GameScene" });
}
preload(): void {
// Load only scene-specific assets
this.load.image('player', 'assets/player.png');
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('*');
this.events.off("*");
}
}
```
**Scene Transitions:**
```typescript
// Proper scene transitions with data
this.scene.start('NextScene', {
this.scene.start("NextScene", {
playerScore: this.playerScore,
currentLevel: this.currentLevel + 1
currentLevel: this.currentLevel + 1,
});
// Scene overlays for UI
this.scene.launch('PauseMenuScene');
this.scene.launch("PauseMenuScene");
this.scene.pause();
```text
```
### 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));
this.components.forEach((component) => component.update(delta));
}
destroy(): void {
this.components.forEach(component => component.destroy());
this.components.forEach((component) => component.destroy());
this.components.clear();
super.destroy();
}
@@ -1110,65 +1137,67 @@ abstract class GameEntity extends Phaser.GameObjects.Sprite {
class Player extends GameEntity {
private movement!: MovementComponent;
private health!: HealthComponent;
constructor(scene: Phaser.Scene, x: number, y: number) {
super(scene, x, y, 'player');
super(scene, x, y, "player");
this.movement = this.addComponent(new MovementComponent(this));
this.health = this.addComponent(new HealthComponent(this, 100));
}
}
```text
```
### 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!');
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!');
throw new Error("GameManager not initialized!");
}
return GameManager.instance;
}
update(delta: number): void {
// Update game logic
}
destroy(): void {
GameManager.instance = null!;
}
}
```text
```
## 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);
@@ -1177,20 +1206,20 @@ class BulletPool {
this.pool.push(bullet);
}
}
getBullet(): Bullet | null {
const bullet = this.pool.find(b => !b.active);
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');
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);
@@ -1202,45 +1231,47 @@ class BulletPool {
### 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.
}
}
```text
```
**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) {
@@ -1250,13 +1281,14 @@ class GameScene extends Phaser.Scene {
}
}
}
```text
```
## Input Handling
### Cross-Platform Input
**Input Abstraction:**
```typescript
interface InputState {
moveLeft: boolean;
@@ -1272,26 +1304,26 @@ class InputManager {
moveRight: false,
jump: false,
action: false,
pause: 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');
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);
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;
@@ -1299,42 +1331,43 @@ class InputManager {
this.inputState.jump = Phaser.Input.Keyboard.JustDown(this.keys.SPACE);
// ... handle touch input
}
getInputState(): InputState {
return { ...this.inputState };
}
}
```text
```
## 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.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');
case "player":
this.scene.load.image("player", "assets/defaults/default-player.png");
break;
default:
console.warn(`No fallback for asset: ${key}`);
@@ -1346,25 +1379,26 @@ class AssetManager {
### 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':
case "update":
// Reset system state
this.reset();
break;
case 'render':
case "render":
// Disable visual effects
this.disableEffects();
break;
@@ -1374,64 +1408,66 @@ class GameSystem {
}
}
}
```text
```
## Testing Standards
### Unit Testing
**Game Logic Testing:**
```typescript
// Example test for game mechanics
describe('HealthComponent', () => {
describe("HealthComponent", () => {
let healthComponent: HealthComponent;
beforeEach(() => {
const mockEntity = {} as GameEntity;
healthComponent = new HealthComponent(mockEntity, 100);
});
test('should initialize with correct health', () => {
test("should initialize with correct health", () => {
expect(healthComponent.currentHealth).toBe(100);
expect(healthComponent.maxHealth).toBe(100);
});
test('should handle damage correctly', () => {
test("should handle damage correctly", () => {
healthComponent.takeDamage(25);
expect(healthComponent.currentHealth).toBe(75);
expect(healthComponent.isAlive()).toBe(true);
});
test('should handle death correctly', () => {
test("should handle death correctly", () => {
healthComponent.takeDamage(150);
expect(healthComponent.currentHealth).toBe(0);
expect(healthComponent.isAlive()).toBe(false);
});
});
```text
```
### Integration Testing
**Scene Testing:**
```typescript
describe('GameScene Integration', () => {
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', () => {
test("should initialize all systems", () => {
scene.create({});
expect(scene.gameManager).toBeDefined();
expect(scene.inputManager).toBeDefined();
});
});
```text
```
## File Organization
@@ -1485,21 +1521,25 @@ src/
### 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
@@ -1512,6 +1552,7 @@ src/
### Code Review Checklist
**Before Committing:**
- [ ] TypeScript compiles without errors
- [ ] All tests pass
- [ ] Performance targets met (60 FPS)
@@ -1525,17 +1566,20 @@ src/
## 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