Example: Formative Events

This example shows how a single severe event produces two effects: an immediate delta that decays, and a permanent base shift that changes who the person is. We model a betrayal event that reduces Agreeableness and increases Neuroticism.

The Scenario

An individual experiences a major betrayal. In BP terms, this is a formative event: it is intense enough to shift baseline personality traits, not just cause temporary emotional disturbance.

Step 1: Create the Entity

use behaviorsim_rs::entity::EntityBuilder;
use behaviorsim_rs::enums::{EventType, HexacoPath, Species};
use behaviorsim_rs::event::EventBuilder;
use behaviorsim_rs::simulation::Simulation;
use behaviorsim_rs::types::{Duration, EntityId, Timestamp};

let person = EntityBuilder::new()
    .id("riley")
    .species(Species::Human)
    .age(Duration::years(29))
    .build()?;

let anchor = Timestamp::from_ymd_hms(2020, 1, 1, 0, 0, 0);
let mut sim = Simulation::new(anchor);
sim.add_entity(person, anchor);

let riley_id = EntityId::new("riley").unwrap();

Step 2: Apply the Formative Event

The betrayal shifts Agreeableness and Neuroticism. We use with_base_shift to encode permanent change.

// Severe betrayal permanently decreases Agreeableness and increases Neuroticism
let betrayal = EventBuilder::new(EventType::ExperienceBetrayalTrust)
    .target(riley_id.clone())
    .severity(0.9)
    .with_base_shift(HexacoPath::Agreeableness, -0.25)
    .with_base_shift(HexacoPath::Neuroticism, 0.15)
    .build()?;

sim.add_event(betrayal, Timestamp::from_ymd_hms(2020, 8, 1, 0, 0, 0));

Step 3: Query the Long-Term State

Months later, Riley's effective state reflects the permanent base shift.

let handle = sim.entity(&riley_id).unwrap();
let state = handle.state_at(Timestamp::from_ymd_hms(2021, 1, 1, 0, 0, 0));

println!(
    "Agreeableness: {:.2}",
    state.individual_state().hexaco().agreeableness()
);
println!(
    "Neuroticism: {:.2}",
    state.individual_state().hexaco().neuroticism()
);

Why This Matters

• Base shifts persist: The event changes the anchor baseline, not just short-term mood.
• Partial settling: Severe events settle to ~70% of their initial impact over time.
• Personality stability applies: Traits resist change based on their stability parameters.

Use formative events sparingly. Most events should create deltas only. Reserve base shifts for major life transitions, trauma, or long-term role changes.