Expert guidance for developing BattleFields, a turn-based hex grid tactical game built with Phaser 3, featuring terrain systems, pathfinding, combat mechanics, and physics-based dice rolling.
Expert guidance for developing BattleFields, a hex-based tactical combat game built with vanilla JavaScript and Phaser 3.
BattleFields is a turn-based tactical game featuring:
**No build process required** - vanilla JavaScript with ES6 modules served directly.
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.
**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:
**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
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)
Per unit, per turn:
End Turn button:
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
All animations created in `BattleScene._createAnimations()`:
**Infantry**:
**Tanks**:
**Death**:
**Effects**:
Damaged animations use separate sprite sets with `_damage` suffix.
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.
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.**
The '?' before general selection uses absolute positioning. If modifying Hud layout, update both `portraitQuestion` and `portraitImage` positions.
```
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)
```
Game state lives in `BattleScene` instance variables:
TurnSystem state:
Unit state (per turn):
**No external state management library used.**
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.
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
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/phaser-3-hex-based-tactical-game/raw