Invocations (JSON → CallFunction)

Invocations are a core pattern in Gnosis Engine that allow for data-driven behavior. Instead of hard-coding every sequence of actions in C#, many systems (like Boons, Consumables, and Upgrades) define their effects as a list of “invocations” in JSON.

How Invocations Work

An invocation is essentially a “remote procedure call” described in data. When the engine “runs” an invocation, it:

1. Identifies the Service: Looks up the target service (e.g., Audio, Currency).
2. Identifies the Function: Looks up the specific function name on that service (e.g., PlaySfx, Add).
3. Prepares Parameters: Converts the JSON parameters object into a GnosisNode and passes it to the function.

The Invocation Object Shape

Every invocation entry in a JSON list follows this structure:

{
  "service": "ServiceId",
  "function": "FunctionName",
  "parameters": {
    "key1": "value1",
    "key2": 100
  }
}

• service (string): The unique ID of the target service.
• function (string): The name of the function to call on that service.
• parameters (object, optional): A key-value map of arguments for the function.

Practical Examples

1. Consumable Effect (Heal + Sound)

A health potion definition might have an invocations array that both restores health and plays a sound effect.

Trigger: Player uses “Health Potion”

"invocations": [
  {
    "service": "Stats",
    "function": "ModifyStat",
    "parameters": { "statId": "HP", "amount": 20 }
  },
  {
    "service": "Audio",
    "function": "PlaySfx",
    "parameters": { "clipId": "heal_potion_01" }
  }
]

2. Boon Activation (Grant Currency + Show UI)

A “Starter Gift” boon might trigger these actions when acquired.

Trigger: Boon Activated

"onActivateInvocations": [
  {
    "service": "Currency",
    "function": "Add",
    "parameters": { "id": "Gold", "amount": 500 }
  },
  {
    "service": "UserInterface",
    "function": "ShowNotification",
    "parameters": { "text": "Received 500 Gold!", "icon": "gold_icon" }
  }
]

Execution Flow

The primary entry point for executing these lists is GnosisEngine.RunInvocationList. It utilizes GnosisInvocationUtilities to process the list.

1. Iterate: The engine loops through the list of invocation objects.
2. Context Merging: If a “context” node is provided (e.g., specific event data), the engine merges it with the parameters defined in the JSON.
   • Note: Values defined in the JSON entry take precedence over context values.
3. Call: The engine calls CallFunction(callerId, serviceId, functionName, finalParameters).
4. Error Handling: By default, the engine continues to the next invocation even if one fails. This can be configured to stop on the first failure.

Extending the System

To make a new feature invokable via JSON:

1. Subclass GnosisServiceBase: You should always subclass GnosisServiceBase to create a new service. It provides standard lifecycle hooks and state helpers.
2. Override InvokeFunction: Handle the incoming function name and parameters.
3. Register the Service: Ensure the service is registered with the GnosisEngine.

// Example Service Implementation
public override GnosisFunctionResult InvokeFunction(string name, GnosisNode parameters)
{
    if (name == "MyCustomAction") {
        var val = (int)parameters["amount"];
        DoSomething(val);
        return GnosisFunctionResult.Ok();
    }
    return base.InvokeFunction(name, parameters);
}

When to use Invocations vs Rules?