Skip to content

Firing Semantics

Jump to bottom
Taeguk edited this page Jun 7, 2026 · 2 revisions

Firing Semantics

Firing semantics control when a guidance entry is allowed to fire. Every time a trigger event occurs, the dispatcher checks these rules before showing anything to the player.

once

The most common control. When once: true (the default), the entry fires exactly once and is then permanently suppressed for that character.

- id: first_bronze_sword
  trigger: { type: craft, item: SwordBronze }
  display:
    mode: raven
    topic: "Bronze Edge"
    text: "Forged in fire, this blade cleaves the Black Forest's beasts."
  once: true      # default — this line is optional

For global scope entries, once: true means once per world (the first player to trigger it fires it for everyone, and it never fires again for that world).

Set once: false to allow the entry to fire repeatedly (combined with cooldown to throttle it).

cooldown

Instead of firing once and stopping, the entry can fire repeatedly on a throttle.

- id: swamp_tip
  trigger: { type: biome, biome: Swamp }
  display:
    mode: message
    text: "Bring an antidote potion into the swamp."
  once: false
  cooldown: 900     # 15 minutes between fires, per character

cooldown is measured in seconds. After the entry fires, it is suppressed for that many seconds. When the cooldown expires, the entry is eligible again.

cooldown and once: true are mutually exclusive — if once: true, the entry never fires a second time regardless of cooldown.

requires

An entry with a requires list only fires after all listed entry IDs have already fired for this character.

- id: swamp_crypt_tip
  trigger: { type: biome, biome: Swamp }
  requires: [first_bronze_sword]      # only show once the player has made a bronze sword
  display:
    mode: raven
    topic: "Sunken Crypts"
    text: "Seek iron in the bog. Bring a key."

This allows you to sequence guidance — don't tell a player about swamp crypts until they've progressed enough to be ready for them.

Important: If any ID in requires does not exist in the YAML, the entry is permanently blocked (treated as an unsatisfied dependency). Double-check that all referenced IDs are valid.

Multiple requirements all must be satisfied:

requires: [entered_swamp, has_bronze_gear]

stop_when

An entry stops firing once any ID in the stop_when list has fired. This is useful for "show a recurring reminder until the player has done X".

- id: troll_armor_reminder
  trigger: { type: kill, creature: Troll }
  display:
    mode: message
    text: "Troll hide makes fine armor. Craft it at a workbench."
  once: false
  cooldown: 600
  stop_when: [crafted_troll_armor]    # stop nagging once they've made the set

stop_when is checked before cooldown, so once any stop condition fires, the entry is suppressed immediately regardless of whether the cooldown has reset.

requires + stop_when Together

Combine both to create narrow windows:

- id: plains_entry_warning
  trigger: { type: biome, biome: Plains }
  requires: [reached_iron_age]         # don't warn until they've progressed
  stop_when: [defeated_yagluth]        # stop once they've beaten the plains boss
  cooldown: 1800
  display:
    mode: message
    text: "The plains are deadly. Bring padded armor and a good shield."

version

If you update the text of an entry that players have already seen, bump version to re-deliver it.

- id: forge_tip
  version: 2           # players who saw version 1 will see this again
  trigger: { type: craft, item: Forge }
  display:
    mode: raven
    topic: "The Forge"
    text: "Updated guidance: the forge also lets you upgrade existing items."
  once: true

The version number is stored alongside the fired state. Raising it resets the "already fired" check for that entry.

Evaluation Order

When a trigger event occurs, the dispatcher checks in this order:

  1. Scope — Is this a global entry? If so, has the world already marked it fired?
  2. requires — Have all prerequisite IDs fired for this character?
  3. stop_when — Has any stop condition fired?
  4. once — Has this entry already fired for this character (if once: true)?
  5. cooldown — Is the entry still on cooldown?
  6. Fire — All checks passed; show the display.

The entry fires if and only if all checks pass.

Fire Modes Reference

Setting Behaviour
once: true (default) Fire once, ever, per character (or per world for global scope).
once: false (no cooldown) Fire every time the trigger condition is met.
once: false + cooldown: N Fire at most once every N seconds.
stop_when: [id] Stop firing permanently once id has fired.
requires: [id] Don't fire at all until id has fired.

Clone this wiki locally