server/chat-plugins/COMMANDS.md

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 six 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) {
		<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`.


Plines
------------------------------------------------------------------------

A lot of the functions refering "plines". A pline is a protocol line,
documented in [PROTOCOL.md][https://github.com/smogon/pokemon-showdown/blob/master/PROTOCOL.md]

Plines are the ones that usually start with `|MESSAGETYPE|`, but a pline
that doesn't start with `|` will be shown as text directly to the user.

Note that currently, most plines starting with `|` break horribly when
sent in PMs, so please be careful about that.


Functions
------------------------------------------------------------------------

Commands have access to the following functions:

`this.sendReply(pline)`
*	Sends a pline to the room/PM 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(pline)`
*	Adds a pline to the room so that everyone can see it.
	This is like `this.sendReply`, except everyone in the room sees it,
	instead of just the user that typed the command.

`this.send(pline)`
*	Sends a pline 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(pline)`
*	Log a pline 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`, but the message is treated like a chat message from the
	user who used the command (notifying and potentially highlighting other
	users). 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.getUserOrSelf(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.splitUser(target, exactName)`
*	Splits a target in the form `<user>, <rest>` into its constituent parts;
	returning
	`{targetUser: User | null, targetUsername: string, inputUsername: string, rest: string}`.
	`inputUsername` will be exactly `<user>` and `rest` will be `<rest>`.

	If a user doesn't exist (because they are offline or otherwise),
	`targetUser` will be null but `targetUsername` will be `inputUsername`.
	If `targetUser` exists, `targetUsername` will be `targetUser.name`
	(fixing capitalization and following name changes if applicable).

	By default, this will track users across name changes. However, if
	`exactName` is true, it will enforce exact matches.

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.");
		},
	},
	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. If help for `/help game stop` doesn't exist, it will show
help for `/help game` instead.