@thijshakkenberg/valkyrie-mom-mcp 1.0.0

package/skills/custom-monsters/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: custom-monsters
+description: Custom monster creation for Valkyrie MoM. Use when creating scenario-specific enemies with custom activations, evade, horror, and spawn triggering.
+---
+
+# /custom-monsters - Custom Monster Creation
+
+Create scenario-specific monsters with unique behaviors, activations, and stat overrides.
+
+## Component Structure
+
+Custom monsters use the `CustomMonster` prefix and require a `base` field referencing a catalog monster.
+
+```
+upsert_token("CustomMonsterBoss", {
+  base: "MonsterCultist",
+  health: "8",
+  healthperhero: "2"
+})
+```
+
+**Note:** Custom monsters are created via the spawn system. The `base` field determines the visual appearance and default stats. Override any field to customize.
+
+### Required Fields
+
+| Field | Description |
+|-------|-------------|
+| `base` | Base monster type from catalog (e.g., MonsterCultist, MonsterGhost) |
+
+### Optional Stat Overrides
+
+| Field | Description |
+|-------|-------------|
+| `health` | Base health points |
+| `healthperhero` | Additional health per investigator |
+| `horror` | Horror value for horror checks |
+| `awareness` | Detection range |
+| `traits` | Space-separated trait keywords |
+
+## Custom Activations
+
+Override the default monster activation with a custom event sequence. When the monster activates during the mythos phase, your custom event fires instead of the standard AI behavior.
+
+### Activation Event Structure
+
+```
+# Monster definition with custom activation
+upsert_spawn("SpawnBoss", {
+  monster: "CustomMonsterCultLeader",
+  uniquehealth: "10",
+  uniquehealthhero: "3"
+})
+
+# Activation event — triggered when the monster activates
+upsert_event("EventCultLeaderActivation", {
+  trigger: "Mythos",
+  buttons: "2",
+  randomevents: "true",
+  event1: "EventCultLeaderAttack",
+  event2: "EventCultLeaderSummon"
+})
+
+# Attack pattern
+upsert_event("EventCultLeaderAttack", {
+  buttons: "1",
+  event1: "EventCultLeaderMoveAndStrike"
+})
+
+# Summon pattern — spawns a minion
+upsert_event("EventCultLeaderSummon", {
+  buttons: "1",
+  add: "SpawnCultistMinion",
+  event1: "EventCultLeaderDone"
+})
+```
+
+### Random Move + Attack Patterns
+
+Use `randomevents=true` to vary monster behavior each activation:
+
+```
+upsert_event("EventBossActivation", {
+  display: "false",
+  buttons: "3",
+  randomevents: "true",
+  event1: "EventBossAggressive",     # charge and attack
+  event2: "EventBossDefensive",      # retreat and heal
+  event3: "EventBossSpecial"         # unique ability
+})
+```
+
+## Evade & Horror Events
+
+### Custom Evade
+
+When an investigator attempts to evade, the custom evade event fires:
+
+```
+upsert_event("EventBossEvade", {
+  buttons: "2",
+  quota: "2",                        # difficulty threshold
+  event1: "EventBossEvadeSuccess",   # pass → escape
+  event2: "EventBossEvadeFail"       # fail → consequence
+})
+
+set_localization({
+  "EventBossEvade.text": "The cult leader blocks your path. Test {agility} to slip past.",
+  "EventBossEvade.button1": "{qst:PASS}",
+  "EventBossEvade.button2": "{qst:FAIL}",
+  "EventBossEvadeSuccess.text": "You dart past the robed figure.",
+  "EventBossEvadeFail.text": "The cult leader grabs your arm. Suffer 1 damage."
+})
+```
+
+### Custom Horror
+
+When an investigator encounters the monster, the custom horror event fires:
+
+```
+upsert_event("EventBossHorror", {
+  buttons: "2",
+  quota: "1",
+  event1: "EventBossHorrorPass",
+  event2: "EventBossHorrorFail"
+})
+
+set_localization({
+  "EventBossHorror.text": "The creature's true form is revealed. Test {will} to resist the madness.",
+  "EventBossHorror.button1": "{qst:PASS}",
+  "EventBossHorror.button2": "{qst:FAIL}"
+})
+```
+
+## Spawn Triggering
+
+### Round-Based Spawning
+
+Use `EndRound` trigger with `#round` vartests and one-shot flags:
+
+```
+# Check if it's time to spawn
+upsert_event("EventRound3Spawn", {
+  trigger: "EndRound",
+  display: "false",
+  buttons: "2",
+  conditions: "round3Spawned,==,0",
+  vartests: "VarOperation:#round,>=,3",
+  event1: "EventRound3SpawnSkip",    # not time yet
+  event2: "EventRound3SpawnFire"     # round >= 3, spawn!
+})
+
+upsert_event("EventRound3SpawnFire", {
+  buttons: "1",
+  operations: "round3Spawned,=,1",
+  add: "SpawnHallwayGhost",
+  event1: "EventRound3SpawnNarrative"
+})
+```
+
+### Progressive Spawning
+
+Spawn increasingly dangerous monsters as the scenario progresses:
+
+```
+# Early game — minor enemies
+upsert_event("EventEarlySpawn", {
+  trigger: "EndRound",
+  display: "false",
+  buttons: "2",
+  conditions: "earlySpawnDone,==,0",
+  vartests: "VarOperation:#round,>=,2",
+  event1: "EventEarlySpawnSkip",
+  event2: "EventEarlySpawnFire"
+})
+
+# Mid game — tougher enemies
+upsert_event("EventMidSpawn", {
+  trigger: "EndRound",
+  display: "false",
+  buttons: "2",
+  conditions: "midSpawnDone,==,0",
+  vartests: "VarOperation:#round,>=,6",
+  event1: "EventMidSpawnSkip",
+  event2: "EventMidSpawnFire"
+})
+
+# Late game — boss
+upsert_event("EventBossSpawn", {
+  trigger: "EndRound",
+  display: "false",
+  buttons: "2",
+  conditions: "bossSpawnDone,==,0",
+  vartests: "VarOperation:#round,>=,10",
+  event1: "EventBossSpawnSkip",
+  event2: "EventBossSpawnFire"
+})
+```
+
+### Event-Triggered Spawns
+
+Spawn monsters in response to player actions:
+
+```
+upsert_event("EventOpenCoffin", {
+  buttons: "1",
+  add: "SpawnCoffinZombie",
+  event1: "EventCoffinNarrative"
+})
+```
+
+## Monster Stats Reference
+
+Common base monsters for the `base` field:
+
+| Monster | Health | Per Hero | Notes |
+|---------|--------|----------|-------|
+| MonsterCultist | 2 | 1 | Basic human enemy |
+| MonsterGhost | 3 | 1 | Incorporeal, horror focus |
+| MonsterZombie | 3 | 1 | Slow but tough |
+| MonsterManiac | 2 | 1 | Fast, aggressive |
+| MonsterWitch | 3 | 1 | Spell-based attacks |
+| MonsterHuntingHorror | 5 | 2 | Flying, strong |
+| MonsterRiotOfFlesh | 4 | 2 | Resilient |
+| MonsterStarSpawn | 6 | 2 | Boss-tier |
+| MonsterDeepOne | 3 | 1 | Aquatic areas |
+| MonsterThrall | 2 | 1 | Swarm enemy |
+
+Use `search_game_content` with query "Monster" to find all available monsters including expansion content.

