[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_385":386,"_387":388},"routes/_app.x.$handle.$name",{"_97":96,"_32":44,"_106":87,"_27":52,"_13":14,"_107":-5,"_11":108,"_109":110,"_111":112,"_113":114,"_115":116,"_20":-5,"_117":-5,"_118":-5,"_119":25,"_120":121,"_122":123,"_124":-5,"_125":-5,"_126":127},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_42":43,"_32":44,"_37":45,"_46":-5,"_47":25,"_48":49,"_50":49,"_51":52,"_53":-5,"_18":54,"_55":-5,"_56":25,"_57":-5,"_58":-5,"_59":60,"_61":62,"_63":64,"_65":66,"_67":68,"_69":-5,"_70":71,"_72":71,"_73":74,"_75":74,"_76":74,"_77":71,"_78":71,"_79":80,"_81":82,"_83":84,"_85":25},"version",278,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":23,"_24":25,"_26":25,"_27":28,"_29":28},"file",{"_30":31,"_32":28,"_33":20,"_34":36,"_37":38,"_39":14,"_40":41,"_24":25},"previous",{"_30":31,"_32":28,"_33":20,"_34":35},"deleted",false,"deletedHere","path","README.md","latestPath","fileId","a9ce1e16-a4d9-11f1-939e-1607ee4eb77e","name","fileType","content","# GuildScribe — Guild Hall for Twitch D&D\n\n**GuildScribe** is a Dungeons & Dragons 5e (2014 SRD-style) **guild hall** that lives in Twitch chat. \nAdventurers create characters, form companies, consult the archives, roll fate’s dice, duel in the arena, and hunt monsters in the wilds.\n\nRuns on **Val Town** (Deno) with **SQLite** persistence and Twitch **EventSub** + Helix chat.\n\n**Live codex (command guide):** set `PUBLIC_BASE_URL` in `main.ts`, then open `{PUBLIC_BASE_URL}/guide` \nChat: `!guide` or `!link` posts that same URL.\n\n---\n\n## Features at a glance\n\n| Pillar | What the guild offers |\n|--------|------------------------|\n| **Parchment** | Characters with level, XP, HP, race/class, save/load |\n| **Company** | Parties with invite, roster (members listed), disband |\n| **Archives** | Spells, items, classes, feats, races, **rules** (+ public links), plus a standalone **Baldur's Gate 3 knowledgebase** (`!bg3lookup`) for companions, origins, classes, races, locations, factions, deities, villains, and legendary items |\n| **Fate’s dice** | `!d20`, `!roll`, roll for another adventurer, `!bg3roll`/`!bg3companion`/`!bg3origin`/`!bg3loot`/`!bg3camp` for Baldur's Gate 3 flavor |\n| **Arena & wilds** | Auto/classic PvP, solo monsters, party duels, **party hunts** |\n| **Maps** | Grid battle maps with paintable terrain (grass, water, wall, lava, and more), ready-made layout templates (tavern, dungeon, forest clearing, graveyard, cave, arena), a live visual web view, and character tokens that adventurers place and move themselves |\n| **XP** | From **monster** victories only (not PvP) |\n| **Subs** | D&D-themed auto thank-you in chat for new subs, renewals, and gift subs — including a welcome for the recipient and (unless anonymous) a shout-out to the gifter (requires `channel:read:subscriptions`) |\n| **Stewards** | Channel on/off, disconnect/purge, in-chat activity logs, OAuth connect |\n| **Custom commands** | Broadcasters/mods add their own `!commands` and passive keyword triggers from chat, no code required |\n| **Passive chat** | Detects plain-chat \"goodnight\" messages and sends the room off with a themed reply |\n\n---\n\n## Module map\n\n| File | Role |\n|------|------|\n| **main.ts** | HTTP entry, OAuth, EventSub, **command router** — Val Town HTTP trigger |\n| **types.ts** | Shared types |\n| **data.ts** | Races, classes, level-scaled monsters, lookup map |\n| **utils.ts** | Dice, formatting, narration |\n| **db.ts** | SQLite schema + persistence |\n| **characters.ts** | Generation, XP, leveling, `!newchar` wizard |\n| **bg3.ts** | `!bg3roll`, `!bg3companion`, `!bg3origin`, `!bg3loot`, `!bg3camp` — standalone Baldur's Gate 3 flavor generators (no DB); `!bg3` — random race/class + player-chosen BG3 point-buy scores, saved via db.ts |\n| **bg3data.ts** | Static Baldur's Gate 3 knowledgebase — companions, origins, classes, races, locations, factions, deities, villains, legendary items |\n| **bg3lookup.ts** | `!bg3lookup` — search + formatting over the `bg3data.ts` knowledgebase (no DB, no external API — it's hand-curated, unlike `lookups.ts`) |\n| **combat.ts** | Duels, parties, hunts, initiative |\n| **customcommands.ts** | `!dndbot add/edit/remove/cooldown/list` custom commands and `!trigger` passive keyword auto-responses |\n| **maps.ts** | `!map` — create/list/view/delete grid battle maps, paint/fill terrain, and place/move/remove character tokens |\n| **lookups.ts** | dnd5eapi + formatting + reference links |\n| **twitch.ts** | Tokens, multi-part chat send |\n| **pages.ts** | Guild Codex HTML, logs, character sheet UI, battle map view/list pages |\n| **README.md** | This document |\n\n---\n\n## Setup (Val Town)\n\n1. Upload all modules into one Val project.\n2. Point the **HTTP trigger** at **`main.ts`**.\n3. Environment variables:\n\n| Variable | Purpose |\n|----------|---------|\n| `TWITCH_CLIENT_ID` | Twitch app client ID |\n| `TWITCH_CLIENT_SECRET` | Twitch app secret |\n| `TWITCH_BOT_ID` | Bot account numeric user ID |\n| `EVENTSUB_SECRET` | EventSub signature secret |\n| `BOT_USERNAMES` | *(optional)* Extra bot logins to ignore |\n| `MAX_PARTIES_PER_CHANNEL` | *(optional)* Party cap per channel; default 50 |\n| `MAX_CHARACTERS_PER_CHANNEL` | *(optional)* Character cap per channel; default 500 |\n| `MAX_MAPS_PER_CHANNEL` | *(optional)* Battle map cap per channel; default 25 |\n| `MAX_CUSTOM_COMMANDS_PER_CHANNEL` | *(optional)* Custom `!dndbot` command cap per channel; default 100 |\n| `MAX_CUSTOM_TRIGGERS_PER_CHANNEL` | *(optional)* Custom `!trigger` cap per channel; default 50 |\n| `ADMIN_API_SECRET` | **Required for operator override**; secret bearer token for `/admin/channels//(disable|enable)` |\n| `SUPPORT_URL` | *(recommended)* Support/contact URL shown in the privacy policy and home page |\n| `PUBLIC_BASE_URL` | *(recommended)* Public HTTPS URL used in chat links; must match the deployed Val URL |\n| `COMMAND_COOLDOWN_MS` | *(optional)* Durable per-channel/user command cooldown; default 1200ms |\n| `GOODNIGHT_COOLDOWN_MS` | *(optional)* Durable per-channel cooldown between \"goodnight\" auto-replies; default 300000ms (5 min), floor 30000ms |\n| `CHAT_GLOBAL_MIN_INTERVAL_MS` | *(optional)* Global bot-account chat-send spacing; default 1600ms. Lower only after Twitch confirms the account's applicable limit/verification. |\n\n4. Twitch Developer Console → OAuth Redirect URL must be exactly: \n `https://.web.val.run/callback`\n5. Set `PUBLIC_BASE_URL` as an environment variable to your public HTTPS URL (used by `!guide` / `!link`).\n6. Open the Val URL → **Raise the Guild Banner** → authorize.\n7. In channel chat: `/mod YourBotName`\n\nThe OAuth flow requests `channel:bot channel:read:subscriptions` — the latter powers the sub/resub thank-you (see below). **Channels that connected before this scope was added need to reconnect** (the home page and guide both have a \"reconnect\" link — both point at `/connect`, same as the initial connect button) for new-sub/resub thank-yous to start firing; the rest of the bot is unaffected either way. `/connect` → `/callback` is idempotent: reconnecting an already-connected channel cleans up its old EventSub subscriptions first, so it's safe to run any time GuildScribe gains a feature that needs a new permission, without duplicating subscriptions or losing existing character/party data.\n\nDelete any old **`http.ts`** entry file after switching the trigger to `main.ts`.\n\n---\n\n## Chat commands (full index)\n\n### Guild hall & help\n| Command | Description |\n|---------|-------------|\n| `!help` | Guild hall welcome + path to begin |\n| `!guide` / `!link` | **Posts the Guild Codex URL** (`/guide`) |\n| `!dndbothelp` | Codex chapters: dice, character, party, combat, lookup, maps, settings |\n| `!dndbothelp ` | Detailed syntax for that chapter |\n\n### Adventurer’s parchment (character)\n| Command | Description |\n|---------|-------------|\n| `!createchar` | Instant level 1 character |\n| `!createchar @user` | Create for another *(mod)* |\n| `!newchar` | Guided wizard |\n| `!bg3` | Random BG3-style race + class, then you assign ability scores via BG3 point-buy (base 8, cap 15, 27-point budget); saves and links the character |\n| `!answer ` | Wizard answer (also used to reply to `!bg3` prompts) |\n| `!cancel` | Cancel wizard / `!bg3` creation |\n| `!char` / `!char @user` | Sheet summary (level, **XP**, stats, HP) |\n| `!levelup` / `!levelup +/-N` | Adjust level |\n| `!hp` / `!hp +/-N` | Show or change HP |\n| `!savechar` / `!loadchar` / `!resetchar` | Backup / restore / reset |\n\n### Fate’s dice\n| Command | Description |\n|---------|-------------|\n| `!d20` | Roll a d20 |\n| `!d20 @user` | Roll for another adventurer |\n| `!roll` / `!r` | Default 1d20 |\n| `!roll 2d6+3` | Custom expression |\n| `!roll @user 4d8` | Roll for someone |\n| `!roll dex` / `!roll strength` | **Saving throw** — uses your saved character's ability modifier (+ proficiency if your class is proficient in that save) |\n| `!roll stealth` / `!roll animal handling` | **Skill check** — uses your saved character's modifier for that skill's ability |\n| `!roll @user dex` / `!roll @user stealth` | Saving throw / skill check using `@user`'s saved character instead of your own |\n| `!roll ?` | D&D-flavored yes/no fate verdict, e.g. `!roll is enya going to die this time?` |\n| `!bg3roll` | Random Baldur's Gate 3 style character: race/subrace, class/subclass, background, alignment, BG3-style point-buy scores, and an origin hook |\n| `!bg3companion` | Rolls which BG3 companion you're traveling with (role, blurb, and an iconic line) |\n| `!bg3origin` | Casts you as one of the six canonical BG3 Origin Characters (or the Dark Urge) for this run, with their hook |\n| `!bg3loot` | Random magic item drop with a BG3-style rarity tier (Common → Legendary) |\n| `!bg3camp` | Random camp-night vignette featuring one of the BG3 companions |\n\n### Guild archives (lookups)\n| Command | Example |\n|---------|---------|\n| `!spell [+N]` | `!spell fireball` |\n| `!item [+N]` | `!item longsword +1` |\n| `!class` / `!feat` / `!ability` / `!race` / `!subrace` | `!class wizard` |\n| `!rule` / `!rules ` | `!rules magic`, `!rule advantage` |\n| `!bg3lookup ` | `!bg3lookup astarion`, `!bg3lookup moonrise towers`, `!bg3lookup faction zhentarim` |\n\n- Bare commands (`!rules` alone) → usage + examples \n- Rules: up to **3** chat messages, **link first** in the response, always a D&D Beyond **search link** (hardcoded Free Rules chapter URLs were dropped — they'd started returning 403s) \n- Other lookups include reference links where applicable, also shown first in the response \n- `!bg3lookup` is a separate, hand-curated **Baldur's Gate 3 knowledgebase** (companions, origins, classes, races, locations, factions, deities, villains, legendary items) — not the D&D 5e SRD data the other lookups use. Optionally narrow the search with a leading category keyword, e.g. `!bg3lookup companion karlach` or `!bg3lookup location grymforge`. Bare `!bg3lookup` lists the recognized categories. Each hit links to a `bg3.wiki` search for that name. \n\n### Guild company (parties)\n| Command | Description |\n|---------|-------------|\n| `!party create ` | Found a company (you are leader **and** member) |\n| `!party join ` | Join |\n| `!party invite @user [name]` | Invite (name optional if you only have one party) |\n| `!party accept [name]` / `decline [name]` | Invited user answers (name optional if only one pending invite) |\n| `!party list` | **Your parties with leaders and members** |\n| `!party list ` | One company roster |\n| `!party leave ` | Leave |\n| `!party disband ` | Leader dissolves the company |\n\n### Arena & wilds (combat)\n| Command | Description |\n|---------|-------------|\n| `!dndduel @user` | Auto PvP challenge |\n| `!dndduel classic @user` | Turn-based PvP |\n| `!dndduel accept` / `decline` | Answer challenge |\n| `!dndduel attack` / `status` / `end` | Classic turn / status / end |\n| `!dndduel` | Auto **solo monster** (level-scaled) |\n| `!dndduel monster` | Classic solo monster |\n| `!dndduel party A B` | Auto party vs party |\n| `!dndduel party classic A B` | Classic party vs party |\n| `!dndduel party accept` / `decline` / `attack` / `status` / `end` | Party duel flow |\n| `!dndduel party hunt ` | Auto **company vs monster** |\n| `!dndduel party hunt classic ` | Classic hunt |\n| `!dndduel party hunt attack` / `status` / `end` | Hunt turns |\n| `!turn start` … `!turn end` | Initiative tracker *(start/add/show/next/prev/remove/end are mod-only; `!turn roll` is open to any player, rolls 1d20+DEX)* |\n\n**XP** is granted only when a **monster** falls (solo or party hunt). PvP awards none.\n\n### Custom commands & triggers\nShares the `!dndbot` word used by [Stewards](#stewards-settings) below, but different subcommands (`add`/`edit`/`remove`/`cooldown`/`list` vs. `on`/`off`/`status`/`leave`), so there's no collision.\n\n| Command | Description |\n|---------|-------------|\n| `!dndbot add ` | Create `!` *(mod)* |\n| `!dndbot edit ` | Change an existing custom command *(mod)* |\n| `!dndbot remove ` | Delete a custom command *(mod)* |\n| `!dndbot cooldown ` | Per-command cooldown, 0-3600s; default 5s *(mod)* |\n| `!dndbot list` | List configured custom command names |\n| `!trigger add ` | Fire `` whenever `` appears in chat, no `!` needed *(mod)* — quote multi-word keywords |\n| `!trigger remove ` | Delete a trigger *(mod)* |\n| `!trigger cooldown ` | Per-trigger cooldown, 0-3600s; default 15s *(mod)* |\n| `!trigger list` | List configured trigger keywords |\n\nResponses support `{user}`, `{target}` (first `@mention`, commands only), `{count}` (uses so far), and `{random:a|b|c}` (picks one option). Custom command/trigger names can't reuse a built-in command word, and each channel has a configurable cap on how many of each it can store.\n\n### Battle maps\n| Command | Description |\n|---------|-------------|\n| `!map create [WxH] [template]` | Create a grid map, default 10x8 up to 20x20, optionally stamped with a preset layout *(mod)* |\n| `!map templates` | List available layout templates (tavern, dungeon, forest_clearing, graveyard, cave, arena) with their default size and description |\n| `!map list` | List maps in this channel |\n| `!map view ` | Post a link to the live, auto-refreshing map page |\n| `!map delete ` / `!map remove ` | Delete a map, its terrain, and all its tokens *(mod)* |\n| `!map terrains` | List terrain types (some block tokens: water, wall, mountain, lava, void) |\n| `!map fill ` | Reset the whole grid to one terrain *(mod)* |\n| `!map paint ` | Set a single cell's terrain, e.g. `!map paint dungeon1 4 2 wall` *(mod)* |\n| `!map addchar [x y]` | Place your saved character on the map |\n| `!map addchar @user [x y]` | Place someone else's character *(mod)* |\n| `!map move ` | Move your token |\n| `!map move @user ` | Move someone else's token *(mod)* |\n| `!map removechar [@user]` | Remove a character from the map (`@user` requires mod) |\n\nCoordinates are 1-indexed from the top-left, `(1,1)`. Creating a map, editing terrain, and moving *someone else's* token require broadcaster/mod status — same trust model as parties and duels. Placing and moving your own character is open to everyone with a saved character. The map view (`!map view `) is a read-only web page; there's no public write endpoint, so editing always goes through chat.\n\n### Stewards (settings)\n| Command | Description |\n|---------|-------------|\n| `!dndbot on` / `off` / `status` | Open or close the guild hall in this channel *(mod)* |\n| `!dndbot leave` | Broadcaster-only: cancel EventSub and disconnect this channel |\n| `!dndbot leave purge` | Broadcaster-only: disconnect and purge this channel's stored characters/parties/logs/gameplay state |\n\n### Passive chat (no command needed)\n| Trigger | Description |\n|---------|-------------|\n| \"goodnight\" / \"gn\" / \"gnite\" / \"nighty night\" / etc. | Bot replies with a themed send-off. One reply per channel per cooldown window (`GOODNIGHT_COOLDOWN_MS`, default 5 min) so a wave of goodnights from chat only draws a single response. |\n\n---\n\n## How the pieces link\n\n```\nChat !guide / !link ──► PUBLIC_BASE_URL/guide (Guild Codex web page)\nChat !dndbothelp ──► Same chapters as Codex + this README\nHome page ──► OAuth connect + link to Codex + Support the Guild\n!logs (chat only) ──► Activity scrolls, scoped to that channel, mods/broadcaster only\n!party list ──► Rosters used by !dndduel party / party hunt\n!createchar / !char ──► Required for duels, hunts, party invite targets\nMonster wins ──► XP on parchment (!char shows Lv + XP)\n!map create/paint ──► Grid + terrain, edited by mods only\n!map addchar / move ──► Character tokens, placed/moved by their owner (mod for others)\n!map view ──► Live read-only web page at PUBLIC_BASE_URL/map\n```\n\n---\n\n## HTTP routes\n\n| Path | Purpose |\n|------|---------|\n| `GET /` | Guild hall — info page, links to `/connect` |\n| `GET /connect` | Starts Twitch OAuth — generates state, redirects straight to Twitch's authorize page (no intermediate GuildScribe page) |\n| `GET /callback` | Twitch OAuth return |\n| `GET /guide` · `/commands` | **Guild Codex** |\n| `GET /donate` | Support the Guild |\n| `GET /privacy` | Privacy policy |\n| `GET /terms` · `/tos` | Short Terms of Service |\n| `GET /healthz` | Health check for uptime monitors |\n| `POST /admin/channels//disable` | Operator-only channel block |\n| `POST /admin/channels//enable` | Operator-only unblock |\n| `GET /?channel=&user=` | Channel-scoped character sheet |\n| `GET /maps?channel=` | List a channel's battle maps |\n| `GET /map?channel=&map=` | Live, auto-refreshing visual battle map (terrain grid + character tokens); read-only — editing happens via chat |\n| `POST /` | EventSub (chat + webhooks) |\n\n---\n\n## XP & monsters\n\n- Start: level 1, 0 XP \n- Monster CR → XP; thresholds can auto-level \n- Monsters chosen by **level** (and party size on hunts), with win-friendly balance \n- Large solo roster across CR bands \n\n---\n\n## Pre-launch checklist\n\n### Code-side security\n\n- [x] OAuth state validation with 10-minute expiry and one-time consumption\n- [x] EventSub HMAC signature validation\n- [x] EventSub timestamp/replay protection\n- [x] Channel-scoped characters, backups, and creation sessions\n- [x] Channel-scoped activity-log retention (90 days / 5,000 rows)\n- [x] Broadcaster-only disconnect and purge\n- [x] EventSub cancellation retry queue\n- [x] Twitch-side revocation marks the broadcaster disconnected\n- [x] Operator blocklist with secret bearer authentication (32+ character secret required)\n- [x] SQL parameterization and HTML escaping for user-controlled values\n- [x] Durable per-channel/user command cooldown\n- [x] Global outbound chat queue for shared bot-account rate-limit protection\n- [x] Production error responses avoid returning raw exception details\n- [x] Chat command text is not written to application logs\n- [x] `/healthz` is cache-disabled and suitable for external monitoring\n\n### Operator-side launch requirements\n\n- [ ] Set production secrets/environment variables\n- [ ] Configure an external uptime monitor/alert destination\n- [ ] Set a real support URL\n- [ ] Set the exact public URL and Twitch OAuth redirect (`/callback`)\n- [ ] Complete Twitch's current bot verification/rate-limit process\n- [ ] Test `!dndbot leave` and `!dndbot leave purge` on a disposable channel\n- [ ] Test Twitch-side EventSub revocation\n- [ ] Test the operator disable/enable endpoints\n- [ ] Test two channels with the same viewer username and confirm characters/wizards remain isolated\n- [ ] Notify already-connected channels to reconnect so `channel:read:subscriptions` is granted and sub/resub thank-yous start firing (existing chat functionality is unaffected either way)\n\n---\n\n## License / content\n\nMechanics and lookups use the **D&D 5e SRD** via public APIs and free reference sites. \nGuildScribe is a fan-made Twitch utility and is **not** affiliated with Wizards of the Coast or Twitch.\n\n\n## Launch / operations checklist\n\n- **Disconnect:** `!dndbot leave` is broadcaster-only, deletes the broadcaster connection record, and attempts to cancel its EventSub subscription. `!dndbot leave purge` additionally removes channel parties, logs, encounters, duel state, channel character associations, and characters/backups that are no longer associated with another channel.\n- **EventSub revocation:** Twitch revocations now mark the broadcaster disconnected, so `!connections` only reports live connections.\n- **Privacy/ToS:** `/privacy` and `/terms` are public and linked from the Codex. Activity logs are pruned per channel to 5,000 rows and 90 days.\n- **Operator override:** keep `ADMIN_API_SECRET` private. Use `POST /admin/channels//disable` with `Authorization: Bearer ` to block one channel without relying on Twitch roles.\n- **Per-channel caps:** set `MAX_PARTIES_PER_CHANNEL`, `MAX_CHARACTERS_PER_CHANNEL`, and `MAX_MAPS_PER_CHANNEL` as needed.\n- **Monitoring:** point an external uptime monitor at `/healthz`; application errors/revocations are also retained in a small internal `monitor_events` table.\n- **Support:** set `SUPPORT_URL` to the project's real support channel/email/form before launch.\n- **Twitch bot verification:** verification is a Twitch-side application process and cannot be completed from the code. Before multi-channel launch, apply in the Twitch Developer Console using the current Twitch developer requirements/rate limits. The codebase is now structured so the shared bot can be operated/limited safely while that process is pending.\n\n### Data ownership and security note\n\nCharacter records, backups, and creation sessions are now **tenant-scoped by `(broadcaster_id, username)`**. A viewer can have a separate character in every channel and cannot retrieve or modify another channel's character by changing a username. Existing legacy character tables are migrated into the channel-scoped schema using the historical `channel_characters` associations; unassociated legacy records are not exposed.\n\nEventSub webhook signatures are checked with HMAC, timestamps older than 10 minutes are rejected, and Twitch message IDs are de-duplicated for 24 hours to prevent replay processing. Chat commands use a durable SQLite per-channel/user cooldown, while outgoing chat sends use a global bot-account queue to reduce shared-account throttling risk.\n\nIf an EventSub cancellation fails during `!dndbot leave`, the subscription ID is retained in a minimal pending-cancellation queue and retried by `/healthz`; the broadcaster row and channel data can still be removed immediately.\n\nThe public character sheet is channel-scoped and requires a currently connected broadcaster: `/?channel=&user=` (without the space). This prevents the old global `?user=` route from crossing tenants.\n\n### Pre-public operational items\n\n- Set `ADMIN_API_SECRET` to a random value of at least 32 characters.\n- Set `SUPPORT_URL` to a real support destination.\n- Set `PUBLIC_BASE_URL` to the exact public HTTPS URL.\n- Configure an external uptime monitor against `/healthz`; the endpoint also retries transient EventSub cancellations.\n- Review the current Twitch developer/bot verification requirements and complete Twitch's verification process separately. Code cannot grant Twitch verification.\n- Keep the conservative `CHAT_GLOBAL_MIN_INTERVAL_MS=1600` until Twitch confirms the account's applicable chat rate limit; lower it only with that confirmation.\n","# GuildScribe — Guild Hall for Twitch D&D\n\n**GuildScribe** is a Dungeons & Dragons 5e (2014 SRD-style) **guild hall** that lives in Twitch chat. \nAdventurers create characters, form companies, consult the archives, roll fate’s dice, duel in the arena, and hunt monsters in the wilds.\n\nRuns on **Val Town** (Deno) with **SQLite** persistence and Twitch **EventSub** + Helix chat.\n\n**Live codex (command guide):** set `PUBLIC_BASE_URL` in `main.ts`, then open `{PUBLIC_BASE_URL}/guide` \nChat: `!guide` or `!link` posts that same URL.\n\n---\n\n## Features at a glance\n\n| Pillar | What the guild offers |\n|--------|------------------------|\n| **Parchment** | Characters with level, XP, HP, race/class, save/load |\n| **Company** | Parties with invite, roster (members listed), disband |\n| **Archives** | Spells, items, classes, feats, races, **rules** (+ public links), plus a standalone **Baldur's Gate 3 knowledgebase** (`!bg3lookup`) for companions, origins, classes, races, locations, factions, deities, villains, and legendary items |\n| **Fate’s dice** | `!d20`, `!roll`, roll for another adventurer, `!bg3roll`/`!bg3companion`/`!bg3origin`/`!bg3loot`/`!bg3camp` for Baldur's Gate 3 flavor |\n| **Arena & wilds** | Auto/classic PvP, solo monsters, party duels, **party hunts** |\n| **Maps** | Grid battle maps with paintable terrain (grass, water, wall, lava, and more), ready-made layout templates (tavern, dungeon, forest clearing, graveyard, cave, arena), a live visual web view, and character tokens that adventurers place and move themselves |\n| **XP** | From **monster** victories only (not PvP) |\n| **Subs** | D&D-themed auto thank-you in chat for new subs, renewals, and gift subs — including a welcome for the recipient and (unless anonymous) a shout-out to the gifter (requires `channel:read:subscriptions`) |\n| **Stewards** | Channel on/off, disconnect/purge, in-chat activity logs, OAuth connect |\n| **Custom commands** | Broadcasters/mods add their own `!commands` and passive keyword triggers from chat, no code required |\n| **Passive chat** | Detects plain-chat \"goodnight\" messages and sends the room off with a themed reply |\n\n---\n\n## Module map\n\n| File | Role |\n|------|------|\n| **main.ts** | HTTP entry, OAuth, EventSub, **command router** — Val Town HTTP trigger |\n| **types.ts** | Shared types |\n| **data.ts** | Races, classes, level-scaled monsters, lookup map |\n| **utils.ts** | Dice, formatting, narration |\n| **db.ts** | SQLite schema + persistence |\n| **characters.ts** | Generation, XP, leveling, `!newchar` wizard |\n| **bg3.ts** | `!bg3roll`, `!bg3companion`, `!bg3origin`, `!bg3loot`, `!bg3camp` — standalone Baldur's Gate 3 flavor generators (no DB); `!bg3` — random race/class + player-chosen BG3 point-buy scores, saved via db.ts |\n| **bg3data.ts** | Static Baldur's Gate 3 knowledgebase — companions, origins, classes, races, locations, factions, deities, villains, legendary items |\n| **bg3lookup.ts** | `!bg3lookup` — search + formatting over the `bg3data.ts` knowledgebase (no DB, no external API — it's hand-curated, unlike `lookups.ts`) |\n| **combat.ts** | Duels, parties, hunts, initiative |\n| **customcommands.ts** | `!dndbot add/edit/remove/cooldown/list` custom commands and `!trigger` passive keyword auto-responses |\n| **maps.ts** | `!map` — create/list/view/delete grid battle maps, paint/fill terrain, and place/move/remove character tokens |\n| **lookups.ts** | dnd5eapi + formatting + reference links |\n| **twitch.ts** | Tokens, multi-part chat send |\n| **pages.ts** | Guild Codex HTML, logs, character sheet UI, battle map view/list pages |\n| **README.md** | This document |\n\n---\n\n## Setup (Val Town)\n\n1. Upload all modules into one Val project.\n2. Point the **HTTP trigger** at **`main.ts`**.\n3. Environment variables:\n\n| Variable | Purpose |\n|----------|---------|\n| `TWITCH_CLIENT_ID` | Twitch app client ID |\n| `TWITCH_CLIENT_SECRET` | Twitch app secret |\n| `TWITCH_BOT_ID` | Bot account numeric user ID |\n| `EVENTSUB_SECRET` | EventSub signature secret |\n| `BOT_USERNAMES` | *(optional)* Extra bot logins to ignore |\n| `MAX_PARTIES_PER_CHANNEL` | *(optional)* Party cap per channel; default 50 |\n| `MAX_CHARACTERS_PER_CHANNEL` | *(optional)* Character cap per channel; default 500 |\n| `MAX_MAPS_PER_CHANNEL` | *(optional)* Battle map cap per channel; default 25 |\n| `MAX_CUSTOM_COMMANDS_PER_CHANNEL` | *(optional)* Custom `!dndbot` command cap per channel; default 100 |\n| `MAX_CUSTOM_TRIGGERS_PER_CHANNEL` | *(optional)* Custom `!trigger` cap per channel; default 50 |\n| `ADMIN_API_SECRET` | **Required for operator override**; secret bearer token for `/admin/channels//(disable|enable)` |\n| `SUPPORT_URL` | *(recommended)* Support/contact URL shown in the privacy policy and home page |\n| `PUBLIC_BASE_URL` | *(recommended)* Public HTTPS URL used in chat links; must match the deployed Val URL |\n| `COMMAND_COOLDOWN_MS` | *(optional)* Durable per-channel/user command cooldown; default 1200ms |\n| `GOODNIGHT_COOLDOWN_MS` | *(optional)* Durable per-channel cooldown between \"goodnight\" auto-replies; default 300000ms (5 min), floor 30000ms |\n| `CHAT_GLOBAL_MIN_INTERVAL_MS` | *(optional)* Global bot-account chat-send spacing; default 1600ms. Lower only after Twitch confirms the account's applicable limit/verification. |\n\n4. Twitch Developer Console → OAuth Redirect URL must be exactly: \n `https://.web.val.run/callback`\n5. Set `PUBLIC_BASE_URL` as an environment variable to your public HTTPS URL (used by `!guide` / `!link`).\n6. Open the Val URL → **Raise the Guild Banner** → authorize.\n7. In channel chat: `/mod YourBotName`\n\nThe OAuth flow requests `channel:bot channel:read:subscriptions` — the latter powers the sub/resub thank-you (see below). **Channels that connected before this scope was added need to reconnect** (the home page and guide both have a \"reconnect\" link — both point at `/connect`, same as the initial connect button) for new-sub/resub thank-yous to start firing; the rest of the bot is unaffected either way. `/connect` → `/callback` is idempotent: reconnecting an already-connected channel cleans up its old EventSub subscriptions first, so it's safe to run any time GuildScribe gains a feature that needs a new permission, without duplicating subscriptions or losing existing character/party data.\n\nDelete any old **`http.ts`** entry file after switching the trigger to `main.ts`.\n\n---\n\n## Chat commands (full index)\n\n### Guild hall & help\n| Command | Description |\n|---------|-------------|\n| `!help` | Guild hall welcome + path to begin |\n| `!guide` / `!link` | **Posts the Guild Codex URL** (`/guide`) |\n| `!dndbothelp` | Codex chapters: dice, character, party, combat, lookup, maps, settings |\n| `!dndbothelp ` | Detailed syntax for that chapter |\n\n### Adventurer’s parchment (character)\n| Command | Description |\n|---------|-------------|\n| `!createchar` | Instant level 1 character |\n| `!createchar @user` | Create for another *(mod)* |\n| `!newchar` | Guided wizard |\n| `!bg3` | Random BG3-style race + class, then you assign ability scores via BG3 point-buy (base 8, cap 15, 27-point budget); saves and links the character |\n| `!answer ` | Wizard answer (also used to reply to `!bg3` prompts) |\n\nEvery adventurer keeps exactly one active character and one saved backup per channel. `!createchar`, `!newchar`, and `!bg3` all warn before overwriting an existing active character — reply `!answer yes` to confirm the overwrite or `!answer no` to keep what you have.\n| `!cancel` | Cancel wizard / `!bg3` creation |\n| `!char` / `!char @user` | Sheet summary (level, **XP**, stats, HP) |\n| `!levelup` / `!levelup +/-N` | Adjust level |\n| `!hp` / `!hp +/-N` | Show or change HP |\n| `!savechar` / `!loadchar` / `!resetchar` | Backup / restore / reset |\n\n### Fate’s dice\n| Command | Description |\n|---------|-------------|\n| `!d20` | Roll a d20 |\n| `!d20 @user` | Roll for another adventurer |\n| `!roll` / `!r` | Default 1d20 |\n| `!roll 2d6+3` | Custom expression |\n| `!roll @user 4d8` | Roll for someone |\n| `!roll dex` / `!roll strength` | **Saving throw** — uses your saved character's ability modifier (+ proficiency if your class is proficient in that save) |\n| `!roll stealth` / `!roll animal handling` | **Skill check** — uses your saved character's modifier for that skill's ability |\n| `!roll @user dex` / `!roll @user stealth` | Saving throw / skill check using `@user`'s saved character instead of your own |\n| `!roll ?` | D&D-flavored yes/no fate verdict, e.g. `!roll is enya going to die this time?` |\n| `!bg3roll` | Random Baldur's Gate 3 style character: race/subrace, class/subclass, background, alignment, BG3-style point-buy scores, and an origin hook |\n| `!bg3companion` | Rolls which BG3 companion you're traveling with (role, blurb, and an iconic line) |\n| `!bg3origin` | Casts you as one of the six canonical BG3 Origin Characters (or the Dark Urge) for this run, with their hook |\n| `!bg3loot` | Random magic item drop with a BG3-style rarity tier (Common → Legendary) |\n| `!bg3camp` | Random camp-night vignette featuring one of the BG3 companions |\n\n### Guild archives (lookups)\n| Command | Example |\n|---------|---------|\n| `!spell [+N]` | `!spell fireball` |\n| `!item [+N]` | `!item longsword +1` |\n| `!class` / `!feat` / `!ability` / `!race` / `!subrace` | `!class wizard` |\n| `!rule` / `!rules ` | `!rules magic`, `!rule advantage` |\n| `!bg3lookup ` | `!bg3lookup astarion`, `!bg3lookup moonrise towers`, `!bg3lookup faction zhentarim` |\n\n- Bare commands (`!rules` alone) → usage + examples \n- Rules: up to **3** chat messages, **link first** in the response, always a D&D Beyond **search link** (hardcoded Free Rules chapter URLs were dropped — they'd started returning 403s) \n- Other lookups include reference links where applicable, also shown first in the response \n- `!bg3lookup` is a separate, hand-curated **Baldur's Gate 3 knowledgebase** (companions, origins, classes, races, locations, factions, deities, villains, legendary items) — not the D&D 5e SRD data the other lookups use. Optionally narrow the search with a leading category keyword, e.g. `!bg3lookup companion karlach` or `!bg3lookup location grymforge`. Bare `!bg3lookup` lists the recognized categories. Each hit links to a `bg3.wiki` search for that name. \n\n### Guild company (parties)\n| Command | Description |\n|---------|-------------|\n| `!party create ` | Found a company (you are leader **and** member) |\n| `!party join ` | Join |\n| `!party invite @user [name]` | Invite (name optional if you only have one party) |\n| `!party accept [name]` / `decline [name]` | Invited user answers (name optional if only one pending invite) |\n| `!party list` | **Your parties with leaders and members** |\n| `!party list ` | One company roster |\n| `!party leave ` | Leave |\n| `!party disband ` | Leader dissolves the company |\n\n### Arena & wilds (combat)\n| Command | Description |\n|---------|-------------|\n| `!dndduel @user` | Auto PvP challenge |\n| `!dndduel classic @user` | Turn-based PvP |\n| `!dndduel accept` / `decline` | Answer challenge |\n| `!dndduel attack` / `status` / `end` | Classic turn / status / end |\n| `!dndduel` | Auto **solo monster** (level-scaled) |\n| `!dndduel monster` | Classic solo monster |\n| `!dndduel party A B` | Auto party vs party |\n| `!dndduel party classic A B` | Classic party vs party |\n| `!dndduel party accept` / `decline` / `attack` / `status` / `end` | Party duel flow |\n| `!dndduel party hunt ` | Auto **company vs monster** |\n| `!dndduel party hunt classic ` | Classic hunt |\n| `!dndduel party hunt attack` / `status` / `end` | Hunt turns |\n| `!turn start` … `!turn end` | Initiative tracker *(start/add/show/next/prev/remove/end are mod-only; `!turn roll` is open to any player, rolls 1d20+DEX)* |\n\n**XP** is granted only when a **monster** falls (solo or party hunt). PvP awards none.\n\n**Timeouts:** a pending challenge (`accept`/`decline`) expires after 5 minutes if unanswered. Any active classic (turn-based) duel — 1v1, party vs. party, or a party hunt — auto-forfeits to the non-idle side if nobody acts for 10 minutes, so an abandoned duel can't block that channel's dueling into the next stream. Both windows are checked lazily the next time anyone runs a `!dndduel` command in that channel (no idle duel needs to be manually ended first).\n\n### Custom commands & triggers\nShares the `!dndbot` word used by [Stewards](#stewards-settings) below, but different subcommands (`add`/`edit`/`remove`/`cooldown`/`list` vs. `on`/`off`/`status`/`leave`), so there's no collision.\n\n| Command | Description |\n|---------|-------------|\n| `!dndbot add ` | Create `!` *(mod)* |\n| `!dndbot edit ` | Change an existing custom command *(mod)* |\n| `!dndbot remove ` | Delete a custom command *(mod)* |\n| `!dndbot cooldown ` | Per-command cooldown, 0-3600s; default 5s *(mod)* |\n| `!dndbot list` | List configured custom command names |\n| `!trigger add ` | Fire `` whenever `` appears in chat, no `!` needed *(mod)* — quote multi-word keywords |\n| `!trigger remove ` | Delete a trigger *(mod)* |\n| `!trigger cooldown ` | Per-trigger cooldown, 0-3600s; default 15s *(mod)* |\n| `!trigger list` | List configured trigger keywords |\n\nResponses support `{user}`, `{target}` (first `@mention`, commands only), `{count}` (uses so far), and `{random:a|b|c}` (picks one option). Custom command/trigger names can't reuse a built-in command word, and each channel has a configurable cap on how many of each it can store.\n\n### Battle maps\n| Command | Description |\n|---------|-------------|\n| `!map create [WxH] [template]` | Create a grid map, default 10x8 up to 20x20, optionally stamped with a preset layout *(mod)* |\n| `!map templates` | List available layout templates (tavern, dungeon, forest_clearing, graveyard, cave, arena) with their default size and description |\n| `!map list` | List maps in this channel |\n| `!map view ` | Post a link to the live, auto-refreshing map page |\n| `!map delete ` / `!map remove ` | Delete a map, its terrain, and all its tokens *(mod)* |\n| `!map terrains` | List terrain types (some block tokens: water, wall, mountain, lava, void) |\n| `!map fill ` | Reset the whole grid to one terrain *(mod)* |\n| `!map paint ` | Set a single cell's terrain, e.g. `!map paint dungeon1 4 2 wall` *(mod)* |\n| `!map addchar [x y]` | Place your saved character on the map |\n| `!map addchar @user [x y]` | Place someone else's character *(mod)* |\n| `!map move ` | Move your token |\n| `!map move @user ` | Move someone else's token *(mod)* |\n| `!map removechar [@user]` | Remove a character from the map (`@user` requires mod) |\n\nCoordinates are 1-indexed from the top-left, `(1,1)`. Creating a map, editing terrain, and moving *someone else's* token require broadcaster/mod status — same trust model as parties and duels. Placing and moving your own character is open to everyone with a saved character. The map view (`!map view `) is a read-only web page; there's no public write endpoint, so editing always goes through chat.\n\n### Stewards (settings)\n| Command | Description |\n|---------|-------------|\n| `!dndbot on` / `off` / `status` | Open or close the guild hall in this channel *(mod)* |\n| `!dndbot leave` | Broadcaster-only: cancel EventSub and disconnect this channel |\n| `!dndbot leave purge` | Broadcaster-only: disconnect and purge this channel's stored characters/parties/logs/gameplay state |\n\n### Passive chat (no command needed)\n| Trigger | Description |\n|---------|-------------|\n| \"goodnight\" / \"gn\" / \"gnite\" / \"nighty night\" / etc. | Bot replies with a themed send-off. One reply per channel per cooldown window (`GOODNIGHT_COOLDOWN_MS`, default 5 min) so a wave of goodnights from chat only draws a single response. |\n\n---\n\n## How the pieces link\n\n```\nChat !guide / !link ──► PUBLIC_BASE_URL/guide (Guild Codex web page)\nChat !dndbothelp ──► Same chapters as Codex + this README\nHome page ──► OAuth connect + link to Codex + Support the Guild\n!logs (chat only) ──► Activity scrolls, scoped to that channel, mods/broadcaster only\n!party list ──► Rosters used by !dndduel party / party hunt\n!createchar / !char ──► Required for duels, hunts, party invite targets\nMonster wins ──► XP on parchment (!char shows Lv + XP)\n!map create/paint ──► Grid + terrain, edited by mods only\n!map addchar / move ──► Character tokens, placed/moved by their owner (mod for others)\n!map view ──► Live read-only web page at PUBLIC_BASE_URL/map\n```\n\n---\n\n## HTTP routes\n\n| Path | Purpose |\n|------|---------|\n| `GET /` | Guild hall — info page, links to `/connect` |\n| `GET /connect` | Starts Twitch OAuth — generates state, redirects straight to Twitch's authorize page (no intermediate GuildScribe page) |\n| `GET /callback` | Twitch OAuth return |\n| `GET /guide` · `/commands` | **Guild Codex** |\n| `GET /donate` | Support the Guild |\n| `GET /privacy` | Privacy policy |\n| `GET /terms` · `/tos` | Short Terms of Service |\n| `GET /healthz` | Health check for uptime monitors |\n| `POST /admin/channels//disable` | Operator-only channel block |\n| `POST /admin/channels//enable` | Operator-only unblock |\n| `GET /?channel=&user=` | Channel-scoped character sheet |\n| `GET /maps?channel=` | List a channel's battle maps |\n| `GET /map?channel=&map=` | Live, auto-refreshing visual battle map (terrain grid + character tokens); read-only — editing happens via chat |\n| `POST /` | EventSub (chat + webhooks) |\n\n---\n\n## XP & monsters\n\n- Start: level 1, 0 XP \n- Monster CR → XP; thresholds can auto-level \n- Monsters chosen by **level** (and party size on hunts), with win-friendly balance \n- Large solo roster across CR bands \n\n---\n\n## Pre-launch checklist\n\n### Code-side security\n\n- [x] OAuth state validation with 10-minute expiry and one-time consumption\n- [x] EventSub HMAC signature validation\n- [x] EventSub timestamp/replay protection\n- [x] Channel-scoped characters, backups, and creation sessions\n- [x] Channel-scoped activity-log retention (90 days / 5,000 rows)\n- [x] Broadcaster-only disconnect and purge\n- [x] EventSub cancellation retry queue\n- [x] Twitch-side revocation marks the broadcaster disconnected\n- [x] Operator blocklist with secret bearer authentication (32+ character secret required)\n- [x] SQL parameterization and HTML escaping for user-controlled values\n- [x] Durable per-channel/user command cooldown\n- [x] Global outbound chat queue for shared bot-account rate-limit protection\n- [x] Production error responses avoid returning raw exception details\n- [x] Chat command text is not written to application logs\n- [x] `/healthz` is cache-disabled and suitable for external monitoring\n\n### Operator-side launch requirements\n\n- [ ] Set production secrets/environment variables\n- [ ] Configure an external uptime monitor/alert destination\n- [ ] Set a real support URL\n- [ ] Set the exact public URL and Twitch OAuth redirect (`/callback`)\n- [ ] Complete Twitch's current bot verification/rate-limit process\n- [ ] Test `!dndbot leave` and `!dndbot leave purge` on a disposable channel\n- [ ] Test Twitch-side EventSub revocation\n- [ ] Test the operator disable/enable endpoints\n- [ ] Test two channels with the same viewer username and confirm characters/wizards remain isolated\n- [ ] Notify already-connected channels to reconnect so `channel:read:subscriptions` is granted and sub/resub thank-yous start firing (existing chat functionality is unaffected either way)\n\n---\n\n## License / content\n\nMechanics and lookups use the **D&D 5e SRD** via public APIs and free reference sites. \nGuildScribe is a fan-made Twitch utility and is **not** affiliated with Wizards of the Coast or Twitch.\n\n\n## Launch / operations checklist\n\n- **Disconnect:** `!dndbot leave` is broadcaster-only, deletes the broadcaster connection record, and attempts to cancel its EventSub subscription. `!dndbot leave purge` additionally removes channel parties, logs, encounters, duel state, channel character associations, and characters/backups that are no longer associated with another channel.\n- **EventSub revocation:** Twitch revocations now mark the broadcaster disconnected, so `!connections` only reports live connections.\n- **Privacy/ToS:** `/privacy` and `/terms` are public and linked from the Codex. Activity logs are pruned per channel to 5,000 rows and 90 days.\n- **Operator override:** keep `ADMIN_API_SECRET` private. Use `POST /admin/channels//disable` with `Authorization: Bearer ` to block one channel without relying on Twitch roles.\n- **Per-channel caps:** set `MAX_PARTIES_PER_CHANNEL`, `MAX_CHARACTERS_PER_CHANNEL`, and `MAX_MAPS_PER_CHANNEL` as needed.\n- **Monitoring:** point an external uptime monitor at `/healthz`; application errors/revocations are also retained in a small internal `monitor_events` table.\n- **Support:** set `SUPPORT_URL` to the project's real support channel/email/form before launch.\n- **Twitch bot verification:** verification is a Twitch-side application process and cannot be completed from the code. Before multi-channel launch, apply in the Twitch Developer Console using the current Twitch developer requirements/rate limits. The codebase is now structured so the shared bot can be operated/limited safely while that process is pending.\n\n### Data ownership and security note\n\nCharacter records, backups, and creation sessions are now **tenant-scoped by `(broadcaster_id, username)`**. A viewer can have a separate character in every channel and cannot retrieve or modify another channel's character by changing a username. Existing legacy character tables are migrated into the channel-scoped schema using the historical `channel_characters` associations; unassociated legacy records are not exposed.\n\nEventSub webhook signatures are checked with HMAC, timestamps older than 10 minutes are rejected, and Twitch message IDs are de-duplicated for 24 hours to prevent replay processing. Chat commands use a durable SQLite per-channel/user cooldown, while outgoing chat sends use a global bot-account queue to reduce shared-account throttling risk.\n\nIf an EventSub cancellation fails during `!dndbot leave`, the subscription ID is retained in a minimal pending-cancellation queue and retried by `/healthz`; the broadcaster row and channel data can still be removed immediately.\n\nThe public character sheet is channel-scoped and requires a currently connected broadcaster: `/?channel=&user=` (without the space). This prevents the old global `?user=` route from crossing tenants.\n\n### Pre-public operational items\n\n- Set `ADMIN_API_SECRET` to a random value of at least 32 characters.\n- Set `SUPPORT_URL` to a real support destination.\n- Set `PUBLIC_BASE_URL` to the exact public HTTPS URL.\n- Configure an external uptime monitor against `/healthz`; the endpoint also retries transient EventSub cancellations.\n- Review the current Twitch developer/bot verification requirements and complete Twitch's verification process separately. Code cannot grant Twitch verification.\n- Keep the conservative `CHAT_GLOBAL_MIN_INTERVAL_MS=1600` until Twitch confirms the account's applicable chat rate limit; lower it only with that confirmation.\n","createdAt",["D",1788646338355],"branchVersion","branchId","05246ac8-a272-4b74-b48a-34d91555f75d","id","20e82baa-ad9c-41ac-a8e5-4d2d285f6a79","dnd-twitch-bot",["D",1787995257440],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","","imageUrl","cc37ba10-6e6d-4af6-a801-9955c92d23c4","pinnedFileId","pinPreview","pinMigrated","screenshotVersion","likeCount",0,"orgId","01a04ba1-c79f-7319-b4f2-7c4f3772837b","tursoName","20e82baaad9c41aca8e54d2d285f6a79","tursoHostname","20e82baaad9c41aca8e54d2d285f6a79-val-town.aws-us-east-2.turso.io","tursoMeasuredAt",["D",1789500119686],"pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_97":96,"_105":101},"org",{"_97":96,"_98":99,"_100":101,"_18":54,"_102":103,"_104":25},"branch",{"_13":86,"_32":87,"_42":41,"_88":43,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":-5,"_94":44,"_95":96},"isOwned",512,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","StonedSheamus","handle","displayName","Shea Stolp","avatar","https://lh3.googleusercontent.com/a/ACg8ocIWmQgR3gyoMMicg2zCAoN1c7i36qX5mf9gRIdIXm8F2mo-ig=s96-c","tier","free","canRestrictVals","profileImageUrl","branchName","adoptOrgId",{"_42":43,"_32":44,"_37":380,"_46":-5,"_47":25,"_48":49,"_50":49,"_51":52,"_53":-5,"_18":54,"_55":-5,"_56":25,"_57":-5,"_58":-5,"_59":60,"_61":62,"_63":64,"_65":66,"_67":381,"_69":-5,"_70":71,"_72":71,"_73":74,"_75":74,"_76":74,"_77":71,"_78":71,"_79":382,"_81":383,"_83":384,"_85":25},"tree",[303,304,305,306,307,308,309,310,311,312,313,314,315,316,317,318,319,320,321],"files",[303,304,305,306,307,308,309,310,311,312,313,314,315,316,317,318,319,320,321],"counts",{"_292":60,"_293":236,"_294":60,"_295":296,"_297":298},"contents",[128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles",true,"grants","orgs","customDomains",{},{"_42":286,"_32":287,"_30":288,"_150":-5,"_40":41,"_39":236,"_152":123,"_37":289,"_13":60,"_33":20,"_34":290,"_24":25,"_157":-5,"_27":291},{"_42":280,"_32":281,"_30":282,"_150":-5,"_40":41,"_39":188,"_152":25,"_37":283,"_13":60,"_33":20,"_34":284,"_24":25,"_157":-5,"_27":285},{"_42":276,"_32":28,"_30":31,"_150":-5,"_40":41,"_39":14,"_152":25,"_37":277,"_13":278,"_33":20,"_34":36,"_24":25,"_157":-5,"_27":279},{"_42":269,"_32":270,"_30":271,"_150":-5,"_40":41,"_39":272,"_152":25,"_37":273,"_13":228,"_33":155,"_34":274,"_24":25,"_157":-5,"_27":275},{"_42":262,"_32":263,"_30":264,"_150":-5,"_40":41,"_39":265,"_152":123,"_37":266,"_13":211,"_33":155,"_34":267,"_24":25,"_157":-5,"_27":268},{"_42":255,"_32":256,"_30":257,"_150":-5,"_40":41,"_39":258,"_152":123,"_37":259,"_13":211,"_33":155,"_34":260,"_24":25,"_157":-5,"_27":261},{"_42":247,"_32":248,"_30":249,"_150":-5,"_40":41,"_39":250,"_152":123,"_37":251,"_13":252,"_33":155,"_34":253,"_24":25,"_157":-5,"_27":254},{"_42":239,"_32":240,"_30":241,"_150":-5,"_40":41,"_39":242,"_152":25,"_37":243,"_13":244,"_33":155,"_34":245,"_24":25,"_157":-5,"_27":246},{"_42":231,"_32":232,"_30":233,"_150":-5,"_40":41,"_39":234,"_152":25,"_37":235,"_13":236,"_33":155,"_34":237,"_24":25,"_157":-5,"_27":238},{"_42":223,"_32":224,"_30":225,"_150":-5,"_40":41,"_39":226,"_152":25,"_37":227,"_13":228,"_33":155,"_34":229,"_24":25,"_157":-5,"_27":230},{"_42":215,"_32":216,"_30":217,"_150":-5,"_40":41,"_39":218,"_152":25,"_37":219,"_13":220,"_33":155,"_34":221,"_24":25,"_157":-5,"_27":222},{"_42":208,"_32":209,"_30":210,"_150":-5,"_40":41,"_39":211,"_152":123,"_37":212,"_13":60,"_33":20,"_34":213,"_24":25,"_157":-5,"_27":214},{"_42":201,"_32":202,"_30":203,"_150":-5,"_40":41,"_39":204,"_152":25,"_37":205,"_13":164,"_33":155,"_34":206,"_24":25,"_157":-5,"_27":207},{"_42":191,"_32":192,"_30":193,"_150":-5,"_40":41,"_39":194,"_152":25,"_37":195,"_13":196,"_33":197,"_34":198,"_24":25,"_157":199,"_27":200},{"_42":183,"_32":184,"_30":185,"_150":-5,"_40":41,"_39":186,"_152":123,"_37":187,"_13":188,"_33":155,"_34":189,"_24":25,"_157":-5,"_27":190},{"_42":175,"_32":176,"_30":177,"_150":-5,"_40":41,"_39":178,"_152":25,"_37":179,"_13":180,"_33":155,"_34":181,"_24":25,"_157":-5,"_27":182},{"_42":167,"_32":168,"_30":169,"_150":-5,"_40":41,"_39":170,"_152":25,"_37":171,"_13":172,"_33":155,"_34":173,"_24":25,"_157":-5,"_27":174},{"_42":159,"_32":160,"_30":161,"_150":-5,"_40":41,"_39":162,"_152":123,"_37":163,"_13":164,"_33":155,"_34":165,"_24":25,"_157":-5,"_27":166},{"_42":147,"_32":148,"_30":149,"_150":-5,"_40":41,"_39":151,"_152":25,"_37":153,"_13":154,"_33":155,"_34":156,"_24":25,"_157":-5,"_27":158},"ae5c8824-75f6-4ad5-822e-552f1819e1c1","utils.ts","7c7a4070-a4d9-11f1-90df-1607ee4eb77e","parentId",274,"latest",["D",1788583818889],14,"script","// Pure helpers and small shared utilities\n\nimport type { Ability, Character } from \"./types.ts\";\nimport { abilityNames, abilityAliases, abilityFullNames, skillAbilities, knownBotAccounts } from \"./data.ts\";\n\nexport const pick = (items: T[]): T => items[Math.floor(Math.random() * items.length)];\n\nexport const modifier = (score: number) => Math.floor((score - 10) / 2);\n\nexport function rollStat() {\n const d = Array.from({ length: 4 }, () => 1 + Math.floor(Math.random() * 6)).sort((a, b) => b - a);\n return d[0] + d[1] + d[2];\n}\n\nexport function formatRaceName(race: string, subrace: string | null) {\n if (!subrace) return race.trim();\n const nr = race.trim().toLowerCase();\n const ns = subrace.trim().toLowerCase();\n return ns === nr || ns.endsWith(` ${nr}`) ? subrace.trim() : `${subrace.trim()} ${race.trim()}`;\n}\n\nexport function escapeHtml(value: string) {\n return value.replace(/[&<>'\"]/g, (c) => ({ \"&\": \"&\", \"<\": \"<\", \">\": \">\", \"'\": \"'\", '\"': \""\" }[c]!));\n}\n\nexport function formatStatLine(c: Character) {\n return `Lv${c.level} XP ${c.xp ?? 0} | ${abilityNames\n .map((a) => `${a} ${c.scores[a]}(${modifier(c.scores[a]) >= 0 ? \"+\" : \"\"}${modifier(c.scores[a])})`)\n .join(\" \")} | HP ${c.hpCurrent}/${c.hpMax} | Speed ${c.speed}ft | Prof +${c.proficiency}`;\n}\n\nexport function duelNarration(stage: string) {\n const lines: Record = {\n challenge: [\n \"The arena gates swing open.\",\n \"The gauntlet has been thrown.\",\n \"Fate calls for a showdown.\",\n \"A challenge echoes through the tavern.\",\n \"The bards ready their instruments—this could be a good one.\",\n \"Steel is drawn before a word is spoken.\",\n \"The crowd senses blood in the air.\",\n \"A dare no adventurer could refuse.\",\n \"The dice are already whispering about this one.\",\n \"Someone just signed up for a legendary tale.\",\n \"The tavern falls silent, waiting.\",\n \"A rivalry is about to be settled the old-fashioned way.\",\n \"The DM reaches for the initiative tracker.\",\n \"Honor, glory, and bragging rights are on the line.\",\n \"The challenge horn sounds across the guild hall.\",\n \"Two adventurers, one arena, zero mercy.\",\n \"The gauntlet lands with a satisfying thud.\",\n \"A duel is declared, and the crowd gathers 'round.\",\n \"The stakes have been set—glory or the ground.\",\n \"Fate shuffles its deck for this one.\",\n ],\n accept: [\n \"The crowd roars—the duel is on.\",\n \"Steel meets destiny.\",\n \"The initiative gods have been consulted.\",\n \"Acceptance granted—may the bones favor the bold.\",\n \"The gauntlet is picked up without hesitation.\",\n \"Both sides square off beneath torchlight.\",\n \"The bard starts composing before the first swing.\",\n \"A nod, a grip on the hilt, and it begins.\",\n \"The tavern clears a space for the coming chaos.\",\n \"Challenge accepted—the dice are drawn.\",\n \"The arena gates seal shut behind them.\",\n \"No turning back now; the die is cast.\",\n \"Two hearts race to the same drumbeat.\",\n \"The DM smiles—always a bad sign.\",\n \"Weapons are drawn, and so is everyone's attention.\",\n \"The duel begins under a watchful moon.\",\n \"Fate nods its approval.\",\n \"The crowd chants for first blood.\",\n \"Initiative rolled, tension rising.\",\n \"The challenge is met in full.\",\n ],\n decline: [\n \"The challenge fades into the tavern gossip.\",\n \"Wisdom wins this round.\",\n \"The duel is postponed by fate.\",\n \"Discretion proves the better part of valor.\",\n \"The gauntlet is left lying in the dirt.\",\n \"A tactical retreat, disguised as good sense.\",\n \"The bard shrugs and writes a different song.\",\n \"Not every quest needs to be accepted.\",\n \"The crowd grumbles but respects the choice.\",\n \"Sometimes the wisest roll is walking away.\",\n \"The challenge is filed under 'maybe later.'\",\n \"Even heroes pick their battles.\",\n \"The arena stays quiet a little longer.\",\n \"A polite decline, sword still sheathed.\",\n \"The duel dissolves back into idle chatter.\",\n \"Better a live coward than a dead hero, some say.\",\n \"The gauntlet is returned, unthrown.\",\n \"The DM shrugs and moves the plot along.\",\n \"Peace prevails, for now.\",\n \"The tavern returns to its usual roar.\",\n ],\n hit: [\n \"A clean strike finds its mark.\",\n \"That hit had advantage from destiny.\",\n \"The dice have chosen violence.\",\n \"Steel sings true.\",\n \"A textbook strike, straight from the manual.\",\n \"The blade finds its mark without mercy.\",\n \"That connected with authority.\",\n \"A solid hit—the crowd cheers.\",\n \"The attack lands clean and true.\",\n \"Fortune favors the aim this time.\",\n \"The strike lands with a satisfying crunch.\",\n \"A well-placed hit, worthy of a bard's verse.\",\n \"The blow connects, no saving throw in sight.\",\n \"That's going straight into the campaign log.\",\n \"A precise, punishing hit.\",\n \"The attack roll clears the armor class with room to spare.\",\n \"Contact made—and it hurt.\",\n \"The strike lands like it was scripted.\",\n \"A hit worthy of a highlight reel.\",\n \"The dice roll high, and the blade follows through.\",\n ],\n miss: [\n \"The attack misses wide; the boots remain unharmed.\",\n \"The blade finds only air.\",\n \"The dice requested a dramatic near miss.\",\n \"A swing and a whiff.\",\n \"The attack sails past, dramatically unthreatening.\",\n \"Armor class wins this exchange.\",\n \"The strike goes wide, to the crowd's disappointment.\",\n \"That one's going in the blooper reel.\",\n \"A valiant effort, poorly aimed.\",\n \"The dice roll low, and the blow follows suit.\",\n \"The attack misses by the length of a goblin's nose.\",\n \"Nothing but air and bruised pride.\",\n \"The blade whistles past, missing entirely.\",\n \"A near miss, emphasis on the miss.\",\n \"The strike lands nowhere useful.\",\n \"Fortune looks away for this swing.\",\n \"The attack fumbles its footing.\",\n \"A miss so clean it's almost impressive.\",\n \"The blow glances off nothing at all.\",\n \"That roll needed a little more luck.\",\n ],\n critical: [\n \"A critical hit! The bards are taking notes.\",\n \"Natural twenty—legendary timing.\",\n \"The D20 of Fate has opened the vault.\",\n \"A critical strike worthy of legend.\",\n \"The crowd loses its collective mind.\",\n \"That's a nat 20 if there ever was one.\",\n \"Critical! Somewhere, a bard just found their next verse.\",\n \"The dice have crowned a champion—for this round.\",\n \"A perfect strike, straight out of a campaign highlight.\",\n \"The heavens themselves seem to approve of that roll.\",\n \"Critical hit! The dungeon master allows a dramatic pause.\",\n \"That roll belongs in the guild's hall of fame.\",\n \"A devastating critical—someone's taking damage rolls twice.\",\n \"The natural 20 gods have smiled upon this strike.\",\n \"Critical! Even the monster looks impressed.\",\n \"A flawless strike for the ages.\",\n \"The dice landed on legendary.\",\n \"That's the kind of hit sequels are made of.\",\n \"Critical success—roll for damage, roll for glory.\",\n \"The stars aligned for that swing.\",\n ],\n defeat: [\n \"A character falls, but the story continues.\",\n \"The HP bar has entered the underworld.\",\n \"A dramatic collapse worthy of the final act.\",\n \"Zero HP, maximum drama.\",\n \"The fallen adventurer earns a moment of respectful silence.\",\n \"Down, but the campaign marches on.\",\n \"A defeat worthy of its own tragic ballad.\",\n \"The dice were not merciful this time.\",\n \"The battlefield claims another combatant.\",\n \"A hard-fought loss, and a story for the tavern.\",\n \"The final blow lands, and the duel ends.\",\n \"Down goes the challenger—someone alert the healer.\",\n \"The HP counter hits zero with theatrical timing.\",\n \"A noble defeat, recorded in the guild log.\",\n \"The fight ends, one combatant left standing.\",\n \"The loser limps off to nurse their pride.\",\n \"That's a wipe—time to regroup at camp.\",\n \"The dice have spoken, and the answer was defeat.\",\n \"A fall worthy of the campaign's next flashback.\",\n \"The duel closes with one combatant down for the count.\",\n ],\n victory: [\n \"Victory belongs to the last character standing.\",\n \"The winner claims the tavern bragging rights.\",\n \"The campaign chronicle gains a new legend.\",\n \"Victory! The bards are already rehearsing.\",\n \"The guild hall erupts in cheers.\",\n \"A win worthy of its own chapter.\",\n \"The victor raises their weapon to a roaring crowd.\",\n \"Glory secured, one HP bar at a time.\",\n \"The champion stands, the dust settles.\",\n \"A hard-won victory, exactly the kind bards love.\",\n \"The dice crowned a winner tonight.\",\n \"Victory earned—the tavern's buying the next round.\",\n \"The last one standing takes the spoils.\",\n \"A triumphant finish worthy of the campaign log.\",\n \"The winner's name goes up on the guild board.\",\n \"Another legend added to the chronicle.\",\n \"The battle ends, and glory is claimed.\",\n \"Victory! Somewhere, a bard just got a new song idea.\",\n \"The champion emerges, battered but triumphant.\",\n \"The dust clears, and one hero remains.\",\n ],\n };\n const pool = lines[stage] ?? lines.hit;\n return pool[Math.floor(Math.random() * pool.length)];\n}\n\nexport function combatStats(c: Character) {\n const ability = Math.max(c.scores.STR, c.scores.DEX);\n const mod = modifier(ability);\n return { attack: 10 + mod + c.proficiency, mod, die: 8 };\n}\n\nexport function isBotAccount(username: string, userId: string, botUserId: string) {\n const normalized = username.toLowerCase();\n const configured = (Deno.env.get(\"BOT_USERNAMES\") ?? \"\")\n .split(\",\")\n .map((x) => x.trim().toLowerCase())\n .filter(Boolean);\n return (\n userId === botUserId ||\n knownBotAccounts.has(normalized) ||\n configured.includes(normalized) ||\n normalized.endsWith(\"bot\")\n );\n}\n\nexport function hasModeratorBadge(event: any) {\n const badges = [...(event?.badges ?? []), ...(event?.source_badges ?? [])];\n return badges.some((badge: any) => badge.set_id === \"moderator\" || badge.set_id === \"broadcaster\");\n}\n\nexport type CheckKind =\n | { type: \"save\"; ability: Ability; label: string }\n | { type: \"skill\"; ability: Ability; label: string };\n\n/**\n * Resolve chat input like \"dex\", \"dexterity\", or \"stealth\" to a saving-throw\n * ability or a skill (and its governing ability). Returns null for anything\n * that isn't a recognized ability/skill name (e.g. a dice expression).\n */\nexport function resolveCheckKind(input: string): CheckKind | null {\n const key = input.trim().toLowerCase();\n if (!key) return null;\n\n const ability = abilityAliases[key];\n if (ability) {\n return { type: \"save\", ability, label: `${abilityFullNames[ability]} Saving Throw` };\n }\n\n const collapsed = key.replace(/\\s+/g, \"\");\n const skillEntry = Object.entries(skillAbilities).find(([name]) => name.replace(/\\s+/g, \"\") === collapsed);\n if (skillEntry) {\n const [name, skillAbility] = skillEntry;\n const label = name\n .split(\" \")\n .map((word, i) => (i > 0 && word === \"of\" ? word : word.charAt(0).toUpperCase() + word.slice(1)))\n .join(\" \");\n return { type: \"skill\", ability: skillAbility, label: `${label} Check` };\n }\n\n return null;\n}\n\nexport function rollDice(input = \"1d20\", customLabel?: string) {\n const expression = input.trim() || \"1d20\";\n const m = expression.match(/^(\\d+)d(\\d+)([+-]\\d+)?$/i);\n if (!m) return null;\n const n = +m[1],\n sides = +m[2],\n mod = m[3] ? +m[3] : 0;\n if (n > 100 || sides > 1000) return null;\n const rolls = Array.from({ length: n }, () => 1 + Math.floor(Math.random() * sides));\n const rawTotal = rolls.reduce((a, b) => a + b, 0);\n const total = rawTotal + mod;\n const label = customLabel ?? (expression.toLowerCase() === \"1d20\" ? \"D20 of Fate\" : \"Dice roll\");\n const rawD20 = n === 1 && sides === 20 ? rolls[0] : null;\n const puns =\n rawD20 === 20\n ? [\n \"Natural 20! The bards are already writing the song.\",\n \"Critical success! Even the dice wanted to be legendary.\",\n \"The gods have stamped this roll approved.\",\n \"A natural 20—today, the dungeon fears you.\",\n \"Fate has opened the treasure chest of victory.\",\n \"Nat 20! Somewhere, a DM sighs and adjusts the encounter.\",\n \"The dice rolled a max and immediately regretted nothing.\",\n \"A perfect roll, straight from the vault of legends.\",\n \"Natural 20—roll for damage, roll for glory.\",\n \"The universe itself cast Bless on this roll.\",\n \"That's a nat 20, framed and hung in the guild hall.\",\n \"Twenty out of twenty—the dice have no notes.\",\n \"A roll so good it should require a saving throw to believe.\",\n \"Natural 20! The crit fairy has visited.\",\n \"The d20 landed face-up and smug about it.\",\n \"A flawless roll worthy of its own campaign arc.\",\n \"Nat 20—even the monsters are taking notes.\",\n \"The dice rolled max and struck a pose.\",\n \"That's the kind of roll adventurers dream about.\",\n \"Natural 20! Somewhere, a bard grabs their lute.\",\n ]\n : rawD20 === 1\n ? [\n \"Natural 1! The floor wins this round.\",\n \"Critical fumble! Somewhere, a goblin just gained confidence.\",\n \"The dice have requested a short rest.\",\n \"A natural 1—excellent roleplay opportunity incoming.\",\n \"Fate rolled a banana peel under your boots.\",\n \"Nat 1—the DM is already smiling.\",\n \"The d20 rolled over and played dead.\",\n \"A critical fumble worthy of the blooper reel.\",\n \"That roll owes the party an apology.\",\n \"Natural 1! Even the mimics are laughing.\",\n \"The dice just cast Fumble on themselves.\",\n \"A one, a shrug, and a very awkward silence.\",\n \"The floor has never looked so inviting.\",\n \"Nat 1—time to check the fumble table.\",\n \"That's going straight into the tavern's blooper reel.\",\n \"The d20 chose chaos, and chaos chose you.\",\n \"A critical whiff for the ages.\",\n \"Natural 1! The goblins are taking notes for once.\",\n \"The dice tripped over their own pips.\",\n \"That roll just volunteered for a plot twist.\",\n ]\n : total >= 17\n ? [\n \"That roll arrived wearing a hero's cape.\",\n \"The adventure is leaning dramatically in your favor.\",\n \"Even the dungeon master raised an eyebrow at that one.\",\n \"A mighty swing of the fate hammer.\",\n \"The prophecy is looking unusually promising.\",\n \"That's a roll worth bragging about at camp.\",\n \"The dice are clearly rooting for you tonight.\",\n \"A strong roll, straight out of a highlight reel.\",\n \"Fortune favors the bold, and apparently you too.\",\n \"The stars aligned nicely for that one.\",\n \"That roll deserves its own toast at the tavern.\",\n \"A hearty result—the bards approve.\",\n \"The dice rolled high and struck a heroic pose.\",\n \"That's the kind of roll legends are built on.\",\n \"A confident roll, worthy of the front lines.\",\n \"The dungeon's odds just got a little worse.\",\n \"That roll practically glows with good fortune.\",\n \"A strong showing—the party's counting on more of these.\",\n \"The dice decided to be generous today.\",\n \"A roll fit for a chosen one.\",\n ]\n : total <= 4\n ? [\n \"That roll took a wrong turn at the tavern.\",\n \"The dungeon master is trying very hard not to smile.\",\n \"Fate has assigned you a side quest.\",\n \"The dice are demanding better snacks.\",\n \"That result has strong mimic-energy.\",\n \"The dice rolled low and immediately apologized.\",\n \"That's a roll better left out of the campaign log.\",\n \"A rough one—even the goblins felt bad.\",\n \"The dice seem to be having an off night.\",\n \"That roll wandered off the beaten path.\",\n \"A humble result, character-building at best.\",\n \"The dungeon's odds just got a little better.\",\n \"That roll needs a long rest and a pep talk.\",\n \"Not every roll can be legendary, apparently.\",\n \"The dice rolled low and hid behind the DM screen.\",\n \"A roll destined for the blooper reel.\",\n \"That result has 'try again' written all over it.\",\n \"The prophecy did not see that one coming, unfortunately.\",\n \"A roll that even the party's cleric can't fix.\",\n \"That's the kind of roll bards leave out of the song.\",\n ]\n : [\n \"Fate has spoken—no rerolling destiny.\",\n \"The dungeon master may now pretend this was planned.\",\n \"That roll wandered in from a side quest.\",\n \"Somewhere, a bard is composing a song about this.\",\n \"Your modifiers are doing the heavy lifting.\",\n \"The goblins are taking notes.\",\n \"The prophecy remains open.\",\n \"Fate rolled over and asked for advantage.\",\n \"The initiative order has noticed you.\",\n \"A perfectly serviceable bit of adventuring.\",\n \"The dice have offered a plot twist.\",\n \"The tavern is buying the next round.\",\n \"The campaign continues, one roll at a time.\",\n \"A solidly average result—the dungeon shrugs.\",\n \"The dice landed right in the middle of the story.\",\n \"Not legendary, not disastrous—just adventuring.\",\n \"The DM nods and moves the story along.\",\n \"A roll that keeps the plot moving forward.\",\n \"The party's chronicler notes it and carries on.\",\n \"That's a roll fit for a Tuesday quest.\",\n ];\n const pun = puns[Math.floor(Math.random() * puns.length)];\n return `🎲 ${label}: ${expression} → [${rolls.join(\", \")}]${mod ? (mod > 0 ? `+${mod}` : mod) : \"\"} = ${total}. ${pun}`;\n}\n\n// Yes/No fate questions, e.g. \"!roll is enya going to die this time?\" — a\n// separate flavor pool from the dice puns above since these need to echo\n// the asker's question back into a verdict rather than a roll total.\nconst FATE_YES: Array<(q: string) => string> = [\n (q) => `🎲 Natural 20! The fates favor a YES on \"${q}\"`,\n (q) => `📜 You cast Augury and receive a weal omen — YES, regarding \"${q}\"`,\n (q) => `🔮 The crystal ball clears... it shows YES for \"${q}\"`,\n (q) => `⚖️ The DM rolls behind the screen, smirks, and says YES to \"${q}\"`,\n (q) => `🃏 You draw from the Deck of Many Things: the Sun. YES — \"${q}\" comes to pass`,\n (q) => `👁️ The beholder's central eye blinks in approval: YES on \"${q}\"`,\n (q) => `✨ The bones fall in a favorable pattern. YES, so it is written — \"${q}\"`,\n (q) => `🗡️ Even a rogue with disadvantage nails this one. YES to \"${q}\"`,\n (q) => `🌟 The Bag of Holding produces exactly what's needed. YES on \"${q}\"`,\n (q) => `🐉 Even the dragon nods in approval. YES to \"${q}\"`,\n (q) => `📯 The horn of victory sounds. YES, regarding \"${q}\"`,\n (q) => `🍀 A stroke of adventurer's luck says YES to \"${q}\"`,\n (q) => `🧙 The wizard's crystal reveals a bright future. YES for \"${q}\"`,\n (q) => `⚔️ The blade hums with approval. YES to \"${q}\"`,\n (q) => `🕊️ A paladin's oath affirms it. YES on \"${q}\"`,\n (q) => `🎯 A natural bullseye of fate. YES, regarding \"${q}\"`,\n (q) => `🏰 The castle gates open wide. YES to \"${q}\"`,\n (q) => `🌕 The full moon favors bold choices. YES on \"${q}\"`,\n (q) => `📖 The tome of fate flips open to a golden page. YES for \"${q}\"`,\n (q) => `🔥 The campfire crackles in agreement. YES to \"${q}\"`,\n];\n\nconst FATE_NO: Array<(q: string) => string> = [\n (q) => `💀 Natural 1! Critical fumble — the answer is NO on \"${q}\"`,\n (q) => `📜 Augury returns a woe omen. NO, regarding \"${q}\"`,\n (q) => `🔮 The crystal ball clouds over... NO for \"${q}\"`,\n (q) => `⚖️ The DM shakes their head slowly. NO to \"${q}\"`,\n (q) => `🃏 You draw from the Deck of Many Things: the Void. NO — \"${q}\" will not come to pass`,\n (q) => `👁️ The beholder's central eye narrows: NO on \"${q}\"`,\n (q) => `✨ The bones scatter unfavorably. NO, so it is written — \"${q}\"`,\n (q) => `🛡️ Even a paladin's Lay on Hands can't save this one. NO to \"${q}\"`,\n (q) => `🕳️ The trapdoor springs early. NO on \"${q}\"`,\n (q) => `🐍 The yuan-ti hisses in disapproval. NO to \"${q}\"`,\n (q) => `⛈️ A storm rolls in over the plan. NO, regarding \"${q}\"`,\n (q) => `🗿 The ancient statue's eyes stay cold. NO for \"${q}\"`,\n (q) => `🦴 The bone dice clatter to a stop, unfavorable. NO to \"${q}\"`,\n (q) => `🕯️ The candle gutters out. NO on \"${q}\"`,\n (q) => `🐺 The wolves howl a warning. NO to \"${q}\"`,\n (q) => `🏹 The arrow falls short of its mark. NO for \"${q}\"`,\n (q) => `🌑 The new moon offers no light on this one. NO for \"${q}\"`,\n (q) => `🧪 The potion fizzles instead of glowing. NO to \"${q}\"`,\n (q) => `⚰️ The crypt door stays sealed. NO, regarding \"${q}\"`,\n (q) => `🐀 Even the rats scurry away from this. NO on \"${q}\"`,\n];\n\nconst MAX_FATE_QUESTION_LEN = 200;\n\n/** A 50/50 D&D-flavored yes/no verdict for a chat-supplied question. */\nexport function rollFate(question: string): string {\n const q = question.trim();\n const displayQuestion = q.length > MAX_FATE_QUESTION_LEN ? q.slice(0, MAX_FATE_QUESTION_LEN) + \"…\" : q;\n const pool = Math.random() < 0.5 ? FATE_YES : FATE_NO;\n const flavor = pool[Math.floor(Math.random() * pool.length)];\n return flavor(displayQuestion);\n}\n\n// !hug — an undocumented, purely warm/supportive command. No dice, no\n// mechanics, no game state. Kept out of !dndbothelp and the guide on\n// purpose (like !connections) so it stays a small, genuine gesture rather\n// than a \"feature\" people grind or spam for a reaction.\nconst HUG_LINES: string[] = [\n \"Even legendary heroes need a long rest sometimes.\",\n \"You've survived every encounter so far — that's a flawless record.\",\n \"No saving throw needed here, just take the hug.\",\n \"Every campaign has a slow chapter. This is yours, and that's okay.\",\n \"You don't have to roll for initiative on the hard days.\",\n \"The party's got your back, no matter your HP.\",\n \"Short rests count too — you don't have to be at full HP to keep going.\",\n \"You've got more allies in this world than you know.\",\n \"Even the mightiest paladin needs someone to lean on sometimes.\",\n \"This one's on the house — no Charisma check required.\",\n \"You're further into the story than you think, and it's a good one.\",\n \"The guild remembers you, even on your quiet days.\",\n \"You don't need a critical hit to be doing great.\",\n \"Rest here a while. The dungeon can wait.\",\n \"You're allowed to hand off the torch for a bit.\",\n \"Whatever today's encounter was, you're still standing.\",\n \"Small victories still go in the campaign log.\",\n \"You're not fighting this one alone.\",\n \"Take the inspiration point — you've earned it.\",\n \"However this chapter reads, you're the hero of it.\",\n];\n\n/** A gentle, sincere hug — optionally directed at another chatter. */\nexport function rollHug(display: string, target?: string | null): string {\n const line = pick(HUG_LINES);\n return target\n ? `🤗 @${display} wraps @${target} in a warm hug. \"${line}\"`\n : `🤗 The guild wraps @${display} in a warm hug. \"${line}\"`;\n}\n\n// Auto thank-you for new and renewed Twitch subscriptions — see main.ts's\n// EventSub handling for \"channel.subscribe\" / \"channel.subscription.message\".\nconst SUB_TIER_NAMES: Record = {\n \"1000\": \"Tier 1\",\n \"2000\": \"Tier 2\",\n \"3000\": \"Tier 3\",\n Prime: \"Prime\",\n};\n\nfunction subTierLabel(tier?: string | null): string {\n if (!tier) return \"\";\n const label = SUB_TIER_NAMES[tier];\n return label ? ` (${label})` : \"\";\n}\n\nconst NEW_SUB_LINES: Array<(name: string, tier: string) => string> = [\n (name, tier) => `⚔️ @${name} has sworn fealty to the guild${tier}! Welcome to the ranks, adventurer — may your rolls be ever favorable.`,\n (name, tier) => `📜 A new name is inked into the guild roster: @${name}${tier}. The hall is a little brighter for it.`,\n (name, tier) => `🛡️ @${name} raises the guild banner for the first time${tier}. Glory and good company await.`,\n (name, tier) => `🎲 @${name} has joined the party${tier}! Grab a seat by the fire — the story's better with you in it.`,\n (name, tier) => `🏰 The gates open for a new adventurer: welcome, @${name}${tier}. Here's to the campaign ahead.`,\n (name, tier) => `✨ @${name} takes up the guild's oath${tier}. May your natural 20s find you often.`,\n (name, tier) => `🗡️ @${name} draws their blade and joins the guild${tier}. The campaign just got more interesting.`,\n (name, tier) => `🍺 @${name} bellies up to the guild tavern for the first time${tier}. First round's on the house.`,\n (name, tier) => `📯 A horn sounds as @${name} enters the guild${tier}. Adventure awaits.`,\n (name, tier) => `🌟 @${name} rolls a natural 20 on their first appearance${tier}. Welcome to the guild!`,\n (name, tier) => `🗺️ @${name} unrolls their map and joins the guild's quest${tier}. Onward!`,\n (name, tier) => `🏹 @${name} nocks an arrow and signs the guild ledger${tier}. Glad to have you.`,\n (name, tier) => `🔮 The seer foresaw this: @${name} joins the guild${tier}.`,\n (name, tier) => `🛶 @${name} arrives by longship, ready to adventure${tier}. Welcome aboard.`,\n (name, tier) => `📚 @${name} adds their name to the guild's grand tome${tier}. Let the story begin.`,\n (name, tier) => `🕯️ A candle is lit in the guild hall for @${name}${tier}. Welcome, adventurer.`,\n (name, tier) => `⚡ @${name} crashes into the guild hall like a lightning bolt${tier}. Let's see what you've got.`,\n (name, tier) => `🐉 @${name} tames the guild dragon on day one${tier}. Bold start.`,\n (name, tier) => `🎻 The bard strikes up a welcome tune for @${name}${tier}.`,\n (name, tier) => `🧭 @${name}'s compass points straight to the guild${tier}. Glad you found us.`,\n];\n\nconst RESUB_LINES: Array<(name: string, months: number, tier: string) => string> = [\n (name, months, tier) => `🔥 @${name} renews their pact with the guild${tier} — ${months} month${months === 1 ? \"\" : \"s\"} strong and still adventuring.`,\n (name, months, tier) => `📖 Another chapter for @${name}${tier}: ${months} month${months === 1 ? \"\" : \"s\"} in the guild, and the story keeps going.`,\n (name, months, tier) => `🛡️ @${name} re-ups their oath to the guild${tier} — ${months} month${months === 1 ? \"\" : \"s\"} of loyalty, and counting.`,\n (name, months, tier) => `🎉 @${name} has stuck with the guild for ${months} month${months === 1 ? \"\" : \"s\"}${tier}. That's a real friendship roll, not just a lucky one.`,\n (name, months, tier) => `⚔️ ${months} month${months === 1 ? \"\" : \"s\"} deep and @${name} is still here${tier} — the guild remembers its own.`,\n (name, months, tier) => `🏰 @${name} returns to the guild hall for month ${months}${tier}. The torches burn a little brighter.`,\n (name, months, tier) => `🗡️ @${name} re-forges their bond with the guild${tier} — ${months} month${months === 1 ? \"\" : \"s\"} and counting.`,\n (name, months, tier) => `📯 The horn sounds again for @${name}${tier}, marking ${months} month${months === 1 ? \"\" : \"s\"} of loyalty.`,\n (name, months, tier) => `🌟 @${name} levels up their guild membership to month ${months}${tier}. Still adventuring strong.`,\n (name, months, tier) => `🍻 @${name} raises a mug for ${months} month${months === 1 ? \"\" : \"s\"} in the guild${tier}. Cheers to the streak.`,\n (name, months, tier) => `📖 Chapter ${months} of @${name}'s guild saga begins${tier}. The story's far from over.`,\n (name, months, tier) => `🛡️ @${name}'s loyalty holds firm at ${months} month${months === 1 ? \"\" : \"s\"}${tier} — a shield wall of dedication.`,\n (name, months, tier) => `🔥 @${name} keeps the campfire burning for month ${months}${tier}. Glad you're still here.`,\n (name, months, tier) => `🗺️ @${name} marks another ${months} month${months === 1 ? \"\" : \"s\"} on the guild map${tier}. Onward, together.`,\n (name, months, tier) => `⚔️ @${name} re-swears the oath for month ${months}${tier}. The guild salutes you.`,\n (name, months, tier) => `🎲 @${name} rolls another month of loyalty (${months} total)${tier} — no natural 1 in sight.`,\n (name, months, tier) => `🏹 @${name} keeps their aim true after ${months} month${months === 1 ? \"\" : \"s\"} with the guild${tier}.`,\n (name, months, tier) => `🕯️ Another candle lit for @${name}'s month ${months}${tier} in the guild.`,\n (name, months, tier) => `🐉 @${name} has outlasted more dragons than most after ${months} month${months === 1 ? \"\" : \"s\"}${tier}.`,\n (name, months, tier) => `📜 The guild scribe adds another entry for @${name} — ${months} month${months === 1 ? \"\" : \"s\"} strong${tier}.`,\n];\n\n/** Thank-you for a brand-new subscription (channel.subscribe). */\nexport function rollNewSubThankYou(displayName: string, tier?: string | null): string {\n return pick(NEW_SUB_LINES)(displayName, subTierLabel(tier));\n}\n\n/** Thank-you for a renewed/resub with a shared message (channel.subscription.message). */\nexport function rollResubThankYou(displayName: string, months: number, tier?: string | null): string {\n const safeMonths = Number.isFinite(months) && months > 0 ? Math.floor(months) : 1;\n return pick(RESUB_LINES)(displayName, safeMonths, subTierLabel(tier));\n}\n\nconst GIFT_SUB_LINES: Array<(name: string, count: number, tier: string) => string> = [\n (name, count, tier) => `🎁 @${name} just gifted ${count} membership${count === 1 ? \"\" : \"s\"} to the guild${tier}! A round of applause for the guild's newest patron of generosity.`,\n (name, count, tier) => `💰 @${name} paid ${count} adventurer${count === 1 ? \"'s\" : \"s'\"} way into the guild${tier}. That's the kind of coin a bard writes songs about.`,\n (name, count, tier) => `✨ @${name} sponsored ${count} new guild membership${count === 1 ? \"\" : \"s\"}${tier} — true guild patronage.`,\n (name, count, tier) => `🛡️ @${name} covered the guild dues for ${count} adventurer${count === 1 ? \"\" : \"s\"}${tier}. The hall remembers acts like this.`,\n (name, count, tier) => `🏹 @${name} fires off ${count} gifted membership${count === 1 ? \"\" : \"s\"}${tier} like a volley of goodwill.`,\n (name, count, tier) => `🌟 @${name} casts Mass Generosity, hitting ${count} lucky adventurer${count === 1 ? \"\" : \"s\"}${tier}.`,\n (name, count, tier) => `🍻 @${name} buys a round of guild memberships for ${count} adventurer${count === 1 ? \"\" : \"s\"}${tier}. Cheers all around!`,\n (name, count, tier) => `📯 @${name} sounds the horn of generosity, gifting ${count} membership${count === 1 ? \"\" : \"s\"}${tier}.`,\n (name, count, tier) => `🗝️ @${name} unlocks the guild gates for ${count} new adventurer${count === 1 ? \"\" : \"s\"}${tier}.`,\n (name, count, tier) => `🎁 @${name}'s Bag of Holding turns out to be full of gifted membership${count === 1 ? \"\" : \"s\"} (${count})${tier}.`,\n (name, count, tier) => `🐉 @${name} raids their own hoard to gift ${count} membership${count === 1 ? \"\" : \"s\"}${tier}. Legendary generosity.`,\n (name, count, tier) => `🛡️ @${name} shields ${count} adventurer${count === 1 ? \"\" : \"s\"} with a gifted membership${count === 1 ? \"\" : \"s\"}${tier}.`,\n (name, count, tier) => `📜 @${name}'s name goes down in the guild's Book of Generous Deeds for ${count} gift${count === 1 ? \"\" : \"s\"}${tier}.`,\n (name, count, tier) => `✨ @${name} sprinkles ${count} membership${count === 1 ? \"\" : \"s\"} across the guild like a Bless spell${tier}.`,\n (name, count, tier) => `🏰 @${name} throws open the guild doors for ${count} new adventurer${count === 1 ? \"\" : \"s\"}${tier}.`,\n (name, count, tier) => `🍀 @${name} shares their luck with ${count} fellow adventurer${count === 1 ? \"\" : \"s\"}${tier}.`,\n (name, count, tier) => `🔥 @${name} lights the way for ${count} new guild member${count === 1 ? \"\" : \"s\"}${tier}.`,\n (name, count, tier) => `🎻 The bards write a tune about @${name}'s ${count}-membership gift${count === 1 ? \"\" : \"s\"}${tier}.`,\n (name, count, tier) => `🗺️ @${name} charts a path into the guild for ${count} adventurer${count === 1 ? \"\" : \"s\"}${tier}.`,\n (name, count, tier) => `⚔️ @${name} arms ${count} new adventurer${count === 1 ? \"\" : \"s\"} with a guild membership${tier}. Well met!`,\n];\n\nconst ANON_GIFT_SUB_LINES: Array<(count: number, tier: string) => string> = [\n (count, tier) => `🎁 A mysterious benefactor just gifted ${count} membership${count === 1 ? \"\" : \"s\"} to the guild${tier}, no name given. The guild thanks you all the same.`,\n (count, tier) => `💰 An anonymous patron paid the guild dues for ${count} adventurer${count === 1 ? \"\" : \"s\"}${tier}. Whoever you are — well met.`,\n (count, tier) => `🕶️ A hooded figure gifts ${count} membership${count === 1 ? \"\" : \"s\"}${tier} and vanishes into the crowd.`,\n (count, tier) => `🧙 An unseen wizard casts a gift of ${count} membership${count === 1 ? \"\" : \"s\"}${tier} and disappears in a puff of smoke.`,\n (count, tier) => `🌙 Under cover of night, someone gifts ${count} membership${count === 1 ? \"\" : \"s\"}${tier}. The guild bows to the shadows.`,\n (count, tier) => `🎭 A masked benefactor leaves ${count} gifted membership${count === 1 ? \"\" : \"s\"}${tier} at the guild door.`,\n (count, tier) => `🐦 A raven delivers ${count} gifted membership${count === 1 ? \"\" : \"s\"}${tier}, sender unknown.`,\n (count, tier) => `✨ A flash of unseen magic grants ${count} membership${count === 1 ? \"\" : \"s\"}${tier}. No name, just generosity.`,\n (count, tier) => `🗝️ Someone slips ${count} membership key${count === 1 ? \"\" : \"s\"}${tier} under the guild door and disappears.`,\n (count, tier) => `🕵️ A rogue in the shadows gifts ${count} membership${count === 1 ? \"\" : \"s\"}${tier} without leaving a trace.`,\n (count, tier) => `📜 An unsigned scroll grants ${count} adventurer${count === 1 ? \"\" : \"s\"} guild membership${tier}.`,\n (count, tier) => `🌫️ A mist rolls through the guild hall, leaving behind ${count} gifted membership${count === 1 ? \"\" : \"s\"}${tier}.`,\n (count, tier) => `🦉 A familiar drops off ${count} gifted membership${count === 1 ? \"\" : \"s\"}${tier} and flies away.`,\n (count, tier) => `🕯️ A single candle burns beside ${count} anonymous gift${count === 1 ? \"\" : \"s\"}${tier}. No name attached.`,\n (count, tier) => `🎁 ${count} membership${count === 1 ? \"\" : \"s\"}${tier} appear, gift-wrapped, with no card in sight.`,\n (count, tier) => `🐉 A hoard's worth of generosity funds ${count} membership${count === 1 ? \"\" : \"s\"}${tier}, courtesy of persons unknown.`,\n (count, tier) => `🌟 A shooting star grants ${count} membership${count === 1 ? \"\" : \"s\"}${tier} — anonymously, as shooting stars do.`,\n (count, tier) => `🛡️ An unnamed champion shields ${count} adventurer${count === 1 ? \"\" : \"s\"} with a gifted membership${tier}.`,\n (count, tier) => `🗿 An ancient statue seems to wink as ${count} gifted membership${count === 1 ? \"\" : \"s\"}${tier} appear.`,\n (count, tier) => `🍀 Fortune smiles, unnamed, granting ${count} membership${count === 1 ? \"\" : \"s\"}${tier}.`,\n];\n\nconst GIFTED_WELCOME_LINES: Array<(name: string, tier: string) => string> = [\n (name, tier) => `🎁 @${name} joins the guild courtesy of a fellow adventurer's generosity${tier}. Welcome to the ranks — your gear's already paid for.`,\n (name, tier) => `⚔️ @${name} has been sponsored into the guild${tier}! Someone believed you belonged here — now go prove them right.`,\n (name, tier) => `📜 @${name}'s name goes on the roster, gifted by a guildmate${tier}. Welcome aboard.`,\n (name, tier) => `🎁 @${name} unwraps a guild membership${tier} they didn't even have to earn. Lucky adventurer.`,\n (name, tier) => `🛡️ @${name} enters the guild shielded by someone else's generosity${tier}. Make it count.`,\n (name, tier) => `🌟 @${name} arrives with a gifted membership in hand${tier} — someone believes in you.`,\n (name, tier) => `🍀 @${name}'s luck just leveled up with a gifted guild spot${tier}.`,\n (name, tier) => `🗺️ @${name} starts their journey with the guild, courtesy of a generous ally${tier}.`,\n (name, tier) => `🏰 The gates open for @${name}, gifted entry and all${tier}. Welcome home.`,\n (name, tier) => `🎻 A tune plays as @${name} steps in on someone else's coin${tier}. Enjoy the show.`,\n (name, tier) => `🕯️ A candle is lit for @${name}'s gifted arrival${tier}. Welcome to the guild.`,\n (name, tier) => `📯 The horn sounds for @${name}, sponsored into the ranks${tier}.`,\n (name, tier) => `🐉 @${name} rides in on someone else's generosity${tier}, dragon-scale luck included.`,\n (name, tier) => `⚔️ @${name} joins the ranks, gear paid for, glory still to be earned${tier}.`,\n (name, tier) => `🔥 @${name}'s guild membership was lit by another's kindness${tier}. Pass it on.`,\n (name, tier) => `🧙 A wizard's generosity conjures @${name} straight into the guild${tier}.`,\n (name, tier) => `🏹 @${name} joins the ranks, quiver full and dues already paid${tier}.`,\n (name, tier) => `📖 A new chapter opens for @${name}, gifted by a fellow adventurer${tier}.`,\n (name, tier) => `🎲 @${name} rolls into the guild on someone else's natural 20 of kindness${tier}.`,\n (name, tier) => `🌙 Under the guild's banner, @${name} arrives — gifted, welcomed, ready${tier}.`,\n];\n\n/** Thank-you for a gift-sub batch (channel.subscription.gift). Pass name=null for anonymous gifts. */\nexport function rollGiftSubThankYou(gifterName: string | null, count: number, tier?: string | null): string {\n const safeCount = Number.isFinite(count) && count > 0 ? Math.floor(count) : 1;\n return gifterName\n ? pick(GIFT_SUB_LINES)(gifterName, safeCount, subTierLabel(tier))\n : pick(ANON_GIFT_SUB_LINES)(safeCount, subTierLabel(tier));\n}\n\n/** Welcome for the recipient of a gifted sub (channel.subscribe with is_gift=true). */\nexport function rollGiftedSubWelcome(recipientName: string, tier?: string | null): string {\n return pick(GIFTED_WELCOME_LINES)(recipientName, subTierLabel(tier));\n}\n\n// Matches \"goodnight\"-style chat messages so the bot can send off adventurers\n// for the night. Word-boundary-wrapped (not anchored to the start), so it\n// fires anywhere in the message — e.g. \"ok chat, gnight!\" or \"that's it for\n// me, good night everyone\" — while still avoiding false hits inside unrelated\n// words like \"midnight\", \"tonight\", \"nightmare\", or \"knight\".\nconst NIGHT = \"(?:n(?:ight|ite))\";\nconst GOODNIGHT_REGEX = new RegExp(\n `\\\\b(?:gn+|g['’]?n?${NIGHT}|good\\\\s*${NIGHT}|nighty\\\\s*${NIGHT}|${NIGHT}\\\\s*${NIGHT}|sleep\\\\s*tight)\\\\b`,\n \"i\",\n);\n\nexport function isGoodnightMessage(message: string): boolean {\n return GOODNIGHT_REGEX.test(message.trim());\n}\n\nconst GOODNIGHT_REPLIES = [\n (n: string) => `Rest well, @${n}! 🌙 May your dreams be free of goblins.`,\n (n: string) => `Goodnight, @${n}! The guild hall banks its fires — safe travels to the Land of Nod. 💤`,\n (n: string) => `Sleep tight, @${n}! A long rest restores HP *and* spell slots. 🛌`,\n (n: string) => `Farewell for now, @${n}! May you wake with advantage on tomorrow's rolls. ✨`,\n (n: string) => `🌜 Sweet dreams, @${n}! May no owlbear disturb your rest.`,\n (n: string) => `🛏️ Off to bed, @${n}? Even legends need their eight hours.`,\n (n: string) => `🌙 Goodnight, @${n}! The watch is set — sleep easy.`,\n (n: string) => `💤 Long rest initiated for @${n}. See you after the next dawn.`,\n (n: string) => `✨ Sleep well, @${n} — may your dreams roll nothing but natural 20s.`,\n (n: string) => `🏕️ Camp's set, @${n}. Rest up for tomorrow's adventure.`,\n (n: string) => `🌌 The stars watch over you tonight, @${n}. Goodnight!`,\n (n: string) => `🦉 The owls take the next watch, @${n}. Rest easy.`,\n (n: string) => `🕯️ The torches dim for the night, @${n}. Sleep well.`,\n (n: string) => `🐉 Even dragons need their sleep, @${n}. Goodnight!`,\n (n: string) => `📖 The chronicle pauses here, @${n}. Same time next session?`,\n (n: string) => `🛡️ Shields down, @${n} — time to rest.`,\n (n: string) => `🌠 May a shooting star bless your dreams, @${n}. Goodnight!`,\n (n: string) => `🍃 The wind carries you off to sleep, @${n}. Rest well.`,\n (n: string) => `🧝 Even the elves need their trance sometimes, @${n}. Goodnight!`,\n (n: string) => `🌒 Until next session, @${n}. Sleep tight, adventurer.`,\n];\n\nexport function goodnightReply(display: string): string {\n const pick = GOODNIGHT_REPLIES[Math.floor(Math.random() * GOODNIGHT_REPLIES.length)];\n return pick(display);\n}\n\nexport function compactText(value: unknown, max = 240) {\n return String(value ?? \"\")\n .replace(/\\s+/g, \" \")\n .replace(/<[^>]+>/g, \"\")\n .trim()\n .slice(0, max);\n}\n\nexport function splitChatMessage(text: string, max = 300) {\n const parts: string[] = [];\n let remaining = text.trim();\n while (remaining.length > max) {\n let cut = remaining.lastIndexOf(\" \", max);\n if (cut < 1) cut = max;\n parts.push(remaining.slice(0, cut).trim());\n remaining = remaining.slice(cut).trim();\n }\n if (remaining) parts.push(remaining);\n return parts;\n}\n\nexport function firstAlive(members: string[], hp: Record) {\n return members.findIndex((name) => Number(hp[name]) > 0);\n}\n\nexport function logRowText(r: any) {\n return `${new Date(Number(r.created_at)).toISOString()} | @${r.username} | ${r.action} | ${r.detail}`;\n}\n","label",[148],"ed31c04a-20e0-4fa9-8ed8-16350f65e9da","types.ts","760b7a24-a4d9-11f1-9139-1607ee4eb77e",266,["D",1788580993350],9,"// Shared type definitions for GuildScribe\n\nexport type Ability = \"STR\" | \"DEX\" | \"CON\" | \"INT\" | \"WIS\" | \"CHA\";\n\nexport type Race = {\n subraces: string[];\n bonuses: Partial>;\n speed: number;\n traits: string[];\n};\n\nexport type ClassData = {\n priority: Ability[];\n savingThrows: Ability[];\n hitDie: number;\n calling: string;\n};\n\nexport type Character = {\n username: string;\n race: string;\n subrace: string | null;\n cls: string;\n level: number;\n xp: number;\n scores: Record;\n speed: number;\n hpMax: number;\n hpCurrent: number;\n proficiency: number;\n traits: string[];\n spells: string[];\n items: string[];\n feats: string[];\n abilities: string[];\n};\n\nexport type CreationSession = {\n broadcasterId: string;\n username: string;\n step: string;\n race?: string | null;\n subrace?: string | null;\n cls?: string | null;\n scores?: number[] | Record | null;\n // BG3-flavored creation only (!bg3) — unused by the standard !newchar wizard.\n subclass?: string | null;\n background?: string | null;\n alignment?: string | null;\n hook?: string | null;\n};\n",[160],"db1d6c9e-14d1-45ee-aea1-41b1833eba6e","twitch.ts","9c5a8652-a4d9-11f1-b87e-1607ee4eb77e",268,["D",1788580993405],13,"// Twitch API helpers (tokens, chat, EventSub)\n\nimport { MAX_LOOKUP_MESSAGE_LENGTH } from \"./data.ts\";\nimport { splitChatMessage } from \"./utils.ts\";\n\nexport const env = (name: string) => {\n const value = Deno.env.get(name);\n if (!value) throw new Error(`Missing environment variable: ${name}`);\n return value;\n};\n\nconst CHAT_MAX = Math.min(MAX_LOOKUP_MESSAGE_LENGTH, 480);\n// Rules need more parts than other lookups; spells use sendSpellSections separately.\nconst MAX_PARTS = 5;\nconst PART_DELAY_MS = 450;\n// Twitch chat-send limits are shared by the bot account. Keep a conservative\n// global queue by default; operators can lower this after Twitch grants the\n// appropriate bot rate limit/verification.\nconst GLOBAL_CHAT_MIN_INTERVAL_MS = Math.max(50, Number(Deno.env.get(\"CHAT_GLOBAL_MIN_INTERVAL_MS\") ?? \"1600\"));\nlet nextChatSendAt = 0;\n\nasync function waitForGlobalChatSlot() {\n const now = Date.now();\n const wait = Math.max(0, nextChatSendAt - now);\n nextChatSendAt = Math.max(now, nextChatSendAt) + GLOBAL_CHAT_MIN_INTERVAL_MS;\n if (wait) await sleep(wait);\n}\n\nfunction sleep(ms: number) {\n return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n/** Cap + truncate parts so multi-message lookups always finish. */\nfunction prepareParts(text: string, maxLen = CHAT_MAX, maxParts = MAX_PARTS): string[] {\n let parts = splitChatMessage(text, maxLen).map((p) => p.slice(0, maxLen));\n if (parts.length > maxParts) {\n parts = parts.slice(0, maxParts);\n const last = parts[parts.length - 1];\n parts[parts.length - 1] = last.slice(0, Math.max(0, maxLen - 12)).trimEnd() + \" …(cut)\";\n }\n return parts.filter((p) => p.length > 0);\n}\n\n/** Keep URL on the first chat part so it is never dropped. */\nfunction preferLinkInFirstPart(parts: string[]): string[] {\n if (parts.length <= 1) return parts;\n const linkMatch = parts.join(\" \").match(/https?:\\/\\/[^\\s|]+/);\n if (!linkMatch) return parts;\n const link = linkMatch[0];\n if (parts[0].includes(link)) return parts;\n const prefix = `🔗 ${link} | `;\n let first = prefix + parts[0].replace(/🔗\\s*https?:\\/\\/[^\\s|]+\\s*\\|\\s*/g, \"\");\n if (first.length > CHAT_MAX) first = first.slice(0, CHAT_MAX - 1) + \"…\";\n const rest = parts\n .slice(1)\n .map((p) => p.replace(link, \"\").replace(/\\s*\\|\\s*$/g, \"\").trim())\n .filter(Boolean);\n return [first, ...rest];\n}\n\nexport async function sendChatMessage(text: string, broadcasterId: string) {\n const message = text.slice(0, 500);\n if (!message.trim()) return true;\n try {\n await waitForGlobalChatSlot();\n const send = async (token: string) =>\n fetch(\"https://api.twitch.tv/helix/chat/messages\", {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${token}`,\n \"Client-Id\": env(\"TWITCH_CLIENT_ID\"),\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n broadcaster_id: broadcasterId,\n sender_id: env(\"TWITCH_BOT_ID\"),\n message,\n }),\n });\n\n let res = await send(await getAppToken());\n if (res.status === 401) {\n // Cached token was rejected (expired/revoked) — drop it and get a fresh one, once.\n invalidateAppToken();\n await waitForGlobalChatSlot();\n res = await send(await getAppToken());\n }\n if (!res.ok && res.status !== 429) {\n console.error(`Twitch chat send failed: ${res.status}`);\n }\n // Brief backoff on rate limit so following parts can still send\n if (res.status === 429) {\n await sleep(1100);\n return false;\n }\n return res.ok;\n } catch (err) {\n console.error(\"sendChatMessage failed\", err);\n return false;\n }\n}\n\nexport async function sendChatMessages(\n text: string,\n broadcasterId: string,\n opts?: { maxParts?: number },\n) {\n const maxParts = opts?.maxParts ?? MAX_PARTS;\n let parts = prepareParts(text, CHAT_MAX, maxParts);\n parts = preferLinkInFirstPart(parts);\n for (let i = 0; i < parts.length; i++) {\n const ok = await sendChatMessage(parts[i], broadcasterId);\n if (!ok && i < parts.length - 1) {\n await sleep(700);\n await sendChatMessage(parts[i], broadcasterId);\n }\n if (i < parts.length - 1) await sleep(PART_DELAY_MS);\n }\n}\n\nexport async function sendSpellSections(sections: string[], display: string, broadcasterId: string) {\n // Flatten sections into a limited stream of chat parts (avoid dropping mid-spell)\n const combined: string[] = [];\n for (const section of sections) {\n combined.push(...prepareParts(`@${display} ${section}`, CHAT_MAX, 3));\n }\n const parts = combined.slice(0, MAX_PARTS);\n if (combined.length > MAX_PARTS && parts.length) {\n parts[parts.length - 1] =\n parts[parts.length - 1].slice(0, Math.max(0, CHAT_MAX - 12)).trimEnd() + \" …(cut)\";\n }\n for (let i = 0; i < parts.length; i++) {\n await sendChatMessage(parts[i], broadcasterId);\n if (i < parts.length - 1) await sleep(PART_DELAY_MS);\n }\n}\n\n// App access tokens (client_credentials) are valid for ~hours, not one request —\n// cache and reuse instead of re-fetching one from Twitch on every chat send.\nlet cachedAppToken: { token: string; expiresAt: number } | null = null;\n\nexport function invalidateAppToken() {\n cachedAppToken = null;\n}\n\nexport async function getAppToken() {\n if (cachedAppToken && Date.now() < cachedAppToken.expiresAt) {\n return cachedAppToken.token;\n }\n const body = new URLSearchParams({\n client_id: env(\"TWITCH_CLIENT_ID\"),\n client_secret: env(\"TWITCH_CLIENT_SECRET\"),\n grant_type: \"client_credentials\",\n });\n const res = await fetch(\"https://id.twitch.tv/oauth2/token\", {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/x-www-form-urlencoded\" },\n body,\n });\n if (!res.ok) throw new Error(`App token failed: ${res.status} ${await res.text()}`);\n const data = await res.json();\n const expiresInMs = Number(data.expires_in ?? 0) * 1000;\n // Refresh a minute early so we never send a request with a token that\n // expires mid-flight.\n cachedAppToken = {\n token: data.access_token as string,\n expiresAt: Date.now() + Math.max(0, expiresInMs - 60_000),\n };\n return cachedAppToken.token;\n}\n\nexport async function exchangeCode(code: string, redirectUri: string) {\n const body = new URLSearchParams({\n client_id: env(\"TWITCH_CLIENT_ID\"),\n client_secret: env(\"TWITCH_CLIENT_SECRET\"),\n code,\n grant_type: \"authorization_code\",\n redirect_uri: redirectUri,\n });\n const res = await fetch(\"https://id.twitch.tv/oauth2/token\", {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/x-www-form-urlencoded\" },\n body,\n });\n if (!res.ok) throw new Error(`OAuth exchange failed: ${res.status} ${await res.text()}`);\n return await res.json();\n}\n\nasync function createEventSubSubscription(\n type: string,\n version: string,\n condition: Record,\n callbackUrl: string,\n) {\n const appToken = await getAppToken();\n const res = await fetch(\"https://api.twitch.tv/helix/eventsub/subscriptions\", {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${appToken}`,\n \"Client-Id\": env(\"TWITCH_CLIENT_ID\"),\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n type,\n version,\n condition,\n transport: {\n method: \"webhook\",\n callback: callbackUrl,\n secret: env(\"EVENTSUB_SECRET\"),\n },\n }),\n });\n const text = await res.text();\n if (!res.ok) throw new Error(`EventSub subscription failed (${type}): ${res.status} ${text}`);\n return JSON.parse(text).data[0];\n}\n\nexport async function createChatSubscription(broadcasterId: string, callbackUrl: string) {\n return createEventSubSubscription(\n \"channel.chat.message\",\n \"1\",\n { broadcaster_user_id: broadcasterId, user_id: env(\"TWITCH_BOT_ID\") },\n callbackUrl,\n );\n}\n\n// New subscriptions (channel.subscribe) and renewals shared with a message\n// in chat (channel.subscription.message) — used to power the D&D-themed\n// !hug-style auto thank-you. Both require the broadcaster to have granted\n// the \"channel:read:subscriptions\" scope during OAuth; older connections\n// made before that scope was requested will need to reconnect for these to\n// take effect. Best-effort: callers should not fail the whole connect flow\n// if these throw (e.g. scope not yet granted).\nexport async function createSubEventSubscriptions(broadcasterId: string, callbackUrl: string) {\n const [newSub, resub, gift] = await Promise.all([\n createEventSubSubscription(\"channel.subscribe\", \"1\", { broadcaster_user_id: broadcasterId }, callbackUrl),\n createEventSubSubscription(\"channel.subscription.message\", \"1\", { broadcaster_user_id: broadcasterId }, callbackUrl),\n createEventSubSubscription(\"channel.subscription.gift\", \"1\", { broadcaster_user_id: broadcasterId }, callbackUrl),\n ]);\n return { newSub, resub, gift };\n}\n\nexport async function deleteEventSubSubscription(subscriptionId: string) {\n if (!subscriptionId) return true;\n const appToken = await getAppToken();\n const res = await fetch(`https://api.twitch.tv/helix/eventsub/subscriptions?id=${encodeURIComponent(subscriptionId)}`, {\n method: \"DELETE\",\n headers: { Authorization: `Bearer ${appToken}`, \"Client-Id\": env(\"TWITCH_CLIENT_ID\") },\n });\n if (res.status === 404) return true;\n if (!res.ok) throw new Error(`EventSub deletion failed: ${res.status} ${await res.text()}`);\n return true;\n}\n\n/** Constant-time string compare — doesn't branch/short-circuit on content,\n * only on length (which isn't secret), so it doesn't leak how many leading\n * characters of the signature matched via response timing. */\nfunction timingSafeEqual(a: string, b: string): boolean {\n if (a.length !== b.length) return false;\n let diff = 0;\n for (let i = 0; i < a.length; i++) {\n diff |= a.charCodeAt(i) ^ b.charCodeAt(i);\n }\n return diff === 0;\n}\n\nexport async function verifyEventSub(req: Request, rawBody: string) {\n const id = req.headers.get(\"Twitch-Eventsub-Message-Id\") ?? \"\";\n const timestamp = req.headers.get(\"Twitch-Eventsub-Message-Timestamp\") ?? \"\";\n const received = req.headers.get(\"Twitch-Eventsub-Message-Signature\") ?? \"\";\n if (!id || !timestamp || !received) return false;\n const receivedAt = Date.parse(timestamp);\n if (!Number.isFinite(receivedAt) || Math.abs(Date.now() - receivedAt) > 10 * 60 * 1000) return false;\n const key = await crypto.subtle.importKey(\n \"raw\",\n new TextEncoder().encode(env(\"EVENTSUB_SECRET\")),\n { name: \"HMAC\", hash: \"SHA-256\" },\n false,\n [\"sign\"],\n );\n const signature = new Uint8Array(\n await crypto.subtle.sign(\"HMAC\", key, new TextEncoder().encode(id + timestamp + rawBody)),\n );\n const hex = [...signature].map((b) => b.toString(16).padStart(2, \"0\")).join(\"\");\n const expected = `sha256=${hex}`;\n return timingSafeEqual(expected, received);\n}\n",[168],"d2cf73a8-58cf-41f6-82b7-4bf406d37e54","pages.ts","a605108c-a4d9-11f1-a673-1607ee4eb77e",267,["D",1788580992803],30,"// HTML page rendering for the web UI\n\nimport type { Character } from \"./types.ts\";\nimport { abilityNames } from \"./data.ts\";\nimport { modifier, formatRaceName, escapeHtml } from \"./utils.ts\";\nimport type { MapRow, MapToken } from \"./db.ts\";\nimport { MAP_TEMPLATES, TERRAINS, tokenColor } from \"./maps.ts\";\n\nexport function page(title: string, body: string) {\n return new Response(\n `${title}${body}`,\n { headers: { \"Content-Type\": \"text/html; charset=utf-8\" } },\n );\n}\n\nexport function renderCharacterPage(c: Character) {\n const statLine = abilityNames\n .map(\n (a) =>\n `

