Trigger System Overview

Concept

Triggers are logic units that respond to in-game events. They consist of:

• Event type (e.g., ENTER_TILE, ON_DAMAGE)

• Condition (e.g., always true, perception check)

• Reaction (e.g., apply damage, spawn trap)

• Optional Chaining to further triggers

• Optional Cooldowns to prevent overfiring

Each trigger listens for events dispatched via the EventBus.

Trigger Flow Diagram

        graph TD
  Event[Game Event: ENTER_TILE] -->|dispatch| Trigger1
  Trigger1 -->|Condition| ConditionCheck[PerceptionCheck]
  ConditionCheck -->|Fails| End1[Do Nothing]
  ConditionCheck -->|Succeeds| Reaction1[ApplyDamage]
  Reaction1 --> Reaction2[AlertGamemaster]
  Reaction2 -->|Optional| NextTrigger
    

Trigger Structure

Trigger Components:

• Event Type: A string identifier (e.g., “ENTER_TILE”).

• Condition: A callable, such as: - AlwaysTrue – always passes. - PerceptionCheck – simulates a skill roll using character_stats. - SkillCheck – supports DC, stat-based success/failure.

• Reaction: A callable or class with an execute() method. Examples: - ApplyDamage - AlertGamemaster - MoveEntity, RevealArea, SpawnEntity

• Chaining: A trigger can define a next_trigger, which is conditionally or automatically fired.

• Cooldown: Prevents reactivation for a number of turns (via TurnManager).

Condition Evaluation

Note

For SkillCheck and PerceptionCheck, the logic is inverted:

• If the check fails, the reaction is triggered.

• This is useful for traps: players failing to notice one may take damage.

Trigger JSON Structure

Note

The trigger system uses a JSON structure to define triggers, making it easy to create, modify, and serialize them. The JSON structure for a trigger includes the event type, label, condition, reaction, and optional chaining and cooldowns. This allows for flexible and dynamic trigger definitions that can be easily modified or extended.

Example:

```python

{ “event_type”: “ENTER_TILE”, “label”: “Trap Trigger”, “condition”: {

“type”: “SkillCheck”, “skill”: “Perception”, “dc”: 12

}, “reaction”: {

“type”: “ApplyDamage”, “args”: { “amount”: 5 }

}, “next_trigger”: {

“event_type”: “CHAIN”, “condition”: { “type”: “AlwaysTrue” }, “reaction”: { “type”: “AlertGamemaster”, “args”: {

“message”: “Trap sprung!”

```