---
name: event-patterns
description: Complex event flow patterns for Valkyrie MoM scenarios. Use when creating event loops, multi-question dialogues, silent events, token swaps, random events, or variable-controlled branching.
---

# /event-patterns - Complex Event Flow Patterns

Advanced event patterns for Mansions of Madness scenarios. Each pattern includes structure, rules, and MCP tool call examples.

## Silent Events

Silent events (`display=false`) auto-advance without showing dialog. Used for logic branching, cleanup, and chaining.

**Critical rules:**
- If a silent event has `event1` set, it MUST have `buttons>=1`. Valkyrie only parses `event1..eventN` up to the `buttons` count.
- A silent event with `buttons=0` is only safe when it has NO `eventN` fields (e.g., a terminal remove-only event).
- Silent events with `vartests` branch based on variable state without player interaction.

**Example — Silent cleanup event:**
```
upsert_event("EventCleanup", {
  display: "false",
  buttons: "1",
  remove: "TokenOldClue SpawnGuard",
  event1: "EventNextPhase"
})
```

**Example — Terminal silent event (no chaining):**
```
upsert_event("EventRemoveInvestigators", {
  display: "false",
  buttons: "0",
  remove: "TokenInvestigators"
})
```

## Event Loops

Loops repeat a block of events until an exit condition is met. Structure: **Controller → Body → Exit**.

### Structure

1. **Init Event**: Set loop counter variable to 0
2. **Controller Event**: Silent event with vartests checking counter vs limit
   - If counter < limit → route to Body
   - If counter >= limit → route to Exit
3. **Body Event(s)**: The repeated content. Increments counter, routes back to Controller.
4. **Exit Event**: Continues the scenario after the loop ends.

### Example — 3-iteration loop

```
# Initialize
upsert_event("EventLoopInit", {
  display: "false",
  buttons: "1",
  operations: "loopCount,=,0",
  event1: "EventLoopController"
})

# Controller — pick exit or body. Valkyrie runs the FIRST listed event whose
# vartests pass, so the tested exit goes first and the untested body is the fallback.
upsert_event("EventLoopController", {
  display: "false",
  buttons: "1",
  event1: "EventLoopExit EventLoopBody"
})

# Body — do work, increment, return to controller
upsert_event("EventLoopBody", {
  display: "true",
  buttons: "1",
  operations: "loopCount,+,1",
  event1: "EventLoopController"
})

# Exit — only enabled once the limit is reached
upsert_event("EventLoopExit", {
  display: "true",
  buttons: "1",
  vartests: "VarOperation:loopCount,>=,3",
  event1: "EventNextScene"
})
```

**Important — how vartests branch:**
- vartests on an event decide whether *that* event runs. If they fail, the event is skipped.
- They never route between event1 and event2. A hidden event (`display: "false"`) always follows button 1, so its event2+ never run.
- Branch by listing candidates in one button (`event1: "EventA EventB"`). Valkyrie runs the first one whose vartests pass.
- `validate_scenario` flags hidden events with unreachable event2+ (rule `event-semantics`).

### Infinite Loop Avoidance

- Always increment the counter in the body
- Always have an exit path when counter reaches the limit
- Test with `>=` not `==` to avoid off-by-one infinite loops

## Multi-Question Dialogues

A dialogue where each of N questions has its own pass/fail outcome, requiring 2^N permutation events for all combinations. For 3 questions, that's 8 final outcome events.

### 3-Question Template (8 permutations)

```
# Question 1 — skill test
upsert_event("EventQ1", {
  buttons: "2",
  quota: "1",
  event1: "EventQ2fromQ1Pass",    # Q1 passed → Q2
  event2: "EventQ2fromQ1Fail"     # Q1 failed → Q2
})

# Question 2 — after Q1 pass
upsert_event("EventQ2fromQ1Pass", {
  buttons: "2",
  quota: "1",
  event1: "EventQ3_PP",    # Q1 pass, Q2 pass → Q3
  event2: "EventQ3_PF"     # Q1 pass, Q2 fail → Q3
})

# Question 2 — after Q1 fail
upsert_event("EventQ2fromQ1Fail", {
  buttons: "2",
  quota: "1",
  event1: "EventQ3_FP",    # Q1 fail, Q2 pass → Q3
  event2: "EventQ3_FF"     # Q1 fail, Q2 fail → Q3
})

# Question 3 — four variants (PP, PF, FP, FF from Q1+Q2)
# Each has 2 outcomes → 8 total final events
upsert_event("EventQ3_PP", {
  buttons: "2",
  quota: "1",
  event1: "EventOutcome_PPP",
  event2: "EventOutcome_PPF"
})
# ... (EventQ3_PF, EventQ3_FP, EventQ3_FF similarly)

# 8 Outcome events: PPP, PPF, PFP, PFF, FPP, FPF, FFP, FFF
# Each shows narrative based on the combination of successes/failures
```

