Triggers System

This page covers how to create custom trigger types and requirement types that integrate with Spark's systems.

Creating Custom Trigger Types

A trigger type defines an action that can be configured in the Spark Editor and executed at runtime. To create one, you need to understand the trigger system's architecture.

Trigger Type Structure

Each trigger type is a class that:

1. Defines its configurable fields (shown in the Spark Editor)

2. Implements execution logic (what happens when the trigger fires)

3. Registers itself with the Triggers plugin

Here is the pattern, based on how built-in trigger types work:

using UnityEngine;

[System.Serializable]
public class GiveReputationTriggerType
{
    [DatabaseEntryDropdown(typeof(FactionEntry))]
    [SerializeField] private string factionId;

    [SerializeField] private int amount = 10;

    [DisplayNameTooltip("Source", "What caused this reputation change.")]
    [SerializeField] private string source = "trigger";

    public void Execute(string characterId)
    {
        Spark.Network?.ExecuteCommand(new ModifyReputationCommand
        {
            CharacterId = characterId,
            FactionId = factionId,
            Amount = amount,
            Source = source
        });
    }
}

Key points:

• Use [SerializeField] for fields the designer configures in the editor.

• Use Spark attributes ([DatabaseEntryDropdown], [ConditionalField], etc.) for a good editor experience.

• Execute actions through commands, not directly. This ensures networking compatibility.

• Keep the trigger focused on a single action.

Trigger Attributes

Use these attributes on trigger type fields:

• [TriggerRefresh]: Marks a field that should refresh the trigger UI when changed.

• [HorizontalRuleTriggers]: Adds a visual separator line before the field.

Creating Custom Requirement Types

A requirement type defines a condition that can be checked at runtime.

Requirement Type Structure

using UnityEngine;

[System.Serializable]
public class FactionReputationRequirementType
{
    [DatabaseEntryDropdown(typeof(FactionEntry))]
    [SerializeField] private string factionId;

    [SerializeField] private ComparisonType comparison = ComparisonType.GreaterThanOrEqual;

    [SerializeField] private int requiredAmount = 0;

    public bool Check(string characterId)
    {
        if (!SparkEntityRegistry.TryGetEntity(characterId, out SparkEntity entity))
            return false;

        var tracker = entity.GetSparkComponent<FactionTrackerEntity>();
        if (tracker == null)
            return false;

        int current = tracker.GetReputation(factionId);

        return comparison switch
        {
            ComparisonType.Equal => current == requiredAmount,
            ComparisonType.NotEqual => current != requiredAmount,
            ComparisonType.GreaterThan => current > requiredAmount,
            ComparisonType.GreaterThanOrEqual => current >= requiredAmount,
            ComparisonType.LessThan => current < requiredAmount,
            ComparisonType.LessThanOrEqual => current <= requiredAmount,
            _ => false
        };
    }
}

Key points:

• Use ComparisonType for numeric comparisons. Spark provides this enum.

• Return bool from the check method.

• Always handle null cases gracefully (entity not found, component missing).

• Use [HorizontalRuleChecks] attribute for visual separators in the editor.

Registration

Trigger types and requirement types are discovered by the Triggers and Requirements plugins through reflection and assembly scanning. Place them in an assembly that references the Triggers or Requirements plugin assembly, and they will be picked up automatically.

Best Practices

• Name trigger types as {Action}TriggerType (e.g., GiveReputationTriggerType).

• Name requirement types as {Condition}RequirementType (e.g., FactionReputationRequirementType).

• Always execute state changes through commands in triggers.

• Always validate all inputs in requirements (null checks, entity checks).

• Use Spark's custom attributes for a polished editor experience.

• Keep triggers and requirements stateless. They should work purely from their serialized fields and the current game state.