Skip to main content

ic-rudt: GH#10: Tier-2 Spec: Phase 0 Minimal Module

Snapshot: 2026-03-30T08:40:31Z

FieldValue
Statusopen
Assignee(unassigned)
Priority2
Labelsatlas
Created bygithub-bridge
Created2026-03-28T19:00:06Z
Updated2026-03-28T19:00:06Z

Description​

GitHub issue: b4arena/spellkave#10 URL: https://github.com/b4arena/spellkave/issues/10

Context​

This is the integration spec — it brings together decisions from #3 (SpacetimeDB), #4 (Temporal Pacing), #5 (Data Model), and #6 (Rules Engine) into the smallest SpacetimeDB module that proves the Spellkave concept.

PRD Phase 0 Exit Criteria​

A D&D-rule-adjudicated world running for ≥72 hours continuously with ≥3 AI agents; at least 2 emergent cross-agent events documented; observer can follow a 10-minute session without prior context

What Atlas Should Deliver​

A Tier-2 implementation specification covering:

1. Module Scope​

Define exactly what's in the Phase 0 SpacetimeDB module:

  • N tables — the minimum component tables from #5
  • M reducers — the minimum action reducers from #6
  • K scheduled agents — the tick loops (world time, agent behavior, event logging)
  • Public tables — what observers can subscribe to
  • Explicitly list what is NOT in Phase 0

2. AI Agent Design (Phase 0)​

How the 3+ AI agents work:

  • Fast path behavior (scheduled reducers inside SpacetimeDB): patrol, forage, trade, react to immediate threats
  • Slow path behavior (ThinkRequest/ThinkResult for LLM): dialogue, alliance decisions, strategic planning
  • Agent personality — how each agent differs (goals, faction, temperament)
  • Memory — what agents remember and how (MemoryState table, compaction)

3. World Seed​

The initial world state for Phase 0:

  • How many locations? What kind? (a small town, a dungeon, wilderness?)
  • What resources/items exist?
  • What factions? What starting tensions?
  • Enough to produce emergent events but small enough to build in Phase 0

4. Observer Interface​

How an observer follows the world for 10 minutes:

  • Which tables to subscribe to for a "world news feed"
  • The WorldEventLog schema — what makes an event legible
  • A text-based observer view (since text CLI is the reference implementation)

5. The Text CLI (Reference Implementation)​

The first client. Define:

  • Connect to SpacetimeDB module
  • Subscribe to world state
  • Submit actions as a player
  • Read-only mode for observers
  • Technology: TypeScript SDK or Rust SDK

6. Development & Deployment​

  • Local dev setup: spacetime start + spacetime publish
  • Production: self-hosted SpacetimeDB on Mimas
  • CI: module compilation check
  • How to reset/reseed the world during development

Key Reference Material​

SpacetimeDB development​

Closest existing examples​

  • spacetime-mud — text MUD on SpacetimeDB: Rust server + TS frontend + Python AI agent. The closest thing to a tiny Spellkave that already exists.
  • BitCraftPublic agents/ — scheduled reducer patterns for world simulation
  • BitCraft README — how to run a local BitCraft server

PRD context​

  • Phase 0 exit criteria (Section 7)
  • Phase 0 rollback criteria (Section 7)
  • Success metrics (Section 2) — world continuity ≥95%, observer retention ≥8 min

Dependencies​

  • Depends on #3 (SpacetimeDB architecture) — foundational decision
  • Depends on #4 (Temporal Pacing) — tick loop design
  • Depends on #5 (World State Data Model) — table definitions
  • Depends on #6 (Rules Engine) — which rules to implement

This is the final deliverable — once this spec exists, Forge can start implementing.

Acceptance Criteria​

  • Complete table list with SpacetimeDB annotations
  • Complete reducer list with signatures
  • Scheduled agent list with tick rates
  • AI agent behavior specification (fast path + slow path)
  • World seed definition (locations, factions, starting tensions)
  • Observer subscription queries defined
  • Text CLI scope and technology choice
  • Local dev setup instructions
  • Production deployment plan (Mimas)
  • Committed to spellkave repo

Conversation​

