Dun Dun Dungeon

Compact gameplay router. Prefer next.on_reply.call_template for direct tools; if tool retention is weak, call this with next.on_reply.router_call.arguments. Routes live play, post-run traits/loot/equip, and run-card actions through the server.

act

ROLE: "Recover the missing run_id for a SPECIFIC character's active run." Use only when the chosen character/run does not already have a run_id in the current roster/hub state, or when resume is ambiguous. Returns a recovery pointer (run ID, dungeon, room), not canonical room content; after it returns a run_id, call take_action action=sync before narrating the room. STRONGLY PREFER passing character_id. If omitted and multiple characters are mid-run, this returns AMBIGUOUS options instead of guessing.

get_active_run

ROLE: "Where am I as a player?" — orientation only. For mid_run it returns a recovery pointer, not canonical room content; call take_action action=sync with the run_id before narrating the room. If connect_player or a roster already gave a run_id for the chosen character, skip this tool and sync directly. In hub state, no character is selected unless character_id was provided or the player explicitly tapped/named one; do not silently use the first roster character. For character display call view_character instead; for run audits use QA tools.

get_player_state

QA/DEBUG ONLY — not a live-play tool. Read-only event tail for one of YOUR runs (room presented, check/combat resolved, damage, clock ticks, outcome) so a fresh agent or auditor can reconstruct what happened without the chat transcript. During normal play the take_action / end_run responses already carry the state you need; reach for this only when explicitly auditing or debugging. Pass run_id (and optional after_sequence to page). Lighter than export_qa_bundle.

get_run_events

Grimble's tutorial aside to explain game mechanics to a new player — his own clean turn with NO widget. You do NOT decide to call this; call it ONLY when a tool response's `next` names it (before room 1 in onboarding, after a room clears, or after the player went down during onboarding). It returns Grimble's line as TEXT; narrate it in his voice, end with the question it carries, then STOP and wait for the player. The response carries its OWN `next` naming the tool to call on the player's reply — take_action(sync) for room 1 or retry after a knockdown, take_action(continue) between rooms. A server call always sits between this aside and the room, so the aside and the room are never the same turn.

grimble_tip

Mint the completion reward — call ONCE after a FULL CLEAR (end_run gave run_status 'completed', loot.available=true). YOU author a themed item (name, flavor, slot, bonuses); the server clamps to the tier budget (total stat+skill+tag points ≤ budget, no single above max): T1 2/max2, T2 3/max2, T3 4/max3 (also in loot.boundaries). If the player slew the optional BONUS boss (loot.bonus_prize=true) the budget is one point richer — theme the item to that harder fight and make it a cut above. Match the fiction (haunted ballroom → Charming trinket; crypt → Warded amulet). The item is added to inventory UNEQUIPPED — the response carries an `equip_offer`; ask the player if they want to equip it now and, on yes, call equip_item with the equip_offer's character_id + item_id.

mint_loot

Rate a dungeon after completing a run. Three axes (1-5): Fun (✨), Difficulty (💀), Overall (⭐), plus an optional one-sentence review (max 280 chars). One rating per completed run. Reviews are aggregated into theme tags once a dungeon hits 10+ reviews. Running averages appear on dungeon cards once 5+ ratings exist.

rate_dungeon

Re-roll the builder's display alias (their dungeon-author name). Builders never type their own name — they get a server-suggested alias on first publish and can re-roll it here, optionally GUIDING the flavor with a free-text vibe like "more nautical", "regal", or "menacing". The vibe only biases which curated words are used; it is never used verbatim. The builder's sequential number (e.g. Architect #7) never changes — only the alias. Call when the player asks to change their builder name.

reroll_builder_alias

REQUIRED after every real run ending (clear, retreat, or defeat) — call it yourself, do NOT ask the player's permission and do NOT skip it. Capture 1-3 CHARACTER TRAITS this run revealed — who this character IS, not what happened. Each trait must be 5 WORDS OR FEWER (e.g. "loves pistols", "never trusts priests", "reckless under pressure"), never a session note like "cleared room 2". end_run shows traits.available + traits.current (the character's strongest established traits) — reinforce the ones that keep recurring and only add a genuinely new one when this run surfaced something new. The server stores reinforcement counts and surfaces the top traits at the next run start so the narrator can play to them. This is how a character accrues identity across runs; skipping it leaves them a blank slate.

record_traits

