Documentation

Everything you need to add new games, configure board rendering, and extend the engine with new topologies or plugins.

What is Moddable Engine

A universal game engine where games are configuration files, not code. Any game expressible as a combination of topology, rules, pieces, and setup can be defined entirely in YAML frontmatter. The engine handles rendering, move validation, state management, and AI.

How games are defined

Every game variant lives as a Markdown file in moddable-rules with an engine: block in its YAML frontmatter. This block tells the engine everything it needs: what topology to use, how to render the board, where pieces start, and what rules apply.

---
title: Standard Chess
engine:
  topology:
    type: grid
    rows: 8
    cols: 8
  surface: parchment
  render:
    cellColor: checkered
    labels: true
    ops:
      - op: cells
        pattern: checkered
  setup: rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR
  pieces:
    set: mce-chess
---

The engine reads this frontmatter, resolves it through a cascade (surface defaults, family defaults, variant overrides), and produces a complete game definition or rendered board diagram.

Architecture at a glance

The engine is organised into layers. Each layer depends only on the layers below it.

┌─────────────────────────────────────────────┐
│  Frontmatter (YAML in moddable-rules)       │  ← game definitions
├─────────────────────────────────────────────┤
│  Schema (parse, validate, produce, cascade) │  ← turns YAML into objects
├─────────────────────────────────────────────┤
│  Plugins (chess, go, mancala, ...)          │  ← game-specific logic
│  Topologies (grid, hex, track, pit, graph)  │  ← spatial structure
│  Rules (castling, capture, turn-flow, ...)  │  ← composable behaviours
├─────────────────────────────────────────────┤
│  Core (state, events, pipeline, registry)   │  ← micro-kernel
└─────────────────────────────────────────────┘

Key concepts

• Topologies are the universal adapter. Every package above topologies defines a contract. Topologies implement it. Higher packages never know which topology they consume.
• Five resource types: topology (spatial), component (operational), rule (behavioural), theme (visual), setup (initial state).
• No game names in source. Core, render, schema, and topology code never reference specific games.
• Moves are opaque. Core passes moves to plugins without inspecting contents.
• Rules compose. Parametric, topology-agnostic rules that combine freely (castling + check + promotion = chess endgame).

Guides

Page	Section	Covers
Authoring a Variant	Guides	Writing a variant from scratch, step by step
Frontmatter	Guides	The engine block: topology, render, pieces, setup notation
Topologies	Guides	Grid, hex, track, pit, graph, tableau and more: fields and coordinates
Surfaces	Guides	Named surfaces and colour customisation
Piece Sets	Guides	Gallery index format, virtual sets, extends, surfaces
SDK	Guides	Every family through one headless SDK, and what each supports
Plugins	Guides	Plugin structure, hooks, registry, adding a family
Families on Shared Plugins	Guides	Naming the plugin that plays a family, and the keys each shared plugin reads
Render Pipeline	Guides	How frontmatter becomes an SVG board
Chess	Families	Chess SDK, embed, variant parameters, AI and puzzles
Go	Families	Go SDK, embed and variants
Draughts	Families	Draughts SDK, embed and variant keys
Hex	Families	Hex connection games: embed, variants, AI
Mancala	Families	Mancala sowing games: embed and variant keys
Morris	Families	Morris mill games: embed and variant keys
Xiangqi	Families	Xiangqi SDK, embed and variants
Shogi	Families	Shogi SDK, embed, drops and variants
Reversi	Families	Reversi: embed and variants
Landlord's Game	Families	The Landlord's Game: embed and editions
Backgammon	Families	The tables games: dice, variant keys, AI
Race Games	Shared Plugins	Routes, declared randomisers and landing rules: Ur, Senet, Nyout, Pachisi, Chaupar
Hopping Games	Shared Plugins	Steps, chained hops, goal camps and asymmetric seats: Halma, Stern-Halma, Asalto
Cards, Tiles and Dice	Shared Plugins	Every card, tile and dice game, and hidden hands
Hex Maps	Tools	Hex map generators and tile styles

Current coverage

The engine renders boards for 335 game variants across 34 families and 8 topology types, plus 3 RPG systems (D&D 5e, Ironsworn, Starforged) via manifest-driven oracle/entity providers. 30 families (agon, asalto, backgammon, bavarian-32, chaupar, chess, dou-shou-qi, double-six-dominoes, draughts, fanorona, flower-48, go, halma, hex, the Landlord's Game, mahjong, mancala, morris, nyout, pachisi, reversi, royal-ur, senet, shogi, standard-52, standard-dice, stern-halma, surakarta, tafl, xiangqi) are fully playable with move execution, AI, embed protocol, and SDK.

Component	Status	Tests
Schema (parse, validate, produce)	Complete	113
Core (state, pipeline, events)	Complete	157
Topologies (6 types)	Complete	165
Plugins (13 families)	Complete	375
Rules (composable, parametric)	Complete	118
Render (SVG generation)	Complete	34
Board diagrams (293 variants)	Complete	293 snapshots
RPG providers (3 systems)	Complete	Manifest-driven
Play (frontend integration)	In progress	—