Moddable.Games Tools API

ENDPOINTS

Connect however you want

POST /mcp/messageMCP protocol (JSON-RPC 2025-03-26)

GET /mcpMCP server-sent events (SSE)

POST /api/callREST API — {"tool": "name", "args": {...}}

GET /api/toolsList all tools with input schemas

GET /helpFull API reference (JSON) with all params

GET /help/:toolDetailed docs + curl example for a specific tool

GET /llms.txtAI-readable discovery file

GET /openapi.jsonOpenAPI 3.1 specification

RENDER (PNG)

Visual assets — boards, pieces, tiles as images

GET /api/board.pngRender board — ?fen=...&variant=... or ?board={id}&size=480

GET /api/piece.pngSingle piece — ?set=chessnut&piece=wK&size=128

GET /api/pieces.pngAll pieces in set — ?set=chessnut&size=64 (grid)

GET /api/tile.pngSingle tile — ?set=nukes&tile=grass&size=256

GET /api/tiles.pngAll tiles in set — ?set=nukes&size=128 (grid)

QUICK START

curl -X POST https://tools.moddable.games/api/call \
  -H "Content-Type: application/json" \
  -d '{"tool": "play_create_game", "args": {"family": "mancala", "variant": "oware"}}'

CHESS ENGINE · 11 TOOLS

Chess puzzles: randomised positions filtered by difficulty and theme from the puzzle pool

chess_generate_puzzle

Get a random chess puzzle from the pool. Filter by difficulty or theme.

chess_list_puzzle_types

List available puzzle variants and themes from the puzzle pool

chess_list_variants

[DEPRECATED — use play_list_variants] List chess variants. Removal: v1.0.0.

chess_get_legal_moves

[DEPRECATED — use play_create_game + play_get_moves] Get legal moves for a chess position. Removal: v1.0.0.

chess_analyze_position

[DEPRECATED — use play_suggest_move] Analyse a chess position. Removal: v1.0.0.

chess_make_move

[DEPRECATED — use play_apply_move] Apply a move to a chess game. Removal: v1.0.0.

chess_validate_move

[DEPRECATED — use play_validate_move] Check if a chess move is legal. Removal: v1.0.0.

chess_get_status

[DEPRECATED — use play_check_status] Get chess game status. Removal: v1.0.0.

chess_render_svg

[DEPRECATED — use play_render_board] Render a chess position as SVG. Removal: v1.0.0.

chess_make_moves

[DEPRECATED — use play_make_moves] Apply a sequence of chess moves. Removal: v1.0.0.

chess_get_opening_book