package/skills/event-patterns/SKILL.md

@@ -0,0 +1,268 @@
+---
+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 — check if done
+upsert_event("EventLoopController", {
+  display: "false",
+  buttons: "2",
+  vartests: "VarOperation:loopCount,>=,3",
+  event1: "EventLoopBody",    # button1 = test FAILS (keep looping)
+  event2: "EventLoopExit"     # button2 = test PASSES (exit)
+})
+
+# Body — do work, increment, return to controller
+upsert_event("EventLoopBody", {
+  display: "true",
+  buttons: "1",
+  operations: "loopCount,+,1",
+  event1: "EventLoopController"
+})
+
+# Exit
+upsert_event("EventLoopExit", {
+  display: "true",
+  buttons: "1",
+  event1: "EventNextScene"
+})
+```
+
+**Important — vartests button mapping:**
+- `button1` / `event1` = test **FAILS** (condition not met)
+- `button2` / `event2` = test **PASSES** (condition met)
+
+### 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 randomly pick one event from the event list instead of showing all buttons.
+
+```
+upsert_event("EventRandomEncounter", {
+  display: "false",
+  buttons: "3",
+  randomevents: "true",
+  event1: "EventEncounterGhost",
+  event2: "EventEncounterCultist",
+  event3: "EventEncounterHorror"
+})
+```
+
+### Preventing Repeats with Flag Variables
+
+Use a flag variable per outcome to skip already-seen events:
+
+```
+# Random selector with conditions on sub-events
+upsert_event("EventRandomEncounter", {
+  display: "false",
+  buttons: "3",
+  randomevents: "true",
+  event1: "EventEncA",
+  event2: "EventEncB",
+  event3: "EventEncC"
+})
+
+# Each encounter sets a "seen" flag
+upsert_event("EventEncA", {
+  buttons: "1",
+  conditions: "seenA,==,0",    # skip if already seen
+  operations: "seenA,=,1",
+  event1: "EventContinue"
+})
+```
+
+## Variable-Controlled Branching
+
+Use vartests to route events based on game state. Events are evaluated in button order.
+
+### Ordered vartests (Multiple Thresholds)
+
+```
+upsert_event("EventCheckProgress", {
+  display: "false",
+  buttons: "2",
+  vartests: "VarOperation:cluesFound,>=,3",
+  event1: "EventNotEnoughClues",    # test FAILS (< 3 clues)
+  event2: "EventEnoughClues"        # test PASSES (>= 3 clues)
+})
+```
+
+### conditions vs vartests
+
+| Feature | `conditions` | `vartests` |
+|---------|-------------|------------|
+| Check timing | Before event displays | After event displays |
+| If false | Event silently skipped | Routes to button1/event1 |
+| If true | Event proceeds normally | Routes to button2/event2 |
+| Format | `var,comparator,value` (space-separated, AND logic) | `VarOperation:var,comparator,value` |
+| Use case | Gate tokens, spawns, events | Branch event flow |
+
+### Multi-variable Check
+
+```
+upsert_event("EventFinalCheck", {
+  display: "false",
+  buttons: "2",
+  vartests: "VarOperation:key1Found,>=,1 VarOperation:key2Found,>=,1 VarTestsLogicalOperator:AND",
+  event1: "EventMissingKeys",
+  event2: "EventBothKeysFound"
+})
+```
+
+## 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

package/skills/items-and-distribution/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: items-and-distribution
+description: Item distribution patterns for Valkyrie MoM. Use when giving random items, unique items, starting items, or creating item inspection events.
+---
+
+# /items-and-distribution - Item Distribution Patterns
+
+Patterns for distributing items to investigators in Mansions of Madness scenarios.
+
+## Item Distribution Modes
+
+### Random Items via Traits
+
+Give a random item matching a trait category. Leave `itemname` empty and set `traits`:
+
+```
+upsert_item("QItemSearchWeapon", {
+  traits: "weapon"
+})
+
+upsert_item("QItemSearchLight", {
+  traits: "lightsource"
+})
+
+upsert_item("QItemSearchCommon", {
+  traits: "common"
+})
+```
+
+Available traits: `weapon`, `lightsource`, `equipment`, `common`, `spell`
+
+The game randomly selects an item matching the trait from its internal pool.
+
+### Unique Items
+
+Give a specific named item. Set `itemname` and leave `traits` empty:
+
+```
+upsert_item("QItemPuzzleBox", {
+  itemname: "ItemCommonPuzzleBox"
+})
+
+upsert_item("QItemKnife", {
+  itemname: "ItemCommonKnife"
+})
+```
+
+Use `search_game_content` with type "Item" to find valid item catalog IDs.
+
+### Multiple Item Pool
+
+Specify multiple items — the game picks one at random:
+
+```
+upsert_item("QItemRandomWeapon", {
+  itemname: "ItemCommonKnife ItemCommonAxe ItemCommonPipe"
+})
+```
+
+### Unique Items with Trait Fallback
+
+Combine `itemname` and `traits`. The `itemname` acts as an exclusion list — the game picks a random item matching the trait that is NOT in the `itemname` list:
+
+```
+# Give a random common item, but never the knife or lantern
+upsert_item("QItemMysteryCommon", {
+  traits: "common",
+  itemname: "ItemCommonKnife ItemCommonKeroseneLantern"
+})
+```
+
+## Starting Items
+
+Items given to investigators at the beginning of the scenario. Set `starting=True`:
+
+```
+# Each investigator gets a random weapon
+upsert_item("QItemStartWeapon", {
+  starting: "True",
+  traits: "weapon"
+})
+
+# Each investigator gets a light source
+upsert_item("QItemStartLight", {
+  starting: "True",
+  traits: "lightsource"
+})
+
+# A specific starting item for the scenario
+upsert_item("QItemStartLetter", {
+  starting: "True",
+  itemname: "ItemCommonOldJournal"
+})
+```
+
+### Starting Items with Exclusions
+
+Give a random starting item from a trait pool, excluding specific items:
+
+```
+upsert_item("QItemStartEquip", {
+  starting: "True",
+  traits: "equipment",
+  itemname: "ItemCommonBarricade ItemCommonAlarmClock"
+})
+```
+
+## Item Inspection Events
+
+Attach an event to an item that fires when the investigator inspects it. Use the `inspect` field:
+
+```
+upsert_item("QItemMysteriousLetter", {
+  itemname: "ItemCommonOldJournal",
+  inspect: "EventReadLetter"
+})
+
+upsert_event("EventReadLetter", {
+  buttons: "1",
+  event1: "EventLetterRead"
+})
+
+set_localization({
+  "EventReadLetter.text": "<i>The faded handwriting reads:\\n\\n\"They must not find the key. I have hidden it where only the moonlight touches.\"</i>",
+  "EventReadLetter.button1": "{qst:CONTINUE}"
+})
+```
+
+Inspection events are great for:
+- Revealing clues when players examine found items
+- Adding lore and world-building
+- Triggering state changes (set variables when an item is read)
+- Multi-use items that change over time (use vartests in the inspection event)
+
+## Adding/Removing Items via Events
+
+### Giving Items During Events
+
+Use the `add` field on an event to give an item to the active investigator:
+
+```
+upsert_event("EventFindKey", {
+  buttons: "1",
+  add: "QItemGoldenKey",
+  event1: "EventKeyFound"
+})
+```
+
+### Removing Items During Events
+
+Use the `remove` field to take an item away:
+
+```
+upsert_event("EventUseKey", {
+  display: "false",
+  buttons: "1",
+  remove: "QItemGoldenKey",
+  add: "TokenUnlockedDoor",
+  event1: "EventDoorUnlocked"
+})
+```
+
+### Conditional Item Checks
+
+Check if a player has found an item by using a tracking variable:
+
+```
+# When finding the key, set a flag
+upsert_event("EventFindKey", {
+  buttons: "1",
+  operations: "hasKey,=,1",
+  add: "QItemGoldenKey",
+  event1: "EventKeyNarrative"
+})
+
+# Later, check the flag
+upsert_event("EventTryDoor", {
+  display: "false",
+  buttons: "2",
+  vartests: "VarOperation:hasKey,>=,1",
+  event1: "EventDoorLocked",     # no key
+  event2: "EventDoorUnlock"      # has key
+})
+```
+
+## Distribution Strategy Tips
+
+1. **Balance**: Aim for 1 search token per tile area, giving roughly 1 item per area explored
+2. **Scaling**: For larger parties (4-5 heroes), add extra search tokens or starting items
+3. **Pacing**: Place weapon searches near combat areas, light sources near dark areas
+4. **Specialization**: Use specific items (`itemname`) for story-critical gear; use traits for general loot
+5. **Economy**: Don't over-distribute — scarcity creates tension. 6-8 total items for a medium scenario
+6. **Starting loadout**: 1 weapon + 1 utility item per hero is a good baseline