jpmschweitzer/settled-reach
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(simulation): Sprint 19 — 7 server systems

Browse Source 
Protocol handshake (#555): HandshakeMessage as first IPC frame,
HandshakeState resource, forward-compatible input handling.

State serialization (#96): serialize_npc_to_frozen/deserialize with
full D-024 axis coverage (10 new optional fields on NpcSaveState).

Scope tags (#98): ScopeTagKind enum, ScopePinned marker, automatic
assignment from KnowledgeGraph and RelationshipGraph.

Timestamp eviction (#97): LastInteractionTick, SimSpacePressure,
BinaryHeap LRU eviction respecting ScopePinned entities.

Save/load (#553): save_to_file/load_from_file via MessagePack,
SaveGame/LoadGame IPC commands, SaveLoadResultWire on snapshot.

Test infrastructure (#200): Layer 3 integration test entry point,
three-layer architecture documented per D-030.

Information boundary tests (#272): 4 negative tests proving no
passive KG leakage, LOS fog holds, tier boundary holds, save
isolation per NPC.

1063 tests passing, 0 failures.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
jpmschweitzer
2026-02-25 12:13:03 +01:00
co-authored by Claude Opus 4.6
parent 0dd33690f7
commit 6ed8d11502
22 changed files with 2561 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
server/src/simulation/input.rs
+30 -4
View File
@@ -9,6 +9,7 @@ use crate::simulation::inventory::{
find_next_slot, occupied_slots_for, CarriedBy, InventorySlot, ItemName, MAX_INVENTORY_SLOTS,
};
use crate::simulation::movement::{MoveIntent, PlayerCharacter, TilePosition};
use crate::simulation::save_io::{SaveLoadCommand, SaveLoadPending};
use crate::simulation::stance::{PlayerMoveCooldown, Stance};
use crate::simulation::time::{SimulationTime, TickRate};
use crate::test_world::reset::{RoomResetTrigger, RoomSnapshots};
@@ -74,7 +75,8 @@ impl InputQueue {
}
/// Drains InputQueue for the current tick, converts PlayerActions to ECS components.
/// Handles stance toggling (D-053), movement cooldown, and Take/Place verbs (#424).
/// Handles stance toggling (D-053), movement cooldown, Take/Place verbs (#424),
/// and save/load commands (#553).
#[allow(clippy::type_complexity, clippy::too_many_arguments)]
pub fn process_player_input(
mut input_queue: ResMut<InputQueue>,
@@ -94,6 +96,7 @@ pub fn process_player_input(
all_positions: Query<&TilePosition>,
reset_triggers: Query<&RoomResetTrigger>,
mut room_snapshots: Option<ResMut<RoomSnapshots>>,
mut save_load: Option<ResMut<SaveLoadPending>>,
) {
let current_tick = time.tick;
let paused = time.paused();
@@ -104,12 +107,15 @@ pub fn process_player_input(
for input in inputs {
// Discard all gameplay actions while paused (D-052, R2-OQ-01).
// Only Pause/Unpause/TeleportToHub are processed — everything else is discarded.
// TeleportToHub is exempted because it's a Gauntlet QA action (#491).
// SaveGame/LoadGame are also exempted — saving while paused is valid (#553).
if paused
&& !matches!(
input.action,
PlayerAction::Pause | PlayerAction::Unpause | PlayerAction::TeleportToHub
PlayerAction::Pause
| PlayerAction::Unpause
| PlayerAction::TeleportToHub
| PlayerAction::SaveGame { .. }
| PlayerAction::LoadGame { .. }
)
{
continue;
@@ -306,6 +312,26 @@ pub fn process_player_input(
PlayerAction::UsePerceptionMode(ref mode) => {
tracing::trace!("UsePerceptionMode({}) — no-op for Sprint 1", mode);
}
PlayerAction::SaveGame { ref path } => {
if let Some(ref mut sl) = save_load {
sl.pending = Some(SaveLoadCommand::Save {
path: std::path::PathBuf::from(path),
});
tracing::info!("SaveGame queued: {:?}", path);
} else {
tracing::warn!("SaveGame received but SaveLoadPending resource not registered");
}
}
PlayerAction::LoadGame { ref path } => {
if let Some(ref mut sl) = save_load {
sl.pending = Some(SaveLoadCommand::Load {
path: std::path::PathBuf::from(path),
});
tracing::info!("LoadGame queued: {:?}", path);
} else {
tracing::warn!("LoadGame received but SaveLoadPending resource not registered");
}
}
}
}
server/src/simulation/mod.rs
+8
View File
@@ -22,6 +22,7 @@ pub mod poi;
pub mod poi_discovery;
pub mod pressure;
pub mod rng;
pub mod save_io;
pub mod save_state;
pub mod sound;
pub mod spatial;
@@ -43,6 +44,7 @@ impl Plugin for SimulationPlugin {
app.init_resource::<time::SimulationTime>()
.insert_resource(rng::SimRng::new(0))
.init_resource::<input::InputQueue>()
.init_resource::<save_io::SaveLoadPending>()
.init_resource::<crate::knowledge::EntityRegistry>()
.init_resource::<sound::SoundEventQueue>()
.init_resource::<spatial::NaiveSpatialIndex>()
@@ -61,6 +63,12 @@ impl Plugin for SimulationPlugin {
Update,
(
input::process_player_input,
// execute_save_load is an exclusive system (takes &mut World).
// Must run after process_player_input (which queues the command)
// and before compute_observer_snapshot (which consumes the result).
save_io::execute_save_load
.after(input::process_player_input)
.before(crate::perception::observer::compute_observer_snapshot),
pathfinding::compute_paths.after(input::process_player_input),
path_follow::follow_paths.after(pathfinding::compute_paths),
movement::validate_movement.after(path_follow::follow_paths),
server/src/simulation/save_io.rs
+629
View File
@@ -0,0 +1,629 @@
// Save/load ECS extraction (#553)
// Implements D-020 MessagePack format for save files, D-010 determinism.
//
// Two entry points:
// save_to_file: queries ECS, builds SaveStateV1, writes MessagePack to path.
// load_from_file: reads path, deserialises SaveStateV1, re-injects ECS state.
//
// IPC: SaveGame / LoadGame PlayerAction variants queue commands here.
// execute_save_load: exclusive system that drains the queue and writes the result
// to SnapshotBuffer.pending_save_result for client feedback.
use std::path::{Path, PathBuf};
use bevy_ecs::prelude::*;
use thiserror::Error;
use crate::bridge::types::SaveLoadResultWire;
use crate::bridge::types::SnapshotBuffer;
use crate::knowledge::graph::KnowledgeGraph;
use crate::knowledge::registry::EntityRegistry;
use crate::npc::Npc;
use crate::npc::relationships::RelationshipGraph;
use crate::simulation::movement::PlayerCharacter;
use crate::simulation::rng::SimRng;
use crate::simulation::save_state::{
deserialize_npc_from_frozen, serialize_npc_to_frozen, SaveStateV1, SAVE_FORMAT_VERSION,
};
use crate::simulation::tier::BackgroundSim;
use crate::simulation::time::SimulationTime;
/// Errors from save/load operations (#553).
#[derive(Debug, Error)]
pub enum SaveLoadError {
#[error("I/O error: {0}")]
Io(String),
#[error("serialization error: {0}")]
Serialize(String),
#[error("deserialization error: {0}")]
Deserialize(String),
#[error("format version mismatch: expected {expected}, found {found}")]
VersionMismatch { expected: u8, found: u8 },
}
/// A queued save or load command (#553).
#[derive(Debug, Clone)]
pub enum SaveLoadCommand {
Save { path: PathBuf },
Load { path: PathBuf },
}
/// Pending save/load command resource (#553).
///
/// `process_player_input` queues commands here when it encounters
/// `PlayerAction::SaveGame` or `PlayerAction::LoadGame`. The
/// `execute_save_load` exclusive system drains this queue each tick.
#[derive(Resource, Debug, Default)]
pub struct SaveLoadPending {
/// Pending command (at most one; new commands overwrite pending ones).
pub pending: Option<SaveLoadCommand>,
}
/// Extract world state into `SaveStateV1` and write MessagePack bytes to `path` (#553).
///
/// Queries all NPC entities, the player knowledge graph, global relationship graph,
/// simulation time, and RNG seed. Builds `SaveStateV1` and writes to disk.
///
/// NPC states are sorted by `stable_id` ascending for determinism (D-010).
/// NPCs without `StableEntityId` trigger a panic (caller invariant — all live
/// NPCs must be registered before save).
///
/// # Errors
/// `SaveLoadError::Io` on filesystem failure.
/// `SaveLoadError::Serialize` on MessagePack encoding failure.
pub fn save_to_file(path: &Path, world: &mut World) -> Result<(), SaveLoadError> {
// Simulation clock
let (tick, tick_rate) = {
let t = world.resource::<SimulationTime>();
(t.tick, t.tick_rate)
};
// RNG seed for deterministic replay (D-010)
let seed = world.resource::<SimRng>().seed();
// Player knowledge graph — the observer's epistemics at save time
let player_knowledge = {
let mut q = world.query_filtered::<&KnowledgeGraph, With<PlayerCharacter>>();
q.single(world)
.cloned()
.unwrap_or_else(|_| KnowledgeGraph::new())
};
// Global NPC social web
let relationship_graph = world.resource::<RelationshipGraph>().clone();
// Per-NPC states: collect then sort by stable_id (D-010 determinism)
let npc_entities: Vec<Entity> = {
let mut q = world.query_filtered::<Entity, With<Npc>>();
q.iter(world).collect()
};
let mut npc_states: Vec<_> = npc_entities
.iter()
.map(|&entity| serialize_npc_to_frozen(entity, world))
.collect();
npc_states.sort_by_key(|s| s.stable_id.0);
let npc_count = npc_states.len();
let state = SaveStateV1 {
format_version: SAVE_FORMAT_VERSION,
tick,
tick_rate,
seed,
player_knowledge,
relationship_graph,
npc_states,
};
let bytes = state
.to_bytes()
.map_err(|e| SaveLoadError::Serialize(e.to_string()))?;
std::fs::write(path, &bytes).map_err(|e| SaveLoadError::Io(e.to_string()))?;
tracing::info!(
"save_to_file: {:?} (tick={}, npcs={}, {} bytes)",
path,
tick,
npc_count,
bytes.len()
);
Ok(())
}
/// Read `path`, deserialise `SaveStateV1`, and re-inject state into the ECS (#553).
///
/// Steps:
/// 1. Read and deserialise bytes; reject if `format_version != SAVE_FORMAT_VERSION`.
/// 2. Despawn all existing NPC entities and unregister them from `EntityRegistry`.
/// 3. Re-spawn each NPC via `deserialize_npc_from_frozen`; register with
/// `register_existing`; insert `BackgroundSim` tier marker.
/// 4. Advance `EntityRegistry` counter past all restored IDs.
/// 5. Restore `RelationshipGraph`, `SimulationTime`, and `SimRng` resources.
/// 6. Update the player entity's `KnowledgeGraph` if a player entity exists.
///
/// **Gotcha (D-010):** Bevy `Entity` handles are generational. `NpcSaveState` uses
/// `StableId(u64)` throughout — `EntityRegistry` maps restored `StableId`s to the
/// new `Entity` handles after re-spawn.
///
/// # Errors
/// `SaveLoadError::Io` on filesystem failure.
/// `SaveLoadError::Deserialize` on MessagePack decoding failure.
/// `SaveLoadError::VersionMismatch` when the save file predates the current schema.
pub fn load_from_file(path: &Path, world: &mut World) -> Result<(), SaveLoadError> {
let bytes = std::fs::read(path).map_err(|e| SaveLoadError::Io(e.to_string()))?;
let state =
SaveStateV1::from_bytes(&bytes).map_err(|e| SaveLoadError::Deserialize(e.to_string()))?;
if state.format_version != SAVE_FORMAT_VERSION {
return Err(SaveLoadError::VersionMismatch {
expected: SAVE_FORMAT_VERSION,
found: state.format_version,
});
}
let npc_count = state.npc_states.len();
// Despawn all existing NPC entities and clear their registry entries.
let npc_entities: Vec<Entity> = {
let mut q = world.query_filtered::<Entity, With<Npc>>();
q.iter(world).collect()
};
for entity in npc_entities {
world.resource_mut::<EntityRegistry>().unregister(entity);
world.despawn(entity);
}
// Track the highest restored StableId so we can advance the counter.
let mut max_id: u64 = 0;
// Re-spawn NPCs, assign tier marker, register pre-existing StableIds.
for npc_state in &state.npc_states {
let entity = deserialize_npc_from_frozen(npc_state, world);
// Loaded NPCs start in BackgroundSim; the distance system promotes as needed.
world.entity_mut(entity).insert(BackgroundSim);
let stable_id = npc_state.stable_id;
world
.resource_mut::<EntityRegistry>()
.register_existing(entity, stable_id);
max_id = max_id.max(stable_id.0);
}
// Advance the registry counter past all restored IDs so future register()
// calls produce non-conflicting IDs.
if npc_count > 0 {
world.resource_mut::<EntityRegistry>().advance_past(max_id);
}
// Restore simulation resources.
world.insert_resource(state.relationship_graph);
{
let mut t = world.resource_mut::<SimulationTime>();
t.tick = state.tick;
t.tick_rate = state.tick_rate;
}
world.insert_resource(SimRng::new(state.seed));
// Update the player entity's KnowledgeGraph if a player exists.
let player_entity = {
let mut q = world.query_filtered::<Entity, With<PlayerCharacter>>();
q.single(world).ok()
};
if let Some(player_entity) = player_entity {
world
.entity_mut(player_entity)
.insert(state.player_knowledge);
}
tracing::info!(
"load_from_file: {:?} (tick={}, npcs={})",
path,
state.tick,
npc_count,
);
Ok(())
}
/// Exclusive system: drain `SaveLoadPending` and execute queued save/load (#553).
///
/// Runs each tick, after `process_player_input`. If a command is pending,
/// executes it and writes `SaveLoadResultWire` to `SnapshotBuffer.pending_save_result`
/// for consumption by `compute_observer_snapshot` the same tick.
pub fn execute_save_load(world: &mut World) {
// Take the pending command (releases the borrow before we use world again).
let command = {
let mut pending = world.resource_mut::<SaveLoadPending>();
pending.pending.take()
};
let Some(command) = command else {
return;
};
let (kind_str, result) = match &command {
SaveLoadCommand::Save { path } => {
let r = save_to_file(path, world);
("save", r)
}
SaveLoadCommand::Load { path } => {
let r = load_from_file(path, world);
("load", r)
}
};
let wire_result = match result {
Ok(()) => {
tracing::info!("execute_save_load: {} completed", kind_str);
SaveLoadResultWire {
success: true,
kind: kind_str.to_string(),
error: None,
}
}
Err(ref e) => {
tracing::error!("execute_save_load: {} failed: {}", kind_str, e);
SaveLoadResultWire {
success: false,
kind: kind_str.to_string(),
error: Some(e.to_string()),
}
}
};
// Write result to SnapshotBuffer for client feedback (one tick only — consumed by
// compute_observer_snapshot via pending_save_result.take()).
if let Some(mut buf) = world.get_resource_mut::<SnapshotBuffer>() {
buf.pending_save_result = Some(wire_result);
}
}
// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------
#[cfg(test)]
mod tests {
use super::*;
use crate::knowledge::graph::KnowledgeGraph;
use crate::knowledge::registry::{EntityRegistry, StableEntityId};
use crate::knowledge::types::StableId;
use crate::npc::Npc;
use crate::npc::relationships::RelationshipGraph;
use crate::simulation::movement::TilePosition;
use crate::simulation::rng::SimRng;
use crate::simulation::save_state::{SaveStateV1, SAVE_FORMAT_VERSION};
use crate::simulation::time::{SimulationTime, TickRate};
use bevy_ecs::world::World;
use std::sync::atomic::{AtomicU64, Ordering};
static COUNTER: AtomicU64 = AtomicU64::new(0);
fn temp_path() -> PathBuf {
let id = COUNTER.fetch_add(1, Ordering::Relaxed);
std::env::temp_dir().join(format!("settled_reach_save_io_test_{}.msgpack", id))
}
fn minimal_world() -> World {
let mut w = World::new();
w.insert_resource(SimulationTime::default());
w.insert_resource(SimRng::new(42));
w.insert_resource(RelationshipGraph::new());
w.init_resource::<EntityRegistry>();
w
}
fn spawn_test_npc(world: &mut World, stable_id: u64) -> Entity {
world
.spawn((
Npc,
StableEntityId(StableId(stable_id)),
TilePosition::new(stable_id as i32, 0, 0),
))
.id()
}
// -----------------------------------------------------------------------
// save_to_file
// -----------------------------------------------------------------------
#[test]
fn save_to_file_creates_valid_msgpack() {
let mut world = minimal_world();
spawn_test_npc(&mut world, 1);
spawn_test_npc(&mut world, 2);
let path = temp_path();
save_to_file(&path, &mut world).expect("save should succeed");
let bytes = std::fs::read(&path).expect("file should exist");
let state = SaveStateV1::from_bytes(&bytes).expect("bytes must be valid msgpack");
assert_eq!(state.format_version, SAVE_FORMAT_VERSION);
assert_eq!(state.npc_states.len(), 2);
let _ = std::fs::remove_file(&path);
}
#[test]
fn save_to_file_sorts_npc_states_by_stable_id() {
let mut world = minimal_world();
// Spawn in reverse order — save should still sort ascending
spawn_test_npc(&mut world, 50);
spawn_test_npc(&mut world, 10);
spawn_test_npc(&mut world, 30);
let path = temp_path();
save_to_file(&path, &mut world).expect("save should succeed");
let bytes = std::fs::read(&path).expect("read saved file");
let state = SaveStateV1::from_bytes(&bytes).unwrap();
let ids: Vec<u64> = state.npc_states.iter().map(|n| n.stable_id.0).collect();
assert_eq!(ids, vec![10, 30, 50], "npc_states must be sorted by stable_id");
let _ = std::fs::remove_file(&path);
}
#[test]
fn save_to_file_preserves_tick_and_seed() {
let mut world = minimal_world();
{
let mut t = world.resource_mut::<SimulationTime>();
t.tick = 9999;
t.tick_rate = TickRate::Half;
}
world.insert_resource(SimRng::new(0xDEADBEEF));
let path = temp_path();
save_to_file(&path, &mut world).expect("save");
let bytes = std::fs::read(&path).unwrap();
let state = SaveStateV1::from_bytes(&bytes).unwrap();
assert_eq!(state.tick, 9999);
assert_eq!(state.tick_rate, TickRate::Half);
assert_eq!(state.seed, 0xDEADBEEF);
let _ = std::fs::remove_file(&path);
}
#[test]
fn save_to_file_returns_io_error_on_bad_path() {
let mut world = minimal_world();
let bad_path = std::path::Path::new("/nonexistent/directory/save.msgpack");
let result = save_to_file(bad_path, &mut world);
assert!(
matches!(result, Err(SaveLoadError::Io(_))),
"expected Io error for bad path"
);
}
// -----------------------------------------------------------------------
// load_from_file
// -----------------------------------------------------------------------
#[test]
fn load_from_file_restores_npc_count() {
let mut world = minimal_world();
spawn_test_npc(&mut world, 1);
spawn_test_npc(&mut world, 2);
let path = temp_path();
save_to_file(&path, &mut world).expect("save");
// Spawn an extra NPC — loading should despawn the old NPCs and restore exactly 2
spawn_test_npc(&mut world, 99);
let pre_load_count = {
let mut q = world.query_filtered::<Entity, With<Npc>>();
q.iter(&world).count()
};
assert_eq!(pre_load_count, 3, "three NPCs before load");
load_from_file(&path, &mut world).expect("load");
let post_load_count = {
let mut q = world.query_filtered::<Entity, With<Npc>>();
q.iter(&world).count()
};
assert_eq!(post_load_count, 2, "exactly the two saved NPCs after load");
let _ = std::fs::remove_file(&path);
}
#[test]
fn load_from_file_restores_stable_ids_in_registry() {
let mut world = minimal_world();
spawn_test_npc(&mut world, 10);
spawn_test_npc(&mut world, 20);
let path = temp_path();
save_to_file(&path, &mut world).expect("save");
load_from_file(&path, &mut world).expect("load");
let registry = world.resource::<EntityRegistry>();
assert!(
registry.to_entity(&StableId(10)).is_some(),
"StableId(10) must be in registry after load"
);
assert!(
registry.to_entity(&StableId(20)).is_some(),
"StableId(20) must be in registry after load"
);
let _ = std::fs::remove_file(&path);
}
#[test]
fn load_from_file_restores_tick_and_seed() {
let mut world = minimal_world();
{
let mut t = world.resource_mut::<SimulationTime>();
t.tick = 5000;
}
world.insert_resource(SimRng::new(12345));
let path = temp_path();
save_to_file(&path, &mut world).expect("save");
// Change time and seed, then load
{
let mut t = world.resource_mut::<SimulationTime>();
t.tick = 1;
}
world.insert_resource(SimRng::new(0));
load_from_file(&path, &mut world).expect("load");
let t = world.resource::<SimulationTime>();
assert_eq!(t.tick, 5000, "tick restored from save");
assert_eq!(
world.resource::<SimRng>().seed(),
12345,
"seed restored from save"
);
let _ = std::fs::remove_file(&path);
}
#[test]
fn load_from_file_rejects_wrong_format_version() {
// Craft a save with a wrong format_version
let bad_state = SaveStateV1 {
format_version: 0xFF, // deliberately wrong
tick: 0,
tick_rate: TickRate::Full,
seed: 0,
player_knowledge: KnowledgeGraph::new(),
relationship_graph: RelationshipGraph::new(),
npc_states: vec![],
};
let bytes = bad_state.to_bytes().expect("serialize");
let path = temp_path();
std::fs::write(&path, &bytes).expect("write");
let mut world = minimal_world();
let result = load_from_file(&path, &mut world);
assert!(
matches!(result, Err(SaveLoadError::VersionMismatch { .. })),
"expected VersionMismatch error, got {:?}",
result
);
let _ = std::fs::remove_file(&path);
}
#[test]
fn load_from_file_returns_io_error_for_missing_file() {
let mut world = minimal_world();
let missing = std::path::Path::new("/tmp/settled_reach_nonexistent_42.msgpack");
let result = load_from_file(missing, &mut world);
assert!(
matches!(result, Err(SaveLoadError::Io(_))),
"expected Io error for missing file"
);
}
#[test]
fn load_from_file_assigns_background_sim_tier() {
let mut world = minimal_world();
spawn_test_npc(&mut world, 1);
let path = temp_path();
save_to_file(&path, &mut world).expect("save");
load_from_file(&path, &mut world).expect("load");
let has_background: bool = {
let mut q = world.query_filtered::<Entity, (With<Npc>, With<BackgroundSim>)>();
q.iter(&world).count() > 0
};
assert!(
has_background,
"loaded NPC should be in BackgroundSim tier"
);
let _ = std::fs::remove_file(&path);
}
// -----------------------------------------------------------------------
// execute_save_load
// -----------------------------------------------------------------------
#[test]
fn execute_save_load_noop_when_no_pending() {
let mut world = minimal_world();
world.init_resource::<SaveLoadPending>();
world.init_resource::<SnapshotBuffer>();
execute_save_load(&mut world);
// No result written when no pending command
let buf = world.resource::<SnapshotBuffer>();
assert!(
buf.pending_save_result.is_none(),
"no pending_save_result when no command was queued"
);
}
#[test]
fn execute_save_load_writes_success_result() {
let mut world = minimal_world();
world.init_resource::<SnapshotBuffer>();
let path = temp_path();
world.insert_resource(SaveLoadPending {
pending: Some(SaveLoadCommand::Save { path: path.clone() }),
});
execute_save_load(&mut world);
let buf = world.resource::<SnapshotBuffer>();
let result = buf
.pending_save_result
.as_ref()
.expect("result must be written after execute");
assert!(result.success, "save should succeed");
assert_eq!(result.kind, "save");
assert!(result.error.is_none());
let _ = std::fs::remove_file(&path);
}
#[test]
fn execute_save_load_writes_error_result_on_bad_path() {
let mut world = minimal_world();
world.init_resource::<SnapshotBuffer>();
world.insert_resource(SaveLoadPending {
pending: Some(SaveLoadCommand::Save {
path: PathBuf::from("/nonexistent/dir/save.msgpack"),
}),
});
execute_save_load(&mut world);
let buf = world.resource::<SnapshotBuffer>();
let result = buf
.pending_save_result
.as_ref()
.expect("result must be written even on failure");
assert!(!result.success, "save should fail with bad path");
assert_eq!(result.kind, "save");
assert!(result.error.is_some(), "error message should be present");
}
// -----------------------------------------------------------------------
// SaveLoadError display
// -----------------------------------------------------------------------
#[test]
fn save_load_error_display() {
let e = SaveLoadError::Io("disk full".into());
assert!(e.to_string().contains("disk full"));
let e2 = SaveLoadError::VersionMismatch {
expected: 1,
found: 2,
};
assert!(e2.to_string().contains("expected 1"));
assert!(e2.to_string().contains("found 2"));
}
}
server/src/simulation/save_state.rs
+480 -6
View File
@@ -2,7 +2,8 @@
//!
//! `SaveStateV1` is the versioned serialization envelope for full game state.
//! Shares architecture with #96 (state serialization system) — this module
//! defines the data model only; ECS extraction and injection is #257.
//! defines the data model AND the per-NPC serialization primitives for tier
//! eviction freeze/thaw (#96).
//!
//! ## Write format: MessagePack
//!
@@ -34,12 +35,22 @@
//! - `NpcMemory` (intentionally excluded — stale inferences would be wrong after
//! reload; memory degrades naturally over time so reset-on-load is acceptable)
use bevy_ecs::entity::Entity;
use bevy_ecs::world::World;
use serde::{Deserialize, Serialize};
use crate::knowledge::graph::KnowledgeGraph;
use crate::knowledge::registry::StableEntityId;
use crate::knowledge::types::StableId;
use crate::npc::{SecretSeverity, Relationships};
use crate::npc::{
CombatCapability, Contentment, DailyRoutine, InformationInventory, JobPerformance, Npc,
PersonalityTraits, Relationships, Secret, SecretSeverity, SkillSet, TellSystem,
ToleranceThreshold, Want, WantKind,
};
use crate::npc::awareness::PlayerAwareness;
use crate::npc::mood::MoodState;
use crate::npc::relationships::RelationshipGraph;
use crate::npc::vision::{NpcMemory, NpcVisionState};
use crate::simulation::movement::TilePosition;
use crate::simulation::time::TickRate;
@@ -76,9 +87,36 @@ pub struct SaveStateV1 {
/// Per-NPC state snapshot for `SaveStateV1`.
///
/// Captures the D-024 axis values and position. On load, the full NPC entity
/// is reconstructed by injecting these values into the appropriate components.
/// Field order matches the 10-axis model (D-024) for readability.
/// Two usage contexts:
/// 1. **Whole-game save** (`SaveStateV1.npc_states`): populated by #553 ECS extraction.
/// Only the core axis fields need to be populated for this use case.
/// 2. **Tier eviction freeze** (produced by `serialize_npc_to_frozen`): captures ALL
/// components needed for full NPC reconstruction from `StateSaved` tier.
/// The extended optional fields (#96) carry all 10 D-024 axes.
///
/// All fields added post-#256 use `#[serde(default)]` for forward compatibility
/// with older save files that predate these fields.
///
/// ## D-024 axis coverage
/// | Axis | Field | Status |
/// |------|-------|--------|
/// | 1: Want | `want` | Full (optional for backward compat) |
/// | 2: Secret | `secret_severity` (legacy) + `secret` | Full |
/// | 3: Relationships | `relationships` | Full |
/// | 4: Tolerance | `current_stress` + `tolerance_threshold` | Full |
/// | 5: Daily routine | `routine` | Full (optional) |
/// | 6: Information inventory | `information_inventory` | Full (optional) |
/// | 7: Contentment | `contentment` | Full |
/// | Supporting 1: Personality | `personality_traits` | Full (optional) |
/// | Supporting 2: Tells | `tell_system` | Full (optional) |
/// | Supporting 3: Skills | `skill_set` + `combat_capability` | Full (optional) |
///
/// ## Components intentionally NOT serialized
/// - `NpcVisionState`: runtime LOS state, reset to default on reactivation
/// - `NpcMemory`: stale inferences would be wrong after reload (intentional drop)
/// - `PlayerAwareness`: runtime derived state, reset to default on reactivation
/// - `AnimationTier`: resets to `Tier1` on reactivation (no persistent state)
/// - `RoutineDeviation`: transient event marker, acceptable to drop on reload
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NpcSaveState {
/// Stable entity identifier (survives serialization — D-020).
@@ -86,7 +124,8 @@ pub struct NpcSaveState {
/// Last known tile position.
pub position: TilePosition,
// Axis 2: Secret severity (description is regenerated from content on load)
// Axis 2: Secret severity (legacy field — description regenerated from content on load).
// Kept for backward compatibility. Prefer `secret` field when doing full reconstruction.
pub secret_severity: SecretSeverity,
// Axis 3: Per-NPC relationship slots
pub relationships: Option<Relationships>,
@@ -99,6 +138,52 @@ pub struct NpcSaveState {
/// Per-NPC knowledge graph (if present — Active-tier NPCs carry KG).
pub knowledge_graph: Option<KnowledgeGraph>,
// --- Full reconstruction fields (added #96, for tier eviction freeze) ---
// All fields below use serde(default) for backward compatibility with saves
// created before #96 shipped.
/// Axis 1: Want (primary drive, intensity, and description).
#[serde(default)]
pub want: Option<Want>,
/// Axis 2: Full secret (description + known_by list).
/// Supersedes `secret_severity` for full reconstruction.
#[serde(default)]
pub secret: Option<Secret>,
/// Axis 5: Daily routine (phase → location schedule).
#[serde(default)]
pub routine: Option<DailyRoutine>,
/// Axis 6: Information inventory (facts this NPC carries).
#[serde(default)]
pub information_inventory: Option<InformationInventory>,
/// Supporting axis 1: Personality traits (2–3 traits, no contradictory pairs).
#[serde(default)]
pub personality_traits: Option<PersonalityTraits>,
/// Supporting axis 2: Tell system (behavioral tells tied to stress/personality).
#[serde(default)]
pub tell_system: Option<TellSystem>,
/// Supporting axis 3: Skill set (proficiency BTreeMap).
#[serde(default)]
pub skill_set: Option<SkillSet>,
/// Optional combat capability (only present for combat-trained NPCs).
#[serde(default)]
pub combat_capability: Option<CombatCapability>,
/// Mood state at save time. Derived from stress but worth preserving across
/// tier transitions to avoid jarring state resets on reactivation.
#[serde(default)]
pub mood_state: Option<MoodState>,
/// Job performance score — drifts over time, persist across tier transitions.
#[serde(default)]
pub job_performance: Option<JobPerformance>,
}
impl SaveStateV1 {
@@ -113,6 +198,166 @@ impl SaveStateV1 {
}
}
// ---------------------------------------------------------------------------
// Per-NPC tier eviction serialization primitives (#96)
// ---------------------------------------------------------------------------
/// Serialize a live NPC entity to a `NpcSaveState` frozen struct.
///
/// Used by the tier eviction system when demoting an entity to `StateSaved`:
/// instead of keeping all ECS components live, the entity is frozen and despawned.
/// The caller should despawn the entity after calling this function.
///
/// **Caller invariant:** The entity must have a `StableEntityId` component.
/// All other components are optional — missing components produce sensible defaults
/// in the output (and will be reconstructed as defaults by `deserialize_npc_from_frozen`).
///
/// # Panics
/// Panics if the entity has no `StableEntityId` component.
pub fn serialize_npc_to_frozen(entity: Entity, world: &World) -> NpcSaveState {
let position = world
.get::<TilePosition>(entity)
.copied()
.unwrap_or_else(|| TilePosition::new(0, 0, 0));
let stable_id = world
.get::<StableEntityId>(entity)
.map(|s| s.0)
.expect("NPC entity must have StableEntityId before serialization (#96)");
let secret = world.get::<Secret>(entity).cloned();
let secret_severity = secret
.as_ref()
.map(|s| s.severity)
.unwrap_or(SecretSeverity::Minor);
let (current_stress, tolerance_threshold) = world
.get::<ToleranceThreshold>(entity)
.map(|t| (t.current_stress, t.threshold))
.unwrap_or((0, 50));
NpcSaveState {
stable_id,
position,
secret_severity,
relationships: world.get::<Relationships>(entity).cloned(),
current_stress,
tolerance_threshold,
contentment: world
.get::<Contentment>(entity)
.map(|c| c.level)
.unwrap_or(0),
knowledge_graph: world.get::<KnowledgeGraph>(entity).cloned(),
want: world.get::<Want>(entity).cloned(),
secret,
routine: world.get::<DailyRoutine>(entity).cloned(),
information_inventory: world.get::<InformationInventory>(entity).cloned(),
personality_traits: world.get::<PersonalityTraits>(entity).cloned(),
tell_system: world.get::<TellSystem>(entity).cloned(),
skill_set: world.get::<SkillSet>(entity).cloned(),
combat_capability: world.get::<CombatCapability>(entity).cloned(),
mood_state: world.get::<MoodState>(entity).cloned(),
job_performance: world.get::<JobPerformance>(entity).cloned(),
}
}
/// Deserialize a frozen `NpcSaveState` and re-spawn a full NPC entity.
///
/// Used by the tier eviction system when reactivating an entity from `StateSaved`.
/// Reconstructs all D-024 axis components from the frozen state.
///
/// **Caller responsibilities after calling this function:**
/// 1. Register the returned `Entity` with `EntityRegistry` (StableId→Entity mapping).
/// 2. Assign the appropriate tier marker (`ActiveSim` or `BackgroundSim`).
///
/// Optional fields that are absent in `state` are reconstructed with sensible defaults:
/// - `Want`: defaults to `Safety` at intensity 5 (conservative non-disruptive default)
/// - `Secret`: reconstructed from `secret_severity` with empty description
/// - `MoodState`, `JobPerformance`: their `Default` implementations
///
/// Components excluded from reconstruction (see `NpcSaveState` doc for rationale):
/// `NpcVisionState`, `NpcMemory`, `PlayerAwareness` are reset to their `Default` states.
pub fn deserialize_npc_from_frozen(state: &NpcSaveState, world: &mut World) -> Entity {
let want = state.want.clone().unwrap_or(Want {
primary: WantKind::Safety, // conservative fallback — see flag comment above
intensity: 5,
description: String::new(),
});
let secret = state.secret.clone().unwrap_or(crate::npc::Secret {
description: String::new(),
severity: state.secret_severity,
known_by: vec![],
});
let relationships = state
.relationships
.clone()
.unwrap_or(Relationships { entries: vec![] });
let tolerance = ToleranceThreshold {
current_stress: state.current_stress,
threshold: state.tolerance_threshold,
};
let contentment = Contentment {
level: state.contentment,
};
let kg = state
.knowledge_graph
.clone()
.unwrap_or_else(KnowledgeGraph::new);
// Spawn the entity with all required components. Tier marker (ActiveSim /
// BackgroundSim) is NOT added here — the caller assigns it after registration.
let entity = world
.spawn((
Npc,
state.position,
StableEntityId(state.stable_id),
want,
secret,
relationships,
tolerance,
contentment,
kg,
state.mood_state.clone().unwrap_or_default(),
state.job_performance.clone().unwrap_or_default(),
// Runtime-computed components: reset to default on reactivation.
NpcVisionState::default(),
NpcMemory::default(),
PlayerAwareness::default(),
))
.id();
// Optional axis components — insert only if present in frozen state.
{
let mut em = world.entity_mut(entity);
if let Some(routine) = state.routine.clone() {
em.insert(routine);
}
if let Some(inventory) = state.information_inventory.clone() {
em.insert(inventory);
}
if let Some(traits) = state.personality_traits.clone() {
em.insert(traits);
}
if let Some(tells) = state.tell_system.clone() {
em.insert(tells);
}
if let Some(skills) = state.skill_set.clone() {
em.insert(skills);
}
if let Some(combat) = state.combat_capability.clone() {
em.insert(combat);
}
}
entity
}
// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------
@@ -121,6 +366,7 @@ impl SaveStateV1 {
mod tests {
use super::*;
use crate::knowledge::graph::KnowledgeGraph;
use crate::knowledge::registry::StableEntityId;
use crate::knowledge::types::{FactId, FactKnowledge, KnowledgeConfidence, StableId};
use crate::npc::relationships::RelationshipGraph;
use crate::simulation::movement::TilePosition;
@@ -193,6 +439,16 @@ mod tests {
tolerance_threshold: 80,
contentment: -15,
knowledge_graph: None,
want: None,
secret: None,
routine: None,
information_inventory: None,
personality_traits: None,
tell_system: None,
skill_set: None,
combat_capability: None,
mood_state: None,
job_performance: None,
},
NpcSaveState {
stable_id: StableId(202),
@@ -203,6 +459,16 @@ mod tests {
tolerance_threshold: 60,
contentment: 30,
knowledge_graph: None,
want: None,
secret: None,
routine: None,
information_inventory: None,
personality_traits: None,
tell_system: None,
skill_set: None,
combat_capability: None,
mood_state: None,
job_performance: None,
},
];
@@ -301,6 +567,16 @@ mod tests {
tolerance_threshold: 50,
contentment: 0,
knowledge_graph: Some(npc_kg),
want: None,
secret: None,
routine: None,
information_inventory: None,
personality_traits: None,
tell_system: None,
skill_set: None,
combat_capability: None,
mood_state: None,
job_performance: None,
}];
let bytes = state.to_bytes().expect("serialize");
@@ -317,4 +593,202 @@ mod tests {
// Document the version explicitly so CI catches unintentional bumps.
assert_eq!(SAVE_FORMAT_VERSION, 1);
}
// -----------------------------------------------------------------------
// Tier eviction serialization primitives (#96)
// -----------------------------------------------------------------------
fn spawn_minimal_npc(world: &mut World, stable_id: StableId) -> Entity {
use crate::npc::{
Contentment, Relationships, Secret, SecretSeverity, ToleranceThreshold, Want, WantKind,
};
use crate::npc::mood::MoodState;
use crate::npc::vision::{NpcMemory, NpcVisionState};
use crate::npc::awareness::PlayerAwareness;
world
.spawn((
Npc,
StableEntityId(stable_id),
TilePosition::new(5, 10, 0),
Want {
primary: WantKind::Safety,
intensity: 7,
description: "wants safety".into(),
},
Secret {
description: "has a minor secret".into(),
severity: SecretSeverity::Minor,
known_by: vec![],
},
Relationships { entries: vec![] },
ToleranceThreshold {
current_stress: 30,
threshold: 70,
},
Contentment { level: 15 },
MoodState::default(),
crate::npc::JobPerformance::default(),
KnowledgeGraph::new(),
NpcVisionState::default(),
NpcMemory::default(),
PlayerAwareness::default(),
))
.id()
}
#[test]
fn serialize_npc_to_frozen_captures_stable_id_and_position() {
let mut world = World::new();
let entity = spawn_minimal_npc(&mut world, StableId(42));
let frozen = serialize_npc_to_frozen(entity, &world);
assert_eq!(frozen.stable_id, StableId(42));
assert_eq!(frozen.position, TilePosition::new(5, 10, 0));
}
#[test]
fn serialize_npc_to_frozen_captures_axes() {
use crate::npc::SecretSeverity;
let mut world = World::new();
let entity = spawn_minimal_npc(&mut world, StableId(1));
let frozen = serialize_npc_to_frozen(entity, &world);
assert_eq!(frozen.secret_severity, SecretSeverity::Minor);
assert_eq!(frozen.current_stress, 30);
assert_eq!(frozen.tolerance_threshold, 70);
assert_eq!(frozen.contentment, 15);
// Full optional axes should be populated when components exist
assert!(frozen.want.is_some(), "want should be captured");
assert!(frozen.secret.is_some(), "secret should be captured");
}
#[test]
fn serialize_deserialize_roundtrip_produces_identical_component_values() {
// Spec (#96): serialize + deserialize produces an entity with identical values.
let mut world = World::new();
let original = spawn_minimal_npc(&mut world, StableId(77));
// Serialize
let frozen = serialize_npc_to_frozen(original, &world);
// Deserialize into a new entity
let restored = deserialize_npc_from_frozen(&frozen, &mut world);
// Verify StableEntityId matches
let orig_stable = world.get::<StableEntityId>(original).unwrap().0;
let rest_stable = world.get::<StableEntityId>(restored).unwrap().0;
assert_eq!(orig_stable, rest_stable, "StableId must match");
// Position
let orig_pos = world.get::<TilePosition>(original).copied().unwrap();
let rest_pos = world.get::<TilePosition>(restored).copied().unwrap();
assert_eq!(orig_pos, rest_pos, "position must match");
// Tolerance
let orig_tol = world.get::<ToleranceThreshold>(original).cloned().unwrap();
let rest_tol = world.get::<ToleranceThreshold>(restored).cloned().unwrap();
assert_eq!(orig_tol.current_stress, rest_tol.current_stress);
assert_eq!(orig_tol.threshold, rest_tol.threshold);
// Contentment
let orig_con = world.get::<Contentment>(original).cloned().unwrap();
let rest_con = world.get::<Contentment>(restored).cloned().unwrap();
assert_eq!(orig_con.level, rest_con.level, "contentment must match");
// Want
let orig_want = world.get::<Want>(original).cloned().unwrap();
let rest_want = world.get::<Want>(restored).cloned().unwrap();
assert_eq!(orig_want.primary, rest_want.primary, "want.primary must match");
assert_eq!(orig_want.intensity, rest_want.intensity, "want.intensity must match");
// Secret severity
let orig_secret = world.get::<Secret>(original).cloned().unwrap();
let rest_secret = world.get::<Secret>(restored).cloned().unwrap();
assert_eq!(orig_secret.severity, rest_secret.severity, "secret severity must match");
}
#[test]
fn deserialize_npc_without_optional_axes_uses_safe_defaults() {
// Spec (#96): optional fields absent in frozen state produce sensible defaults.
use crate::npc::SecretSeverity;
let frozen = NpcSaveState {
stable_id: StableId(999),
position: TilePosition::new(0, 0, 0),
secret_severity: SecretSeverity::Moderate,
relationships: None,
current_stress: 10,
tolerance_threshold: 50,
contentment: 0,
knowledge_graph: None,
want: None,
secret: None,
routine: None,
information_inventory: None,
personality_traits: None,
tell_system: None,
skill_set: None,
combat_capability: None,
mood_state: None,
job_performance: None,
};
let mut world = World::new();
let entity = deserialize_npc_from_frozen(&frozen, &mut world);
// Entity must exist with required components
assert!(world.get::<Npc>(entity).is_some());
assert!(world.get::<StableEntityId>(entity).is_some());
assert!(world.get::<ToleranceThreshold>(entity).is_some());
assert!(world.get::<Contentment>(entity).is_some());
assert!(world.get::<Want>(entity).is_some(), "Want defaults to Safety");
assert!(world.get::<Secret>(entity).is_some(), "Secret built from secret_severity");
// Secret severity must be preserved from the legacy field
let secret = world.get::<Secret>(entity).unwrap();
assert_eq!(secret.severity, SecretSeverity::Moderate);
// Optional axes absent in frozen state → not inserted or use defaults
assert!(world.get::<DailyRoutine>(entity).is_none(), "routine absent when not frozen");
}
#[test]
fn frozen_npc_roundtrips_via_messagepack() {
// Spec (#96): NpcSaveState must survive MessagePack roundtrip.
let mut world = World::new();
let entity = spawn_minimal_npc(&mut world, StableId(55));
let frozen = serialize_npc_to_frozen(entity, &world);
// Wrap in SaveStateV1 for MessagePack encoding
let save = SaveStateV1 {
format_version: SAVE_FORMAT_VERSION,
tick: 100,
tick_rate: TickRate::Full,
seed: 12,
player_knowledge: KnowledgeGraph::new(),
relationship_graph: RelationshipGraph::new(),
npc_states: vec![frozen],
};
let bytes = save.to_bytes().expect("serialize");
let recovered = SaveStateV1::from_bytes(&bytes).expect("deserialize");
let bytes2 = recovered.to_bytes().expect("re-serialize");
assert_eq!(bytes, bytes2, "frozen NPC state must roundtrip via MessagePack");
}
#[test]
fn serialize_npc_panics_without_stable_entity_id() {
// Spec (#96): StableEntityId is required — missing it is a programmer error.
let mut world = World::new();
let entity = world.spawn((Npc, TilePosition::new(0, 0, 0))).id();
// World doesn't implement UnwindSafe — wrap in AssertUnwindSafe.
let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
serialize_npc_to_frozen(entity, &world);
}));
assert!(result.is_err(), "must panic without StableEntityId");
}
}
server/src/simulation/tier.rs
+790
View File
@@ -1,9 +1,21 @@
// Simulation tier system
// Implements D-026: Active/Background/State-saved/Ungenerated tiers
// Tier transitions based on player approach distance (#99).
// Scope tag system: NPCs with active scope tags stay pinned to ActiveSim (#98).
// Timestamp-based eviction: LRU eviction when ActiveSim exceeds capacity (#97).
use std::collections::{BTreeSet, BinaryHeap};
use std::cmp::Reverse;
use bevy_app::prelude::*;
use bevy_ecs::prelude::*;
use serde::{Deserialize, Serialize};
use crate::knowledge::graph::KnowledgeGraph;
use crate::knowledge::registry::StableEntityId;
use crate::knowledge::types::KnowledgeConfidence;
use crate::npc::{Npc, RelationshipKind};
use crate::npc::relationships::RelationshipGraph;
use crate::simulation::movement::{PlayerCharacter, TilePosition};
// --- Tier radius constants (D-026) ---
@@ -38,20 +50,356 @@ pub struct BackgroundSim;
#[derive(Component, Debug, Clone, Copy, Default)]
pub struct StateSaved;
// ---------------------------------------------------------------------------
// Eviction system (D-026, #97)
// ---------------------------------------------------------------------------
/// Maximum number of entities in `ActiveSim` before LRU eviction kicks in (D-026).
pub const ACTIVE_SIM_CAPACITY: usize = 80;
/// Tracks the tick at which the player last interacted with or observed an NPC (#97).
/// Updated by `update_last_interaction_tick` when an NPC is in the player's LOS.
/// Used by `evict_excess_active` as the LRU sort key.
#[derive(Component, Debug, Clone, Copy, Default, Serialize, Deserialize)]
pub struct LastInteractionTick(pub u64);
/// Tracks current `ActiveSim` entity count vs. capacity (#97, D-026).
/// Updated each tick by `evict_excess_active`.
#[derive(Resource, Debug, Clone)]
pub struct SimSpacePressure {
/// Number of entities currently in `ActiveSim`.
pub active_count: usize,
/// Capacity ceiling.
pub capacity: usize,
}
impl Default for SimSpacePressure {
fn default() -> Self {
Self {
active_count: 0,
capacity: ACTIVE_SIM_CAPACITY,
}
}
}
// ---------------------------------------------------------------------------
// Scope tag system (D-026, #98)
// ---------------------------------------------------------------------------
/// Scope tag kinds: reasons why an NPC stays pinned to `ActiveSim` (D-026).
///
/// Four variants track distinct reasons for pinning. An NPC may have multiple
/// reasons simultaneously — all are tracked in `ScopeTag`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
pub enum ScopeTagKind {
/// NPC is in the player's immediate neighborhood.
/// Set at session start for NPCs within `ACTIVE_RADIUS`. Managed by
/// `assign_neighborhood_tags_on_start` (deferred: future sprint).
Neighborhood,
/// NPC is involved in an active quest.
/// Reserved for the quest system (deferred: future sprint).
ActiveQuest,
/// NPC has a `Friend` or `Colleague` relationship with the player character.
/// Assigned by `assign_scope_tags` each tick from `RelationshipGraph`.
Colleague,
/// NPC is known to the player with confidence >= `KnowsOf`.
/// Assigned by `assign_scope_tags` each tick from player `KnowledgeGraph`.
KnownContact,
}
/// Scope tag component: which scope tags currently apply to this NPC (D-026).
///
/// NPCs carrying at least one scope tag are kept in `ActiveSim` regardless of
/// distance or LRU eviction pressure. `ScopePinned` is the eviction guard;
/// this component is the source of truth.
///
/// Assignment:
/// - `KnownContact` and `Colleague`: recomputed by `assign_scope_tags` each tick.
/// - `Neighborhood`: set at session start (see `ScopeTagKind::Neighborhood`).
/// - `ActiveQuest`: reserved for future quest system.
#[derive(Component, Debug, Clone, Default, Serialize, Deserialize)]
pub struct ScopeTag {
pub tags: BTreeSet<ScopeTagKind>,
}
impl ScopeTag {
/// Create a `ScopeTag` with a single initial kind.
pub fn with(kind: ScopeTagKind) -> Self {
let mut tags = BTreeSet::new();
tags.insert(kind);
Self { tags }
}
/// Add a scope tag kind.
pub fn add(&mut self, kind: ScopeTagKind) {
self.tags.insert(kind);
}
/// Remove a scope tag kind.
pub fn remove(&mut self, kind: ScopeTagKind) {
self.tags.remove(&kind);
}
/// True if this NPC carries at least one scope tag.
pub fn is_pinned(&self) -> bool {
!self.tags.is_empty()
}
/// True if this specific kind is present.
pub fn contains(&self, kind: ScopeTagKind) -> bool {
self.tags.contains(&kind)
}
}
/// Marker component: this NPC is scope-pinned — the eviction system must skip it.
///
/// Kept in sync with `ScopeTag` by `sync_scope_pins`. Always use `ScopeTag`
/// as the source of truth; treat `ScopePinned` as a query-optimisation cache.
#[derive(Component, Debug, Clone, Copy, Default)]
pub struct ScopePinned;
/// Plugin registering the tier marker components and the tier transition system.
pub struct TierPlugin;
impl Plugin for TierPlugin {
fn build(&self, app: &mut App) {
app.init_resource::<SimSpacePressure>();
// Tier transition runs after movement so positions are current.
app.add_systems(
Update,
update_tier_markers.after(crate::simulation::movement::validate_movement),
);
// Scope tag assignment runs each tick to keep KnownContact / Colleague current.
// Must run before sync_scope_pins so pins are correct before eviction checks.
// Eviction runs after scope pins are synced (respects ScopePinned).
// LastInteractionTick update runs after visibility geometry.
app.add_systems(
Update,
(
assign_scope_tags,
sync_scope_pins.after(assign_scope_tags),
update_last_interaction_tick
.after(crate::perception::observer::compute_visibility_geometry),
evict_excess_active
.after(sync_scope_pins)
.after(update_tier_markers),
),
);
tracing::debug!("TierPlugin initialized");
}
}
// ---------------------------------------------------------------------------
// Scope tag systems (D-026, #98)
// ---------------------------------------------------------------------------
/// System: assign `KnownContact` and `Colleague` scope tags from player epistemics.
///
/// Runs each tick. Clears and recomputes `KnownContact` and `Colleague` tags for all
/// NPCs based on:
/// - `KnownContact`: player `KnowledgeGraph` has an entry for this NPC with
/// confidence >= `KnowsOf`.
/// - `Colleague`: global `RelationshipGraph` has an edge from the player to this NPC
/// with kind `Friend` or `Colleague`.
///
/// `Neighborhood` and `ActiveQuest` tags are NOT touched by this system:
/// - `Neighborhood` is set at session start and persists (future sprint).
/// - `ActiveQuest` is reserved for the quest system (future sprint).
///
/// No-op when there is no `PlayerCharacter` entity.
pub fn assign_scope_tags(
player_query: Query<(&KnowledgeGraph, &StableEntityId), With<PlayerCharacter>>,
rel_graph: Res<RelationshipGraph>,
mut npcs: Query<(Entity, &StableEntityId, Option<&mut ScopeTag>), With<Npc>>,
mut commands: Commands,
) {
let Ok((player_kg, player_stable)) = player_query.single() else {
return;
};
let player_id = player_stable.0;
// Collect KnownContact set: entities in player KG with confidence >= KnowsOf.
// BTreeSet for deterministic iteration (D-010).
let known_contacts: BTreeSet<_> = player_kg
.entities
.iter()
.filter(|(_, ek)| ek.confidence >= KnowledgeConfidence::KnowsOf)
.map(|(id, _)| *id)
.collect();
// Collect Colleague set: player → NPC relationship edges with Friend/Colleague kind.
let colleagues: BTreeSet<_> = rel_graph
.relationships_of(&player_id)
.into_iter()
.filter(|(_, edge)| {
matches!(edge.kind, RelationshipKind::Friend | RelationshipKind::Colleague)
})
.map(|(target_id, _)| *target_id)
.collect();
for (entity, npc_stable, maybe_scope_tag) in &mut npcs {
let npc_id = npc_stable.0;
let is_known = known_contacts.contains(&npc_id);
let is_colleague = colleagues.contains(&npc_id);
match maybe_scope_tag {
Some(mut scope_tag) => {
// Remove computed tags, then re-add if still applicable.
scope_tag.remove(ScopeTagKind::KnownContact);
scope_tag.remove(ScopeTagKind::Colleague);
if is_known {
scope_tag.add(ScopeTagKind::KnownContact);
}
if is_colleague {
scope_tag.add(ScopeTagKind::Colleague);
}
}
None if is_known || is_colleague => {
// Create a new ScopeTag component for this NPC.
let mut scope_tag = ScopeTag::default();
if is_known {
scope_tag.add(ScopeTagKind::KnownContact);
}
if is_colleague {
scope_tag.add(ScopeTagKind::Colleague);
}
commands.entity(entity).insert(scope_tag);
}
None => {} // NPC not known or related — no scope tag needed.
}
}
}
/// System: keep `ScopePinned` markers in sync with `ScopeTag` components.
///
/// Runs after `assign_scope_tags`. For each NPC:
/// - `ScopeTag` present and non-empty → add `ScopePinned` (if not already present).
/// - `ScopeTag` absent or empty → remove `ScopePinned` (if present).
///
/// The eviction system (#97) queries `Without<ScopePinned>` to skip pinned NPCs.
pub fn sync_scope_pins(
mut commands: Commands,
needs_pin: Query<(Entity, &ScopeTag), Without<ScopePinned>>,
may_need_unpin: Query<(Entity, Option<&ScopeTag>), With<ScopePinned>>,
) {
// Add ScopePinned to NPCs that have a non-empty ScopeTag.
for (entity, scope_tag) in &needs_pin {
if scope_tag.is_pinned() {
commands.entity(entity).insert(ScopePinned);
}
}
// Remove ScopePinned from NPCs whose ScopeTag is absent or empty.
for (entity, maybe_scope_tag) in &may_need_unpin {
let still_pinned = maybe_scope_tag.map(|s| s.is_pinned()).unwrap_or(false);
if !still_pinned {
commands.entity(entity).remove::<ScopePinned>();
}
}
}
// ---------------------------------------------------------------------------
// Eviction systems (D-026, #97)
// ---------------------------------------------------------------------------
/// System: update `LastInteractionTick` for NPCs visible to the player (#97).
///
/// Runs after visibility geometry is computed. Any NPC at a visible position
/// (in the player's LOS) gets its `LastInteractionTick` set to the current tick.
/// NPCs without this component get it inserted on first observation.
pub fn update_last_interaction_tick(
time: Res<crate::simulation::time::SimulationTime>,
vis_geo: Res<crate::perception::query::VisibilityGeometry>,
mut npcs_with_tick: Query<(&TilePosition, &mut LastInteractionTick), With<Npc>>,
npcs_without_tick: Query<(Entity, &TilePosition), (With<Npc>, Without<LastInteractionTick>)>,
mut commands: Commands,
) {
let current_tick = time.tick;
// Update existing LastInteractionTick for visible NPCs.
for (pos, mut last_tick) in &mut npcs_with_tick {
if pos.z == vis_geo.observer_z
&& vis_geo.visible_positions.contains(&(pos.x, pos.y))
{
last_tick.0 = current_tick;
}
}
// Insert LastInteractionTick for NPCs that don't have it yet but are visible.
for (entity, pos) in &npcs_without_tick {
if pos.z == vis_geo.observer_z
&& vis_geo.visible_positions.contains(&(pos.x, pos.y))
{
commands.entity(entity).insert(LastInteractionTick(current_tick));
}
}
}
/// System: evict excess `ActiveSim` entities when count exceeds capacity (#97).
///
/// When more than `ACTIVE_SIM_CAPACITY` entities are in `ActiveSim`:
/// 1. Skip all `ScopePinned` entities (they stay Active regardless).
/// 2. Sort remaining by `LastInteractionTick` (oldest first) via min-heap.
/// 3. Demote the oldest N entities to `BackgroundSim` (or `StateSaved` if beyond
/// background radius).
///
/// Updates `SimSpacePressure` resource with current counts.
pub fn evict_excess_active(
mut commands: Commands,
player_query: Query<&TilePosition, With<PlayerCharacter>>,
active_npcs: Query<
(Entity, &TilePosition, Option<&LastInteractionTick>),
(With<ActiveSim>, With<Npc>, Without<ScopePinned>),
>,
active_count_query: Query<(), With<ActiveSim>>,
mut pressure: ResMut<SimSpacePressure>,
) {
let total_active = active_count_query.iter().count();
pressure.active_count = total_active;
if total_active <= pressure.capacity {
return;
}
let excess = total_active - pressure.capacity;
let Ok(player_pos) = player_query.single() else {
return;
};
// Min-heap keyed by LastInteractionTick (oldest = smallest = evicted first).
// Entities without LastInteractionTick get tick 0 (most stale).
let mut heap: BinaryHeap<Reverse<(u64, Entity, TilePosition)>> = BinaryHeap::new();
for (entity, pos, maybe_tick) in &active_npcs {
let tick = maybe_tick.map(|t| t.0).unwrap_or(0);
heap.push(Reverse((tick, entity, *pos)));
}
let mut evicted = 0;
while evicted < excess {
let Some(Reverse((_, entity, pos))) = heap.pop() else {
break;
};
let dist = tile_distance(player_pos, &pos);
if dist > BACKGROUND_RADIUS {
commands.entity(entity).remove::<ActiveSim>().insert(StateSaved);
} else {
commands.entity(entity).remove::<ActiveSim>().insert(BackgroundSim);
}
evicted += 1;
}
if evicted > 0 {
tracing::debug!(
"evicted {} excess ActiveSim entities (was {}, cap {})",
evicted,
total_active,
pressure.capacity,
);
}
}
// --- Tier transition system (D-026, #99) ---
/// Manhattan tile distance between two positions, returning `u32::MAX` for
@@ -432,4 +780,446 @@ mod tests {
assert!(world.get::<ActiveSim>(npc).is_none(), "demoted to Background");
assert!(world.get::<BackgroundSim>(npc).is_some());
}
// -----------------------------------------------------------------------
// ScopeTag component tests (#98, D-026)
// -----------------------------------------------------------------------
#[test]
fn scope_tag_with_creates_single_kind() {
let tag = ScopeTag::with(ScopeTagKind::KnownContact);
assert!(tag.contains(ScopeTagKind::KnownContact));
assert!(!tag.contains(ScopeTagKind::Colleague));
assert!(tag.is_pinned());
}
#[test]
fn scope_tag_add_and_remove() {
let mut tag = ScopeTag::default();
assert!(!tag.is_pinned(), "new ScopeTag is empty");
tag.add(ScopeTagKind::Colleague);
assert!(tag.is_pinned());
assert!(tag.contains(ScopeTagKind::Colleague));
tag.add(ScopeTagKind::KnownContact);
assert!(tag.contains(ScopeTagKind::KnownContact));
tag.remove(ScopeTagKind::Colleague);
assert!(!tag.contains(ScopeTagKind::Colleague));
assert!(tag.is_pinned(), "still pinned by KnownContact");
tag.remove(ScopeTagKind::KnownContact);
assert!(!tag.is_pinned(), "unpinned when all tags removed");
}
#[test]
fn scope_tag_multiple_kinds_coexist() {
let mut tag = ScopeTag::default();
tag.add(ScopeTagKind::Neighborhood);
tag.add(ScopeTagKind::ActiveQuest);
tag.add(ScopeTagKind::Colleague);
tag.add(ScopeTagKind::KnownContact);
assert_eq!(tag.tags.len(), 4, "all four kinds present");
assert!(tag.is_pinned());
}
// -----------------------------------------------------------------------
// sync_scope_pins system tests (#98)
// -----------------------------------------------------------------------
fn run_sync_scope_pins(world: &mut World) {
let mut schedule = bevy_ecs::schedule::Schedule::default();
schedule.add_systems(sync_scope_pins);
schedule.run(world);
}
#[test]
fn sync_scope_pins_adds_scope_pinned_for_non_empty_tag() {
let mut world = World::new();
let npc = world
.spawn((Npc, ScopeTag::with(ScopeTagKind::KnownContact)))
.id();
run_sync_scope_pins(&mut world);
assert!(
world.get::<ScopePinned>(npc).is_some(),
"ScopePinned added for non-empty ScopeTag"
);
}
#[test]
fn sync_scope_pins_does_not_add_for_empty_tag() {
let mut world = World::new();
let npc = world.spawn((Npc, ScopeTag::default())).id();
run_sync_scope_pins(&mut world);
assert!(
world.get::<ScopePinned>(npc).is_none(),
"ScopePinned must NOT be added for empty ScopeTag"
);
}
#[test]
fn sync_scope_pins_removes_scope_pinned_when_tag_emptied() {
let mut world = World::new();
// Start with ScopePinned already set but ScopeTag now empty.
let npc = world.spawn((Npc, ScopePinned, ScopeTag::default())).id();
run_sync_scope_pins(&mut world);
assert!(
world.get::<ScopePinned>(npc).is_none(),
"ScopePinned removed when ScopeTag is empty"
);
}
#[test]
fn sync_scope_pins_removes_scope_pinned_when_tag_absent() {
let mut world = World::new();
// NPC has ScopePinned but no ScopeTag component at all.
let npc = world.spawn((Npc, ScopePinned)).id();
run_sync_scope_pins(&mut world);
assert!(
world.get::<ScopePinned>(npc).is_none(),
"ScopePinned removed when ScopeTag absent"
);
}
#[test]
fn sync_scope_pins_keeps_existing_scope_pinned() {
// An NPC that already has ScopePinned AND a non-empty ScopeTag should remain pinned.
let mut world = World::new();
let npc = world
.spawn((Npc, ScopePinned, ScopeTag::with(ScopeTagKind::Colleague)))
.id();
run_sync_scope_pins(&mut world);
// After sync, the NPC should still have ScopePinned (it was already there
// AND the scope tag is non-empty — so no change needed).
assert!(
world.get::<ScopePinned>(npc).is_some(),
"ScopePinned preserved for non-empty ScopeTag"
);
}
// -----------------------------------------------------------------------
// assign_scope_tags system tests (#98)
// -----------------------------------------------------------------------
fn run_assign_scope_tags(world: &mut World) {
let mut schedule = bevy_ecs::schedule::Schedule::default();
schedule.add_systems(assign_scope_tags);
schedule.run(world);
}
#[test]
fn assign_scope_tags_no_op_without_player() {
let mut world = World::new();
world.init_resource::<RelationshipGraph>();
// NPC exists but no PlayerCharacter
let npc = world.spawn((Npc, StableEntityId(crate::knowledge::types::StableId(1)))).id();
run_assign_scope_tags(&mut world);
// No ScopeTag should be assigned — no player
assert!(world.get::<ScopeTag>(npc).is_none());
}
#[test]
fn assign_scope_tags_known_contact_from_player_kg() {
use crate::knowledge::types::StableId;
let mut world = World::new();
world.init_resource::<RelationshipGraph>();
let npc_stable = StableId(10);
let player_stable = StableId(1);
// Set up player with a KnowledgeGraph that knows the NPC at KnowsOf level.
let mut player_kg = KnowledgeGraph::new();
player_kg.observe_entity(npc_stable, make_pos(5, 5), 0);
world.spawn((
PlayerCharacter,
make_pos(0, 0),
player_kg,
StableEntityId(player_stable),
));
// Spawn the NPC
let npc = world
.spawn((Npc, make_pos(10, 0), StableEntityId(npc_stable)))
.id();
run_assign_scope_tags(&mut world);
let scope_tag = world.get::<ScopeTag>(npc).expect("ScopeTag should be assigned");
assert!(
scope_tag.contains(ScopeTagKind::KnownContact),
"NPC known at KnowsOf level should get KnownContact tag"
);
}
#[test]
fn assign_scope_tags_colleague_from_relationship_graph() {
use crate::knowledge::types::StableId;
use crate::npc::relationships::RelationshipEdge;
let mut world = World::new();
let npc_stable = StableId(20);
let player_stable = StableId(1);
// Player KG is empty — no KnownContact.
let player_kg = KnowledgeGraph::new();
world.spawn((
PlayerCharacter,
make_pos(0, 0),
player_kg,
StableEntityId(player_stable),
));
// Set up RelationshipGraph with player → NPC as Friend.
let mut rel_graph = RelationshipGraph::new();
rel_graph.set_relationship(
player_stable,
npc_stable,
RelationshipEdge {
kind: RelationshipKind::Friend,
trust: 5,
history: vec![],
last_interaction_tick: 0,
},
);
world.insert_resource(rel_graph);
let npc = world
.spawn((Npc, make_pos(0, 5), StableEntityId(npc_stable)))
.id();
run_assign_scope_tags(&mut world);
let scope_tag = world.get::<ScopeTag>(npc).expect("ScopeTag assigned for colleague");
assert!(
scope_tag.contains(ScopeTagKind::Colleague),
"Friend relationship should grant Colleague scope tag"
);
}
#[test]
fn assign_scope_tags_does_not_affect_unknown_npcs() {
use crate::knowledge::types::StableId;
let mut world = World::new();
world.init_resource::<RelationshipGraph>();
let player_stable = StableId(1);
let player_kg = KnowledgeGraph::new(); // empty — knows nobody
world.spawn((
PlayerCharacter,
make_pos(0, 0),
player_kg,
StableEntityId(player_stable),
));
// NPC that the player doesn't know
let npc = world
.spawn((Npc, make_pos(10, 0), StableEntityId(StableId(99))))
.id();
run_assign_scope_tags(&mut world);
assert!(
world.get::<ScopeTag>(npc).is_none(),
"unknown NPC should not receive ScopeTag"
);
}
#[test]
fn scope_pinned_npc_in_query_without_scope_pinned_marker() {
// Verify that ScopePinned is a separate marker and Without<ScopePinned>
// correctly excludes pinned NPCs from eviction queries.
let mut world = World::new();
let pinned = world.spawn((Npc, ScopePinned)).id();
let unpinned = world.spawn(Npc).id();
let mut query = world.query_filtered::<Entity, (With<Npc>, Without<ScopePinned>)>();
let unpinned_results: Vec<Entity> = query.iter(&world).collect();
assert_eq!(unpinned_results.len(), 1, "only one unpinned NPC");
assert_eq!(unpinned_results[0], unpinned);
assert!(!unpinned_results.contains(&pinned), "pinned NPC excluded from eviction query");
}
// -----------------------------------------------------------------------
// Eviction system tests (#97, D-026)
// -----------------------------------------------------------------------
fn run_evict_excess_active(world: &mut World) {
let mut schedule = bevy_ecs::schedule::Schedule::default();
schedule.add_systems(evict_excess_active);
schedule.run(world);
}
#[test]
fn no_eviction_when_under_capacity() {
let mut world = World::new();
world.insert_resource(SimSpacePressure {
active_count: 0,
capacity: 5,
});
world.spawn((PlayerCharacter, make_pos(0, 0)));
// Spawn 3 active NPCs (under cap of 5)
let npc1 = world.spawn((Npc, ActiveSim, make_pos(5, 0), LastInteractionTick(10))).id();
let npc2 = world.spawn((Npc, ActiveSim, make_pos(6, 0), LastInteractionTick(20))).id();
let npc3 = world.spawn((Npc, ActiveSim, make_pos(7, 0), LastInteractionTick(30))).id();
run_evict_excess_active(&mut world);
// All should remain Active
assert!(world.get::<ActiveSim>(npc1).is_some());
assert!(world.get::<ActiveSim>(npc2).is_some());
assert!(world.get::<ActiveSim>(npc3).is_some());
}
#[test]
fn evicts_oldest_when_over_capacity() {
let mut world = World::new();
world.insert_resource(SimSpacePressure {
active_count: 0,
capacity: 2,
});
world.spawn((PlayerCharacter, make_pos(0, 0)));
// 3 NPCs, cap=2 → must evict 1 (the oldest: tick 10)
let oldest = world.spawn((Npc, ActiveSim, make_pos(5, 0), LastInteractionTick(10))).id();
let mid = world.spawn((Npc, ActiveSim, make_pos(6, 0), LastInteractionTick(20))).id();
let newest = world.spawn((Npc, ActiveSim, make_pos(7, 0), LastInteractionTick(30))).id();
run_evict_excess_active(&mut world);
assert!(world.get::<ActiveSim>(oldest).is_none(), "oldest evicted");
assert!(world.get::<BackgroundSim>(oldest).is_some(), "oldest → Background");
assert!(world.get::<ActiveSim>(mid).is_some(), "mid stays Active");
assert!(world.get::<ActiveSim>(newest).is_some(), "newest stays Active");
}
#[test]
fn eviction_skips_scope_pinned() {
let mut world = World::new();
world.insert_resource(SimSpacePressure {
active_count: 0,
capacity: 1,
});
world.spawn((PlayerCharacter, make_pos(0, 0)));
// 2 NPCs, cap=1. The oldest is ScopePinned → skip it, evict the other.
let pinned = world.spawn((
Npc, ActiveSim, ScopePinned,
ScopeTag::with(ScopeTagKind::KnownContact),
make_pos(5, 0), LastInteractionTick(5),
)).id();
let unpinned = world.spawn((
Npc, ActiveSim,
make_pos(6, 0), LastInteractionTick(20),
)).id();
run_evict_excess_active(&mut world);
assert!(world.get::<ActiveSim>(pinned).is_some(), "pinned NPC stays Active");
assert!(world.get::<ActiveSim>(unpinned).is_none(), "unpinned NPC evicted");
assert!(world.get::<BackgroundSim>(unpinned).is_some());
}
#[test]
fn eviction_demotes_to_state_saved_if_beyond_background_radius() {
let mut world = World::new();
world.insert_resource(SimSpacePressure {
active_count: 0,
capacity: 1,
});
world.spawn((PlayerCharacter, make_pos(0, 0)));
// NPC at distance 200 (beyond BACKGROUND_RADIUS=120) → StateSaved
let far = world.spawn((
Npc, ActiveSim,
make_pos(200, 0), LastInteractionTick(5),
)).id();
// NPC at distance 5 (within ACTIVE_RADIUS) → stays
let near = world.spawn((
Npc, ActiveSim,
make_pos(5, 0), LastInteractionTick(50),
)).id();
run_evict_excess_active(&mut world);
assert!(world.get::<ActiveSim>(far).is_none(), "far NPC evicted");
assert!(world.get::<StateSaved>(far).is_some(), "far NPC → StateSaved");
assert!(world.get::<ActiveSim>(near).is_some(), "near NPC stays Active");
}
#[test]
fn eviction_handles_npcs_without_last_interaction_tick() {
let mut world = World::new();
world.insert_resource(SimSpacePressure {
active_count: 0,
capacity: 1,
});
world.spawn((PlayerCharacter, make_pos(0, 0)));
// NPC without LastInteractionTick defaults to tick 0 (most stale)
let no_tick = world.spawn((Npc, ActiveSim, make_pos(5, 0))).id();
let with_tick = world.spawn((
Npc, ActiveSim,
make_pos(6, 0), LastInteractionTick(100),
)).id();
run_evict_excess_active(&mut world);
assert!(world.get::<ActiveSim>(no_tick).is_none(), "no-tick NPC evicted first");
assert!(world.get::<BackgroundSim>(no_tick).is_some());
assert!(world.get::<ActiveSim>(with_tick).is_some(), "with-tick NPC stays");
}
#[test]
fn sim_space_pressure_updated_after_eviction() {
let mut world = World::new();
world.insert_resource(SimSpacePressure {
active_count: 0,
capacity: 2,
});
world.spawn((PlayerCharacter, make_pos(0, 0)));
world.spawn((Npc, ActiveSim, make_pos(5, 0), LastInteractionTick(10)));
world.spawn((Npc, ActiveSim, make_pos(6, 0), LastInteractionTick(20)));
world.spawn((Npc, ActiveSim, make_pos(7, 0), LastInteractionTick(30)));
run_evict_excess_active(&mut world);
let pressure = world.resource::<SimSpacePressure>();
// active_count is set BEFORE eviction runs (it reads the pre-eviction count).
// The actual count changes via deferred commands, which apply after the system.
assert_eq!(pressure.active_count, 3, "pressure tracks pre-eviction count");
}
// -----------------------------------------------------------------------
// LastInteractionTick component tests (#97)
// -----------------------------------------------------------------------
#[test]
fn last_interaction_tick_defaults_to_zero() {
let tick = LastInteractionTick::default();
assert_eq!(tick.0, 0);
}
}