Connecting with an IRC Client

Basil runs an IRC gateway alongside the game server, so you can read and write the same chat from any standard IRC program — no needed osu! client running.

This is the same chat the game shows. A message you send from IRC reaches players in the osu! client, and theirs reach you. You can run BasilBot commands such as !mp from here too, which is how most referees run a tournament: an IRC window open, no game client needed.

One account can be logged in on the game and on IRC at the same time. Neither kicks the other off. The one thing an IRC connection cannot do is take a slot in a multiplayer room — you can create a room, referee it, and talk in it, but only the game client can actually play.

Connecting

Setting Value
Server The server's domain or IP — the same address as the game server, with no subdomain.
Port 6667 by default. Ask the server admin if they changed it.
TLS / SSL Off. The gateway speaks plain TCP.
Nickname Your Basil username.
Server password Your Basil account password, in plain text. 
/server basil.local 6667
/pass your-account-password
/nick YourUsername
Most clients (HexChat, mIRC, Irssi, WeeChat, Textual) have a server password field in their connection settings. Fill that in and the client sends PASS for you.
Your password crosses the network unencrypted. There is no TLS on the IRC port, so treat it the way you would any plaintext login: fine on a LAN or over a VPN, riskier over the open internet. If that matters for your deployment, tunnel the port through SSH or a VPN rather than exposing it directly.

Once connected, you are put into the server's default channels automatically, the same ones the game joins you to. Two logins on the same account at once are refused: if you are already connected from another IRC client, the second one is told the nickname is in use.

Your nickname is fixed. It is your account name, and /nick after connecting is refused. This matches osu!'s own IRC gateway.

What you can do

Standard IRC commands. Anything not listed here is answered with "unknown command".

Talking

Command What it does
/join #channel Enters a channel if your account is allowed to read it.
/part #channel Leaves it.
/msg #channel text
/msg Username text		 Says something in a channel, or sends a private message. A message starting with ! runs as a BasilBot command.
/notice target text Same delivery, but never triggers an automatic reply: no BasilBot command runs, and no away message comes back. This is what a bot should use to avoid two bots answering each other forever.
/away [message] Marks you away; no message clears it.
/quit Disconnects.

Looking around

Command What it does
/list Every channel you are allowed to see, with its member count and topic.
/names [#channel] Who is in a channel. No channel given lists them all.
/topic #channel Shows the channel topic.
/mode #channel Shows the channel's modes.
/who #channel
/who Username		 One line per member of a channel, or for a single person.
/whois Username Someone's channels, away message, idle time, and when they signed on.
/ison Nick1 Nick2 Which of those people are online right now. Most clients use this for their notification list.
/motd, /version, /time, /lusers The message of the day, the gateway version, the server's clock, and how many people are online.

What you cannot do

Basil's channels are run by the server, not by their members. /topic #channel new topic, /mode #channel +m, /kick, and /invite are all refused — use BasilBot's !mp commands to manage a match room instead.

/nick, /pass, and /user after connecting are refused too: your identity is fixed at login.

Capability negotiation (CAP) is answered with an empty list, so modern clients connect cleanly — but there is nothing to enable: no SASL, no message tags, no multi-prefix. Log in with the server password instead.

The @ and + next to names

Standing is judged per channel, so the same person can be marked differently in two windows:

Prefix Meaning
@ Whoever runs this channel: a referee inside a match room, a staff member anywhere else.
+ Can talk here.
(none) Can read here, but not talk.

So a referee shows as @ in their own match room and unmarked in a general channel, and a staff member is not an operator of a room they are not refereeing.

Refereeing a match

You do not join a match room from IRC — an IRC connection cannot take a slot, and it is never put into the room's channel. You referee it by pointing your !mp commands at it, from wherever you are: 

/msg BasilBot !mp make Group A: Team Alpha vs Team Beta
→ BasilBot: "Created the match #42 Group A: Team Alpha vs Team Beta. You are now scoped to this
   match, and added as a referee."

/msg BasilBot !mp settings
/msg BasilBot !mp map 111222 && !mp start 30

Creating a room scopes you to it straight away, so everything after that just works. To pick up a different room later — or one someone else made — use !mp in 42 with the id BasilBot reported. You need to already be a referee of that match.

BasilBot answers you privately and repeats the same line into the room, so the players see what you did. To read the players' own chat as well, /join #mp_42 — the channel is named after the id BasilBot reported. You will be in the room's chat without occupying a slot, which is exactly what a referee wants.

A match room's channel is named #mp_ plus the id BasilBot reported (#mp_42 for match #42), and only its referees and its currently seated players can join it or see it in /list. Since you were added as a referee the moment you created or were given the room, joining works for you — anyone else gets "Cannot join channel (no permission)" instead. A room stays hidden from anyone browsing /list with no standing in it, but a direct JOIN attempt against its exact name tells you it exists and simply refuses entry, rather than pretending the room isn't there.

See the BasilBot page for every !mp subcommand.

If something goes wrong

What you see What it means
Password incorrect Wrong password, or no account with that name. The gateway does not say which.
Nickname is already in use That account already has an IRC connection open. A game client logged in at the same time is not the cause.
You have not registered You sent a command before the password and nickname went through.
Cannot send to channel You are not in that channel, or your account may not talk there.
Cannot join channel (no permission) on a #mp_ room You are neither a referee of that match nor currently seated in it.
No such channel on a #mp_ room The match id in the channel name doesn't correspond to any current live room.
Your message vanishes with no error You are silenced, or the person you messaged is offline, has blocked you, or accepts messages from friends only.
A !mp command gets an error reply You are not a referee of the match you are scoped to, or the subcommand is unknown. !mp addref/!mp removeref also fail unless you are the match's creator (see the Referee, Host, and Creator table on the BasilBot page). If you typed the command in a shared channel, the error is DM'd back to you rather than posted there.

Written for people connecting an IRC client. If you are working on the gateway itself, the design notes live in the project's docs/for-developers/irc.md.