search

Meowhal / osu-ahr

irc bot for osu multi lobby auto host rotation
MIT License
129 stars 36 forks source link
irc-bot osu osu-ahr

readme

osu-ahr

Auto Host Rotation bot for osu! multiplayer.
The host rotation is managed with a queue. Players are added to the queue when joining a multiplayer lobby and are sent to the back of the queue once their beatmap has been played.

Command List

Player Commands

Command Description
!queue Shows host queue.
!skip Triggers vote to skip current host.
!start Triggers vote start the match.
!abort Triggers vote abort the match. Use when the match is stuck.
!update Updates current selected map to the latest version. Use when a host picks an outdated map.
!regulations Shows any current regulations.
!rank Show player rank.

Host Commands

Command Description Example
!skip Transfers host to next player in the queue.
!start [seconds] Starts the match after a set time in seconds. !start 30
!stop Stops active start timer.
!version or !v Show bot version.

Administrator Commands

Command Description Example
*start Forces the match to start.
*skip Forces current host to skip.
*order [players list] Reorders the queue in specified order. *order p1, p2, p3
*keep size [1-16] Keeps the size of the lobby at specified number. *keep size 8
*keep password [password] Keeps the lobby password. *keep password foobar
*keep mode [0-3] [0-3] Keeps the lobby team and score mode. *keep 0 0, *keep HeadToHead Combo
*keep mods [mod] ([mod]) ([mod]) ... Keeps the lobby allowed mods. *keep mods HR DT
*keep title [title] Keeps the lobby title. *keep title 0-2.99* Auto Host Rotate
*no keep size Stops keeping the size of the lobby at specified number.
*no keep password Stops keeping the lobby password.
*no keep mode Stops keeping the team and score mode.
*no keep mod Stops keeping the lobby allowed mods and set mod to FreeMod.
*no keep title Stops keeping the lobby title.
*regulation enable Enable Map Checker
*regulation disable Disable Map Checker.
*no regulation Disable Map Checker.
*regulation min_star [number] Changes the lower star cap. If set to 0, the cap will be removed. *regulation min_star 2
*regulation max_star [number] Changes the upper star cap. *regulation max_star 6
*regulation min_length [sec] Changes the minimum allowed map length. *regulation min_length 60
*regulation max_length [sec] Changes the maximum allowed map length. *regulation max_length 600
*regulation gamemode [osu\|taiko\|fruits\|mania] Changes the gamemode. *regulation gamemode osu
*regulation [name]=[value] [name]=[value]... Changes multiple settings. *regulation min_star=6.00 max_star=6.99 gameode=taiko
*regulation allow_convert Allows conversion of maps for alternate game modes. *regulation allow_convert
*regulation disallow_convert Disallows conversion of maps for alternate game modes. *regulation disallow_convert
*denylist add [username] Blacklists a player. *denylist add bad_guy
*denylist remove [username] Removes a player from blacklist. *denylist remove bad_guy

Note: Administrator commands are also available on the cli and discord bot. Here are examples of Administrator commands using cli and discord:

Cli

#mp_123456 > *keep size 16

Discord

/say *keep size 16

Recent Changes

1.6.1

1.6.0

Setup

  1. Install Node.js and Git
  1. Clone this repo and install libraries
> git clone https://github.com/Meowhal/osu-ahr.git
> cd osu-ahr
> npm install
  1. Create a file ./config/local.json, use ./config/default.json as template.
  2. Get irc password from osu! IRC Authentication
  3. Enter your account ID and irc password to ./config/local.json as in the following example.
{
  "irc": {
    "server": "irc.ppy.sh",
    "nick": "[your account id]",
    "opt": {
      "port": 6667,
      "password": "[your account password]"
    }
  }
}
  1. Configure the bot (Optional). See the Configuration section for details.
  2. Launch the bot
> npm run start
starting up...
Connecting to Osu Bancho ...
Connected :D

=== Welcome to osu-ahr ===

MainMenu Commands
  [make <Lobby_name>] Make a lobby.  e.g. 'make 5* auto host rotation'
  [enter <LobbyID>]   Enter the lobby. e.g. 'enter 123456' (It only works if you are a referee in the lobby).
  [help] Show this message.
  [quit] Quit the application.

