World State & Lifecycle

Relevant source files

The following files were used as context for generating this wiki page:

• crates/cyrus-world/src/lib.rs
• crates/cyrus-world/src/lifecycle.rs
• crates/cyrus-world/src/transform.rs
• crates/cyrus-session/src/lib.rs
• crates/cyrus-web/src/debug.rs

World State & Lifecycle manages the transitions, preparation, and persistent data of the game worlds. The system coordinates the asynchronous loading of assets—including scripts, models, and environments—while maintaining logical continuity across world swaps through session snapshots.

The lifecycle ensures that a running world remains active until all dependencies of a destination world are fully prepared. It handles state synchronization for actors, player placement, and environmental effects to maintain a faithful reproduction of the original game experience.

Sources: crates/cyrus-world/src/lifecycle.rs, crates/cyrus-session/src/lib.rs:41-61, crates/cyrus-web/src/debug.rs:32-55

World Preparation and Loading

The preparation process converts requests into staged worlds by loading essential sidecar assets. A PreparedWorld acts as a container for asset handles, including scripts, animations, and scene paths.

Preparation Flow

When you request a new scene, the system inserts a WorldPreparationPending resource and stages the destination. The current scene is only replaced once all handles in the StagedWorld report a loaded state.

The system uses CurrentScene to track the active world index and name. If a load fails, the system reports a SceneLoadError and retains the existing world.

Sources: crates/cyrus-world/src/lifecycle.rs, crates/cyrus-web/src/debug.rs:40-62, crates/cyrus-web/src/debug.rs:115-135

Session State and Snapshots

Session state captures the logical and physical state of the world for persistence and restoration. The RuntimeSessionSnapshot serves as the primary data structure for storing world state, player information, and logical actor data.

Snapshot Components

Component	Description
lifecycle	Stores current scene names and preparation hints.
logical	Contains script actor states, global flags, and visited world records.
player	Captures entity ID, pose, placement markers, and controller runtime state.
entity_bindings	Maps saved entity IDs to active logical actors.
environment_edits	Retains per-world console edits for sky and water parameters.

Sources: crates/cyrus-session/src/lib.rs:41-65, crates/cyrus-session/src/lib.rs:420-435

Restoration Lifecycle

The restoration process follows a "Plan-Finish-Commit" pattern to ensure atomicity.

1. Plan: The system validates logical identities and source identities against the snapshot.
2. Finish: The system prepares service replacements (audio, HUD, dialogue) without replacing live resources.
3. Commit: The SessionBoundary applies the candidate state to the live world, replacing active entities and resources.

Spatial State and Transforms

The transform module manages the positioning and orientation of world objects. It uses a custom Matrix structure to handle 3D rotations and translations derived from original game data.

Matrix and Coordinates

The system operates on local and effective transforms.

• Local Matrix: Represents the specific rotation/scale of an entity.
• Position: Stored as 3D integer coordinates, often requiring quantization or scaling for rendering.

pub struct Matrix {
    pub rows: [[f32; 3]; 3],
}

impl Matrix {
    pub const IDENTITY: Self = Self {
        rows: [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]],
    };
}

Sources: crates/cyrus-world/src/transform.rs:1-20, crates/cyrus-session/src/lib.rs:480-495

Platform Navigation

The lifecycle adapts to platform-specific constraints, particularly for web environments. Since browsers lack native background preparation threads, the web implementation swaps world caches using a StagedWorld resource.

Web World Updates

When you select a world in the browser:

1. The system identifies the requested name.
2. It loads sidecars (animations, scripts, player data) via the AssetServer.
3. It updates the browser URL parameters (e.g., ?scene=ISLAND) to reflect the new state without a full page reload if configured.

Sources: crates/cyrus-web/src/debug.rs:32-75, crates/cyrus-web/src/debug.rs:145-165

Conclusion

The World State & Lifecycle system ensures robust world transitions by separating logical preparation from physical commitment. By using a multi-stage loading process and comprehensive session snapshots, it maintains the consistency of scripts, actor states, and environmental configurations across different game sessions and platforms.

Sources: crates/cyrus-world/src/lifecycle.rs, crates/cyrus-session/src/lib.rs