v3.2.0

AI RPG Engine Build worlds. Simulate them. Improve them.

A TypeScript toolkit for deterministic RPG simulation: a composable module runtime, six-pillar tactical combat, and an optional AI-assisted design library. Every run replays exactly.

Get started Read the Handbook

Install

npm install -g @ai-rpg-engine/cli

Play

ai-rpg-engine run

Scaffold

ai-rpg-engine create-starter my-world

Core Capabilities

What makes AI RPG Engine different.

Deterministic Simulation

Tick-based engine with world state, events, perception, cognition, faction beliefs, rumor propagation, and seeded RNG. Every run can be replayed exactly.

AI-Assisted Worldbuilding

An optional design studio (install @ai-rpg-engine/ollama, run `ai chat`) scaffolds content, critiques designs, and analyzes balance against a local Ollama model — or use it as a library. AI suggests — you decide.

Replay Analysis

Structured findings explain why events happened, where mechanics break down, and which systems create instability. Analysis feeds directly into tuning.

Experiment-Driven Balancing

Run batches of simulations across seeds. Detect variance, sweep parameters, compare tuned vs baseline. Turn world design into a testable process.

Plug-in Profiles

Per-entity rule resolution: a might fighter and a will mystic resolve combat in one fight, each reading stats through its own mapping. 10 starter-derived templates and a profile CLI command.

Six-Pillar Combat

Guard, brace, engagement, interception, precision-vs-force dimensions, and AI tactics. Party ally-targeting, status effects, and DoT/HoT. Stats shape every formula. buildCombatStack wires it in ~7 lines.

30+ Built-In Modules

Combat, tactics, engagement, abilities, status, dialogue, cognition, perception, factions, rumors, districts, progression, environment, and more. All composable, all deterministic.

Genre-Agnostic

Same core runs dark fantasy, cyberpunk, detective noir, or any setting. 10 starter worlds show composition patterns to learn from and remix. Genre belongs to content packs, not the engine.

Optional On-Ledger Play

An opt-in adapter backs coin and tradeable items with real XRPL testnet tokens, settled at checkpoints via XLS-85 token escrow — entirely outside the deterministic core, which never imports it. A run is byte-identical with or without it, and on-chain reconciliation is a genuine external verifier of the economy.

Quick Start

Install

npm install -g @ai-rpg-engine/cli

Play a starter

ai-rpg-engine run

Scaffold your own world

ai-rpg-engine create-starter my-world
ai-rpg-engine scaffold zone town-square

Validate content

ai-rpg-engine validate my-world/content.json

Built-In Modules

30+ composable simulation modules — a representative selection.

Module

Description

combat-core

Hit/damage formulas, guard, defeat, stat-mapped combat

combat-tactics

Brace and reposition actions with AI scoring

combat-states

Guarded, off-balance, exposed, fleeing — with narration

combat-intent

AI action selection with 8 tactical intents and pack biases

combat-resources

Stamina costs, resource gains/drains, AI resource awareness

combat-roles

Boss phases, role templates, encounter builders

engagement-core

Engaged/protected/backline/isolated zones, frontline collapse

defeat-flow

Morale cascades, flee/surrender thresholds, defeat narration

combat-recovery

Post-combat HP/morale/resource restoration

combat-review

Traced formula explanations for balance analysis

dialogue-core

Graph-based dialogue trees with conditions

ability-core

Abilities with cooldowns, costs, targeting, and AI intent

ability-effects

Status application, healing, damage, stat modification

inventory-core

Items, equipment, use/equip/unequip

traversal-core

Zone movement and exit validation

status-core

Status effects with duration and stacking

environment-core

Dynamic zone properties, hazards, decay

cognition-core

AI beliefs, intent, morale, memory

perception-filter

Sensory channels, clarity, cross-zone hearing

narrative-authority

Truth vs presentation, concealment, distortion

progression-core

Currency-based advancement, skill trees

faction-cognition

Faction beliefs, trust, inter-faction knowledge

rumor-propagation

Information spread with confidence decay

district-core

Spatial memory, zone metrics, alert thresholds

belief-provenance

Trace reconstruction across perception/cognition/rumor

observer-presentation

Per-observer event filtering, divergence tracking

simulation-inspector

Runtime inspection, health checks, diagnostics

Design Workflow

Author with the CLI

ai-rpg-engine create-starter my-world
ai-rpg-engine scaffold quest rescue-the-smith

Generate with the AI library

import { createClient, createLocationPack } from '@ai-rpg-engine/ollama';

const client = createClient();
const pack = await createLocationPack(client, {
  theme: 'abandoned mine',
  factions: ['miners_guild', 'deep_crawlers'],
});

Validate & explain

ai-rpg-engine validate my-world/content.json
// or programmatically: explainValidationError(client, err)

Simulate & replay

ai-rpg-engine run
ai-rpg-engine replay --replay   # deterministic re-simulation