Documentation

Overview

Moddable Hexmaps is a shared hex map rendering engine and randomiser framework. It supports six board games out of the box and can be extended with custom game configs.

Three ways to integrate: embed via iframe (Embedding), mount directly via JavaScript (Consumer SDK), or query from an AI assistant (MCP Server).

URL Parameters

Control the generator via query parameters:

Parameter	Values	Description
`game`	nukes, talisman, twilight, colony, mongo, endless	Which game to generate
`seed`	any string	RNG seed for reproducible maps
`size`	2–6 (nukes), 4–5 (talisman)	Ring count / map size (hidden when layouts used)
`players`	2–8 (varies by game)	Player count for base placement
`style`	artistic, classic, kenney, realistic	Visual style (see API docs for per-game availability)
`layout`	varies per game	Board layout variant (Twilight: 3p–8p; Colony: standard, expanded, newWorld, newShores, fourIslands, desert, fogIslands)
`boardonly`	1	Hide all UI chrome, show only the map canvas
`bg`	hex colour (e.g. 1a1a2e or #1a1a2e)	Background colour for the canvas area
`mode`	view, edit, fullscreen	view = read-only (no click editing); edit = interactive; fullscreen = full-viewport map display

Embedding

Embed a hex map in any page using an iframe. Use boardonly=1 to strip navigation, sidebar, and footer, leaving just the map canvas that fills the iframe.

Basic embed

<iframe
  src="https://hex.moddable.games/generate/?game=nukes&boardonly=1&seed=42&size=4"
  width="600"
  height="400"
  frameborder="0"
></iframe>

Custom background

Pass bg= to match your site's background. Hex colours can omit the # prefix for cleaner URLs.

<iframe
  src="https://hex.moddable.games/generate/?game=twilight&boardonly=1&bg=0d1117&players=6"
  width="600"
  height="600"
  frameborder="0"
></iframe>

Read-only vs interactive

By default, boardonly=1 embeds are read-only. Add mode=edit to allow click-to-cycle terrain editing inside the embed.

<iframe
  src="https://hex.moddable.games/generate/?game=nukes&boardonly=1&mode=edit&size=3"
  width="500"
  height="400"
  frameborder="0"
></iframe>

Full page (no embed)

Without boardonly, the full UI is shown. Useful for linking users to the generator directly:

https://hex.moddable.games/generate/?game=nukes&size=4&seed=42

Fullscreen mode

Add mode=fullscreen to display the map at full viewport size with all chrome hidden. An Exit button appears in the top-right corner, and pressing Escape also exits. The fullscreen button in the canvas footer bar activates this from the normal generate view.

https://hex.moddable.games/generate/?game=twilight&mode=fullscreen&players=6

Consumer SDK

Embed and control hex maps programmatically without iframes. The SDK provides a createMapController factory that mounts an interactive canvas into any container element.

import './js/hex-controller-entry.js';

const map = HexApp.createMapController(container, {
  game: 'nukes', seed: '42', size: 4, players: 4
});
map.on('hexClick', (e) => console.log(e.hex));

Full reference: API docs | Live demo

Games

Nukes

Nuclear war hex maps with 5 map sizes (2–6 rings). Terrain types: water, forest, mountain, plains, desert, and player HQ bases. Supports 2–6 players with pre-defined base positions per map size.

Talisman Worlds

Hex adaptation of the Talisman board game. Uses concentric rings: inner (crown), middle, river, outer, and optional dungeon ring. Each ring has its own terrain palette. Styles: artistic (illustrated tiles with descriptions), classic (flat colours), kenney (Kenney Hexagon Pack), realistic (Screaming Brain terrain textures).

Twilight Imperium

Galaxy generator for TI4. Seven layout variants from 3-player to 8-player (including Prophecy of Kings expansion and Hyper Imperium). Tile types: blue (planet systems), red (anomalies), green (home systems), lanes (hyperlanes), and legends.

Colony

Hex board generator inspired by Settlers of Catan. 7 layouts: standard (19 hex), expanded (30 hex, 5-6 players), and 5 Seafarers scenarios (New World, Four Islands, New Shores, Through the Desert, Fog Islands). Sea frame, port placement, number token overlays with 6/8 non-adjacency constraint. Terrain: forest, pasture, fields, hills, mountains, desert, sea, gold, fog. Styles: classic (flat colours), kenney, realistic.

Planet Mongo

Territory control generator set on the Flash Gordon planet. 6-ring board (127 hexes) with 8 factions placed at fixed positions on ring 4. Each faction has starting tiles clustered around their home city, with remaining tiles placed by proximity. Biomes: oceanic, submerged, glacial, volcanic, mountain, woodland, desert, jungle. Central market tile. Supports 2-8 players. Styles: classic (flat colours), kenney, realistic.

Endless Skies

4X space exploration galaxy generator based on the Endless Sky video game. 8 asymmetric factions with home systems, faction regions, wormhole networks (4 types), asteroid fields, and nebulae. Three layout sizes: compact (4 rings, 2-3 players), standard (5 rings, 4-6 players), grand (6 rings, 7-8 players). System types: homeworld, core, frontier, rim, contested, nebula, asteroid, wormhole, void.

MCP Server

The engine is available as an MCP (Model Context Protocol) server for AI assistants. Six tools expose generation, analysis, and SVG export.

node mcp/server.js                    # standalone stdio server
claude mcp add moddable-hexmaps node mcp/server.js  # Claude Code

Tools: hex_list_games, hex_generate_map, hex_get_info, hex_compute_fov, hex_export_svg, hex_pathfind

Full reference: API docs

Architecture

js/game-registry.js      — Plugin registry (HexApp.registerGame API)
js/app.js                — Framework controller (sidebar, tabs, URL, embed bridge)
js/hex-controller.js     — Consumer SDK (createMapController factory)
js/hex-controller-entry.js — Convenience bundle (all games + window.HexApp)
js/games/                — Game plugins (one file per game)
  nukes.js               — Nukes: terrain gen, editor, ring-format export
  talisman.js            — Talisman: ring-based terrain pools
  twilight.js            — Twilight Imperium: multi-layout tile draw
  colony.js              — Colony: terrain + number tokens with constraints
  mongo.js               — Planet Mongo: fixed 127-hex faction board
  endless.js             — Endless Skies: sector-based galaxy generator
js/xorshift.js           — Seeded PRNG (XorShift128)
js/hex-math.js           — Axial coordinate math, grid generation
js/hex-renderer.js       — Canvas-based hex rendering
js/hex-svg.js            — SVG serialiser (export, postMessage, annotations)
mcp/tools.js             — MCP tool definitions + handler
mcp/server.js            — Standalone stdio JSON-RPC server
data/                    — Game data files (coordinate maps, tile pools)
img/tiles/               — Committed tile images per game and style

Each game is a self-contained plugin file that calls HexApp.registerGame(key, config). The framework auto-generates the game selector tabs from the registry and delegates all game-specific behaviour to plugin hooks.

Plugin System

Add a new hex game by creating a file in js/games/ that calls HexApp.registerGame(). The game auto-appears in the tab bar with zero changes to framework code.

Minimal game plugin

HexApp.registerGame('mygame', {
    label: 'My Game',
    orientation: 'pointy',
    sizes: [{ value: 3, label: '3 Rings' }],
    defaultSize: 3,
    defaultPlayers: 0,
    styles: null,
    hasEditor: false,

    playerCounts: function(size) { return []; },

    generate: function(size, players, seed) {
        var rng = createSeededRng(seed + '_mygame');
        var grid = HexMath.generateHexGrid(size);
        return grid.map(function(h, i) {
            return {
                id: 'R' + h.ring + 'D' + i,
                q: h.q, r: h.r,
                type: 'default',
                label: 'D'
            };
        });
    },

    getColors: function(style) {
        return { default: '#4CAF50' };
    }
});

Available hooks

Hook	Required	Description
`generate(size, players, seed, layout)`	Yes	Return hex data array for the given params
`getColors(style)`	Yes	Return terrain→colour map for given visual style
`playerCounts(size)`	Yes	Return array of valid player counts for size
`onHexClick(hex)`	No	Handle click on a hex (e.g. cycle terrain). Return modified hex
`editorPanel(container, state)`	No	Build custom editor UI. `state.resetRing(ring, terrain)` available
`exportForParent(hexData, meta)`	No	Custom export format for postMessage embed bridge
`importFromParent(data)`	No	Parse incoming data from parent app
`importMap(data, hexData)`	No	Handle non-standard import format (e.g. ring-format)
`getImages(style)`	No	Return terrain→image path map for tile rendering, or null for flat colours
`constraints(hexData)`	No	Return true if valid, false to re-generate with incremented seed (max 100 retries)
`rendererOptions(size)`	No	Return `{ hexSize, flat }` overrides

Config properties

Property	Type	Description
`label`	string	Display name in the game tab bar
`orientation`	'pointy' \| 'flat'	Hex orientation for this game
`sizes`	array	`[{ value: N, label: 'text' }]` — available map sizes
`defaultSize`	number	Initial map size
`defaultPlayers`	number	Initial player count
`styles`	array \| null	`['artistic', 'classic', 'kenney']` — alphabetically sorted, or null to hide style selector
`layouts`	array \| null	`[{ value: '6p', label: '6 Players' }]` — layout variants (hides size selector when present)
`defaultLayout`	string	Initial layout value when layouts defined
`hasEditor`	boolean	Show the Editor sidebar tab for this game
`labels`	boolean	Set to `false` to hide hex labels in classic mode (default: true)

Coordinate System

Uses axial coordinates (q, r) with ring-based generation. The centre hex is always (0, 0). Each ring N contains 6×N hexes arranged around the centre.

Supports both pointy-top (Nukes, Talisman) and flat-top (Twilight) orientations.

Sister Projects

Moddable Hexmaps is part of the Moddable Engines family:

Moddable Chess — 30+ chess variants with full move generation, AI, and embeddable SVG renderer
All Engines — browse the full collection