LogicState

LogicState

LogicState is Fio's general-purpose persistent state entity for the event-driven I/O system.

It provides a small, deterministic state model that can be read, written, compared and manipulated through normal Fio inputs and outputs. State is represented using typed values rather than a fixed-size collection of string key/value pairs.

LogicState is designed to work with Fio's UUID-based entity identity, I/O connections, Logic Graph, save/load system and dormant-world systems.

State Types

Fio supports six state types:

Type	Example	Description
string	"left"	Arbitrary text
int	42	Integer value
float	3.14	Floating-point value
bool	true	Boolean state
null	null	Explicitly empty value
uuid	550e8400-e29b-41d4-a716-446655440000	Fio object identity

UUIDs are stored as their canonical string representation but have their own state type because a UUID represents persistent Fio object identity.

There is no 25-key limit.

Create as many state entries as the application requires. Organise state using multiple LogicState entities when that makes a world easier to author and understand.

Inputs

LogicState exposes its state through the normal Fio I/O system.

Input	Parameter	Description
SetValue	key=value	Sets a state value. The value is parsed into the appropriate state type.
GetValue	key	Reads a state value and emits it through the corresponding output.
TestValue	key==value	Compares a state value using ==, !=, >, <, >= or <=.
ClearKey	key	Removes one state entry.
ClearAll	(none)	Removes all state entries.
Increment	key,amount	Adds a numeric amount to a state value. Amount defaults to 1.
Decrement	key,amount	Subtracts a numeric amount from a state value. Amount defaults to 1.
Add	key,amount	Adds a numeric amount.
Subtract	key,amount	Subtracts a numeric amount.
Multiply	key,amount	Multiplies a numeric value.
Divide	key,amount	Divides a numeric value. Division always produces a float.
Min	key,value	Replaces the value with the lower of the two numeric values.
Max	key,value	Replaces the value with the higher of the two numeric values.
Clamp	key,min,max	Restricts a numeric value to a specified range.
Toggle	key	Toggles a boolean state.

The exact input set available to an entity is defined by Fio's I/O registry and handlers. Inputs are not merely editor labels: Fio validates the relationship between declared I/O contracts and executable handlers.

Typed Values

I/O parameters are strings on the wire, but LogicState interprets them using Fio's state type system.

For example:

health=100

creates an integer value.

alive=true

creates a boolean value.

speed=2.5

creates a floating-point value.

An explicit type can be requested when necessary:

health:int=100

:::text
code:string=007

This prevents values such as 007 from being interpreted as an integer when the designer intends them to remain text.

Outputs

LogicState outputs allow state to participate directly in normal Fio I/O chains.

Typical outputs include:

Output	Payload	Description
OnValueSet	changed value	Fired when a state value is successfully changed.
OnValueRead	stored value	Fired by GetValue.
OnCompareTrue	actual value	Fired when a TestValue comparison succeeds.
OnCompareFalse	actual value	Fired when a TestValue comparison fails.
OnKeyCleared	key	Fired when an existing key is removed.
OnKeyNotFound	key	Fired when an operation targets a missing key.

Payload-carrying outputs can pass their payload through connections whose authored parameter is blank.

For example:

story.GetValue "ending"
        ↓
story.OnValueRead
        ↓
GameText.SetText

If the GameText.SetText connection has a blank parameter, it receives the value produced by OnValueRead.

An explicitly authored connection parameter takes precedence over the payload.

Comparison

TestValue supports:

==
!=
>
<
>=
<=

Numeric values are compared numerically when both sides represent numbers. Otherwise comparison uses the appropriate value semantics.

For example:

score==100

and:

health>=50

are numeric comparisons.

This avoids the old string-only problem where values such as "10" and "9" could otherwise be compared lexicographically.

Arithmetic

LogicState supports:

Add
Subtract
Multiply
Divide
Min
Max

For example:

Increment "gold,10"

can increase a player's gold counter.

Arithmetic understands existing numeric strings as well as typed numeric values, preserving compatibility with older maps.

Division always produces a float.

Division by zero fails without mutating the stored value.

Boolean State

Boolean values are real state values rather than strings.

These forms are recognised:

true
false
yes
no
on
off

A boolean can therefore be used directly as world state:

