Glossary

This glossary defines the core terms and concepts used within the Gnosis Engine ecosystem.

A

Ability : A persistent gameplay feature (e.g., a special move or passive skill) defined in configuration. Abilities often trigger Invocations when used and can be selected or unselected during a Run.

Adapter (Unity Adapter) : The bridge between Gnosis Engine’s pure logic services and the Unity environment. Adapters handle Unity-specific tasks like playing sounds, updating UI, or managing GameObject life cycles in response to engine events.

C

Calculations : Named math steps defined within a Rule. They are evaluated sequentially before Conditions are checked, and their results can be used in both conditions and Outcomes.

Communication Policy : A setting that defines how a Service or System is exposed. It controls whether other services can call it directly and whether Unity Adapters are allowed to bind to it.

Conditions : The “if” part of a Rule. A list of logical comparisons (e.g., hp < 50) that must all pass for the rule’s Outcomes to be applied.

E

Ephemeral State : Data that exists only for the duration of a single Run. This includes transient values like current player HP, temporary inventory, or active buffs. It is wiped when the engine resets.

Event Bus : The central nervous system of Gnosis Engine. It facilitates communication between Services, Systems, and Adapters by allowing them to publish and subscribe to Requests and Facts.

F

Fact : An event published after a state change has been successfully applied. It is immutable and informs the engine that something has officially happened. (e.g., FACT_CURRENCY_ADDED).

G

GnosisContext : The shared object passed to every Service during initialization. It provides access to the engine’s core infrastructure, including the Event Bus, Store, State, and Logger.

GnosisEvent : The data structure used by the Event Bus to carry information across the engine. It contains an ID (e.g., FACT_PLAYER_DIED) and a data payload.

GnosisNode : A high-performance, handle-based proxy for structured data. To the developer, it acts like a dynamic object or a JSON node. Internally, it is just a 12-byte handle to data stored in the GnosisStore.

GnosisState : A lightweight wrapper for the logical state tree. It provides a simple API for services to read and write data into their namespaced regions of the Store.

GnosisStore : The low-level memory manager that powers GnosisNodes. It uses flat arrays and object pooling to provide 100% zero-allocation updates to the engine’s state during gameplay.

I

Interceptor : A type of Rule that directly modifies an event’s payload (typically a Request) before it reaches its final destination. They are commonly used for buffs, debuffs, or conditional modifiers.

Invocation : A data-driven “remote procedure call” described in JSON. Instead of hard-coding sequences of actions in C#, many systems (like Boons or Consumables) define their effects as a list of Invocations.

L

Lifetime : Defines the existence span of a Service or System.

• Permanent: Exists for the entire life of the engine application.
• Ephemeral: Created fresh for each run and destroyed when the run ends.

O

Observer : A type of Rule that listens for Fact events to trigger side effects (e.g., playing a sound when a purchase is completed) without modifying the original action.

Outcomes : The “then” part of a Rule. A list of actions (e.g., setting a value, calling a service function) that are executed if all Conditions pass.

P

Persistent State : Data that is saved across sessions and runs. This includes player progress, unlocked items, settings, and the game’s core configuration (rules, abilities, etc.).

Q

Query : A declarative way to find specific GnosisNodes within a state tree. Queries use a path-based syntax (e.g., ephemeral.inventory.items[type == 'potion']) to filter and retrieve data.

R

Request : An event published before any state change occurs. Its purpose is to allow Interceptor Rules to modify the payload (e.g., applying damage reduction before health is actually subtracted). (e.g., REQUEST_CURRENCY_ADD).

Run : A single gameplay session. When a run starts, the engine initializes Ephemeral services and state; when it ends, this transient state is wiped.

S

Service : A logic and state manager within the Gnosis Engine. Services are C# classes that handle specific domains like Inventory, Health, or Currency. They are the only components allowed to write directly to the Store.

System : Engine or game logic that understands rules, balance, and synergies. Systems decide what should happen and express it as Requests. They are often implemented via JSON rules rather than dedicated C# classes.

T

Trigger : A type of Rule that performs a one-time engine action (such as spawning VFX, playing audio, or calling a specific service function) when its trigger event occurs.