LogicKeyValueStore

LogicKeyValueStore

Stores up to 25 global key/value pairs that survive level changes

Allows events in one map to affect another map

Inputs

Input	Parameter Format	Description
SetValue	"key=value" or "key" (value="1")	Stores a key/value pair. Fires OnValueSet on success, OnStoreFull if at max capacity.
GetValue	"key_name"	Reads a key and fires OnValueRead with the value as payload, or OnKeyNotFound if the key doesn't exist.
TestValue	"key==value" (also != > < >= <=)	Compares a stored key against a value and fires OnCompareTrue or OnCompareFalse. Comparison is numeric when both sides parse as numbers, otherwise string. Fires OnKeyNotFound if the key doesn't exist.
ClearKey	"key_name"	Removes a single key. Fires OnKeyCleared if key existed.
ClearAll	(none)	Removes all keys. No output fired.
CopyFrom	"other_store_name"	Copies all keys from another LogicKeyValueStore by name. Fires OnValueSet.
Increment	"key,amount" or "key" (amount=1)	Treats value as integer and increments. Fires OnValueSet.
Decrement	"key,amount" or "key" (amount=1)	Treats value as integer and decrements. Fires OnValueSet.

Outputs

Output	Parameter	Description
OnValueSet	"key=value"	Fired when any key is successfully set or modified.
OnValueRead	value	Fired by GetValue with the retrieved value as payload.
OnCompareTrue	actual value	Fired when a TestValue comparison passes.
OnCompareFalse	actual value	Fired when a TestValue comparison fails.
OnKeyCleared	"key_name"	Fired when a key is removed via ClearKey.
OnStoreFull	(none)	Fired when trying to add beyond the 25 key limit.
OnKeyNotFound	"key_name"	Fired when GetValue or TestValue targets a missing key.

Parameter Pass-Through

Outputs that carry a payload (see table above) pass it to any connection whose editor-authored parameter is blank. A connection with an explicit parameter always keeps its own parameter. This lets a stored value flow directly into another entity, e.g.:

story.GetValue "ending" → story.OnValueRead → GameText.SetText (blank param)

The GameText receives the stored value of ending as its text.

Properties

Property	Default	Description
store_name	entity name	Unique identifier for cross-level persistence. Matching names share data across levels.
initial_data	{}	Designer-set key/value pairs loaded at level start (max 25 pairs). Ignored if the registry already holds data for this store_name.

Limits

Limit	Value
Max key/value pairs	25
Value type	String (cast to int for Increment/Decrement, numeric compare in TestValue where possible)
Persistence scope	Class-level (survives level transitions within same process)

Example I/O Chain

The rule: put a LogicKeyValueStore in each level and give them all the same store_name (e.g. story). Same name = same data. That's it — the engine keeps the values alive between level loads automatically. Level 1 — write a value:

Trigger.OnTrigger → story.SetValue "door=left"

Level 2 — read it back:

PlayerStart.OnPlayerSpawn → story.TestValue "door==left"
story.OnCompareTrue  → SpeakerA.Play
story.OnCompareFalse → SpeakerB.Play

So: SetValue to write, TestValue to ask "is it X?" and branch. The value set in level 1 is still there when level 2 asks.

Multi-way branching — chain tests, since OnCompareFalse can feed the next TestValue (give that connection an explicit parameter so pass-through doesn't clobber it):

PlayerStart.OnPlayerSpawn → story.TestValue "state==confused"
story.OnCompareFalse      → story.TestValue "state==defiant"

Cross-Level Persistence

The LogicKeyValueStore uses a class-level _persistent_registry that survives level transitions. When a level loads a LogicKeyValueStore with a store_name that exists in the registry, it automatically inherits those values.

This allows:

• Quest progress tracking across maps
• Puzzle state persistence
• Global flags and counters
• Inventory-like systems Values persist for the whole session (they survive level changes, not quitting the game — save files embed the store's data separately). Fire ClearAll at the start of a new game to reset story state.