Report a dungeon for content issues. Expanded reason codes include wrong_rating (content doesn't match declared rating), offensive, sexual_content, graphic_violence, hate_or_harassment, broken, exploit, spam, other. One report per player per dungeon. Dungeons with 3+ reports are auto-archived.

report_dungeon

Generate a new AI portrait for the character. Offer the player a choice: a fresh take on the SAME look (call with no appearance), or a DIFFERENT look — if they describe changes (e.g. "give him a scar and red armor"), pass the full updated visual description as `appearance` and it overrides the stored one (and is saved for future rerolls). Each reroll is a unique variation.

reroll_portrait

Retire ONE character and free a roster slot. Use this when the player wants to delete/remove a specific character (NOT delete_account, which wipes the whole player). The character's run history is kept; they just leave the roster. DESTRUCTIVE + requires confirmation: confirm with the player by name first, then call with confirm:true. If called without confirm it returns needs_confirmation with guidance.

delete_character

Begin a dungeon run. Shows the threshold, returns run_id and protocol; the canonical first room is presented by take_action sync. A tapped browse card may provide "(dungeon_id: ...)"; pass that id through.

start_run

Submit a playable draft dungeon for human review. Approval is manual, final images are generated by the reviewer, and only approved dungeons appear in the player directory. Re-validates before submission. Builders can submit 2 dungeons/day by default (+2/day per "Builder's Writ of Expansion" bought at level 5); if this returns daily_limit_reached, tell the player the draft is saved and they can try tomorrow or visit the shop. After success, tell the builder it is waiting for review and is not public yet.

submit_dungeon_for_review

Advance a live run. Follow protocol. Active rooms use choose_approach as advertised; use continue between rooms. Cool=advantage; reckless=disadvantage.

take_action

Show a character. view='card' (collectible portrait card — the default display), 'sheet' (stats sheet: Might/Cunning/Spirit, skills, gear, gold, XP, plus an Inventory of unequipped gear), or 'roster' (compact picker of ALL your characters with each character's current dungeon/run status; use it to see or switch characters). card & sheet need character_id; roster needs none. Use view='roster' whenever the player asks to "show/see my characters," "my roster," "who do I have," "pick a character," or "change character"; view='card' for a single character; view='sheet' for stats/gear/inventory. (This is the tool for rendering characters — not get_player_state.) SOURCE OF TRUTH: the data this returns (stats, equipped gear, `unequipped_inventory`) is authoritative — trust the sheet over memory of fiction; what's listed exists. To equip a named item, match it in `unequipped_inventory` and call equip_item with its item_id.

view_character

Shop, buy gear, browse equipment, spend gold. Show Grimble's shop as a WIDGET (don't narrate the catalog as a text list). Call this when the player wants to browse/see the shop. Pass the active character_id; the widget shows gear filtered to their level and class, plus their gold. They buy with buy_item.

view_shop

Render a SHAREABLE result card for a finished run — portrait + outcome headline + stats + a Grimble line, sized to look good as a screenshot the player sends to a friend. end_run signals when to offer it (share_card.available) with guidance on when it lands. Call with the run_id. Read-only and re-summonable. The dungeon's name is on the card, so a shared card also advertises that dungeon.

view_run_card

Finalize approved builder checkpoints as a playable private dungeon draft. Requires builder_id from start_builder, followed by approved submit_arc and submit_rooms checkpoints. Does not publish or generate images.

create_dungeon

Read compact room-type templates, field rules, enums and common mistakes before authoring rooms or when validation errors are unclear. Does not change a dungeon.

describe_dungeon_schema

Equip one item the character already owns, replacing the current item in that equipment slot. Use item_id from view_character sheet unequipped_inventory. Does not buy gear or spend gold.

equip_item

Preview a saved private dungeon as text and image placeholders. This preview does not publish or generate artwork; final art is generated during human approval.

review_dungeon

Sell one owned item for fictional in-game gold at its resale value. Removes the item from inventory. Confirm the player intends to sell this item.

sell_item

Start a private dungeon builder session from the player’s plain-language concept. Returns builder_id. Continue through submit_arc, submit_rooms, create_dungeon, private playtest/edit, then submit_dungeon_for_review to request human review. Checkpoints cannot be skipped.

start_builder

Save the story checkpoint for a private dungeon build and return it for player approval. Include story, room-0 entryway (description and setup, no mechanics), voice with canonical examples, rewards and cover direction. Preserve approved content when making targeted revisions. Call describe_dungeon_schema for field rules.

submit_arc

Save the ordered room contracts after the story checkpoint is approved. Each room has a name, narrative description, immediate setup and type-specific mechanics. Call describe_dungeon_schema for compact room-type templates and field rules. Preserve already approved rooms when revising a targeted layer.

submit_rooms

Unequip the item in one equipment slot. The item remains in the character’s inventory.

unequip_item

Validate a saved dungeon draft by its dungeon_id without modifying it.

validate_dungeon_draft

Validate an unsaved dungeon specification without writing it. Returns validation errors and warnings.

validate_dungeon_payload