whalehunting/.planning/codebase/CONVENTIONS.md

# Coding Conventions

**Analysis Date:** 2026-02-04

## Naming Patterns

**Files:**
- PascalCase for scene classes: `IntroScene.js`, `MapScene.js`, `HuntingScene.js`, `ShipDeckScene.js`, `TransitionScene.js`
- kebab-case for test files: `game-logic.test.js`, `game-flow.spec.js`
- camelCase for configuration files: `vitest.config.js`, `playwright.config.js`

**Functions:**
- camelCase for all methods: `drawWaves()`, `createLocation()`, `updateInventoryDisplay()`, `spawnWhale()`, `hitWhale()`
- Method names are descriptive and indicate action: `create*` for initialization, `update*` for state changes, `draw*` for graphics
- Private-like pattern: methods starting with event handlers (`on*` callbacks) or utility methods

**Variables:**
- camelCase for local variables and object properties: `whaleOil`, `currentWhale`, `inventory`, `crosshairX`, `swimSpeedX`
- PascalCase for class names: `IntroScene`, `MapScene`, `HuntingScene`
- SCREAMING_SNAKE_CASE for constants is not used; magic numbers are inline or stored as camelCase object properties
- Abbreviated names in loops: `i`, `x`, `y` for coordinates

**Types:**
- No TypeScript; vanilla JavaScript with JSDoc comments for complex logic
- Object literals for data structures (e.g., inventory: `{ whaleOil: 0, fuel: 100, penguins: 0 }`)
- No explicit type annotations; types inferred from usage context

## Code Style

**Formatting:**
- No explicit formatter configured (no .prettierrc or similar found)
- 4 spaces for indentation (observed consistently across all files)
- Single statements per line; no cramping of expressions
- Line length varies; some lines exceed 100 characters

**Linting:**
- No ESLint or similar linting tool configured
- No explicit style guide enforced; conventions followed naturally

## Import Organization

**Order:**
1. Phaser framework imports: `import Phaser from 'phaser'`
2. Scene exports: `export default class SceneName extends Phaser.Scene`
3. Test framework imports: `import { describe, it, expect } from 'vitest'` and `import { test, expect } from '@playwright/test'`

**Path Aliases:**
- No path aliases configured
- Relative imports with `.js` extension explicit: `import IntroScene from './scenes/IntroScene.js'`

## Error Handling

**Patterns:**
- Defensive checks before operations: `if (this.currentWhale && this.currentWhale.getData('alive'))`
- Boundary checking for game state: `if (this.inventory.fuel < 2)` before processing whale
- No explicit error throwing; invalid states default to safe fallbacks
- Scene transitions use `this.scene.start()` with null coalescing: `this.inventory = data.inventory || { whaleOil: 0, fuel: 100, penguins: 0 }`
- Array bounds checking: loop guards with `.length` checks, array splice after removal

## Logging

**Framework:** console (implicit; not found in code)

**Patterns:**
- No logging statements observed in source code
- Game messaging via `showMessage()` method: text display in game UI
- Debug output would likely use console.log if needed (not observed)

## Comments

**When to Comment:**
- Method-level comments for non-obvious logic: `// Ocean blue background`, `// Draw decorative waves`
- Inline comments for complex calculations: `// Can't hit whale while diving`, `// Keep within bounds`
- Comment frequency is moderate; most code is self-documenting through naming

**JSDoc/TSDoc:**
- No JSDoc comments found
- Vanilla JavaScript with method names that describe intent

## Function Design

**Size:**
- Methods range from 10-70 lines
- Larger methods like `create()` (30+ lines) perform initialization with calls to smaller helper methods
- Complex game logic broken into focused methods: `updateWhale()`, `updateHarpoons()`, `checkCollisions()`

**Parameters:**
- Methods accept 0-3 parameters typically
- Event handlers use single parameter (e.g., `pointerdown` callbacks)
- Data passed through scene initialization: `this.scene.start('NextScene', { inventory: data })`

**Return Values:**
- Mostly void/no return (Phaser scene lifecycle methods)
- Some utility functions return boolean: `hasOwnProperty()` checks
- Game state propagated through `this` context, not function returns

## Module Design

**Exports:**
- Each scene file exports default class: `export default class SceneName extends Phaser.Scene`
- All scenes imported into `src/main.js` as class references
- Scene registration in Phaser config array: `scene: [IntroScene, ShipDeckScene, MapScene, TransitionScene, HuntingScene]`

**Barrel Files:**
- No index.js or barrel files found
- Each scene is independent; imports are explicit by filename

## Data Structures

**Object Literals:**
- Inventory object: `{ whaleOil: 0, fuel: 100, penguins: 0 }`
- Configuration objects: Phaser game config in `src/main.js`
- Destination mapping in `TransitionScene.js`: `destinations` object with title, description, backgroundColor, visualType

**Phaser-Specific Patterns:**
- `setData(key, value)` / `getData(key)` for storing state on game objects
- Container objects with `add([children])` for grouping (e.g., whale body with parts)
- Scene transitions with inventory passed as data parameter

## Common Patterns Observed

**Scene Lifecycle:**
1. `constructor()`: Set scene key
2. `init(data)`: Receive data from previous scene
3. `create()`: Initialize scene graphics and setup
4. `update()`: Game loop updates (only used in HuntingScene)

**UI Element Creation:**
- Rectangle/circle/text created with `.add.rectangle()`, `.add.circle()`, `.add.text()`
- Interactive zones created with `setInteractive()` and `.on('pointerX', callback)`
- Hover/click feedback with `setScale()`, `setFillStyle()` updates

**Animation:**
- Phaser tweens for smooth transitions: `this.tweens.add({ targets: obj, property: value, duration: ms })`
- Sine/cosine wave patterns for natural movement: `Math.sin()`, `Math.cos()` for bobbing/sway

---

*Convention analysis: 2026-02-04*