${a} ${c.scores[a]} (${modifier(c.scores[a]) >= 0 ? \"+\" : \"\"}${modifier(c.scores[a])})

`,\n )\n .join(\"\");\n return `${escapeHtml(c.username)}'s Character

${escapeHtml(c.username)}

Level ${c.level} ${escapeHtml(formatRaceName(c.race, c.subrace))} ${escapeHtml(c.cls)}

HP: ${c.hpCurrent}/${c.hpMax} | Speed: ${c.speed} ft | Proficiency: +${c.proficiency}

${statLine}

Traits: ${c.traits.map(escapeHtml).join(\", \")}

`;\n}\n\n// Not currently wired to any route — the activity log is only exposed via\n// the in-chat !logs command, which is scoped to one channel and restricted\n// to that channel's broadcaster/moderators. Kept here in case an\n// authenticated (per-channel, per-steward) web view is added later; do not\n// route this to a public GET endpoint without adding auth + per-channel scoping.\nexport function renderLogsPage(rows: any[]) {\n const lines = rows\n .map(\n (r: any) =>\n `${escapeHtml(new Date(Number(r.created_at)).toLocaleString())}${escapeHtml(r.username || \"unknown\")}${escapeHtml(r.broadcaster_id || \"\")}${escapeHtml(r.action || \"\")}${escapeHtml(r.detail || \"\")}`,\n )\n .join(\"\");\n return `

GuildScribe Activity Logs

Recent bot activity with timestamps, Twitch usernames, channels, and command details.

Back to guide · Bot home

${lines || ``}

Timestamp	Username	Channel ID	Action	Details
No activity recorded yet.

`;\n}\n\nfunction renderMapTemplateList(): string {\n return Object.values(MAP_TEMPLATES)\n .map(\n (t) =>\n `

${escapeHtml(t.name)} — ${escapeHtml(t.label)} (${t.width}x${t.height}): ${escapeHtml(t.description)}

`,\n )\n .join(\"\");\n}\n\nexport function renderGuidePage() {\n return `

Guild hall · D&D 5e

GuildScribe Codex

Welcome to the guild hall. Herein lie the rites of character, company, dice, duels, and the archives of the SRD.

Raise your banner Support the Guild Privacy Terms

Entering the hall: Grant the scribes a voice with /mod GuildScribeBot, then use !help for the welcome guide or !dndbothelp to browse this reference from chat.

Adventurer’s parchment

Create and view

!newchar

Start a guided chat wizard. Reply with !answer <choice> to select a race, subrace, class, and ability scores. Use !cancel to abandon the wizard mid-way.

!bg3

Rolls a random Baldur's Gate 3 style race and class, then lets you assign ability scores under BG3 point-buy rules (base 8, cap 15, 27-point budget) with !answer <STR> <DEX> <CON> <INT> <WIS> <CHA>. Confirm with !answer yes to save it as your character and get a link to its page. Use !cancel to abandon.

!createchar

Immediately create a level 1 character.

!createchar @username

Broadcaster/moderator only: create a level 1 character for someone else, such as for a viewer who can't chat directly.

!char!char @username

Display your current character summary, or view another player’s saved character.

Manage progress

!levelup!levelup +2!levelup -1

Adjust levels from 1 through 20. HP maximum, current HP, and proficiency are recalculated.

!hp +5!hp -3

Adjust current HP within the character’s valid range.

Save and restore

!savechar!loadchar!resetchar

Save a backup, restore the latest backup, or reset your character.

Fate’s dice

!d20!d20 @username!roll!r

Call upon the D20 of Fate. Use !d20 @username to roll for another adventurer.

!roll NdS[+/-M]

Roll a custom dice expression, such as !roll 1d20+5, !roll 2d6, or !roll 4d8-2.

!roll @username [NdS[+/-M]]

Roll on behalf of someone else in chat, such as !roll @friend or !roll @friend 2d6+3. Anyone can do this.

!roll dex!roll strength

Ability saving throw. Uses your saved character's ability modifier, plus proficiency if your class is proficient in that save. Works with abbreviations (str, dex, con, int, wis, cha) or full names.

!roll stealth!roll animal handling

Skill check. Uses your saved character's modifier for that skill's governing ability. Add @username to roll using someone else's saved character, e.g. !roll @friend perception.

!roll <question>?

Consult fate for a yes-or-no verdict, delivered with a random D&D-flavored omen (natural 20s, Augury, a beholder's judgment, the Deck of Many Things, and more). Example: !roll is enya going to die this time?

Baldur's Gate 3

Roll a character (saved)

!bg3

Rolls a random BG3-style race and class, then lets you assign ability scores under BG3 point-buy rules (base 8, cap 15, 27-point budget) with !answer <STR> <DEX> <CON> <INT> <WIS> <CHA>. Confirm with !answer yes to save it as your character and get a link to its page — see Adventurer's parchment for the rest of the character commands.

Roll a character (flavor only)

!bg3roll

Rolls a full BG3-flavored character in one line: race (with subrace where BG3 has one, like High Elf or Lolth-Sworn Drow), class and subclass, background, alignment, a BG3-style 27-point point-buy ability spread weighted toward the class's primary stat, and a one-line origin hook straight off the Nautiloid.

Companion & origin

!bg3companion

Rolls which BG3 companion you're traveling with — their role, a one-line personality blurb, and an iconic line.

!bg3origin

Casts you as one of the six canonical BG3 Origin Characters — or the Dark Urge — for this run, with their signature hook.

Loot & camp

!bg3loot

Rolls a random magic item drop with a BG3-style rarity tier, from Common up through Legendary.

!bg3camp

Rolls a random camp-night vignette featuring one of the companions.

Knowledgebase

!bg3lookup <name>

Searches a hand-curated Baldur's Gate 3 knowledgebase — companions, origins, classes, races, locations, factions, deities, notable villains, and legendary items — and returns a short blurb with a link to bg3.wiki. Examples: !bg3lookup astarion, !bg3lookup moonrise towers.

!bg3lookup <category> <name>

Narrow the search to one category, e.g. !bg3lookup faction zhentarim or !bg3lookup location grymforge. A bare !bg3lookup lists all recognized categories.

!bg3roll, !bg3companion, !bg3origin, !bg3loot, and !bg3camp are flavor rolls only — they print straight to chat and aren't saved, and none of them touch your !createchar/!char sheet. !bg3 is different — it saves a real character (see the parchment section above). !bg3lookup is also different: it's a reference lookup against the static knowledgebase above, not a roll, so the same query always returns the same entry.

Guild archives

Consult the SRD archives by name. Optional +N upcasts a spell or adds an item attack/damage bonus. Incomplete commands (e.g. bare !rules) return usage tips.

Spells, classes & rules

!rules <topic>!rule <topic>

Summarize a rule (up to 3 messages) with a public link. Examples: !rules magic, !rules combat, !rule advantage.

!spell <spell> [+N]

Shows level, school, casting details, range, duration, components, damage dice, damage type, save, area, classes, and higher-level scaling.

!class <class> [+N]

Shows Hit Die, saving throws, and proficiencies.

!feat <feat> [+N]

Shows prerequisites and the feat description.

Equipment and abilities

!item <item> [+N]

Shows weapon damage, type, range, weight, cost, armor class, properties, and modifier.

!ability <ability> [+N]

Shows the ability score, related skills, and description.

Races

!race <race> [+N]

Shows ability bonuses, speed, size, languages, and racial traits.

!subrace <subrace> [+N]

Shows subrace bonuses, parent race, speed, languages, and traits.

Arena, wilds & the company

A moderator or the broadcaster starts and manages the encounter; any adventurer can roll their own initiative once it's started. Duels and hunts are open to any adventurer with a saved character.

!turn start!turn roll!turn add <name> <initiative>!turn show!turn next!turn prev!turn remove <name>!turn end

!turn start opens the roll window; players call !turn roll to roll 1d20 plus their character's DEX modifier for initiative (each player rolls once per encounter). Moderators can still !turn add monsters, NPCs, or manual scores. The tracker stores one encounter per connected channel, sorts combatants from highest to lowest initiative, shows the active combatant with an arrow, and advances the round automatically.

Parties

!party create <name>!party join <name>!party invite @user [name]!party accept [name]!party decline [name]!party list [name]

!party list shows each of your companies with leader and members. An invite only adds someone once they !party accept it — the party name is optional if they only have one pending invite.

!party leave <name>!party disband <name>

Create a party (you become leader and member), invite friends, and list rosters. Party name is optional on invite if you only belong to one party.

Player duels & hunts

Auto challenges resolve when accepted. Classic modes use turn-based attack. Solo !dndduel fights a level-scaled monster (auto); !dndduel monster is classic. Party hunts fight a shared monster and award XP on victory. PvP gives no XP.

Custom commands & triggers

Broadcasters and moderators can add their own commands and passive keyword auto-responses right from chat — no code required. These share the !dndbot word used for bot settings below, but different subcommands, so nothing collides. list is open to everyone; the rest are mod/broadcaster only.

!dndbot add <name> <response>!dndbot edit <name> <response>!dndbot remove <name>!dndbot cooldown <name> <seconds>!dndbot list

Creates !<name> as a new chat command. Built-in command names can't be used or overridden.

!trigger add <keyword> <response>!trigger remove <keyword>!trigger cooldown <keyword> <seconds>!trigger list

Fires the response automatically whenever <keyword> appears in chat (no ! needed to trigger it) — wrap multi-word keywords in quotes, e.g. !trigger add \"good luck\" May the dice favor you!

Responses can use {user}, {target} (first @mention, commands only), {count} (times used), and {random:a|b|c} to pick one option at random. Each channel has a cap on the number of custom commands/triggers and a default cooldown to prevent spam.

Battle maps

Create & view

!map create <name> [WxH] [template]

Mod/broadcaster only. Makes a new grid map (default 10x8, up to 20x20), starting as all grass — or stamped with a template's terrain if you name one, e.g. !map create tav1 tavern or !map create tav1 14x10 tavern.

!map list!map view <name>

List every map in the channel, or post a link to one — the map page is a live, auto-refreshing visual grid.

!map delete <name>!map remove <name>

Mod/broadcaster only. Deletes the map along with its terrain and every character token on it — this can't be undone.

Templates

!map templates

Lists every ready-made layout you can stamp onto a new map with !map create <name> [WxH] <template>. A template sets its own default size (overridable) and pre-paints walls, doors, hazards, and features — a starting point you can still touch up with !map paint/!map fill afterward.

${renderMapTemplateList()}

Edit the terrain

!map terrains

Lists every terrain type (grass, forest, water, sand, mountain, road, floor, wall, door, trap, lava, void) — some, like water/wall/mountain/lava/void, block tokens from standing there.

!map fill <name> <terrain>

Mod/broadcaster only. Resets the whole grid to one terrain.

!map paint <name> <x> <y> <terrain>

Mod/broadcaster only. Sets a single cell, e.g. !map paint dungeon1 4 2 wall. Coordinates start at (1,1) in the top-left.

Place & move characters

!map addchar <name> [x y]

Puts your saved character on the map, at the coordinates you give or the first free cell otherwise.

!map addchar <name> @user [x y]

Mod/broadcaster only: place someone else's character.

!map move <name> <x> <y>!map move <name> @user <x> <y>

Move a token; the second form (moving someone else) is mod/broadcaster only.

!map removechar <name> [@user]

Take a character off the map.

Map creation, terrain painting, and moving someone else's token are restricted to the broadcaster/moderators, the same as the rest of the guild's shared state; everyone can place and move their own character.

Onboarding and support

In chat

!help

Welcome to the guild hall and a path to begin your legend.

!guide!link

Post the Guild Codex URL in chat.

!dndbothelp

List codex chapters.

Expand one of: !dndbothelp dice, !dndbothelp character, !dndbothelp party, !dndbothelp combat, !dndbothelp lookup, !dndbothelp settings.

Connect and support

Use the onboarding page to connect a Twitch channel. After connecting, run /mod GuildScribeBot in that channel.

Already connected? Reconnect your channel any time to grant newly requested permissions as GuildScribe gains features — safe to run repeatedly, and won't duplicate or lose your existing data.

Support the project through the donations page.

Moderators can review recent activity for their channel with !logs in chat.

Guild stewards (mod/broadcaster)

!dndbot on!dndbot off!dndbot status!dndbot leave!dndbot leave purge

Enable/disable the bot. The broadcaster can disconnect with !dndbot leave; add purge to delete channel data.

GuildScribe provides reference and gameplay utilities. Always verify rules, character choices, and wallet details before acting.

`;\n}\n\n// ── Battle maps ──\n\nexport function renderMapPage(map: MapRow, cells: Record, tokens: MapToken[], baseUrl: string) {\n const cellPx = map.width > 16 || map.height > 16 ? 28 : 36;\n const byCell = new Map(tokens.map((t) => [`${t.x},${t.y}`, t]));\n let gridCells = \"\";\n for (let y = 1; y <= map.height; y++) {\n for (let x = 1; x <= map.width; x++) {\n const terrain = cells[`${x},${y}`] ?? map.default_terrain;\n const info = TERRAINS[terrain] ?? TERRAINS.grass;\n const token = byCell.get(`${x},${y}`);\n const initials = token ? escapeHtml((token.display_name || token.username).slice(0, 2).toUpperCase()) : \"\";\n const tokenHtml = token\n ? `

${initials}

`\n : \"\";\n gridCells += `

${tokenHtml}

`;\n }\n }\n const legend = Object.entries(TERRAINS)\n .map(([k, v]) => `${escapeHtml(v.label)}${v.blocksMovement ? \" 🚫\" : \"\"}`)\n .join(\"\");\n const roster = tokens.length\n ? `

${escapeHtml(t.display_name || t.username)} — (${t.x},${t.y})

`\n : `

No characters placed yet. In chat: !map addchar ${escapeHtml(map.map_name)}

`;\n return `${escapeHtml(map.map_name)} — GuildScribe Map

← All maps

🗺️ ${escapeHtml(map.map_name)}

${map.width}×${map.height} — updated ${escapeHtml(new Date(map.updated_at).toLocaleString())}. This page auto-refreshes every 15s.

${gridCells}

${legend}

Characters on this map

${roster}

Edit from Twitch chat: !map paint ${escapeHtml(map.map_name)} x y terrain · !map addchar ${escapeHtml(map.map_name)} · !map move ${escapeHtml(map.map_name)} x y · !map removechar ${escapeHtml(map.map_name)} · full list: !dndbothelp maps

`;\n}\n\nexport function renderMapListPage(maps: MapRow[], broadcasterId: string, baseUrl: string) {\n const items = maps.length\n ? `

${escapeHtml(m.map_name)} (${m.width}×${m.height})

`\n : `

No maps yet. In chat, a moderator can start one with !map create <name> [WxH].

`;\n return `Maps — GuildScribe

🗺️ Maps in this channel

${items}

See !dndbothelp maps in chat for the full command list.

`;\n}\n",[176],"46a39247-7fc6-491f-88ab-87159927b1ec","maps.ts","a4656b02-a743-11f1-b2a7-1607ee4eb77e",238,["D",1788488650689],2,"// GuildScribe — battle maps\n//\n// Chat commands create/edit maps and place character tokens on them; a\n// public, read-only web page (see pages.ts / main.ts route \"/map\") renders\n// the grid visually. Editing (creating a map, painting terrain, deleting a\n// map, and moving someone else's token) stays behind Twitch chat identity\n// (chatterId, verified by EventSub) rather than an open web form — that\n// matches how every other piece of shared channel state in this bot\n// (parties, duels, the initiative tracker) is only ever mutated through an\n// authenticated chat command, never through an unauthenticated web request.\n\nimport { sendChatMessage } from \"./twitch.ts\";\nimport {\n createMap,\n deleteMap,\n fillMap,\n findTokenAt,\n getCharacter,\n getMap,\n getMapCells,\n getMapToken,\n getMapTokens,\n listMaps,\n removeMapToken,\n setMapCell,\n upsertMapToken,\n} from \"./db.ts\";\n\n// ── Map templates ──\n//\n// Publicly listable (!map templates), publicly usable (!map create \n// [WxH]

${escapeHtml(c.username)}

GuildScribe Activity Logs

GuildScribe Codex

Adventurer’s parchment

Create and view

Manage progress

Save and restore

Fate’s dice

Baldur's Gate 3

Roll a character (saved)

Roll a character (flavor only)

Companion & origin

Loot & camp

Knowledgebase

Guild archives

Spells, classes & rules

Equipment and abilities

Races

Arena, wilds & the company

Parties

Player duels & hunts

Custom commands & triggers

Battle maps

Create & view

Templates

Edit the terrain

Place & move characters

Onboarding and support

In chat

Connect and support

Guild stewards (mod/broadcaster)

🗺️ ${escapeHtml(map.map_name)}

Characters on this map

🗺️ Maps in this channel

GuildScribe Privacy Policy

How it is used

Retention

Deletion

GuildScribe Terms of Service

GuildScribe Codex

Support the Guild

Ethereum (ETH)

Bitcoin (BTC)

Connection cancelled

The Guild renews your banner

The Guild accepts your banner

Connection failed

GuildScribe

Hi

Diff · v278