An extensible MUSH / MUD server written in Java.
The Grounds API is a limited interface for plugins to use in order to interact with the universe beyond their results.
Like calls to plugins themselves, API calls to Grounds are also conducted using JSON RPC. A plugin opens a connection to the Unix domain socket that Grounds listens on and writes a JSON RPC request to it, and receives a JSON RPC response from it. API calls are synchronous.
By default, the API domain socket is at /tmp/groundsapi.sock, but it may be configured to a different location.
The total size of an API request may not exceed 4096 bytes.
The request method defines which API method to run.
The request ID is a random value. The JSON RPC response returned by Grounds must use the matching ID to be valid.
The request params is a JSON object with fields that depend on the API method being run. The following additional fields are supported.
| Name | Type | Purpose |
|---|---|---|
| _plugin_call_id | string | (required) Unique identifier for the current plugin call |
| _as_extension | bool | true to run as the plugin's extension |
When a plugin calls back to the Grounds API, it has to supply its plugin call ID so that Grounds can retrieve that context and satisfy the API call. Without this param, Grounds rejects the call.
By default, API methods run on behalf of the player who called the plugin (which is in turn calling the API). If the _as_extension parameter is set to true, and a method supports it, then the method is instead run on behalf of the extension where the plugin command or listener attribute is defined. Use this mechanism to allow a plugin to perform tasks that a player cannot otherwise do, such as manipulate attributes on the extension.
If the API call is considered successful, Grounds provides a result and no error. The type of the result depends on the method that was run.
If the API call is considered a failure, then Grounds provides an error and no result. The error contains an error code and a message, but no data.
In these method descriptions, the “caller” is the player who executed the plugin command which is in turn calling the Grounds API. If a method indicates that it can run as an extension, then the caller is instead the extension where the plugin command resides.
Executes the given command line, as if the caller had entered it into their own shell. This is the primary means for plugins to work with the game universe.
Under the hood, Grounds executes only one command at a time. Commands run using exec are run as part of their encompassing plugin command, so a plugin does not need to wait for results, and no other commands will interfere. However, a plugin should not spend too long executing commands, so that the server can respond to commands from other players.
| params | ||
|---|---|---|
| commandLine | array of string | (required) command line to execute |
| may be run as an extension | ||
| result | ||
| string form of the command result | ||
| error codes | ||
| -32602 | a required param is missing, or a param is the wrong type | |
| -32603 | command line execution failed | |
Gets an attribute with the given name from the referenced thing.
See the attributes documentation for the attribute JSON definition.
| params | ||
|---|---|---|
| thingId | string | (required) thing ID |
| name | string | (required) attribute name |
| may be run as an extension | ||
| result | ||
| attribute JSON | ||
| error codes | ||
| -32004 | the attribute is not found | |
| -32602 | a required param is missing, or a param is the wrong type | |
| -32603 | getting the attribute failed | |
Lists the names of all attributes of the referenced thing.
| params | ||
|---|---|---|
| thingId | string | (required) thing ID |
| may be run as an extension | ||
| result | ||
| attribute names as an array of strings | ||
| error codes | ||
| -32602 | a required param is missing, or a param is the wrong type | |
| -32603 | getting the attribute names failed | |
Gets the name of the plugin caller.
| params | ||
|---|---|---|
| may *not* be run as an extension | ||
| result | ||
| caller name as a string | ||
| error codes | ||
| none |
Gets the timezone of the plugin caller, if their actor has set one. If the caller has no actor, or the actor has not set a timezone, returns “UTC”.
| params | ||
|---|---|---|
| may *not* be run as an extension | ||
| result | ||
| caller timezone as a string | ||
| error codes | ||
| none |
Lists the roles of the referenced player. Either the player’s ID or name must be supplied.
Remember that the GOD player has no roles, but a plugin should allow GOD to do anything.
| params | ||
|---|---|---|
| thingId | string | player ID |
| playerName | string | player name |
| may be run as an extension | ||
| result | ||
| roles as an array of strings | ||
| error codes | ||
| -32004 | the player is not found | |
| -32602 | a required param is missing, or a param is the wrong type | |
| -32603 | getting the roles failed | |
Removes an attribute with the given name from the referenced thing.
| params | ||
|---|---|---|
| thingId | string | (required) thing ID |
| name | string | (required) attribute name |
| may be run as an extension | ||
| result | ||
| empty string | ||
| error codes | ||
| -32602 | a required param is missing, or a param is the wrong type | |
| -32603 | getting the attribute failed | |
Sends the given message from the caller to the named player.
A message can take one of three forms, and exactly one of the forms must be provided. The simplest is an ordinary message string, supplied with message.
To format the message as a set of key-value pairs, pass JSON under the recordparam. Here is an example of how the JSON must be formatted.
{
"keys": ["key1", "key2", "key3"],
"values": ["value1", "value2", "value3"]
}
If a key is empty, then its value is printed alone.
To format the message as a table, pass JSON under the table param. Here is an example of how the JSON must be formatted. The format strings in column definitions are Java format strings.
{
"columns": [
[
"column1 string",
"%s"
],
[
"column2 with special formatting for row values",
"%s",
"%40s"
]
],
"rows": [
[
"row1",
"42"
],
[
"row2",
"43"
],
[
"row3",
"44"
]
]
}
Markup is supported for the following message pieces:
message is usedrecord is usedtable is used| params | ||
|---|---|---|
| playerName | string | (required) player to send message to |
| message | string | plain message string (may use markup) |
| record | string | record JSON to use as message |
| table | string | table JSON to use as message |
| header | string | header line to emit before message (may use markup) |
| may be run as an extension | ||
| result | ||
| empty string | ||
| error codes | ||
| -32602 | a required param is missing, or a param is the wrong type, or if record or table JSON is invalid | |
Sends the given message from the caller to the caller. See sendMessage for details about how to specify a message.
| params | ||
|---|---|---|
| message | string | plain message string (may use markup) |
| record | string | record JSON to use as message |
| table | string | table JSON to use as message |
| header | string | header line to emit before message (may use markup) |
| may be run as an extension | ||
| result | ||
| empty string | ||
| error codes | ||
| -32602 | a required param is missing, or a param is the wrong type, or if record or table JSON is invalid | |
Sets an attribute with the given name from the referenced thing.
See the attributes documentation for the list of valid types and, for each type, how its value should be represented as a string.
| params | ||
|---|---|---|
| thingId | string | (required) thing ID |
| name | string | (required) attribute name |
| value | string | (required) attribute value |
| type | string | (required) attribute type |
| may be run as an extension | ||
| result | ||
| empty string | ||
| error codes | ||
| -32602 | a required param is missing, or a param is the wrong type | |
| -32603 | getting the attribute failed | |