AI RPG Engine Handbook

A guide to building simulation-driven RPG worlds — from first room to experiment-driven balancing.

Start Here

New to AI RPG Engine? Follow this path:

What AI RPG Engine Is — overview and positioning
Engine Philosophy — deterministic worlds, truth vs presentation
Quick Start — install, run, create your first content

By Topic

Building Worlds

Create rooms, entities, factions, quests, and content packs.

Content Files — how content is structured
Rooms and Zones — spatial design
Entities — NPCs, creatures, players
Dialogue Trees — branching conversations
Items and Status Effects — equipment, consumables, buffs
Equipment — gear types, item provenance, relic growth
Character Profiles — progression state, injuries, reputation
The Chapel Threshold — fantasy starter walkthrough
Neon Lockbox — cyberpunk starter walkthrough

Composing Games

Build your own game from engine pieces.

Composition Guide — the 5-step workflow for building a game
Create Your Own Starter — scaffold a new game from the CLI or template
Plug-in Profiles — per-entity rule resolution: mixed-playstyle combat (shipped v2.5)
Build a Combat Pack — deep combat authoring with buildCombatStack
Tuning Philosophy — what to tune vs leave alone

Combat & Abilities

Powers, statuses, resistances, AI intent, and balance tools.

Combat System — roles, encounters, bosses, engagement, recovery
Abilities System — ability definitions, statuses, resistance, AI scoring, audit

Understanding the Simulation

How the engine processes actions, events, perception, and cognition.

The Simulation Core — tick loop, world state, action pipeline
The Event System — structured events, subscriptions
AI Cognition — beliefs, intent, morale, memory
Perception Layers — sensory channels, clarity, distortion
Narrative Authority — truth vs presentation, unreliable narration

Living Systems

NPC agency, districts, companions, leverage, and strategic play.

NPC Agency — goals, obligations, loyalty breakpoints, consequence chains
District Life — commerce, morale, safety, mood derivation
Companions & Party Dynamics — recruitment, morale, departure risk
Economy, Scarcity & Trade — supply categories, contextual value, faction economic agency
Crafting, Salvage & Item Transformation — materials, recipes, repair, modification, quality bonuses
Quest Webs & Emergent Opportunities — contracts, bounties, favors, supply runs, investigations
Endgames & Campaign Conclusions — arc detection, endgame triggers, resolution classes, finale rendering

Balancing Worlds

Analyze replay data, tune mechanics, run experiments.

AI-Assisted Worldbuilding — scaffold, critique, tune, experiment workflows
Deterministic Replay — reproduce and inspect any session
Observability — runtime inspection, health checks

Using Chat Mode

The interactive design studio.

AI-Assisted Worldbuilding — chat shell commands, guided workflows, studio UX

Diagrams

Simulation Pipeline

action → validation → resolution → events → perception → cognition → faction beliefs → district metrics → economy tick → crafting/salvage → opportunity evaluation → arc detection → endgame evaluation → NPC agency → companion reactions

AI Authoring Pipeline

prompt → scaffold → critique → iterate → session memory

Studio Workflow

build → simulate → analyze → tune → experiment

Full Table of Contents

Part I — Orientation

Part II — Engine Architecture

Part III — Simulation Systems

Part IV — Authoring Games

Part V — Building Modules

Part VI — Starter Examples

Part VII — Character Systems

Part VIII — Debugging and Tools

Part IX — Live Systems

Part X — Composition

Composition Guide — Build your own game by composing engine modules
Create Your Own Starter — Scaffold a new game from the CLI or template
Plug-in Profiles — Per-entity rule resolution: a might fighter and a will mystic in one fight

See also: Profile Roadmap — the original “why profiles” vision doc (Plug-in Profiles shipped in v2.5 — see Chapter 59)

Part XI — Combat Reference

Combat System — Roles, encounters, bosses, recovery, defeat fallout
Abilities System — Definitions, effects, status semantics, builders 49a. Combat Overview — The six pillars, actions, states, authoring map
Combat Tactics — The five actions, soft counters, brace/reposition
Combat States — GUARDED, OFF_BALANCE, EXPOSED, FLEEING
Zone Positioning — ENGAGED, PROTECTED, BACKLINE, ISOLATED, chokepoints
Defeat Flow — Morale cascade, FLEEING, frontline collapse
Precision vs Force — Three stat dimensions, breakthrough, guard counter
Companion Interception — Scored formula, role bonuses, AI cover
Build a Combat Pack — Author guide for buildCombatStack and stat mapping
Tuning Philosophy — What to tune, what to leave alone

Appendix

AI RPG Engine does not tell you what kind of world to build. It gives you the tools to build one that behaves.