Phaser 3 Hex-Based Tactical Game

Expert guidance for developing BattleFields, a hex-based tactical combat game built with vanilla JavaScript and Phaser 3.

Project Overview

BattleFields is a turn-based tactical game featuring:

**No build process required** - vanilla JavaScript with ES6 modules served directly.

Running the Game

1. Start any local web server from the root directory

2. Open `index.html` in a browser

3. ES6 modules require web server (not `file://` protocol)

No `package.json`, no npm commands.

Core Architecture

Essential Systems (`src/core/`)

**HexGrid** - Coordinate conversion and grid logic:

**TerrainMap** - Extracts terrain from Tiled hex layer:

**Pathfinder** - BFS movement calculation:

**CombatSystem** - Attack and damage handling:

**Unit** - Base unit class:

**Hud** - Bottom UI bar (280px high):

**Dice** - Physics-based rolling system:

BattleScene Initialization Order

**CRITICAL**: Follow this exact sequence to avoid initialization errors:

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 720×1280 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

Turn System Flow

Round Structure

Each round has 5 phases:

1. **Initiative** (Round 1 only) - Dice roll determines first player for ENTIRE game

2. **Commander Hiring** (every round) - Both players roll for colonel with bonuses (1-6 = different types)

3. **Company Activation** (skipped in first day of Round 1) - Roll for artillery or supply

4. **Unit Actions** - Players alternate 5 actions each (one unit per action)

5. **Night Phase** - Roll determines Rest (company activation) or Night Battle (repeat day)

Turn Switching

Unit Action Rules

Per unit, per turn:

End Turn button:

Key Game Flow

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

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

3. Enemies in attack range highlighted red

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

5. Player taps destination:

- Empty reachable hex → move unit (if `!unit.hasMoved`), set `hasMoved = true`, `movesLeft = 0`

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

6. After action, `_checkTurnEnd()` calls `turnSystem.recordAction()` (no auto-switch)

7. Player clicks End Turn → `turnSystem.endPlayerTurn()` → switches player or ends phase

Animation System

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

**Infantry**:

**Tanks**:

**Death**:

**Effects**:

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

Common Issues & Solutions

Tileset Offset Problems

Red bases layer has `tileoffset {x:-16, y:7}` in Tiled. Compensated in code after scaling (line 289 in BattleScene). Apply similar compensation for new offset tilesets.

Tank Trench Movement

Tanks can cross trenches but cannot end on them. Pathfinder checks `cur.costLeft > 1` before crossing and `checkLeft > 0` after. **Do not remove these checks.**

Animation Timing

Portrait Question Mark

The '?' before general selection uses absolute positioning. If modifying Hud layout, update both `portraitQuestion` and `portraitImage` positions.

Depth/Z-Index

File Organization

```

src/

core/ - Game logic classes (no Phaser dependency except Unit)

scenes/ - Phaser scene classes

main.js - Phaser config and game instantiation

assets/

first-map.json - Tiled hex map

map/ - Tileset images

green soldier/ - Infantry sprite frames

red soldiers/ - Infantry sprite frames

green tank/ - Tank sprite frames

red tank/ - Tank sprite frames

shoot and explode/ - Combat effect frames

companies/ - UI icons for companies

colonels/ - UI icons for generals

index.html - Entry point

phaser.js - Phaser 3 library (vendored)

```

State Management

Game state lives in `BattleScene` instance variables:

TurnSystem state:

Unit state (per turn):

**No external state management library used.**

Coordinate System

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

**Always use HexGrid methods rather than manual coordinate math.**

World coordinates origin at map's top-left after applying `offsetX`/`offsetY`. Map is dynamically centered and scaled based on screen size.

Development Guidelines

1. **Maintain initialization order** in BattleScene - Hud and Dice must exist before Pathfinder/CombatSystem

2. **Preserve tank trench logic** - movement cost checks are critical

3. **Use HexGrid methods** for all coordinate operations

4. **Apply tileset offset compensation** when adding new tilesets with offsets

5. **Match animation timing** to state changes to prevent visual glitches

6. **Test turn system** thoroughly - initiative, commander hiring, and night phases have complex interdependencies

7. **Validate unit state** - `hasMoved`, `usedStaticWeapon` flags control action availability

Map Configuration