> make 5-6* | auto host rotation

Note: You can also run your bot on discord. See the Discord Integration section for details.

Configuration

You can edit local.json to configure the bot's behavior. It is also possible to set values via environment variables. (.env files are also supported.) The format of environment variable name is ahr_[section_name]_[config_name].

IRC Section

local.json

{
  "irc": {
    "server": "irc.ppy.sh",
    "nick": "meowhal",
    "opt": {
      "port": 6667,
      "password": "123456"
    }
  },
...

env

ahr_irc_server="irc.ppy.sh"
ahr_irc_nick=meowhal
ahr_irc_port=6667
ahr_irc_password=123456

Lobby Section

local.json

"Lobby": {
  "authorized_users": ["peppy", "abcedf"], 
  "listref_duration_ms": 1000,
  "info_message": [
    "welcome to ahr lobby!",
    "The second item is displayed on the second line.",
    "Too many lines will result in a silent penalty"
  ],
  "info_message_cooltime_ms": 60000,
  "stat_timeout_ms": 5000,
  "info_message_announcement_interval_ms": 0
}

env

ahr_Lobby_authorized_users='["peppy", "abcedf"]'
listref_duration_ms=1000
info_message='["welcome to ahr lobby!", "The second item is displayed on the second line.","Too many lines will result in a silent penalty"]'

AfkKicker Section

Points are added to players who seem AFK. Any player with points totaling above the threshold will be kicked.

  1. Finishes the match with no score -> add 2 points
  2. Match starts when the player is missing the map -> add 2 points
  3. !stat command shows the player as AFK -> add 3 points
{
  ...
  "AfkKicker": {
    "enabled": true,
    "threshold": 6,
    "cooltime_ms": 30000
  },
  ...
}

AutoHostSelector Section

AutoStartTimer Section

The match start timer will automatically activate after the host selects a map.

HistoryLoader Section

HostSkipper Section

Configs related to host-skip vote and automatic AFK host skip.

LobbyKeeper Section

{
 ...
 "LobbyKeeper": {
    "mode": {"team": 2, "score": 1 },
    "size": 16,
    "title": "4-5 auto host rotation"
  }
  ...
}

"LobbyKeeper": { "mode": {"team": 2, "score": 1 }, "size": 13 }

LobbyTerminator Section

MapChecker Section

MatchStarter Section

!start vote configs

MatchAborter Section

!abort vote and auto abort configs

WordCounter Section

Used to measure the amount of bot messages

OahrCli Section

WebApi Section

Features

Making Lobby

Issue the !mp make command to create a new lobby. Bot manages lobbies via IRC, but only lobbies where you are a referee can be communicated with via IRC.

Entering Lobby

When you restart the bot, it will be able to re-enter the lobby it has already created. The bot will analyze the lobby history and try to restore the order of hosts.

IRC Chat

You can send a chat message to the lobby from the console. Type say followed by the message you want to send.

#mp_10000 > say hello guys!

Auto Host Rotation

When a player enters a room, they are added to the end of the host queue. The player at the front of the queue is the host. If a player who has left the room re-enters, they will be added to the end of the queue. The host queue is rotated immediately after the game starts, so players who join during the game will be added behind the current host. If a host leaves the lobby after selecting a map, the next host can choose to start the game or re-select a map. If the new host starts the game, they will continue to be the host after the game. To check the current queue, type info on the console screen.

#mp_10000 > info
=== lobby status ===
  lobby id : 10000
  status : Entered
  players : 3, inGame : 0 (playing : 0)
  refs : xxxx
  host : player1, pending : null
-- AutoHostSelector --
  current host queue
    palyer1, player2, player3
...

Voting for skipping current host

Typing !skip when you aren't host results in a vote. When half of the lobby has voted, the host will be forcibly skipped. The required percentage of votes can be changed in the config file. If a host skips, it will immediately move to the next person. Hosts that have been AFK can be skipped with this feature.

Starting the match

The game will start automatically when everyone is in the ready state. Please note that the game will not start automatically when everyone is ready as a result of a user leaving the game. A player can vote for the start of the game with !start. The host can start the start timer with !start <time>.

Voting for abort the match

If the game starts and the message "waiting for players" is displayed and the game cannot proceed, the game may be aborted by voting with !abort. If the abort is approved but the map has not been played, the host will not be changed. If the map is changed through the console, the host will be rotated. If a player has finished the map, the game will behave as if it had ended normally.

Closing the lobby

Lobbies created with !mp make will continue to exist until a certain amount of time has passed, even if there are no more players. Since this is a long time, and may cause problems for other users, the lobby will be automatically be closed if no one is in it for a certain period of time. If close now is issued in the console, the !mp close command will be sent and the lobby will be closed immediately.
If a number of seconds is specified as an argument, such as close 30, the lobby will wait until a password is set and for everyone to leave, then the lobby will close after the specified number of seconds has passed. If close is issued, the lobby will be closed after the password is set and everyone has left.

Discord Integration

You can control AHR lobbies via a Discord bot, which allows you to access in-game chat and execute lobby control commands from Discord channels.

Discord Setup

discord.js requires Node.js 16.6 or higher to use, so make sure you're up to date. To check your Node version, use node -v in your terminal or command prompt, and if it's not high enough, update it.

Creating your bot

Setting up a bot application

Follow the link above to create a bot and obtain the token for the bot. The obtained token should be written in ./config/local.json as follows:

{
  "irc": {
    "server": "irc.ppy.sh",
    "nick": "------",
    "opt": {
      "port": 6667,
      "password": "-------",
    }
  },
  "Discord": {
    "token": "THISiSsAMPLEtOKENasdfy.X-hvzA.Ovy4MCQywSkoMRRclStW4xAYK7I"
  }
}

Startup

Start the bot with the following command:

npm run start:discord

After successful activation, a Discord Bot invitation link will appear in the terminal. Click on it to invite it to your guild.

[12:00:00.000][INFO] discord - discord bot is ready.
[12:00:00.100][INFO] discord - invite link => https://discord.com/api/oauth2/authorize?client_id=123&scope=bot+applications.commands&permissions=268435472

[Caution] For security reasons, please do not make this bot a public bot. Any problems that may arise are entirely your responsibility.

Role settings

When a bot is invited to a guild, the ahr-admin role is created. Only users with this role will be able to manage the lobby. You should assign this role to your own account.

Make a new lobby

how to make a lobby

You can make a lobby by executing the /make (lobby name) command in your guild. (You need to have the ahr-admin role to run this command). If the command succeeds, a tournament lobby will be created in OSU multiplayer, and a #matches channel will be created for your guild.

You can make up to four lobbies at the same time, but the bot can only send ten messages every five seconds. It is recommended to keep the number of lobbies to one or two, as each additional lobby increases the delay in sending messages for the bot.

Check match Status

match status panel

The status of each match can be check in the information panel on the "matches" channel. The information panel will be automatically updated as needed.

Transfer ingame chat

You can transfer the in-game chat to your guild's channel by pressing the "Start Transfer" button at the bottom of the information panel. When you press that button, a bridge channel will be created starting with "#mp_", where you can see the in-game chat and some logs.

Join an existing lobby

If the bot has been terminated due to a glitch or some other reason, you can use the /enter command after restarting to resume lobby management. The command requires lobby_id. It is the numerical part of "#mp_12345".

/enter lobby_id:123456

If the guild still has the bridge channel, you can run the /enter command without the lobby_id in the bridge channel.

Chat forwarding

The /say [message] command is used to forward a message to the in-game chat. This command takes the message to be forwarded and the lobby_id as options, but you can omit the lobby_id if you are in a bridge channel. It can also be used to issue tournament commands such as !mp start, and owner commands such as *regulation.

/say message:hello lobby_id:123456
/say message:!mp start 120
/say message:*regulation max_star=8.99

Slash Commands

command desc ex
/make [lobbyName] Make a tournament lobby. /make 4.00-5.99 auto host rotation
/enter (lobbyId) Enter the lobby. /enter or /enter 12345
/say [message] (lobbyId) Send a message. /say hello! or /say !mp start
/info (lobbyId) Shows the status of the lobby. /info or /info 12345
/quit (lobbyId) Quit managing the lobby. /quit or /quit 12345
/close (lobbyId) Close the lobby. /close or /close 12345

Special thanks