door_unlocked = true
quest_complete = false
alarm_active = true

Toggle changes a boolean value from true to false or false to true.

State and UUIDs

UUIDs can be stored directly in LogicState.

For example:

target=550e8400-e29b-41d4-a716-446655440000

A UUID is represented as a string for serialization but is recognised as the uuid state type.

This is important because Fio uses UUIDs as persistent object identity.

A LogicState value can therefore refer to another entity without relying on its display name.

This is especially important for systems involving:

• persistent world objects
• entity references
• BigWorld dormancy
• save/load
• delayed events
• cross-entity I/O

Persistence

LogicState is part of Fio's normal world/save persistence model.

State is not maintained by a special class-level registry keyed by store_name.

The old model:

LogicKeyValueStore
        ↓
store_name
        ↓
class-level persistent registry

is obsolete.

The current model is based on the actual LogicState entity and Fio's normal persistent world state.

This means state belongs to the world/entity model rather than being an independent global dictionary hidden inside the Python process.

Backwards Compatibility

Older maps may contain string-only state.

Fio deliberately preserves legacy stored values when loading them rather than rewriting the map's data into new types automatically.

However, the new state system understands those legacy strings for comparison and arithmetic.

For example, an old value:

"10"

can participate correctly in numeric operations without requiring the map to be rewritten first.

This allows existing maps to continue working while gaining the newer state semantics.

Parameter Pass-Through

Fio's I/O system allows output payloads to flow into connected inputs.

For example:

LogicState.GetValue
        ↓
OnValueRead
        ↓
GameText.SetText

With a blank connection parameter, GameText receives the state value.

With an explicit parameter:

OnValueRead → GameText.SetText "The door is open"

the authored parameter remains authoritative.

This allows LogicState to function both as a state store and as a source of data for other entities.

Event-Driven Composition

LogicState is intended to be composed with Fio's other I/O entities rather than becoming a scripting language of its own.

For example:

Trigger
   │
   ▼
LogicState.SetValue
   │
   ▼
OnValueSet
   │
   ▼
Door.Open

Or:

PlayerStart
   │
   ▼
LogicState.TestValue
   │
   ├── OnCompareTrue  → SpeakerA.Play
   │
   └── OnCompareFalse → SpeakerB.Play

More complex behaviour can be constructed by chaining ordinary Fio entities:

Trigger
   ↓
LogicState
   ↓
LogicGate / Relay
   ↓
LogicState
   ↓
Door / Mover / Light / Speaker

The resulting behaviour remains visible in the Logic Graph and represented as world data rather than requiring a script.

Example: Quest State

A quest can maintain explicit typed state:

quest_stage:int=2
quest_complete:bool=false
reward_gold:int=100
quest_target:uuid=550e8400-e29b-41d4-a716-446655440000

A trigger can advance the quest:

Trigger.OnTrigger
    → QuestState.Increment "quest_stage"

The resulting state can then drive other world behaviour:

QuestState.OnValueSet
    → Door.Open

or branch:

PlayerStart.OnPlayerSpawn
    → QuestState.TestValue "quest_stage>=3"

QuestState.OnCompareTrue
    → EndQuest

QuestState.OnCompareFalse
    → ContinueQuest

Design Principles

LogicState is deliberately small.

It does not contain:

• a Lua runtime
• an event bus
• arbitrary Python execution
• editor-only state
• a second persistence mechanism
• a fixed 25-entry capacity

Its purpose is to provide typed, persistent, inspectable state that participates directly in Fio's existing event-driven I/O architecture.

That makes LogicState usable by the editor, runtime, Logic Graph, save/load system and world-streaming systems without requiring those systems to know about an unrelated scripting layer.

Summary

LogicState is the state primitive for Fio's event-driven world-control system.

It provides:

• typed state
• arbitrary numbers of state entries
• string, integer, float, boolean, null and UUID values
• comparisons
• arithmetic
• boolean toggling
• state clearing
• I/O payload pass-through
• UUID-based references
• save/load persistence
• backwards compatibility with legacy string state
• direct Logic Graph composition

The old LogicKeyValueStore model of 25 string key/value pairs shared through a class-level store_name registry is no longer the Fio state model.

LogicState is now part of the normal Fio world and I/O architecture.