Example: State Hydration

If you persist genesis state for entities, you can hydrate them later and replay events. This keeps your simulation deterministic while enabling save/load workflows.

Scenario

You store an NPC's initial state at creation time. Later, you load that state and replay stored events to reconstruct current behavior.

Step 1: Load Genesis State

// Load persisted genesis state (your serialization format)
let genesis: GenesisState = load_from_json("npc_001_genesis.json")?;

Step 2: Hydrate the Entity

use behaviorsim_rs::entity::EntityBuilder;
use behaviorsim_rs::enums::Species;

let entity = EntityBuilder::new()
    .id(&genesis.id)
    .species(Species::Human)
    .birth_date(genesis.birth_date)
    .age(genesis.age)
    .hexaco(genesis.hexaco)
    .person_characteristics(genesis.person_characteristics)
    .mood(genesis.mood)
    .needs(genesis.needs)
    .mental_health(genesis.mental_health)
    .social_cognition(genesis.social_cognition)
    .disposition(genesis.disposition)
    .build()?;

Step 3: Replay Events

use behaviorsim_rs::simulation::SimulationBuilder;
use behaviorsim_rs::types::Timestamp;

let mut sim = SimulationBuilder::new(genesis.anchor_timestamp).build()?;

sim.add_entity(entity, genesis.anchor_timestamp);
for event in stored_events {
    sim.add_event(event.event, event.timestamp);
}

let current_state = sim
    .entity(&genesis.id)
    .unwrap()
    .state_at(Timestamp::from_ymd_hms(2024, 6, 1, 0, 0, 0));

Why This Matters

• Deterministic replay: The same genesis + events yields the same state.
• Save/load ready: Store state once, replay deltas later.
• Auditability: You can inspect or diff event logs over time.