Create a gist now

Instantly share code, notes, and snippets.

What would you like to do?

IRC Roleplay Commands

Daniel Oaks daniel@danieloaks.net


Introduction

People like to use IRC to roleplay. In other words, to act out characters as part of a channel and between clients. Often, this means it's desirable to send messages with names other than the client's nickname, and to send messages not explicitly attached to a name at all.

There are a standard set of commands for this purpose from and based off falerin's Farpoint IRC project. Some IRCds have implemented these commands either natively or through community modules, so here we document how they work today (with some very useful extensions) to simplify adoption.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.


Roleplaying Modes

The primary purpose of these commands is to essentially impersonate other nicknames. Because of that, these commands MUST only be allowed when joined to a channel with the roleplaying mode enabled, or when the recipient has allowed these messages to be sent to them.

Roleplaying User Flag

The recommended mode letter for this is "+E".

If a user has roleplaying mode enabled, they will be able to accept roleplaying commands. Otherwise, the sender will be notified that they cannot send the message successfully.

The RPUSER RPL_ISUPPORT parameter advertises which mode letter is used for the roleplaying user mode.

  Format: RPUSER=<letter>

Example:

  RPUSER=E

Roleplaying Channel Flag

The recommended mode letters for this are "+E" and "+N". It is a type D mode, which means a flag without any arguments.

If a channel has this flag enabled, it will be able to accept roleplaying commands. Otherwise, the sender will be notified that they cannot send the message successfully.

The RPCHAN RPL_ISUPPORT parameter advertises which mode letter is used for the roleplaying channel flag.

  Format: RPCHAN=<letter>

Examples:

  RPCHAN=E

  RPCHAN=N

Commands

These commands are relatively widely implemented across implementations of the IRC roleplaying commands. There are also others that exist such as NARRATOR and NARRATORA, but they are not yet described here.

SCENE message

     Command: SCENE
  Parameters: <target> <text to be sent>

The SCENE command is used to send a scene notification. The text is sent to <target> as a PRIVMSG, with the following source details:

  • <nickname>: "=Scene="
  • <username>: Nickname of the user who send the command.
  • <hostname>: "npc.fakeuser.invalid"

The spoofed nickname may differ from that above, but it MUST NOT be a valid nickname on the network.

In addition, the text should also be appended with the original client's nickname to alert users as to who posted the message. For example:

  "<original text to be sent> (<source nick>)"

If the target does not have roleplaying mode enabled, ERR_CANNOTSENDRP MUST be sent to the sender and the message MUST NOT be relayed to the target.

Example from client Dan!~d@example.com:

  C:  SCENE #test :The leaves outside rustle in the wind
  S:  :=Scene=!Dan@npc.fakeuser.invalid PRIVMSG #test :The leaves outside rustle in the wind (Dan)

AMBIANCE message

     Command: AMBIANCE
  Parameters: <target> <text to be sent>

The AMBIANCE command is an alias for the SCENE command, to improve backwards compatibility.

NPC message

     Command: NPC
  Parameters: <target> <sourcenick> <text to be sent>

The NPC command is used to send a message to the target as the source. The text is sent to <target> as a PRIVMSG, with the following source details:

  • <nickname>: <sourcenick>
  • <username>: Nickname of the user who send the command.
  • <hostname>: "npc.fakeuser.invalid"

In addition, the text should also be appended with the original client's nickname to alert users as to who posted the message. For example:

  "<original text to be sent> (<source nick>)"

If <sourcenick> contains characters that cannot be in a nickname, either those characters MUST be stripped or the message MUST be rejected with ERR_CANNOTSENDRP. When being sent, the server MUST insert at least one character into <nickname> that cannot be contained in a real client nickname. This is to prevent collisions with real client nicks.

If the target does not have roleplaying mode enabled, ERR_CANNOTSENDRP MUST be sent to the sender and the message MUST NOT be relayed to the target.

Example from client Dan!~d@example.com:

  C:  NPC #test CoolPerson :"Hi!"
  S:  :*CoolPerson*!Dan@npc.fakeuser.invalid PRIVMSG #test :"Hi!" (Dan)

  C:  NPC #test CoolPerson@asdf :"Hi!"
  S:  :irc.example.com 573 Dan #test :Roleplay nick cannot contain !, @, * or ?

NPCA message

     Command: NPCA
  Parameters: <target> <sourcenick> <text to be sent>

The NPCA command is used to send a message to the target as the source. The text is sent to <target> as a CTCP ACTION, with the following source details:

  • <nickname>: <sourcenick>
  • <username>: Nickname of the user who send the command.
  • <hostname>: "npc.fakeuser.invalid"

In addition, the text should also be appended with the original client's nickname to alert users as to who posted the message. For example:

  "<original text to be sent> (<source nick>)"

If <sourcenick> contains characters that cannot be in a nickname, either those characters MUST be stripped or the message MUST be rejected with ERR_CANNOTSENDRP. When being sent, the server MUST insert at least one character into <nickname> that cannot be contained in a real client nickname. This is to prevent collisions with real client nicks.

If the target does not have roleplaying mode enabled, ERR_CANNOTSENDRP MUST be sent to the sender and the message MUST NOT be relayed to the target.

Example from client Dan!~d@example.com:

  C:  NPC #test CoolPerson :is pretty cool
  S:  :*CoolPerson*!Dan@npc.fakeuser.invalid PRIVMSG #test :\001ACTION is pretty cool (Dan)\001

  C:  NPC #test CoolPerson@asdf :is pretty cool
  S:  :irc.example.com 573 Dan #test :Roleplay nick cannot contain !, @, * or ?

Numerics

The following numeric(s) are used in roleplaying commands.

ERR_CANNOTSENDRP (573)

  "<client> <target> :<info>"

Indicates that a message could not be sent to the target because the target has not enabled the roleplay flag, or because of another issue specifically related to how the roleplay commands operate.

It should be noted that if a more appropriate or specific numeric such as ERR_NOTONCHANNEL or ERR_NOSUCHCHANNEL exists, that should be used instead of this very general error.


Acknowledgements

Thanks to Naram Qashat (CyberBotX) for his assistance and suggestions with this document and InspIRCd implementation. Falerin Ardendor for creating the Farpoint IRC project, which I believe these commands originated from. As well, Namegduf, KeiroD, and the Charybdis authors for their various implementations of these commands.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment