Gameplay Systems
OpenReality ships with a complete game logic toolkit: state machines, events, timers, coroutines, tweens, behavior trees, health/damage, inventory, quests, dialogue, config management, and a debug console. All systems integrate through the EventBus and run automatically in the FSM render loop.
# Game State Machine
The FSM manages distinct game states (menu, playing, paused, etc.). Define concrete states by subtyping GameState, register them with the machine, and let the render loop drive transitions. Transitions support optional guards and callbacks.
# State Callbacks
Each state type can override four lifecycle hooks. Only override the ones you need — defaults are no-ops that return nothing.
# GameContext
GameContext provides a command buffer for deferred entity spawning and despawning. Scripts call spawn! and despawn! during the frame, and the engine flushes all mutations at once via apply_mutations!.
# Prefab System
A Prefab wraps a factory function that returns an EntityDef. Use instantiate to create entity definitions with optional parameter overrides, or spawn! to instantiate and enqueue in one step.
# Event Bus
The EventBus is a global pub/sub system with priority ordering, one-shot listeners, deferred events, listener filters, and event cancellation. Define event types by subtyping GameEvent.
# Game Config
A global key-value store for runtime configuration. Supports typed retrieval, difficulty presets, TOML file loading, and hot-reload during development.
# Timers
One-shot and repeating timers with pause/resume. Entity-scoped timers automatically cancel when the owning entity is despawned.
# Coroutines
Cooperative coroutines for writing sequential game logic that spans multiple frames. Yield by time, frame count, or arbitrary condition. Entity-scoped coroutines auto-cancel on despawn.
# Tweens & Easing
Animate entity properties (position, scale, rotation, color, opacity) with configurable easing curves. Supports looping, ping-pong, chaining, and completion callbacks. 18 built-in easing functions.
# Behavior Trees
Composable AI behavior trees with selector, sequence, parallel, decorator, and action nodes. Each entity gets a per-entity Blackboard for shared state between nodes. Built-in helpers for common patterns like move-to and wait.
# Health & Damage
HealthComponent provides HP tracking, armor, typed damage resistances, knockback, and auto-despawn on death. All damage/heal/death events flow through the EventBus.
# Inventory & Items
A slot-based inventory with a global item registry. Register item definitions once, then place PickupComponent entities in the world. The pickup system handles auto-collection within radius and stacking.
# Quests & Objectives
Define quests with typed objectives (kill, collect, reach location, interact, custom). Progress tracking integrates with the EventBus for automatic advancement. Supports rewards and failure states.
# Dialogue System
Branching dialogue trees with per-choice conditions, callbacks, and auto-advance nodes. The engine handles input processing and UI rendering. Integrates with quests and events.
# Debug Console
An in-game console toggled with the backtick key. Register custom commands, add on-screen watches for real-time values, and use built-in commands for entity inspection and config editing.
# Scene Switching
Return a StateTransition from on_update! to switch states. Providing new_scene_defs rebuilds the entire scene; omitting it preserves the current scene.
# FSM Render Loop
Pass the GameStateMachine to render to launch the engine with automatic state management, scene rebuilding, and all gameplay systems running each frame.