🎮 Hex Tower Defense - Thủ Thành Lục Giác

Game thủ thành chiến thuật trên lưới lục giác, data-driven, ECS architecture.

📋 Tính Năng

• ✅ Lưới lục giác atomic với pathfinding thông minh
• ✅ Flow Field cho di chuyển hiệu quả (không A* per unit)
• ✅ ECS architecture với 6 systems: Spawn → AI → Movement → Combat → Effects → Cleanup
• ✅ Event Bus với deferred queue (deterministic)
• ✅ Fixed timestep 60 tick/s với speed multiplier (x1, x2, x4)
• ✅ Data-driven - Tất cả units/skills/waves định nghĩa trong JSON
• ✅ SuperNode pathfinding - Structures as graph nodes
• ✅ Soft-stacking - 6 units per tile capacity

🚀 Quick Start

Prerequisites

• Node.js 18+ (khuyến nghị 20+)
• npm hoặc yarn

Installation

# Install dependencies
npm install

# Run dev server
npm run dev

# Open browser to http://localhost:3000

Build for Production

npm run build
npm run preview

📁 Cấu Trúc Project

someTD/
├── src/
│   ├── core/           # Core systems (Types, EventBus, GameLoop, HexUtils)
│   ├── ecs/            # Entity Component System
│   │   ├── components/ # Transform, Stats, Faction, Skills, etc.
│   │   ├── systems/    # 6 systems theo thứ tự fixed
│   │   └── ...
│   ├── grid/           # Hex grid & Tile
│   ├── pathfinding/    # GraphBuilder & FlowField
│   ├── ai/             # AI behaviors
│   ├── data/           # Data loaders
│   ├── ui/             # Renderer
│   └── runtime/        # Game runtime
├── public/
│   └── data/
│       ├── catalog.json  # Unit/Structure/Skill definitions
│       └── map.json      # Map layout & waves
└── index.html

🎮 Game Controls

• Pause/Resume: Click "Pause" button
• Speed Control: Click "Speed" button (1x → 2x → 4x)
• Skills: Q (Hex Command), E (Break Formation) - Coming soon

📊 Demo Content

Units

• Quân Sư Lục Giác (Hero): Support hero với 2 skills

  • Hex Command: +20% AS, +10% MS cho đồng minh (6s duration, 12s CD)
  • Break Formation: Slow 30% + Stun 0.5s (radius 2, 25s CD)

• Kỵ Binh Nhẹ (Soldier): Fast cavalry với Charge skill

• Cẩu Vương (Mob): Fast runner, reroute khi bị slow ≥40%

• Tổng Trấn Tam Giác (Boss):

  • Khiên góc quay (2 hướng mở)
  • Phase transitions mỗi -20% HP
  • Rally 2 elite mỗi 15s hoặc khi Hero ≤ 3 tiles

Waves

1. Wave 1 (5s): 5 Wolf Runners
2. Wave 2 (15s): 16 Wolf Runners (2 spawns)
3. Wave 3 (30s): 10 Wolf Runners + Boss

🔧 Data Format

catalog.json

{
  "units": {
    "unit_id": {
      "id": "unit_id",
      "displayName": "Tên Hiển Thị",
      "tags": ["hero", "soldier"],
      "base": {
        "hp": 100,
        "maxHp": 100,
        "armor": 5,
        "moveSpeed": 3.0,
        "attackDamage": 20,
        "attackSpeed": 1.5,
        "attackRange": 2
      },
      "skills": ["skill_id_1", "skill_id_2"],
      "ai": {
        "behavior": "runner",
        "params": { "slow_threshold": 0.4 }
      }
    }
  },
  "structures": { ... },
  "skills": { ... }
}

map.json

{
  "grid": { "radius": 12 },
  "spawnPoints": [{ "q": -10, "r": 5 }],
  "goalPoints": [{ "q": 0, "r": 0 }],
  "structures": [
    {
      "id": "wall_1",
      "ref": "wall",
      "cells": [{ "q": -3, "r": 2 }]
    }
  ],
  "playerUnits": [
    { "ref": "hero_tactician", "pos": { "q": 0, "r": 0 }, "count": 1 }
  ],
  "waves": [
    {
      "time": 300,
      "groups": [{ "ref": "wolf_runner", "count": 5, "interval": 60, "spawn": 0 }]
    }
  ]
}

🎯 Core Algorithms

Flow Field (Multi-source Dijkstra)

1. Initialize: All goal tiles → distance 0
2. Dijkstra from goals outward → distance map d(Tile)
3. Movement: Each unit picks neighbor with lowest d()

Graph Building

• TileNode: Individual passable tiles (not in structures)
• SuperNode: All tiles in a structure footprint
• Edges:
  • Tile-Tile: 6 directions, weight = avg(moveCost)
  • Super-Tile: Outer ring connections, weight = moveCost(Tile)
  • NO Super-Super edges

Movement (per tick)

1. Get best neighbor (lowest distance)
2. Check capacity (6 units max)
3. If full → fan-out (try neighbors within Δ=1)
4. If no space → wait

📈 Performance

• Target: 60 tick/s với 150 units
• Timestep: Fixed 1/60s (deterministic)
• Speed multipliers: x2, x4 không đổi logic
• Flow field: Precomputed, O(1) per movement query

🧪 Testing

Kiểm tra theo tiêu chí spec (section 19):

• Flow field correctness
• Movement không dùng A* per unit
• Validate (1 BFS) sau mỗi structure change
• Event defer queue
• Combat deterministic
• Slow cap 60%
• 60 tick/s với ~150 units

🛠️ Extending

Add New Unit

1. Thêm definition vào catalog.json
2. (Optional) Tạo AI behavior file trong src/ai/
3. Reload game

Add New Skill

1. Định nghĩa trong catalog.json → skills
2. Reference trong unit definition
3. Effect áp dụng tự động bởi EffectsSystem

Add New Map

1. Tạo file JSON mới trong public/data/
2. Modify Runtime.ts để load map khác

📚 References

• Spec: hex_td_spec_FINAL.md
• Hex coordinates: Axial system (q, r)
• ECS pattern: Component composition
• Flow field: Multi-source Dijkstra

🐛 Known Issues

• AI behaviors chưa hoàn chỉnh (Runner, Boss)
• Wave system chưa implement
• Skill casting chưa có UI
• Telemetry chưa có
• Editor chưa có

📝 License

MIT

---

Made with ❤️ following the spec exactly