Skip to content

Overview

plant_runner is the shared runtime host for all forge-backed schema objects. It provides the infrastructure that plant_world and any future forged crates (plant_area, plant_creature, plant_vehicle, plant_quest) need to participate in the clock-driven frame lifecycle without duplicating that machinery.

Purpose

Before the forge_runner extraction, all of the following lived inside plant_world:

  • FrameManager and frame phase orchestration
  • Clock runtime (tick interval, pause, resume)
  • HookDispatcher for string-keyed lifecycle callbacks
  • KvStore and snapshot storage backends
  • Generic spec upload surface (SpecStore)
  • Brand plugin command channel types
  • Stream event transport types

This conflation forced every consumer of generic host infrastructure to take a dependency on plant_world, pulling in world geometry, spatial types, and region semantics that have nothing to do with running a forged object.

plant_runner separates those concerns cleanly. plant_world now imports them via thin shim modules (pub use plant_runner::...), so no call site in world or its consumers was broken.

Dependency Rule

plant_atom  <-  plant_forge  <-  plant_runner  <-  plant_world
                                                      <-  plant_region (indirectly)

plant_runner must not depend on plant_world or plant_region. It may depend on plant_forge, plant_atom, plant_frame, and anyhow.

Modules

Module Public Types Purpose
clock ClockState, ClockRequest, ClockResponse, ClockAction, ClockStatus Tick interval management, pause/resume, time utilities
frame_manager FrameManager, RegisteredService, ServiceDescriptor, BrandPatchSink Frame phase orchestration, service dispatch
hook_dispatcher HookDispatcher, HookCallback, HookStats, HookExecutionRecord String-keyed lifecycle callback system
storage KvStore, MemoryKvStore, CachedKvStore, SnapshotStore (+ feature-gated backends) Storage seam and backends
spec_store GenericSpecStore (re-exported as SpecStore) Generic (kind, id) -> YAML cache
transport StreamEvent Runtime-facing stream channel message envelope
brand_host BrandHostCommand, HostCommandSink Host command channel for WASM brand components

Feature Flags

Feature Enables
server YamlSnapshotStore (requires tempfile, tokio/fs)
redb RedbSnapshotStore (requires redb crate)

Neither feature is enabled by default. Hosts that need persistent storage opt in via their Cargo.toml:

plant_runner = { path = "../forge_runner", features = ["server"] }

plant_world Shim Pattern

plant_world retains thin shim modules so that all existing call sites remain valid without change:

// world/src/clock/mod.rs
pub use plant_runner::clock::*;

// world/src/frame_manager.rs
pub use plant_runner::frame_manager::*;

// world/src/storage/mod.rs
pub use plant_runner::storage::YamlSnapshotStore;

The world Boundary Specification documents which modules are shims and which remain world-owned.