mirror of
https://github.com/smogon/pokemon-showdown.git
synced 2026-04-03 07:35:39 -05:00
267 lines
8.9 KiB
Markdown
267 lines
8.9 KiB
Markdown
Pokémon Showdown Command API
|
|
========================================================================
|
|
|
|
Defining a Command
|
|
------------------------------------------------------------------------
|
|
|
|
You can define the commands such as 'whois', then use them by typing
|
|
`/whois` into Pokémon Showdown.
|
|
|
|
A command can be in the form:
|
|
|
|
ip: 'whois',
|
|
|
|
This is called an alias: it makes it so `/ip` does the same thing as
|
|
`/whois`.
|
|
|
|
But to actually define a command, it's a function:
|
|
|
|
avatars(target, room, user) {
|
|
if (!this.runBroadcast()) return;
|
|
this.sendReplyBox('You can <button name="avatars">change ' +
|
|
'your avatar</button> by clicking on it in the <button ' +
|
|
'name="openOptions"><i class="icon-cog"></i> Options' +
|
|
'</button> menu in the upper right. Custom avatars are ' +
|
|
'only obtainable by staff.');
|
|
}
|
|
|
|
|
|
Parameters
|
|
------------------------------------------------------------------------
|
|
|
|
Commands are actually passed five parameters:
|
|
|
|
function (target, room, user, connection, cmd, message)
|
|
|
|
Most of the time, you only need the first three, though.
|
|
|
|
- `target` = the part of the message after the command
|
|
- `room` = the room object the message was sent to
|
|
(The room name is `room.roomid`)
|
|
- `user` = the user object that sent the message
|
|
(The user's name is `user.name`)
|
|
- `connection` = the connection that the message was sent from
|
|
- `cmd` = the name of the command
|
|
- `message` = the entire message sent by the user
|
|
|
|
For instance, if a user types in `/msg zarel, hello`,
|
|
|
|
`target` = `"zarel, hello"`
|
|
`cmd` = `"msg"`
|
|
`message` = `"/msg zarel, hello"`
|
|
|
|
Commands return the message the user should say. If they don't
|
|
return anything or return something falsy, the user won't say
|
|
anything.
|
|
|
|
|
|
Help Entries
|
|
------------------------------------------------------------------------
|
|
|
|
A `/help` entry can be added for a command by adding a command in the
|
|
form `<command>help: ["<help text>"],`, where `<command>` is the primary function
|
|
name, followed by an array or function.
|
|
|
|
If the help entry is an array, each element of the array will be sent as a
|
|
new line. If the help entry is a function, the help command will execute
|
|
that function.
|
|
|
|
As an example:
|
|
|
|
ip: 'whois',
|
|
rooms: 'whois',
|
|
whois(target, room, user, connection, cmd) {
|
|
<function body>
|
|
},
|
|
whoishelp:["/whois - Get details on yourself: alts, group, IP address,
|
|
and rooms.",
|
|
"/whois [username] - Get details on a username: group and rooms."],
|
|
|
|
`/help whois` will send the information in `whoishelp`.
|
|
|
|
|
|
Functions
|
|
------------------------------------------------------------------------
|
|
|
|
Commands have access to the following functions:
|
|
|
|
`this.sendReply(message)`
|
|
* Sends a message back to the room the user typed the command into.
|
|
|
|
`this.sendReplyBox(html)`
|
|
* Same as sendReply, but shows it in a box, and you can put HTML in it.
|
|
|
|
`this.popupReply(message)`
|
|
* Shows a popup in the window the user typed the command into.
|
|
|
|
`this.add(message)`
|
|
* Adds a message to the room so that everyone can see it.
|
|
This is like `this.sendReply`, except everyone in the room gets it,
|
|
instead of just the user that typed the command.
|
|
|
|
`this.send(message)`
|
|
* Sends a message to the room so that everyone can see it.
|
|
This is like `this.add`, except it's not logged, and users who join the
|
|
room later won't see it in the log, and if it's a battle, it won't show
|
|
up in saved replays.
|
|
You USUALLY want to use `this.add` instead.
|
|
|
|
`this.roomlog(message)`
|
|
* Log a message to the room's log without sending it to anyone. This is
|
|
like `this.add`, except no one will see it.
|
|
|
|
`this.addModAction(message)`
|
|
* Like this.add, except it logs the message as being sent as the user who used the command.
|
|
This does not log anything into the modlog
|
|
|
|
`this.modlog(action, user, note, options)`
|
|
* Adds a log line into the room's modlog, similar to `this.globalModlog`.
|
|
The arguments `user` (the targeted user), `note` (details), and `options` (no ip, no alts) are optional.
|
|
|
|
`this.checkCan(permission)`
|
|
`this.checkCan(permission, targetUser)`
|
|
* Checks if the user has the permission to do something, or if a
|
|
targetUser is passed, check if the user has permission to do it to that
|
|
user. Will automatically give the user an "Access denied" message, and stop the command there, if
|
|
the user doesn't have permission: use `user.can()` if you don't want that
|
|
message.
|
|
|
|
Should usually be near the top of the command, like:
|
|
|
|
this.checkCan('potd');
|
|
|
|
`this.runBroadcast()`
|
|
* Signifies that a message can be broadcast, as long as the user has
|
|
permission to. This will check to see if the user used `!command`
|
|
instead of `/command`. If so, it will check to see if the user has
|
|
permission to broadcast (by default, voice+ can), and return `false` if
|
|
not. Otherwise, it will add the message to the room, and turn on the
|
|
flag `this.broadcasting`, so that `this.sendReply` and `this.sendReplyBox`
|
|
will broadcast to the room instead of just the user that used the
|
|
command.
|
|
|
|
Should usually be near the top of the command, like:
|
|
|
|
this.checkBroadcast();
|
|
|
|
`this.runBroadcast(suppressMessage)`
|
|
* Functionally the same as `this.canBroadcast()`. However, it will look as
|
|
if the user had written the text `suppressMessage`.
|
|
|
|
`this.checkChat()`
|
|
* Checks to see if the user can speak in the room. Returns false if the
|
|
user can't speak (is muted, the room has modchat on, etc), or true
|
|
otherwise.
|
|
|
|
Should usually be near the top of the command, like:
|
|
|
|
this.checkChat();
|
|
|
|
`this.checkChat(message, room)`
|
|
* Checks to see if the user can say the message in the room.
|
|
If a room is not specified, it will default to the current one.
|
|
If it has a falsy value, the check won't be attached to any room.
|
|
In addition to running the checks from `this.checkChat()`, it also checks
|
|
to see if the message has any banned words, is too long, or was just
|
|
sent by the user. Returns the filtered message, or a falsy value if the
|
|
user can't speak.
|
|
|
|
Should usually be near the top of the command, like:
|
|
|
|
target = this.checkChat(target);
|
|
if (!target) return false;
|
|
|
|
`this.parse(message, inNamespace)`
|
|
* Runs the message as if the user had typed it in.
|
|
|
|
Mostly useful for giving help messages, like for commands that require
|
|
a target:
|
|
|
|
if (!target) return this.parse('/help msg');
|
|
|
|
If `inNamespace` is true, then the message is parsed in that
|
|
corresponding namespace:
|
|
|
|
// command msg is in namespace test. (ie. /test msg)
|
|
this.parse('/help', true); // is parsed as if the user said
|
|
// '/test help'
|
|
|
|
After 10 levels of recursion (calling `this.parse` from a command called
|
|
by `this.parse` from a command called by `this.parse` etc) we will assume
|
|
it's a bug in your command and error out.
|
|
|
|
`this.targetUserOrSelf(target, exactName)`
|
|
* If `target` is blank, returns the user that sent the message.
|
|
Otherwise, returns the user with the username in target, or a falsy
|
|
value if no user with that username exists.
|
|
By default, this will track users across name changes. However, if
|
|
`exactName` is true, it will enforce exact matches.
|
|
|
|
`this.splitTarget(target, exactName)`
|
|
* Splits a target in the form `<user>, <message>` into its constituent parts.
|
|
Returns `<message>`, and sets `this.targetUser` to the user, and
|
|
`this.targetUsername` to the username.
|
|
|
|
If a user doesn't exist (because they are offline or otherwise),
|
|
`this.targetUser` will be falsy but `this.targetUsername` will still exist.
|
|
If `this.targetUser` exists, this.targetUsername will have the same
|
|
capitalization as the user's username, otherwise the capitalization
|
|
will be however it was passed into the function.
|
|
|
|
By default, this will track users across name changes. However, if
|
|
`exactName` is true, it will enforce exact matches.
|
|
|
|
Remember to check if `this.targetUser` exists before going further.
|
|
|
|
Unless otherwise specified, these functions will return undefined, so you
|
|
can `return this.sendReply` or something to send a reply and stop the command
|
|
there.
|
|
|
|
|
|
Namespace Commands
|
|
------------------------------------------------------------------------
|
|
|
|
A command can also be an object, in which case is treated like
|
|
a namespace:
|
|
|
|
game: {
|
|
play(target, room, user) {
|
|
user.isPlaying = true;
|
|
this.sendReply("Playing.");
|
|
},
|
|
stop(target, room, user) {
|
|
user.isPlaying = false;
|
|
this.sendReply("Stopped.");
|
|
}
|
|
}
|
|
|
|
These commands can be called by `/game play` and `/game stop`.
|
|
|
|
Namespaces help organise commands, and nest them under
|
|
one main command.
|
|
|
|
Note: Multiple namespaces can be nested, but the final (innermost)
|
|
command must be a function.
|
|
|
|
Namespace objects can have help entries and so can the internal
|
|
commands:
|
|
|
|
game: {
|
|
play(target, room, user) {
|
|
user.isPlaying = true;
|
|
this.sendReply("Playing.");
|
|
},
|
|
playhelp: ["Tells you if the user is playing."],
|
|
stop(target, room, user) {
|
|
user.isPlaying = false;
|
|
this.sendReply("Stopped.");
|
|
},
|
|
stophelp: ["Tells you if the user has stopped playing."]
|
|
},
|
|
gamehelp: ["commands for /game are:",
|
|
"/game play - Tells you if the user is playing.",
|
|
"/game stop - Tells you if the user stopped playing."]
|
|
|
|
The help entries are accessed with `/help game play` and `/help game`
|
|
respectively.
|