osu!performance

This is the program computing "performance points" (pp), which are used as the official player ranking metric in osu!.

Current Versions

This is part of a group of projects which are used in live deployments where the deployed version is critical to producing correct results. The master branch tracks ongoing developments. If looking to use the correct version for matching live values, please consult this wiki page for the latest information.

Compiling

All that is required for building osu!performance is a C++11-compatible compiler. Begin by cloning this repository and all its submodules using the following command:

$ git clone --recursive https://github.com/ppy/osu-performance

If you accidentally omitted the --recursive flag when cloning this repository you can initialize the submodules like so:

$ git submodule update --init --recursive

osu!performance runs on Windows, macOS, and Linux. The build environment is set up using CMake as follows.

Windows

Open the command line and navigate to the root folder of this repository.

osu-performance> mkdir build
osu-performance> cd build
osu-performance\build> cmake ..

Now the build folder should contain a Visual Studio project for building the program. Visual Studio 2017 and a 64-bit build are recommended (cmake -G "Visual Studio 15 2017 Win64" ..).

macOS / Linux

On macOS / Linux you need to install the MariaDB MySQL connector and cURL packages. Afterwards, in a terminal of your choice, do

osu-performance$ mkdir build
osu-performance$ cd build
osu-performance/build$ cmake ..
osu-performance/build$ make -j

Sample Data

Database dumps with sample data can be found at https://data.ppy.sh. This data includes the top 10,000 users along with a random 10,000 user sample across all users, along with all required auxiliary tables to test this system. Please note that this data is released for development purposes only (full licence details available here).

You can import these dumps to mysql (after first extracting them) by running cat *.sql | mysql. Note that all existing data in tables will be dropped and replaced. Make sure to import the latest available data dumps as older snapshots may be incompatible with the latest version of osu!performance.

Usage

First, set up a MySQL server and import the provided data from above which is most relevant to your use case. Next, edit bin/config.json with your favourite text editor and configure mysql.master to point to your MySQL server.

After compilation, an executable named osu-performance is placed in the bin folder. You can use it via the command line as follows:

./osu-performance COMMAND {OPTIONS}

where command controls which scores are the target of the computation. The following commands are valid:

• all: Compute pp of all users
• new: Continually poll for new scores and compute pp of these
• scores: Compute pp of specific scores
• users: Compute pp of specific users
• sql: Compute pp of users given by a SQL select statement

The gamemode to compute pp for can be selected via the -m option, which may take the value osu, taiko, catch, or mania.

Information about further options can be queried via

./osu-performance -h

and further options specific to the chosen command can be queried via

./osu-performance COMMAND -h

Configuration options beyond these parameters, such as various API hooks, can be adjusted in bin/config.json.

Docker

osu!performance can also be run in Docker.

Configuration is provided via environment variables or by mounting the config file at /srv/config.json.
Availables environment variables:

MYSQL_HOST
MYSQL_PORT
MYSQL_USER
MYSQL_PASSWORD
MYSQL_DATABASE

MYSQL_SLAVE_HOST
MYSQL_SLAVE_PORT
MYSQL_SLAVE_USER
MYSQL_SLAVE_PASSWORD
MYSQL_SLAVE_DATABASE

MYSQL_USER_PP_TABLE_NAME
MYSQL_USER_METADATA_TABLE_NAME

WRITE_ALL_PP
WRITE_USER_TOTALS

POLL_INTERVAL_DIFFICULTIES
POLL_INTERVAL_SCORES

SENTRY_HOST
SENTRY_PROJECTID
SENTRY_PUBLICKEY
SENTRY_PRIVATEKEY

DATADOG_HOST
DATADOG_PORT

Example:

docker build -t osu-performance .
docker run --rm -it \        
  -e MYSQL_HOST=172.17.0.1 \
  -e MYSQL_USER=osu \
  -e MYSQL_PASSWORD=changeme \
  -e MYSQL_DATABASE=osu \
  osu-performance all -m osu

A docker-compose.yml file is also provided, with a built-in MySQL and phpMyAdmin server provided for convenience.
It supports having *.sql files in a dump folder, such as those found at https://data.ppy.sh, for import at first start.

Licence

osu!performance is licensed under AGPL version 3 or later. Please see the licence file for more information. tl;dr if you want to use any code, design or artwork from this project, attribute it and make your project open source under the same licence.

Note that the sample data is covered by a separate licence.