whalehunting/.planning/codebase/STRUCTURE.md

Codebase Structure

Analysis Date: 2026-02-04

Directory Layout

whalehunting/
├── src/                    # Game source code
│   ├── main.js            # Phaser game initialization and configuration
│   └── scenes/            # Game scene implementations
│       ├── IntroScene.js
│       ├── ShipDeckScene.js
│       ├── MapScene.js
│       ├── TransitionScene.js
│       └── HuntingScene.js
├── tests/                 # Test suites
│   ├── unit/              # Unit tests (Vitest)
│   │   └── game-logic.test.js
│   └── e2e/               # End-to-end tests (Playwright)
│       └── game-flow.spec.js
├── .planning/             # GSD planning documents
│   └── codebase/          # Architecture analysis
├── index.html             # HTML entry point
├── package.json           # Dependencies and scripts
├── vitest.config.js       # Unit test configuration
├── playwright.config.js   # E2E test configuration
├── nginx.conf             # Web server config for deployment
├── Dockerfile             # Container image definition
├── docker-compose.yml     # Multi-container orchestration
└── deploy.sh              # Automated deployment script

Directory Purposes

src/:

• Purpose: All game source code
• Contains: Main game initialization and scene implementations
• Key files: main.js is the entry point that configures Phaser

src/scenes/:

• Purpose: Game scene implementations
• Contains: Five scene classes, one per major game location/mode
• Key files: IntroScene starts the game, HuntingScene has most complex logic

tests/:

• Purpose: All test code separated from source
• Contains: Unit tests and E2E tests in separate subdirectories
• Key files: game-logic.test.js for game mechanics, game-flow.spec.js for user flows

tests/unit/:

• Purpose: Logic testing without Phaser
• Contains: Vitest tests for inventory calculations, fuel costs, barrel logic
• Key files: game-logic.test.js

tests/e2e/:

• Purpose: Full application flow testing
• Contains: Playwright tests simulating user interactions on actual game canvas
• Key files: game-flow.spec.js

.planning/codebase/:

• Purpose: Analysis documents for code navigation
• Contains: ARCHITECTURE.md, STRUCTURE.md, CONVENTIONS.md, TESTING.md, CONCERNS.md
• Generated by: GSD mapping processes

Key File Locations

Entry Points:

• index.html: Browser loads this, contains game-container div and script import
• src/main.js: Phaser game configuration and scene list initialization

Configuration:

• vitest.config.js: Unit test runner with jsdom environment, port 51204 for UI server
• playwright.config.js: E2E test runner with Chromium and iPhone 12 profiles
• package.json: Dependencies (Phaser 3.80.1, Vite, Vitest, Playwright)
• nginx.conf: Web server routing (not actively used in dev)
• docker-compose.yml: Local dev: port 5173 for Vite server
• Dockerfile: Production build with multi-stage for size optimization

Core Logic:

• src/scenes/IntroScene.js: Game entry, starts with fuel=100, oil=0, penguins=0
• src/scenes/ShipDeckScene.js: Inventory display, barrel visualization, penguin cage reveal
• src/scenes/MapScene.js: Location selection (Hunting Grounds, Antarctic, Port)
• src/scenes/TransitionScene.js: Atmospheric journey scenes, destination-specific visuals
• src/scenes/HuntingScene.js: Core gameplay - whale spawning, harpoon mechanics, fuel consumption

Testing:

• tests/unit/game-logic.test.js: Barrel calculations, inventory limits, fuel costs, whale health, crosshair clamping
• tests/e2e/game-flow.spec.js: Full flows (intro→ship→map→hunting), mobile viewport, desktop scaling

Naming Conventions

Files:

• PascalCase + Scene suffix: IntroScene.js, ShipDeckScene.js
• camelCase for non-scene modules: Would apply if utilities existed
• Test files: Matched source with .test.js or .spec.js suffix
• Config files: kebab-case: playwright.config.js, vitest.config.js

Directories:

• lowercase plural: src/scenes/, tests/unit/, tests/e2e/
• camelCase for compound: Not currently used

Class Names:

• PascalCase: IntroScene, ShipDeckScene, MapScene, TransitionScene, HuntingScene
• Extend Phaser.Scene directly

Methods:

• camelCase: create(), update(), init(), createDeck(), createBarrels(), updateInventoryDisplay()
• Lifecycle methods (create, update) are Phaser conventions
• Helper methods prefix with action: create*(), update*(), show*(), draw*()

Variables:

• camelCase for instance: this.inventory, this.currentWhale, this.harpoons
• camelCase for local: barrelCount, swimSpeedX, healthPercent
• UPPERCASE for constants: FUEL_COST = 2, MAX_HEALTH = 3

Game State Objects:

• Inventory structure: { whaleOil: number, fuel: number, penguins: number }
• Whale data stored via setData(): health, alive, diving, swimSpeedX, swimSpeedY, direction

Where to Add New Code

New Scene/Location:

1. Create src/scenes/NewScene.js extending Phaser.Scene
2. Implement init(data) to receive inventory
3. Implement create() for rendering
4. Implement update() if frame-by-frame logic needed
5. Call this.scene.start('MapScene', { inventory: this.inventory }) to transition
6. Add to scene list in src/main.js config array
7. Add location marker in MapScene.js that routes to new scene

New Game Mechanic:

• Hunting scene has most game logic: HuntingScene.js handles whale spawning, harpoon firing, collision detection, health tracking
• Add mechanics as methods in relevant scene class
• Store persistent state in this.inventory object
• Display UI changes via updateInventoryDisplay() pattern

Utilities (if needed):

• Create src/utils/ directory for shared helpers
• Example: src/utils/inventory.js for max capacity functions
• Example: src/utils/collision.js for distance calculations
• Import in scenes: import { calculateBarrels } from '../utils/inventory.js';

New UI Component Pattern:

• Create methods in scene: createInventoryDisplay(), createMessageBox()
• Return reference to element for later updates
• Update via methods: updateInventoryDisplay(), showMessage(text)
• Use semi-transparent rectangles for panels with .setFillStyle(0x000000, 0.7)

Special Directories

node_modules/:

• Purpose: Installed dependencies
• Generated: Yes (via npm install)
• Committed: No (.gitignore)

dist/:

• Purpose: Vite production build output
• Generated: Yes (via npm run build)
• Committed: No (.gitignore)
• Files: Optimized JS/CSS for deployment

.git/:

• Purpose: Git repository metadata
• Generated: Yes (git init)
• Committed: Meta repository
• Notable: Recent commits track feature additions and testing infrastructure

.planning/:

• Purpose: GSD orchestration files and analysis documents
• Generated: Yes (via /gsd commands)
• Committed: Yes (tracked in git)
• Structure: codebase/ contains ARCHITECTURE.md, STRUCTURE.md, etc.

---

Structure analysis: 2026-02-04