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

Current coverage

The engine currently handles board rendering for 284 game variants across 42 families and 5 topology types. Play (move execution, AI) is architecturally complete but not yet wired to the frontend.

Component	Status	Tests
Schema (parse, validate, produce)	Complete	113
Core (state, pipeline, events)	Complete	157
Topologies (5 types)	Complete	165
Plugins (13 families)	Complete	375
Rules (composable, parametric)	Complete	118
Render (SVG generation)	Complete	34
Board diagrams (284 variants)	Complete	284 snapshots
Play (frontend integration)	In progress	—