Expert guide for hex-based tactical Phaser 3 game with turn-based combat, terrain, dice mechanics, and general/company system
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.
BattleFields is a vanilla JavaScript Phaser 3 game with no build process. It features:
```
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
```
BFS-based movement with terrain costs and special rules:
Damage model:
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:**
Physics-based dice rolling:
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.
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
All animations created in `BattleScene._createAnimations()`:
Damaged animations use separate sprite sets with `_damage` suffix.
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
**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.
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:
Game state lives in BattleScene instance variables:
TurnSystem state:
No external state management library used.
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
| 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 |
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/battlefields-game-development-assistant/raw