Door Master Script

Licensed under the Apache License, Version 2.0

This Roll20® API script gives the GM the ability to drop a control token onto the virtual table and have it automatically be made into an interractive door object with rollable token images and dynamic lighting walls. Players can interract with the door image to perform various actions (such as opening, closing, searching for traps, etc.), while the GM can use the control token to adjust everything from locked state to trap effects.

In addition to the API script itself, we are also including a set of door images to use in your games as door tokens. These include images for closed, open, and broken states of a porticullis, wooden, and stone doors as well as control tokens to use for the Door Controller. These images are licensed under a Creative Commons Attribution-NonCommercial 4.0 International License and are free to use in your games, provided they are not used commercially. If your games are streamed, please provide attribution for the door tokens to Crystal Forge Games.

Features

  • Multiple Door Images: Using multisided tokens and door states
  • Dynamic Lighting: Using created or linked paths and changes based on door states
  • Opening/Closing: Players and GMs may open or close a door using a simple API button, doing so automatically manages the door image and dynamic lighting changes.
  • Breaking: Strong players may break down doors (based on a difficulty), bypassing locks, traps, and making the door open and inoperable until fixed.
  • Locks: GMs may set a door state to locked, including lock difficulty, so players can’t open it (unless they can pick locks or break down the door). (In a future release, I hope to add a key system (see: Roadmap)
  • Lockpicking: Players with the skills or abilities to do so can attempt to pick the lock on locked doors.
  • Secret Doors: GMs may make secret doors with configurable difficulty, that players will automatically try to detect if they get close enough and have the skill or ability to do so. Detecting a secret door will automatically make it visible and interractive.
  • Traps: GMs may set traps on the door (complete with effects!), including:
    • Passive and active trap searches for players with the skill or ability
    • Trap Disarming for players with the skill or ability
    • Area of effect (still to-do) and single target damage
    • Customizable damage dice and damage type
    • Automatic rolling of trap saves / avoidance for players with the skill or ability
    • Trap Special Effects
    • Configurable automatic reset
  • Variable Messages: For variation, script messages can be configured with (random) variable text options, this way a character may bash one door open and kick another door open.
  • Configurable to Various Systems: Currently the script handles (through configuration options) D20 and D100 based systems. GMs may configure the script to work with their particular character sheet.
    • D20 Systems: Roll 1d20 and add the character’s modifier to try and beat a specified DC (difficulty class)
    • D100 Systems: Roll 1d100 to try and roll below a character’s skill level +/- the difficulty

Usage

To use a door, players may select the door image token, and click the [Door] token macro button (or issue the command !DoorMaster_menu). This will whisper a menu of door options to the player. Note that players must be playing AS their character, and have a valid token on the map which is close enough to the door. The script will inform the player if they are too far or don’t have a token.

GMs may target either the door image token, or the door control token, depending on which layer they happen to be on, and use the same macro button or issue the same command. GMs will have extra options available on the door menu. GMs do not have to have a character token, and can issue door commands from anywhere on the map.

Adding a Door

Once a door controller has been set up (see: Controller Setup), simply drag a controller token onto the map and put it into place. The defaults for the door will be automatically applied, and any of the individual settings can be adjusted as desired. Basic settings (such as open or closed, locked or unlocked, or broken) can be set with the normal Door Menu, advanced configuration can be done using the Configuration Menu.

The Door Menu

The door menu lists a series of button macros for players and GMs to use to interract with doors. To use any of the macro buttons, a door object (either control token or image token) must be selected, and if a player, the player must be within range.

Open: !DoorMaster_open
Opens the currently selected door if it’s not open or locked. If the character has the ability, a passive check will be made to detect any traps and will stop the player if found or set off an armed trap if not.
Close: !DoorMaster_close
Closes the currently selected door if it’s open and not broken.
Break Open (Skill Based): !DoorMaster_break
Breaks open the door, bypassing locks, traps, and rendering the door inoperable.
Repair (GM Only): !DoorMaster_break
Fixes a broken door, setting it to an open, but operable, state.
Lock (GM Only): !DoorMaster_lock
Locks the currently selected door if it’s unlocked.
Unlock (GM Only): !DoorMasster_unlock
Unlocks the currently selected door if it’s locked.
Pick Lock (Player Only, Skill Based): !DoorMaster_pick
Attempts to pick a locked door if the character has a lockpick skill. If the character has the ability, a passive check will be made to detect any traps and will stop the player if found or set off an armed trap if not.
Look for Traps (Player Only, Skill Based): !DoorMaster_search
Attempts to find any traps on the door (will not set off any traps).
Disarm Traps (Skill Based): !DoorMaster_disarm
Will attempt to disarm a trap, if it has already been discovered.
Reset Traps (GM Only): !DoorMaster_rearm
Re-arms a disarmed trap on a door.
Config (GM Only): !DoorMaster_config
Opens the configuration menu for the door (see: Configuration Menu).

Configuration Menu

The configuration menu allows the GM to adjust any individual setting on a door control token. The menu can be access through the Door menu via the Config button or by issuing the command !DoorMaster_config with a control token selected. Optionally, the GM can simply edit the JSON within the GM Notes field of the control token, but it is recommended to use the menu to avoid errors. The configuration menu options are:

Tools
Link Path:
Link a wall path to the current door controller. The path will be saved, deleted, and recreated (as the script rebuilds the path each time the door token changes).
Set Default:
Save the currently selected door settings as the default settings for this controller. All future door instances created from this controller will use these defaults.
Basic Settings
Option JSON Prop Default Description
Door Type type “wooden” door type descriptor
Blocks Light has_wall true true if the door has a dynamic lighting wall
Broken Status broken false true if the door is broken (open and inoperable)
Hidden Status hidden false true if the door is hidden (secret)
Locked Status locked false true if the door is locked
Opened Status open false true if the door is open, false if closed
Trapped Status trapped false true if the door is trapped (see: Trap Menu)
Difficulty Settings (for skill based interractions)
Option JSON Prop Default Description
Stregth bash_dc 15 difficulty of breaking the door open
Secrecy detect_dc 20 difficulty to detect the door if hidden
Lock lock_dc 15 difficulty of picking the lock

Trap Menu

The trap menu allows the GM to configure the trap on a door control token. The menu can be access through the Configuration Menu via the Trap Settings button or by issuing the command !DoorMaster_trap with a control token selected. Optionally, the GM can simply edit the JSON within the GM Notes field of the control token, but it is recommended to use the menu to avoid errors. The configuration menu options are:

Trap Settings (settings only apply if trapped=true)
Option JSON Prop Default Description
Damage Dice trap.damage “2d6” trap damage (may be a number or dice)
Damage Type trap.dmg_type “acid” trap damage type descriptor
Detect trap.detect_dc 15 difficulty to detect the trap
Disarm trap.disarm_dc 15 difficulty to disarm the trap
Disarmed trap.disarmed false true if disarmed, false if active
Effect trap.effect “burn” trap effect type (from the effects dropdown)
Color trap.color “acid” trap effect color (from the effects dropdown)
Found trap.found false true if the trap is known, false if not
Resets trap.resets false true for a trap that automatically resets itself
Save trap.save_dc 15 difficulty of avoiding the trap effects
Skill trap.save_skill “dexterity_mod” sheet reference of skill check to avoid the trap effects
Target trap.target “char” trap effect target (only “char”) is currently supported
Message trap.message "" trap effect message (when triggered)

Deleting a Door

To delete a door, simply select the door control token (on the GM Layer), and hit the delete key or right click and select "Delete" from the token menu. The script will automatically delete the associated door image token and wall path. Note: in some cases, if there is an error, the script may fail to delete the wall or door. If this happens, just delete them as normal individually.

Changing Dynamic Lighting

TODO

Installation

Installation of the script is simple, just add the script in the API and change any necessary configuration options. However, there are a number of things to do in order to set up door control tokens so that adding the doors is as simple as dropping them on the virtual table. Please read through this section carefully, as proper installation and set up is important for this script to work properly.

To install the script, go to your Game and do the following:

  1. Click on "Settings" and then "API Scripts"
  2. Click "New Script"
  3. Set the name to DoorMaster.js
  4. Cut and Paste the contents of DoorMaster.js to the editor
  5. Click "Save Script"

Script Configuration

There are a number of options that are configurable within the script itself, all of these are near the top of the file within the config object. The options and settings are described below as well as with comments in the JS file. Change these in DoorMaster.js to suit your own game.

Options
These options set some basic functionality for the script, such as distances and system type.

  • interact_range - Distance (in units) for player tokens to interact with the door
  • detect_range - Distance (in units) for passive detection by player tokens
  • wall_color - Default color of paths for dynamic lighting
  • roll_type - System roll type, options are “d20” or “d100”

Character Sheet References
The options for sheet define references to skills or abilities used by the script for challenge rolls (e.g. when a character attempts to pick a lock). By default, these are set for the 5E Roll20 OGL sheet, and may need to be changed if you use a different sheet or system.

  • bash_skill - Reference name for skill or attribute used to bash or break a door
  • lockpick_skill - Reference name for skill or attribute used to pick a lock
  • secret_detect - Reference name for skill or attribute used to detect a secret door (passive)
  • secret_search - Reference name for skill or attribute used to find a secret door (searching)
  • trap_detect - Reference name for skill or attribute used to detect a trap (passive)
  • trap_disarm - Reference name for skill or attribute used to disarm a trap
  • trap_search - Reference name for skill or attribute used to find a trap (searching)

Defaults
The options here reflect the global defaults of the properties described in Configuration Menu and Trap Menu above. These options describe the behavior of a default door, with no customizations.

Messages
These are the output messages used by the script in whispers, emotes, and descriptions. These can be changed to fit your game feel and play-style, with a couple of notes:

  • All [name]_success, [name]_failure, and [name]_noskill messages are emotes, the message should reflect this.
  • search_traps, secret_found, trap_triggered are also emotes.
  • All other messages are used as descriptions and whispers
  • Some messages have variables that will be replaced before output, these may be:
    • [name] - replaced with the character’s name
    • [option 1|option 2|option _n_] - replaced with one of the options, randomly selected

Sides
This option sets the order of images used in Multisided token roll tables. The names must stay the same, but you may re-order them to match how your roll tables are created. The descriptions of each, and the default order are:

  1. control - this is the door control token (only seen by GMs)
  2. closed - door “closed” state image
  3. open - door “open” state image
  4. broken - door “broken” state image

Door Controller Setup

Once the script is installed and configured, you must set up one (or more) Door Controller. This is a character with a specific name which uses a multisided token as it’s default token. It is possible to set up individual defaults on a per-controller basis. This way you can have a controller with defaults and images for wooden doors, as well as a controller for secret doors, with different defaults and images.

  1. Create a new character with the name: DoorControl_[name] where [name] is a unique name.
  2. Create a multisided token (see: Multisided Tokens).
  3. Add the multisided token to the map.
  4. Set the multisided token's "represents character" dropdown to the controller (this should create a door image and dynamic lighting wall on the map).
  5. Set the token as the default token for the controller.
  6. Configure the token to the default settings you want to use for doors made by this controller.
  7. With the token selected, open the configuration menu (!DoorMaster_config) and click "set default".
  8. Delete the door controller token used for setup

If everything is set up correctly, you can drag your controller onto the map and it will create a door controller token on the "GM Layer", as well as a door image token on the "objects" layer, and a dynamic lighting path on the "walls" layer (if the token defaults include dynamic lighting).

Multisided Tokens

Use these instructions to create a rollable table token that can be used as a multisided token. Select a name that represents the door type (e.g. wooden_door), and add the necessary images for each door state. This script uses one rollable table per door type, and the order of images for the door states must match the order in the script configuration (see: Script Configuration: Sides).

All images should be the same size and orientation. The default dynamic lighting wall created by the script expects the door images to be oriented vertically (as if the door opens north/south), and in the center of the image. The images I use are 70x140 (or one square by two squares) to ensure players can click the door image even if half is blocked by dynamic lighting.

By default, the order of images the script expects are:

  1. Door Control Image (this is only seen by the GM and lives on the GM Layer)
  2. Closed Door Image
  3. Open Door Image
  4. Broken Door Image

Help

If you experience any issues while using this script, need help using it, or if you have a suggestion for a new feature, please send me a PM on Roll20:
https://app.roll20.net/users/107167

Roadmap

To-Do

  • Trap Area Effects: Traps only currently affect the character opening the door, I still need to add area effects to traps such as cones or radius.

Potential Future Improvements

  • Key System: I would like to add a working key system so characters can unlock or lock doors that they own keys for. Once I figure out where to store them and how to handle key management (adding, removing, listing, etc.)
  • More than Doors? I realized while coding this, that 90% of the functionality in the script could be used for doors and containers (things like chests, crates, barrels, urns, etc.) I may expand this script to be interracive objects instead of just doors. Functionally, the only real differences between them are linguistic (descriptors) and dynamic lighting.

Version History

v.0.1.0 - released: 2019.01.18

  • Initial Development