[REMOVED — engine#98] Opening book resolution is broken in Worker context. No replacement.

HEX MAPS · 6 TOOLS

Procedural map generation for 6 strategy games with field-of-view, pathfinding, and SVG export

hex_list_games

List all available hex map game types with configuration options

hex_generate_map

Generate a hex map for a specific game and player count

hex_export_svg

Generate a hex map and export as SVG

hex_get_info

Get info about a specific hex coordinate (terrain, neighbours, distance)

hex_compute_fov

Compute field of view from a hex position

hex_pathfind

Find shortest path between two hex coordinates

UNIVERSAL PLAY · 13 TOOLS

6 game families via universal interface: start, move, check status, get AI recommendations

play_list_families

List all playable game families supported by the engine (chess, draughts, go, reversi, shogi, xiangqi)

play_list_variants

List available variants for a game family. Each variant can be passed to play_create_game.

play_get_definition

Get the full engine definition (topology, render config, pieces, setup FEN) for a game variant. Returns the resolved frontmatter used to render and play the game.

play_create_game

Create a new game instance for a given family. Returns initial state to pass to subsequent calls.

play_get_moves

Get all legal moves for the current position. Requires state from play_create_game or play_apply_move.

play_apply_move

Apply a move to the game and return the new state. Pass the move object exactly as returned by play_get_moves (format varies by family: chess uses {from,to}, go uses {coord} or {action:"pass"}).

play_check_status

Check the current game status: whose turn it is, whether the game is over, and who won.

play_suggest_move

Use AI to analyse the position and suggest the best move. Supports 5 difficulty levels across all 6 playable families.

play_render_board

Render the current board position as SVG for any playable family (chess, draughts, go, reversi, shogi, xiangqi).

play_export_fen

Export the current board position as a FEN-style notation string. Works for all 6 families (chess, draughts, go, reversi, shogi, xiangqi).

play_load_fen

Create a game state from a FEN-style position string. Works for all 6 families.

play_validate_move

Check whether a move is legal in the current position without applying it. Pass the move object in the same format as play_get_moves returns.

play_make_moves

Apply a sequence of moves to a game and return the final state. Stops at the first illegal move. Move objects must match play_get_moves format.

RULES LIBRARY · 5 TOOLS

Full-text search across 46 game rulebooks with variant rules in markdown

rules_list_games

List all available game rulebooks with metadata (players, duration, complexity)

rules_get_game

Get full rulebook content for a specific game

rules_get_variant

Get rules for a specific game variant

rules_search

Full-text search across all published rulebooks

rules_random

Get a random game suggestion from the library

ASSET GALLERY · 9 TOOLS

Pieces (115 sets), boards (333 layouts), and hex tiles (7 sets) — search, browse, and stats for each

board_gallery_search

Search the board gallery (333 rendered board layouts across 33 game families)

board_gallery_get

Get details of a specific board layout by ID

tile_gallery_search

Search hex tile sets by name, game, or terrain type

tile_gallery_get

Get details of a specific tile set with all tile types

tile_gallery_stats

Get statistics about available tile sets

board_gallery_stats

Get statistics about the board gallery (total boards, families, topologies)

piece_gallery_search

Search the piece set gallery by name, style, or game type

piece_gallery_get_set

Get full details and piece list for a specific set

piece_gallery_stats

Get statistics about the piece gallery (total sets, styles, authors, game families)

ORACLES & RPG · 17 TOOLS

10 RPG systems: oracle tables, scene recipes, character generation, encounter building, 3,385 entities

oracle_list_games

List all supported RPG systems with oracle tables and entity data availability

rpg_chargen

Generate a random character for an RPG system (D&D 5e, Pathfinder, Ironsworn, Cairn, Knave, etc)

oracle_roll

Roll on a random oracle table (Ironsworn, Starforged, Maze Rats, etc)

oracle_list_tables

List available oracle tables for a system

oracle_ask

Ask the oracle a yes/no question with likelihood modifier

oracle_scene

Generate a scene using oracle tables. With a recipe, rolls each table in the recipe, resolves cross-references, and composes a narrative sentence. Without, picks random tables.

rpg_search_entities

Search RPG entities (spells, monsters, classes, items) across all systems

rpg_get_entity

Get full details of a specific RPG entity by name

rpg_random_encounter

Generate a random encounter for a system and difficulty level

rpg_browse_category

Browse entities by category with pagination

rpg_loot

Generate random loot/treasure for a system and tier

oracle_list_recipes

List all predefined scene recipes — curated multi-table compositions that produce coherent narrative prompts

oracle_interpret

Resolve oracle cross-references. Given a result like "Action + Theme", follows references and returns expanded results

oracle_table_view

View the complete contents of an oracle table — all entries with roll ranges

oracle_encounter

Generate a tabletop RPG encounter with CR-appropriate monsters, terrain, and loot (D&D 5e or Pathfinder 1e)

rpg_list_categories

List entity categories for an RPG system (spells, monsters, classes, equipment, etc)

rpg_random

Get random entities from an RPG system for inspiration or encounter prep

GAME SESSIONS · 17 TOOLS

TI4 faction drafting and objectives, Nukes setup, Colony odds, card decks (6 types), and Mod Jam

ti4_random_factions

Generate random faction assignments for Twilight Imperium 4th Edition

ti4_draft_factions

Milty-style TI4 draft with pick pools per player

ti4_list_factions

List all TI4 factions with colors, flags, and expansion info

ti4_draw_objectives

Draw random public objectives for TI4

ti4_draw_agendas

Draw random agenda cards for TI4 political phase

nukes_setup_generator

Generate random territory/resource setup for a Nukes game

game_nukes_combat

Resolve a Nukes combat encounter between units

colony_dice_odds

Calculate settlement dice probability for Colony/Catan-style resource numbers

game_deck_create

Create, shuffle, and optionally draw/deal from a card deck

game_deck_list_types

List all available deck types with metadata

game_deck_deal

Shuffle and deal a custom deck of arbitrary named cards

game_score_tracker

Track scores for players in any game

talisman_draw_characters

Draw random characters from the Talisman 4e (revised) base set for a character lottery

talisman_draw_encounter

Draw a random encounter for a Talisman ring (outer, middle, inner, crown)

jam_status

Get the current Mod Jam status (active jam, deadline, submissions)

jam_timer

Get time remaining in the current Mod Jam

jam_vote

Get voting status for the current Mod Jam

UTILITIES · 7 TOOLS

Dice with probability maths, coin flip, team split, turn order, timer suggestions

dice_roll

Roll dice using standard notation (e.g. 2d6+3, 4d8, d20). Supports comma-separated pools and keep-high/low (4d6kh3).

coin_flip

Flip one or more coins, or pick from a list of choices

team_split

Randomly divide players into teams

random_player_order

Randomise turn order for a list of players

timer_suggest

Suggest time controls for a game based on player count and complexity

game_jam_theme

Generate a random game jam theme combining mechanics and themes

dice_odds

Calculate probability of meeting a target with a dice expression. Supports keep-high/low (4d6kh3).

MIGRATION

Chess tools → Generic play tools (6 families, 133 variants)

Eight chess-only tools have been replaced by family-generic equivalents. Deprecated names still work but will be removed in v1.0.0.

Deprecated	Replacement
`chess_list_variants`	`play_list_variants`
`chess_get_legal_moves`	`play_create_game` + `play_get_moves`
`chess_analyze_position`	`play_suggest_move`
`chess_make_move`	`play_apply_move`
`chess_validate_move`	`play_validate_move`
`chess_get_status`	`play_check_status`
`chess_render_svg`	`play_render_board`
`chess_make_moves`	`play_make_moves`
~~chess_get_opening_book~~	Removed (engine#98)

ECOSYSTEM

Static APIs consumed by this service

engine.moddable.games/api/pieces/index.json115 piece sets (SVG) across chess, shogi, xiangqi, Go, draughts, backgammon

engine.moddable.games/api/boards/index.json333 board layouts (SVG) spanning 33 game families

engine.moddable.games/api/tiles/index.json7 hex tile sets (PNG) for strategy maps

engine.moddable.games/api/puzzles/index.json1,876 chess puzzles with FEN, solutions, and difficulty ratings

rules.moddable.games/api/catalogue.json46 games, 296 variants, 177 pages of rules in markdown

rules.moddable.games/api/oracles.json458 oracle tables across 6 RPG systems

rules.moddable.games/api/entities.json3,385+ RPG entities (monsters, spells, items) across 10 systems

rules.moddable.games/api/search-index.jsonFull-text search index across all published rulebooks

EMBEDDABLE WIDGETS

Drop interactive tools into any page — fully customizable via CSS and postMessage

GET /embed/diceDice Lab — 9 wargame simulators (40K, Risk, TI4, A&A, X-Wing, Blood Bowl, Memoir, Custom)

GET /embed/ti4TI4 Tools — faction draft picker + agenda voter with vote tracking

GET /embed/decksCard Decks — shuffle and deal from 6 deck types (standard, hanafuda, mahjong, dominoes...)

GET /embed/talismanTalisman Tools — character lottery + encounter quick-draw for any ring

GET /embed/nukesNukes Tools — combat strength calculator + hostage tracker + unit reference

GET /embed/oraclesOracle Tools — scene forge, table roller, yes/no oracle, thread weaver, encounter builder, RPG library

<iframe src="https://tools.moddable.games/embed/dice?tab=risk"
        width="100%" height="600" style="border:none"></iframe>

// Or with theming via URL params:
/embed/dice?tab=roller&vars={"--embed-bg":"#1a1a2e","--embed-text":"#eee"}

// Or control programmatically via postMessage:
iframe.postMessage({ type: 'moddable:setTab', tab: 'ti4' }, '*')
iframe.postMessage({ type: 'moddable:config', vars: {'--embed-accent':'#ff0'} }, '*')

CLIENT SDK (@moddable/tools-sdk)

One import — API calls, render URLs, and managed embeds with auto-resize

import { ModdableTools } from '@moddable/tools-sdk'
const tools = new ModdableTools({ base: 'https://tools.moddable.games' })

// API calls
const result = await tools.utilities.diceRoll({ notation: '4d6kh3' })
const factions = await tools.games.ti4DraftFactions({ players: 6, hand_size: 3 })

// Managed embeds (auto-resize, theming, event hooks)
const widget = tools.embed.dice('#mount-point', {
  tab: 'risk',
  vars: { '--embed-bg': '#0a0d2a', '--embed-text': '#eee' },
  onResult: (tool, data) => console.log(data),
  onResize: (height) => console.log('height:', height),
})
widget.setTab('ti4')    // switch tab
widget.setVars({...})   // retheme
widget.destroy()        // teardown

// Render URLs (for <img> tags)
const boardUrl = tools.render.boardUrl({ variant: 'chess960', fen: '...' })