### Simplification with Variables

For more than 3 questions, use variables instead of permutation events:
```
# Track successes with a variable
upsert_event("EventQ1", {
  buttons: "2",
  quota: "1",
  operations: "successes,=,0",
  event1: "EventQ1Pass",
  event2: "EventQ1Fail"
})

upsert_event("EventQ1Pass", {
  display: "false",
  buttons: "1",
  operations: "successes,+,1",
  event1: "EventQ2"
})
# ... then check successes threshold at the end
```

## Token Swap (Silent Update)

Replace one token with another in a single event. Used to update the map state (e.g., locked door → open door).

```
upsert_event("EventUnlockDoor", {
  display: "false",
  buttons: "1",
  remove: "TokenLockedDoor",
  add: "TokenOpenDoor",
  event1: "EventDoorOpened"
})
```

**When to use:**
- Changing token type (explore → interact)
- Updating visual state (locked → unlocked)
- Replacing a monster spawn with a different one
- Any state transition that should be invisible to the player

## Random Event Selection

Use `randomevents=true` to pick one event at random from a button's list. Put **all candidates in event1**: a hidden event always follows button 1, so candidates in event2+ are never picked.

```
upsert_event("EventRandomEncounter", {
  display: "false",
  buttons: "1",
  randomevents: "true",
  event1: "EventEncounterGhost EventEncounterCultist EventEncounterHorror"
})
```

### Preventing Repeats with Flag Variables

Only events whose vartests pass are candidates, so a "seen" flag per outcome removes it from the pool:

```
upsert_event("EventRandomEncounter", {
  display: "false",
  buttons: "1",
  randomevents: "true",
  event1: "EventEncA EventEncB EventEncC"
})

# Each encounter is only a candidate while unseen, and marks itself seen
upsert_event("EventEncA", {
  buttons: "1",
  vartests: "VarOperation:seenA,==,0",
  operations: "seenA,=,1",
  event1: "EventContinue"
})
```

## Variable-Controlled Branching

An event's vartests decide whether that event runs; they never choose a button. Branch by listing the candidates in one button — Valkyrie runs the **first** one whose vartests pass (list the most specific first and end with an untested fallback).

### Ordered vartests (Multiple Thresholds)

```
upsert_event("EventCheckProgress", {
  display: "false",
  buttons: "1",
  event1: "EventAllClues EventSomeClues EventNoClues"
})

upsert_event("EventAllClues",  { buttons: "1", vartests: "VarOperation:cluesFound,>=,3", event1: "EventContinue" })
upsert_event("EventSomeClues", { buttons: "1", vartests: "VarOperation:cluesFound,>=,1", event1: "EventContinue" })
upsert_event("EventNoClues",   { buttons: "1", event1: "EventContinue" })   # fallback, no tests
```

### Button-Level Conditions

To enable or hide a *button* on a displayed event, put the test on the button:

```
upsert_event("EventLockedDoor", {
  buttons: "2",
  event1: "EventUseKey",
  event1Condition: "VarOperation:hasKey,==,1",
  event1ConditionAction: "hide",     # disable (default) | hide | none
  event2: "EventLeave"
})
```

### conditions is legacy

`conditions: "var,op,val"` is the old AND-only form of vartests. Valkyrie **ignores it whenever vartests is set**, so never combine them (validate_scenario reports this as an error). Write everything in vartests.

### Multi-variable Check

Logical operators go *between* tests:

```
upsert_event("EventBothKeys", {
  buttons: "1",
  vartests: "VarOperation:key1Found,>=,1 VarTestsLogicalOperator:AND VarOperation:key2Found,>=,1",
  event1: "EventOpenVault"
})
```

## Pattern Naming Conventions

Use consistent naming to keep complex event flows readable:
- `Event<Location><Action>` — e.g., `EventStudyExplore`, `EventHallwayFight`
- `Event<Name>Pass` / `Event<Name>Fail` — skill test outcomes
- `Event<Name>Loop` / `Event<Name>LoopBody` / `Event<Name>LoopExit` — loop components
- `EventQ1`, `EventQ2`, etc. — dialogue questions
- `0_<Name>` / `1_<Name>` prefixes for loop init/body events within a tile context
