Loreloom

A persistent agentic world woven from state and story.

Loreloom is a Rust terminal game in which a Bevy ECS world is the source of gameplay truth and LLM-powered characters act through explicit Tools. Character state, relationships, knowledge, inventory, locations, goals, and other facts that affect future play belong to structured world state instead of being left for a model to remember from prompt history.

The game builds on Armillae, an open-source Rust infrastructure project that provides Bevy ECS simulation, provider-independent LLM calls, and Tool execution. Loreloom is an independent project and owns its game domain, Agent harness, persistence policy, player experience, and TUI. A clean Loreloom checkout must build using publicly resolvable dependencies.

Status

Loreloom now has a playable vertical slice: a directory-owned root world, durable SurrealKV saves, content and rule Mods, a Bevy ECS working world, Narrator/NPC orchestration, declarative gameplay Tools, and a responsive two-pane TUI. Its accepted architecture and active runtime baseline are recorded in:

• Design index
• RFC 0001: persistent agentic world and TUI architecture
• Active runtime specification
• Runtime implementation checklist

RFC 0001 is Accepted and the runtime specification is Active. Deterministic Store shutdown and the physical backup/restore/save-switch APIs remain gated on the configured database driver. Loreloom is distributed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only).

Run

The repository root is a playable world described by world.toml, content/world.json, and prompts/narrator.md. Copy loreloom.example.toml, keep credentials in the named environment variable or a referenced Secret file, and run:

cargo run -p loreloom -- --config loreloom.toml

Interactive play opens the current world's launcher, where you can continue a compatible save, start a new game, inspect Mods and settings, or choose another save. Worlds may start with a fixed player, a preset character choice, or a deterministic UGC character form. Use --save PATH to open an existing save directly or create a new game at that exact path, --world PATH to select another game root, and --headless "your input" for one non-TTY turn. Repeat --mod PATH to enable explicit directory Mod package roots. Merely placing a package below mods/ does not enable it. Existing saves reopen only when both the root WorldLock and enabled extension ModLock match exactly. Worlds and Mods can also provide dynamic layered character appearances under appearance/; see the Mod authoring guide. On a wide terminal the TUI renders the player portrait through the detected Kitty/iTerm2/Sixel protocol, with half-block and text-only fallbacks.

The strict config rejects unknown fields and raw api_key/token values. Custom endpoints also require an exact allowed_endpoint_hosts entry; non-loopback custom endpoints require HTTPS.

Rust policy

Loreloom follows the latest stable Rust toolchain and Rust 2024 edition. The project does not define or test an MSRV and must not add a rust-version compatibility promise.