Gold Hunter Game Development Guide
A comprehensive development guide for building Gold Hunter, a top-down 2D action-adventure game where players explore a vast world collecting gold ingots while trading, fighting, and discovering secrets.
Core Development Principles
This skill guides you through the architectural patterns and development practices for the Gold Hunter game project, ensuring consistent, maintainable, and scalable code.
Development Guidelines
1. Iterative Slices First
Ship tiny, vertical slices; integrate end-to-end before expandingPrefer a working, small feature over an incomplete, large oneAlways deliver functional increments2. Modular, Composable Architecture
Keep systems in small modules with narrow responsibilities (inventory, economy, enemies, world, UI)Design for composition over inheritance; prefer plain objects and functions wired togetherDefine tiny contracts: inputs, outputs, side-effects, and failure modes**Example module structure:**
```javascript
// src/lib/inventory.js
export function addToInventory(scene, item) {
// item: { type, subtype, name, stats, size, color }
}
export function equipWeapon(scene, item) { }
export function equipShield(scene, item) { }
```
3. Stable Boundaries and Minimal Coupling
Isolate cross-cutting concerns behind helpers (e.g., transitions freeze enemies via a single function)Use data-driven configs (JSON/objects) to avoid hard-wiring logicPass dependencies explicitly as parameters; avoid hidden globals4. Extensibility by Convention
New enemy types implement the same minimal lifecycle: create → update → destroyNew items declare a data shape (type, subtype, stats) that UI and systems can renderAdd optional capability flags (e.g., `persistentAcrossMaps`) for varied behaviors without branching everywhere**Enemy extensibility pattern:**
```javascript
// Keep fields: enemyType, health, damage, flags
function createEnemy(scene, type, x, y, opts) { }
function updateEnemy(scene, enemy, time, delta) { }
```
5. Testability and Observability
Keep pure helpers pure; side-effecting code should be thin wrappersPrefer deterministic updates (time/delta inputs) so behaviors are sim-testableAdd lightweight logging hooks or event emitters for key actions (purchases, hits, transitions)6. UI Layout Discipline
Centralize layout metrics (viewport, HUD height, padding) and compute positions; don't sprinkle constantsAlways word-wrap and clamp text to safe bounds; paginate when neededBlock conflicting inputs when a modal UI is open; clean up all UI nodes on close7. Performance as a Habit
Avoid per-frame allocations; reuse objects/arrays where practicalCap per-frame loops and bail early when not visible/activePrefer simple math and cheap physics; profile before adding complexity8. Data and Save Safety
Validate external/data files against schemas before loadingVersion save data; include migrations for breaking changesKeep save writes atomic and infrequent; batch when possible9. Code Style and Documentation
Keep module headers with AI-INDEX tags and purpose summariesName functions for intent; include JSDoc on public helpersUpdate README/docs alongside features; document assumptions and limitsMaintain the AI Index: update `docs/ai/index.json` anchors and tags when modules/functions changeKeep AI-INDEX tags in source headers in sync with actual responsibilities**Module header example:**
```javascript
/**
* @module inventory
* @ai-index inventory, items, equipment, inventory-ui
* Responsibilities: store items, equip/unequip, render inventory UI
*/
```
10. Feature Flags and Dev Ergonomics
Gate WIP systems behind flags; toggle via a central dev configProvide debug overlays (grid, bounds, state) to speed iterationAdd small smoke tests or scripts to assert no syntax errors after edits11. Documentation Workflow
When adding or moving systems, update:
`docs/development-phases.md` if scope/timeline shifts`.github/copilot-instructions.md` guidelines if conventions change`README.md` links and quickstart if dev flow changes`CONTRIBUTING.md` for contributor steps and checklists`docs/ai/index.json` and source AI-INDEX tags for discoverability**Assistant progress summaries**: Keep extremely brief; prefer lists and concrete data (files, diffs, counts, statuses); avoid semantic prose; report only deltas.
Module Contracts
Inventory (`src/lib/inventory.js`)
**Responsibilities:** Store items, equip/unequip, render inventory UI
**Inputs:**
`addToInventory(scene, item)` — item: `{ type: 'weapon'|'shield', subtype: string, name: string, stats?, size?, color? }``equipWeapon(scene, item)`, `equipShield(scene, item)`**Outputs/Side-effects:**
Updates `scene.equippedWeapon`/`equippedShield`, HUD via UISceneEmits logs/hooks (optional) for analytics**Failure modes:**
Inventory full → returns falseInvalid index → no-opEconomy (`src/lib/economy.js`)
**Responsibilities:** Currency specs, wallet management, pricing helpers
**Inputs:**
`addToWallet(scene, type, amount)``spendFromWallet(scene, costPence)``getItemPrice(type, subtype)`**Outputs/Side-effects:**
Updates HUD currency counters**Failure modes:**
Unknown currency → no-opInsufficient funds → falseEnemies (`src/lib/enemies.js`)
**Responsibilities:** Spawn/update/destroy enemies; shared combat helpers
**Inputs:**
`createEnemy(scene, type, x, y, opts)``updateEnemies(scene, time, delta)``damageEnemy(scene, enemy, amount, opts?)`**Outputs/Side-effects:**
Adds sprites to `scene.worldLayer`/`enemiesGroup`Applies knockback/stun; kill FX**Failure modes:**
Unknown type → warnMissing physics → no-op**Extensibility:**
Implement `create<Enemy>`, `update<Enemy>`Keep fields: `enemyType`, `health`, `damage`, `flags`World/Maps (`src/lib/world.js`)
**Responsibilities:** Place objects on grid, build map layers, doors, shop
**Inputs:**
`createMapObjects(scene, opts?)``placeObjectOnGrid(scene, gx, gy, type, group?, data?)`**Outputs/Side-effects:**
Creates containers/sprites, sets collisions/overlaps, wires transitions**Failure modes:**
Blocked cell → returns nullUnknown type → no-op**Extensibility:**
Add new object types via `placeObjectOnGrid`Keep data-driven flagsUI (`src/scenes/UIScene.js`)
**Responsibilities:** HUD, modal dialogs (shop), prompts/toasts
**Inputs:**
`updateHealthBar(hp, max)`, `updateCurrency(total, copper, silver)`Shop dialog: takes list of items with `name`/`type`/`subtype`/`price`**Outputs/Side-effects:**
Blocks conflicting inputs when openCleans up nodes on close**Failure modes:**
UI scene not active → silently skip updates**Extensibility:**
Compute layout from centralized metricsPaginate when overflowTransitions (`src/lib/transitions.js`)
**Responsibilities:** Map scroll transitions, input/physics lock, enemy freeze
**Inputs:**
`scrollTransitionToMap(scene, direction, newMapId, playerX, playerY)``beginTransition(scene)`, `endTransition(scene)`**Outputs/Side-effects:**
Builds new layer, slides containers, re-homes persistent enemies**Failure modes:**
Transition already running → ignore**Extensibility:**
Keep enemy freeze/unfreeze via a single helperMove/destroy only old-layer entitiesCombat (`src/lib/combat.js`)
**Responsibilities:** Melee swings, shield raise/lower, basic hit logic
**Inputs:**
`swingMeleeWeapon(scene)``raiseShield(scene)`, `lowerShield(scene)`, `updateShieldPosition(scene)`**Outputs/Side-effects:**
Damages enemies in a front arc with cooldown/knockbackChops bushes; shield blocks**Failure modes:**
No weapon/shield → no-op with log**Extensibility:**
Factor hitboxes laterKeep shared damage helpers in enemiesTechnical Stack
**Engine:** Phaser 3**Language:** JavaScript/ES6+**Map Editor:** Tiled**Version Control:** Git**Build System:** Webpack/ViteQuality Standards
Consistent 60 FPS performanceCross-browser compatibilityResponsive design for different screen sizesClean, maintainable codeComprehensive documentationIntuitive user interfaceEngaging gameplay mechanicsUsage Example
When implementing a new enemy type:
1. Create `create<EnemyType>` function following the lifecycle pattern
2. Implement `update<EnemyType>` with time/delta inputs
3. Add to enemy registry with minimal fields: `enemyType`, `health`, `damage`, `flags`
4. Update `docs/ai/index.json` with new enemy anchor
5. Add AI-INDEX tag to module header
When adding a new item:
1. Define data shape: `{ type, subtype, name, stats, size, color }`
2. Add pricing to `economy.js` via `getItemPrice`
3. Extend inventory rendering if needed (paginate if overflow)
4. Update documentation with new item type
Constraints
Keep all per-frame operations cheap (< 1ms)Validate all external data before loadingNever break existing module contracts without versioningAll modal UI must block conflicting inputsAll text must be word-wrapped and clamped to safe bounds