BattleFields Game Development Assistant

Expert assistant for developing and maintaining BattleFields, a hex-based tactical game built with Phaser 3. Helps with combat mechanics, pathfinding, animation systems, turn management, and hex grid operations.

Game Architecture

BattleFields is a vanilla JavaScript Phaser 3 game with no build process. It features:

**Hex grid battlefield** with offset coordinates (odd-row stagger)

**Turn-based combat** with green vs red armies

**Terrain system**: void, water, forest, trench, grass (each with different movement costs)

**Unit types**: infantry (2 attacks, wounded before death) and tanks (1 attack, trench crossing rules)

**Static weapons**: machine guns (4 attacks) and anti-tank guns

**Dice mechanics**: physics-based rolling for initiative, commander hiring, and company activation

**General/company system**: colonels provide bonuses, companies (artillery/supply) activate based on rolls

**Damage model**: ready → wounded → dead (with corresponding animations)

Project Structure

```

src/

core/ # Game logic (HexGrid, TerrainMap, Pathfinder, CombatSystem, Unit, Dice, Hud)

scenes/ # Phaser scenes (BattleScene main game, AnimationDemo for testing)

main.js # Phaser config

assets/

first-map.json # Tiled hex map

map/ # Tilesets

[units]/ # Sprite frames for infantry/tanks (green/red, normal/damaged)

shoot and explode/ # Combat effects

companies/ # UI icons

colonels/ # General portraits

```

Core Systems

HexGrid (src/core/HexGrid.js)

`toWorld(q, r)` — convert hex to pixel coordinates

`fromWorld(x, y)` — convert pixel to hex coordinates

`neighbors(q, r)` — get valid neighbor hexes

`hexDistance(q1, r1, q2, r2)` — cube distance between hexes

Pathfinder (src/core/Pathfinder.js)

BFS-based movement with terrain costs and special rules:

Forest costs 2 movement

Tanks crossing trenches need >1 movement remaining and cannot end on trenches

Returns Map of reachable hexes with `costLeft` for each

CombatSystem (src/core/CombatSystem.js)

Damage model:

First hit: `ready` → `wounded` (damaged animations, no tint)

Second hit: `wounded` → `dead` (death animation for infantry, static texture for tanks)

Dead units: `attacks=0`, `movesLeft=0`, non-interactive sprite

TurnSystem (new system)

Manages round phases:

1. **Initiative** (Round 1 only) — determines first player for entire game

2. **Commander Hiring** (every round) — both players roll for colonel bonuses

3. **Company Activation** (skipped Round 1 day 1) — roll for artillery or supply

4. **Unit Actions** — players alternate 5 actions each (manual End Turn button)

5. **Night Phase** — roll for Rest or Night Battle

**Per-turn unit state:**

`hasMoved` — can only move once per turn (remaining movement lost after first move)

`usedStaticWeapon` — cannot attack if used MG/AT and left the position

Attacks reset each turn (infantry=2, tank=1, MG=4)

Dice System (src/core/Dice.js)

Physics-based dice rolling:

Drag-to-throw mechanic with velocity based on swipe strength (max 2000 units/sec)

Real-time physics: gravity, friction, bounce, boundary collision

Random value changes during roll, settles on final result

Auto-returns to home position after 1 second

Callbacks: `onDiceResolved(value)`, `onCompanyUsed(kind)`

Running the Game

1. Serve the project with any local web server from root directory (e.g., `python -m http.server`)

2. Open `index.html` in browser

3. Requires ES6 module support (cannot use `file://` protocol)

**No build process, package.json, or npm commands** — pure vanilla JavaScript.

Scene Initialization Order (Critical)

In BattleScene.create():

1. Load assets (background, tilemap JSON, tilesets, sprite frames)

2. Create tilemap with layers: hexes, bases, flags, machine-gun, antitank-gun

3. Calculate dynamic scale to fit screen (720x1280 portrait, 280px HUD reserved)

4. **Apply tileoffset compensation** for red bases layer (+16x, -7y scaled)

5. Initialize HexGrid, UnitFactory, TerrainMap

6. Create Hud and Dice **before** pathfinder/combat

7. Wire callbacks between Dice ↔ Hud

8. Initialize Pathfinder and CombatSystem with units array

9. Spawn initial units

10. Register input handlers

Animation System

All animations created in `BattleScene._createAnimations()`:

**Infantry**: walk_left, walk_right, idle (green/red × normal/damage variants)

**Tank**: move_left, move_right, move_up, move_down, idle (green/red × normal/damage)

**Death**: dying_left, dying_right (infantry only, green/red)

**Effects**: explosion, soldier_muzzle_{direction}, tank_muzzle_{direction}

Damaged animations use separate sprite sets with `_damage` suffix.

Game Flow

1. Player taps unit → `_selectUnit()` if correct side

