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

Guide	Audience	Covers
Frontmatter Schema	Game authors	Writing engine: blocks, topology options, render config, setup notation
Topologies	Game authors / Engine devs	Grid, hex, track, pit, graph — fields, defaults, coordinate systems
Surfaces	Game authors	Named surfaces (parchment, slate, etc.), colour customisation
Piece Sets	Game authors / Artists	Gallery index format, virtual sets, extends, surface rendering
Plugins	Engine devs	Plugin structure, hooks, registry, adding new game families
Render Pipeline	Engine devs	Frontmatter → cascade → produceLayout → topology renderer → SVG
Chess	Consumers	Embed protocol, SDK reference, 100 variants, AI, puzzles API
Go	Consumers	Embed protocol, SDK reference, 9 variants, territory/area scoring, AI
Draughts	Consumers	Embed protocol, SDK reference, 13 variants, parametric capture rules
Shogi	Consumers	Embed protocol, SDK reference, 5 variants, drops, promotion zones
Xiangqi	Consumers	Embed protocol, SDK reference, 3 variants, palace/river/cannon rules
Hex Maps	Consumers	Embed protocol, SDK reference, 6 games, seeded generation, tile sets

Current coverage

The engine renders boards for 333 game variants across 33 families and 6 topology types, plus 3 RPG systems (D&D 5e, Ironsworn, Starforged) via manifest-driven oracle/entity providers. Six families (chess, draughts, go, shogi, xiangqi, reversi) 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	—