Locksmith

Locksmith/README.md

@@ -0,0 +1,48 @@
+# Locksmith
+
+Automatic lock-picking and Knock spell resolution for D&D 5e in Roll20 - works with both the legacy (5e) and Beacon (5.5e) character sheets.
+
+Roll20 has no native trigger for "a player clicks a locked door," so lock-picking has always meant manual GM adjudication. Locksmith closes that gap: set a difficulty on a door or window once, and from then on a player's own Thieves' Tools roll - or a Knock spell - is automatically checked against the nearest locked door/window in range. No extra command on the player's side.
+
+## Features
+
+- **Automatic pick resolution** - Thieves' Tools rolls are detected and compared against the nearest locked door/window in range, on both the legacy and Beacon sheets. Success posts an Unlock button; failure never reveals the DC.
+- **Knock spell support** - detected automatically, no roll involved, and can bypass Magic-only locks that mundane picking can't.
+- **No custom data storage for lock state** - the difficulty is encoded directly into the door/window's own color property, so it survives page duplication, copy/paste, and everything else Roll20 already does to that property.
+- **GM setup menu** (`!lock`) - set a DC, mark a lock Unpickable or Magic-only, and toggle on-map status labels (which turn yellow if a key-holder is already on the map).
+- **Keys and keyrings** - hand a key to a token directly, or generate a self-service loot macro for treasure. Each character's `!keyring` report lets them Use (toggle), Give, or Drop a key, plus a "Try all Keys" button that finds the nearest match automatically.
+- **One-click token action** - `!keyring` can be added as a token action, so players never type a command.
+- **In-game help** - `!lock --help` builds a full handout (GM and player sections, screenshots, jump links) right in your game.
+
+## Installation
+
+Install via Roll20's One-Click API script installer (search "Locksmith"), or copy `Locksmith.js` into a new API script in your game's API Scripts page.
+
+## Getting Started
+
+1. Select a door or window on your map.
+2. Run `!lock` to open the setup menu.
+3. Use the **Set** row to give it a DC, or mark it Unpickable/Magic.
+
+From there, players just make Thieves' Tools checks or cast Knock as normal - Locksmith handles the rest. Run `!lock --help` at any time for the full documentation, including a player-facing section you can point your table to directly.
+
+## Commands
+
+| Command | Who | What it does |
+|---|---|---|
+| `!lock` | GM | Opens the setup menu (select doors/windows first for per-lock options) |
+| `!lock --report-dc` | GM | Lists every selected door/window's status, or the whole page if nothing is selected |
+| `!lock --help` | Anyone | Creates or refreshes the help handout |
+| `!keyring` (or `!lock --keyring`) | Anyone | Reports the selected token's keys - requires a token to be selected |
+
+Everything else - setting a DC, marking a lock Unpickable/Magic, granting or looting a key, giving/dropping a key, toggling map labels, creating the `!keyring` token action - is reached through buttons in the menu and reports above, not additional typed commands.
+
+## Notes
+
+- A door or window needs *both* a DC/Unpickable/Magic setting *and* Roll20's own locked state turned on before a pick attempt or Knock will do anything with it.
+- Manually changing the color of a door/window Locksmith manages can break its ability to track that lock - use the menu to reconfigure it instead.
+- All key-related output (granting, looting, keyring reports, Use/Give/Drop) is private to the GM and whoever ran the command - it's never broadcast to the table, unlike pick-attempt and Knock outcomes, which might be public, depending on sheet settings.
+
+## Changelog
+
+**1.0.0** - Debut release.

Locksmith/script.json

@@ -0,0 +1,17 @@
+{
+  "name": "Locksmith",
+  "script": "Locksmith.js",
+  "version": "1.0.0",
+  "description": "**Locksmith** automates lock-picking and the Knock spell for D&D 5e games, working with both the legacy (5e) and Beacon (5.5e) character sheets.\n\nRoll20 has no native trigger for \"a player interacts with a locked door,\" so lock-picking has always meant manual GM adjudication. Locksmith closes that gap: a GM sets a difficulty (or marks a lock Unpickable or Magic-only) directly on a door or window, and from then on, a player's own Thieves' Tools roll - or a Knock spell - is automatically compared against the nearest locked door/window in range, with no extra command needed on the player's side.\n\nNo custom data storage is used for lock state - the difficulty is encoded directly into the door/window's own color property, so it survives page duplication, copy/paste, and everything else Roll20 already does to that property.\n\n**Key features**\n- Automatic resolution of Thieves' Tools rolls and the Knock spell against nearby locked doors/windows, on both the legacy and Beacon sheets\n- A GM menu (`!lock`) for setting a DC, marking a lock Unpickable or Magic-only, and toggling on-map status labels\n- A full keys and keyrings system: hand out a key to bypass a lock entirely, loot a key from treasure via a pasted macro, and a per-character `!keyring` report with Use/Give/Drop and a one-click \"try all my keys\" option\n- A one-click token action for `!keyring`, so players never need to type the command\n- A GM/player help handout (`!lock --help`), including screenshots and a table of contents\n\n**Getting started**\nRun `!lock` with a door or window selected to open the setup menu. Full documentation - GM setup and the player-facing experience - is available in-game via `!lock --help`, which creates a handout with everything covered above in more depth.\n\n**Commands**\n- `!lock` - open the setup menu (select doors/windows first for per-lock options)\n- `!lock --report-dc` - list every selected door/window's status, or the whole page if nothing is selected\n- `!lock --help` - create or refresh the help handout\n- `!keyring` (or `!lock --keyring`) - report the selected token's keys; requires a token to be selected\n\nEverything else (setting a DC, marking Unpickable/Magic, granting or looting a key, toggling map labels) is reached through buttons in the menu and reports above, not typed commands.",
+  "authors": "Keith Curtis",
+  "roll20userid": "162065",
+  "dependencies": [],
+  "patreon": "https://www.patreon.com/c/KeithCurtis",
+  "modifies": {
+    "door": "read,write",
+    "window": "read,write",
+    "handout": "read,write"
+  },
+  "conflicts": [],
+  "previousversions": ["1.0.0"]
+}