2. Pathfinder highlights reachable hexes (black overlay) if `!unit.hasMoved`

3. Enemies in attack range highlighted red

4. Usable MG/AT positions highlighted blue if `!unit.hasMoved`

5. Player taps destination:

- Empty hex → move unit (sets `hasMoved = true`, `movesLeft = 0`)

- Enemy → `combat.performAttack()` (checks `usedStaticWeapon`)

6. `_checkTurnEnd()` records action (no auto-switch)

7. Player clicks End Turn button → switches player or ends phase

Common Pitfalls

**Tileset offsets**: Red bases layer has tileoffset {x:-16, y:7} in Tiled — compensated in code after scaling (line 289). Apply similar compensation for new offset tilesets.

**Tank trench crossing**: Tanks need `costLeft > 1` before crossing and `checkLeft > 0` after. Cannot end movement on trenches. Don't remove these checks.

**Animation timing**: Movement duration is 380ms per hex. Attack visual delays (e.g., 250ms for infantry shoot) must complete before state changes to avoid flickering.

**Depth/z-index**: Help modal uses depth 1000+, bases layer depth 1, background -1000. Other objects default to 0.

Coordinate System

Uses **offset coordinates (q,r)** with odd-row horizontal stagger. Neighbor offsets differ between odd/even rows.

**Always use HexGrid methods** instead of manual coordinate math:

`toWorld(q, r)` for rendering

`fromWorld(x, y)` for input handling

`neighbors(q, r)` for adjacency

`hexDistance(q1, r1, q2, r2)` for range checks

State Management

Game state lives in BattleScene instance variables:

`this.units[]` — all units (including dead)

`this.currentPlayer` — 'green' or 'red'

`this.turnNumber` — increments when green's turn starts

`this.selectedUnit` — currently selected unit or null

`this.dice.value` — current dice value (0 if used)

`this.dice.colonel` — selected general object

TurnSystem state:

`initiativeDetermined` — boolean, true after first initiative roll

`initiativeWinner` — 'green' or 'red', preserved for entire game

`currentRound` — round number (1-5)

`currentPhase` — 'initiative', 'commander', 'companies', 'actions', 'night', 'rest'

`playerTurnFinished` — {green: boolean, red: boolean}

`currentActionPlayer` — current player during actions phase

No external state management library used.

Development Guidelines

1. **Terrain changes**: Update TerrainMap GID mappings if modifying Tiled tileset

2. **New unit types**: Extend Unit class, add animations in `_createAnimations()`, update combat damage model

3. **UI modifications**: HUD is 280px high at bottom. Update Hud class and adjust scene scaling calculations

4. **Pathfinding rules**: Modify Pathfinder with terrain cost logic, maintain tank trench checks

5. **Combat effects**: Add sprite frames to `shoot and explode/` folder, register in `_createAnimations()`

6. **Map edits**: Export from Tiled as JSON to `assets/first-map.json`, ensure layer names match code

Debugging Tips

Use `console.log(this.grid.fromWorld(x, y))` to debug hex coordinate calculations

Check `this.units` array for unit state (hasMoved, usedStaticWeapon, attacks, movesLeft)

Verify animation keys match sprite frame names exactly

Use AnimationDemo scene to test new animations in isolation

Check browser console for Phaser warnings about missing textures/animations

Key Files Reference

| File | Purpose |

|------|---------|

| `src/core/HexGrid.js` | Hex ↔ world coordinate conversion |

| `src/core/Pathfinder.js` | BFS movement calculation with terrain costs |

| `src/core/CombatSystem.js` | Attack resolution and damage model |

| `src/core/Unit.js` | Base unit class with movement/state |

| `src/core/Dice.js` | Physics-based dice rolling |

| `src/core/Hud.js` | Bottom UI bar with general/company icons |

| `src/scenes/BattleScene.js` | Main game scene (1200+ lines) |

| `assets/first-map.json` | Tiled hex map definition |

Constraints

No build process — vanilla JavaScript only

ES6 modules required (served via web server)

Portrait orientation (720x1280), 280px reserved for HUD

Phaser 3 library vendored in `phaser.js`

All sprites must have corresponding animation definitions

Hex grid uses offset coordinates (odd-row stagger) — use HexGrid methods for all coordinate operations

BattleFields Game Development Assistant

BattleFields Game Development Assistant

Game Architecture

Project Structure

Core Systems

HexGrid (src/core/HexGrid.js)

Pathfinder (src/core/Pathfinder.js)

CombatSystem (src/core/CombatSystem.js)

TurnSystem (new system)

Dice System (src/core/Dice.js)

Running the Game

Scene Initialization Order (Critical)

Animation System

Game Flow

Common Pitfalls

Coordinate System

State Management

Development Guidelines

Debugging Tips

Key Files Reference

Constraints

Reviews (0)