State Tree: Persistent & Ephemeral

The engine organizes its shared state into two primary branches under a single root node. This helps maintain a clear “source of truth” while keeping data lifecycle management simple.

The Root Branches

1. Persistent

Contains data that survives between game runs.

• configuration: JSON configurations loaded at startup (rules, definitions, boons, etc.).
• save_data: The current player’s profile (unlocked items, settings).
• global_stats: High-level telemetry like “Total Kills” or “Matches Played”.

2. Ephemeral

Contains data that is transient and typically reset at the start of a match/run.

• run: The state of the current match (player HP, current inventory, score).
• shop: Current shop stock and prices.
• rules: A dynamic list of active rule IDs that the event bus should process.

Accessing State in C#

You can interact with the state tree using the engine.State helper.

Reading Data

// Using engine.State helpers
int hp = engine.State.GetInt("Ephemeral.run.player.hp", 100);
string name = engine.State.GetString("Persistent.profile.playerName");
 
// Directly using the root node
GnosisNode root = engine.State.Root;
float volume = (float)root["Persistent.settings.volume"];

Writing and Modifying Data

// Simple sets
engine.State.SetInt("Ephemeral.run.player.hp", hp - 10);
 
// Using Increment helper
engine.State.Increment("Persistent.global_stats.total_games", 1);
 
// Bulk initialization with SetDeep
engine.State.Root.SetDeep("Ephemeral.run.startingItems", startingItemsNode);