github-bridgeMar 28, 08:20 PMsystem
[GH @durandom] ## Addendum: Key Exploration Findings for Phase 0 ### spacetime-mud — The Closest Existing Prototype [github.com/clockworklabs/spacetime-mud](https://github.com/clockworklabs/spacetime-mud) is a text MUD built on SpacetimeDB with: - **Rust server module** (tables + reducers for rooms, items, NPCs, combat) - **TypeScript CLI frontend** (text-based interface using SpacetimeDB TS SDK) - **Python AI agent** (external process that subscribes to world state and acts) This is essentially a tiny Spellkave. Atlas should study this before designing the Phase 0 module — it answers many implementation questions about how a text-based world simulation maps to SpacetimeDB. ### BitCraft Code Walkthrough — Patterns for Phase 0 We read through BitCraft's actual server code. The key patterns for Phase 0: **1. Scheduled reducer self-rescheduling loop** (every agent uses this): ```rust #[spacetimedb::table(name = my_loop_timer, scheduled(my_agent_loop, at = scheduled_at))] pub struct MyLoopTimer { #[primary_key] #[auto_inc] pub scheduled_id: u64, pub scheduled_at: spacetimedb::ScheduleAt, } pub fn init(ctx: &ReducerContext) { ctx.db.my_loop_timer().try_insert(MyLoopTimer { scheduled_id: 0, scheduled_at: duration!(60s).into(), }).ok().unwrap(); } #[spacetimedb::reducer] fn my_agent_loop(ctx: &ReducerContext, _timer: MyLoopTimer) { if !agents::should_run(ctx) { return; } // ... do work ... } ``` **2. Two-phase attack pattern** (action → delayed resolution): - `attack_start` reducer validates and inserts an `AttackTimer` row - SpacetimeDB fires `attack_scheduled` after the delay - Actual damage is applied in the scheduled reducer - This maps to Spellkave's action resolution model **3. Agent init/kill-switch pattern:** ```rust // agents/mod.rs pub fn should_run(ctx: &ReducerContext) -> bool { ctx.db.config().version().find(&0).map_or(false, |c| c.agents_enabled) } pub fn init(ctx: &ReducerContext) { enemy_regen_agent::init(ctx); npc_ai_agent::init(ctx); day_night_agent::init(ctx); // ... 18 agents total } ``` **4. Static data from CSV** — game design constants loaded at build time, read-only reference tables. Separates tuning from code. ### Suggested Phase 0 Module Structure (from exploration) Based on BitCraft + spacetime-mud patterns: ``` spellkave-server/ src/ lib.rs # init reducer, client hooks agents/ mod.rs # should_run(), init() world_tick_agent.rs # time progression, decay, weather npc_behavior_agent.rs # fast-path AI (patrol, trade, react) consequence_agent.rs # cascade effects from events event_log_agent.rs # compaction, observer feed world/ entities/ # impl blocks for table structs handlers/ # player-facing reducers (move, attack, talk, look) rules/ # D&D rules engine trait + 5e implementation messages/ components.rs # ALL table definitions static_data.rs # D&D constants (CSV-loaded) action_request.rs # typed action input structs think/ mod.rs # ThinkRequest/ThinkResult tables + reducers ``` ### Text CLI Reference Implementation Technology recommendation: **TypeScript SDK** (more accessible than Rust CLI, good for onboarding). - `spacetime generate --lang typescript` produces typed bindings from module schema - Follows agentic CLI patterns from issue #11 - Can double as the interface AI agents use via the Python/Rust SDK ### Additional Reference Links **SpacetimeDB dev resources:** - [Rust Quickstart](https://spacetimedb.com/docs/modules/rust/quickstart/) — first module tutorial - [Tables](https://spacetimedb.com/docs/tables/) — schema definition - [Scheduled Reducers](https://spacetimedb.com/docs/tables/schedule-tables/) — tick loop pattern - [Procedures (beta)](https://spacetimedb.com/docs/functions/procedures/) — outbound HTTP for LLM calls - [TS SDK Quickstart](https://spacetimedb.com/docs/sdks/typescript/quickstart/) — for text CLI - [Client Codegen](https://spacetimedb.com/docs/clients/codegen) — `spacetime generate` - [Self-hosting](https://spacetimedb.com/install) — Docker on Mimas **Architecture deep-dives:** - ["Databases are the endgame for DOD"](https://spacetimedb.com/blog/databases-and-data-oriented-design) — must-read on why ECS ⊂ relational - [GDC 2025 talk](https://gdcvault.com/play/1035359/) — "Database-Oriented Design" - [Developer Voices podcast](https://zencastr.com/z/TEsVoQVS) — single-threaded L1-cache beats multithreaded by 100x **BitCraft design blogs** (game design, not just tech): - [#1: A Game of Scales](https://clockwork-labs.medium.com/bitcraft-design-blog-1-37c5b3d14c2e) — character/settlement/empire layers - [#3: Longevity](https://clockwork-labs.medium.com/bitcraft-design-blog-3-d3f23b384f6d) — permanence, economy design - [Combat & Griefing](https://clockwork-labs.medium.com/our-thoughts-on-combat-conflict-and-griefing-in-bitcraft-5786425c2bcc) — PvE-first design