Skip to content

README.md

Latest commit

 

History

History
138 lines (100 loc) · 6.58 KB

README.md

File metadata and controls

138 lines (100 loc) · 6.58 KB
Raw

Hex Strategy Map

Hexagonal grid toolkit for Godot 4.6+ with coordinates, pathfinding, fog of war, rendering, and camera controls. The foundation for any hex-based strategy game, tactical RPG, hex-and-counter wargame, hex crawl, or roguelike.

Why this tier

  • Deterministic, JSON-serializable simulation. Logic runs on coordinates and data, with no rendering or hidden randomness — suitable for play-by-email, lockstep multiplayer, headless servers, replays, and AI/ML training environments.
  • One toolkit for the hex fundamentals. Coordinates, pathfinding (Dijkstra + A*), 3-state fog of war with LOS, rendering, batch mode for large maps, and camera — packaged together.

Not for

  • Square or isometric grids — use Godot's built-in TileMap.
  • Free-form 3D movement on meshes — use NavigationServer3D.
  • Real-time action games — designed around turn-based and step-based simulation.

Logic vs rendering

The simulation layer is render-agnostic: HexGrid, HexCell, PathFinder and FogOfWar operate on coordinates and data — no rendering dependency. Drive them from a 3D scene, a headless server, or any custom renderer.

The bundled HexRenderer, BatchHexLayer and MapCamera are the 2D rendering layer (Polygon2D / Sprite2D / Node2D under Camera2D). Examples ship as 2D scenes; replace those modules if you target 3D.

Features

  • HexGrid — Offset and cube coordinates, neighbors, distances, terrain costs, edge costs, LOS
  • HexCell — Cell model with terrain, tag, metadata, per-player fog state, locations
  • PathFinder — Dijkstra and A* pathfinding, reachable hex calculation (O((V+E) log V))
  • FogOfWar — 3-state per-player fog (Hidden/Explored/Visible), LOS-based reveal
  • HexRenderer — Node-per-hex rendering with HexPalette for colors, fog overlays, highlights, edges
  • HexBatchRenderer — Standalone batch renderer for large maps (terrain + fog + highlights with viewport culling)
  • HexPalette — Shared Resource with terrain/fog colors and injectable color_fn
  • MapCamera — Follow target, drag, zoom, edge-scroll

Installation

  1. Copy addons/hex_strategy_map/ into your project's addons/ folder
  2. Enable the plugin in Project → Project Settings → Plugins

Quick Start

# Create a hex grid
var grid := HexGrid.new(12, 12)
grid.generate_cells()

# Render hexes (node-per-hex)
var palette := HexPalette.new()
var renderer := HexRenderer.new(palette, HexGrid.HEX_SIZE)
for coord in grid.cells:
    renderer.create_hex_visual(hex_container, coord, HexGrid.offset_to_pixel(coord), grid.cells[coord])
renderer.render_edges(edge_container, grid)

# Pathfinding (Dijkstra and A*)
var reachable := PathFinder.find_reachable(grid, Vector2i(2, 2), 4.0)
var path := PathFinder.find_path(grid, Vector2i(2, 2), Vector2i(8, 8))
var astar_path := PathFinder.find_path_astar(Vector2i(2, 2), Vector2i(8, 8), grid)

# Fog of war (3 states: HIDDEN, EXPLORED, VISIBLE) per player
var fog := FogOfWar.new(grid)
fog.reveal_around(0, Vector2i(2, 2), 3)
renderer.update_fog(hex_container, grid, 0)

# Batch mode for large maps (200x200+)
var batch := HexBatchRenderer.new(HexPalette.new(), HexGrid.HEX_SIZE)
batch.render(hex_container, grid)

# Camera
var camera_ctrl := MapCamera.new(camera_node)
camera_ctrl.follow(target_node)
camera_ctrl.enable_drag()

Customization

Everything is injectable via constructor parameters and callables:

  • Terrain costs: HexGrid.new(15, 15, custom_cost_table)
  • Edge costs: HexGrid.new(15, 15, {}, 0.0, edge_cost_table)
  • Palette: assign palette.terrain_colors, palette.fog_colors, palette.color_fn and pass to the renderer
  • Renderer callables: HexRenderer.new(palette, hex_size, {"cell_icon_fn": fn, "texture_fn": fn, "animation_fn": fn, "tile_visual_fn": fn, "overlay_fn": fn, "fog_material": mat})
  • Batch rendering: HexBatchRenderer.new(palette, hex_size) for large maps with viewport culling

Classes

Class Base Description
HexGrid RefCounted Grid, coordinates, neighbors, terrain costs, edge costs, LOS
HexCell RefCounted Cell with terrain, tag, metadata, fog state, locations
PathFinder RefCounted Dijkstra + A* pathfinding, reachable hex calculation
FogOfWar RefCounted 3-state per-player fog with LOS reveal
HexRenderer RefCounted Node-per-hex rendering, fog overlays, highlights, edges
HexBatchRenderer RefCounted Batch rendering for large maps
HexPalette Resource Shared color palette with terrain_colors, fog_colors, color_fn
BatchHexLayer Node2D Internal batch layer with viewport AABB culling
MapCamera RefCounted Camera follow, drag, zoom, edge-scroll

Examples

Mini Description
grid_only/ HexGrid + HexRenderer basics
pathfinding/ PathFinder — Dijkstra vs A* vs Flow Field comparison
texture_tiles/ HexRenderer with texture/atlas/animated sprite support

Benchmarks

Microbenchmarks for the free-tier modules live in benchmarks/. Run with godot --headless --script benchmarks/run_benchmarks.gd. See docs/benchmarks.md for reference results and a guide on picking between A*, cached Dijkstra and FlowField.

Testing

~360 automated tests (gdUnit4), free-tier slice:

HexGrid(98) · HexCell(29) · PathFinder(36) · HexRenderer(77) · HexBatchRenderer(22) · HexPalette(17) · BatchHexLayer(12) · MapCamera(14) · FogOfWar(49)

Go Pro

Need unit movement, turn management, flow fields, procedural generation, combat, save/load, or a minimap?

Hex Strategy Map Pro adds:

  • FlowField — Flow field for efficient group movement (one computation serves N units)
  • MapToken — Unit movement with configurable points, path following, signals
  • TurnManager — Turn cycle with player phases and configurable interval hooks
  • MapGenerator — Procedural terrain, rivers, scatterable locations
  • UnitRegistry — Unit tracking by owner, coordinate index, auto-sync, stacking
  • CombatResolver — Pluggable combat with injectable damage, terrain bonus, flanking
  • SaveManager — JSON-based save/load slot management
  • HexMiniMap — Minimap rendering with fog per player and token markers
  • TiledImporter — Import Tiled Map Editor JSON maps

Includes visual map editor (@tool HexMapNode) for in-editor terrain painting and full skirmish demo with 2 players, combat, city capture, fog of war, and victory conditions.

License

MIT — use freely in commercial and non-commercial projects.