Character Vault
Any Concept / Any System
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Script:Command Shell"

From Roll20 Wiki

Jump to: navigation, search
(Update for v1.1)
Line 77: Line 77:
=== Changelog ===
=== Changelog ===
{{changelog version|1.0|2015-01-07|* Release}}
{{changelog version|1.1|2015-05-31|* Fix argument parsing when final token is quoted}}
{{changelog version|1.0|2015-01-07|* Initial release}}

Revision as of 11:20, 31 May 2015

API ScriptAuthor: manveti
Version: 1.0
Last Modified: 2015-01-07
Code: CommandShell
Dependencies: None
Conflicts: None

CommandShell is a framework for chat commands, intended to ease their processing and avoid command name collisions. CommandShell provides a central system for registering commands and marshalling chat commands to the appropriate callback, POSIX-style argument parsing, access control, and simple output functions.

It is recommended that this script be used in conjunction with the IsGM Auth Module, which will improve detection of messages coming from the GM. In the absence of that module, a player will only be detected as GM when sending chat as their player name (i.e. not speaking as a character).



By default, commands may only be executed by a GM. The !shell-permission command is provided to set permissions to allow or deny execution by other players, while the !help command may be used to list all available commands. By default, the !help command has world-execute permission, but that permission can be revoked like any other command.

!shell-permission <action> <command name> [player]


→ !shell-permission action


→ !help


→ add


→ remove




→ ε


Parameter Values
action Valid values are add and remove. This will add or remove permission for a specified player (or all players, if no player is specified) to use the given command. World-execute permission is stored separately from player-specific permission, so if world-execute permision is revoked, any player-specific permissions will remain.
command name The name of the command to alter permissions for. The command given must be registered to the shell. (See below)
player Optional. If set, the permission for the given player will be added or removed for the given command. If omitted, world-execute permission will be changed instead.

Registering Commands

Each usable command in a script needs to be registered in code somewhere. Commands may also be unregistered.

Registered commands can be executed by name (e.g. !mycommand). If a user attempts to execute a command for which they lack permission, they will receive an error message and execution will fail.

Shell.registerCommand(command, signature, description, callback)


The command name. Multiple commands of the same name may not be registered. Scripts may include or omit the leading exclamation mark; the shell will handle its requirement automatically.
Example syntax of the command (e.g. "!mycommand [some arguments]"). This will be used in the automatically-generated help output.
A more detailed description of the command and how to use it. This will be used in the automatically-generated help output.
The function which will be called whenever the command is invoked by a user with appropriate permission. The function should accept an array of the command arguments (e.g. ["!mycommand", "foo", "bar"]) and the original chat message object.

Utility Functions

Several utility functions are also made available by the shell.

Shell.write(message[, to[, style[, from]]])
Shell.rawWrite(message[, to[, style[, from]]])
Shell.writeAndLog(message[, to])
  • write sends message to the chat, preserving whitespace and angle brackets.
  • rawWrite sends message to the chat without preserving any special characters. Useful for writing HTML directly to the chat.
  • writeAndLog is equivalent to write while additionally logging message to the console.
  • writeErr is equivalent to writeAndLog(message, 'gm')
  • tokenize splits the given string around whitespace; quotes within the message may be used to preserve the whitespace. Useful for splitting an input message into command arguments.


A message to output or parse
Player or character to send message to. If not specified, the message will be visible to everyone.
Inline CSS to include in the <div> that wraps the message.
Used as first argument to sendChat. If not specified, the name "Shell" will be used instead.


v1.1 (2015-05-31)

  • Fix argument parsing when final token is quoted

v1.0 (2015-01-07)

  • Initial release