ppy/osu-tools

command line tools to get stuff done

osu!tools

Tools for 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.

Requirements

• A desktop platform with the .NET 8.0 SDK installed.
• When working with the codebase, we recommend using an IDE with intelligent code completion and syntax highlighting, such as the latest version of Visual Studio, JetBrains Rider or Visual Studio Code.
• These instructions assume you have the the CLI git client installed, but any other GUI client such as GitKraken will suffice.

Getting Started

I just want to run it

• Clone the repository (git clone https://github.com/ppy/osu-tools)
• Navigate to each tool's directory (i.e. cd PerformanceCalculator) and follow the instructions listed in the tool's README.
  • PerformanceCalculator - A tool for calculating the difficulty of beatmaps and the performance of replays.
  • PerformanceCalculatorGUI - A GUI tool for calculating the difficulty of beatmaps, changes in profile scores and leaderboards.

I want to make changes

Most relevant code is in the main ppy/osu repository. To make any meaningful changes you will likely need to edit that as well.

• Clone all relevant repos into the same directory

git clone https://github.com/ppy/osu-tools
git clone https://github.com/ppy/osu

• Run the ./UseLocalOsu.ps1 powershell script (or ./UseLocalOsu.sh) to use your local copy of ppy/osu

I want to run someone else's changes

• Clone all relevant repos into the same directory

git clone https://github.com/ppy/osu-tools
git clone https://github.com/ppy/osu

• Navigate to osu repository and checkout version you want to run

cd osu
git remote add smoogi https://github.com/smoogipoo/osu.git
git fetch smoogi branch_name
git checkout -b branch_name smoogi/branch_name

• Run the ./UseLocalOsu.ps1 powershell script (or ./UseLocalOsu.sh) to use your local copy of ppy/osu

Contributing

When it comes to contributing to the project, the two main things you can do to help out are reporting issues and submitting pull requests.

Note that while we already have certain standards in place, nothing is set in stone. If you have an issue with the way code is structured, with any libraries we are using, or with any processes involved with contributing, please bring it up. We welcome all feedback so we can make contributing to this project as painless as possible.

For those interested, we love to reward quality contributions via bounties, paid out via PayPal or osu!supporter tags. Don't hesitate to request a bounty for your work on this project.

Licence

osu!'s code, framework, and tools are licensed under the MIT licence. Please see the licence file for more information. tl;dr you can do whatever you want as long as you include the original copyright and license notice in any copy of the software/source.

Please note that this does not cover the usage of the "osu!" or "ppy" branding in any software, resources, advertising or promotion, as this is protected by trademark law.

Please also note that game resources are covered by a separate licence. Please see the ppy/osu-resources repository for clarifications.

osu-tools's Issues

How to use?

when I type
dotnet PerformanceCalculator.dll
into Powershell, it returns with

No executable found matching command "dotnet-PerformanceCalculator.dll"

where do I go from here?

Non-difficulty-adjusting mod combinations are broken

Broke after the recent change: #110 (comment)

Should use a RulesetStore rather than hardcoding ruleset IDs

osu-tools/PerformanceCalculator/ProcessorScoreParser.cs

Line 30 in 310960f

case 0:

This should not be a thing

osu!mania mod multipliers not applied to score

picture
EZ NF HT，The results of these mods are wrong. like this picture, scores need to be recalculated.
fix
This is my change(Is bad Code)

HD mod being ignored in simulate command

Mods list only displays CL and other mods present in the play, but not HD. Values seem to support it being calculated without HD aswell.

2 Examples

Either I am doing something wrong (please excuse this then) or there is an issue with the -m argument maybe?

Max Combo is being processed wrong

I wanted to check pp changes on one my map, but max combo is being shown wrong
https://osu.ppy.sh/beatmapsets/2019978 there is 1025 max combo but perfcalc shows 725 or maybe i'm doing something wrong

(Question) How to search the username with '-' as its first character?

It seems that the program recognizes the username as an option.

Edit: I noticed that this problem can be solved by using uid (6078056 in this example), but what will the situation be if the uid is also registered as a username?

Is it possible to build vinxis' branch?

I'm wondering if it's possible to build VINXIS/osu version of the pp calculations?

Use osu-web APIv2

The profile command currently uses APIv1. This tool should eventually be converted to APIv2 (see: https://docs.ppy.sh) to allow calculation of a larger set of the user's top scores.

.NET core incompatibilies

osu-tools only supports
<TargetFramework>netcoreapp2.0</TargetFramework>
but osu repo which is used by this repo needs <TargetFramework>netstandard2.1</TargetFramework>
which is included only in .NET Core 3.0+
Resulting in this error when trying to run
dotnet run -- simulate osu "C:\Users\Korn\AppData\Local\osu!\Songs\1116349 Ariabl'eyeS - Kegare Naki Bara Juuji\Ariabl'eyeS - Kegare Naki Bara Juuji (Reform) [Anguish].osu " -a 98.96 -m hr -m hd -o whitecatkegare.txt
C:\Users\Korn\osu-tools\PerformanceCalculator\PerformanceCalculator.csproj : error NU1201: Project osu.Game.Rulesets.Catch is not compatible with netcoreapp2.0 (.NETCoreApp,Version=v2.0). Project osu.Game.Rulesets.Catch supports: netstandard2.1 (.NETStandard,Version=v2.1)

Slightly different pp results on Windows vs Linux/macOS

There seems to be some platform differences causing pp calculations to differ between Windows and Linux/macOS systems.

For example Idke's score on https://osu.ppy.sh/b/1201636?m=0 results in ~720pp on Windows, and the expected ~718pp on Linux/macOS.

This is probably an issue with the .NET Core runtime itself and will require further investigation + possibly reporting to the dotnet team.

HD is ignored in simulate command for taiko and catch

#150 fixes HD for std:

But taiko and catch still don't show hidden.

It isn't just visual either, the pp is calculated as if the score didn't have hidden enabled.

Catch errors when calculating an entire folder.

Currently, trying to calculate the difficulty for a folder of .osu files can cause the process to crash halfway through because there's one map throwing an error during calculation. This also happens with the current archive of all ranked/loved/approved .osu files from https://data.ppy.sh/.

Instead, it should continue running with a notice that there was an error with this map.

Invalid json returned for beatmaps with double quotes in beatmap name

Example: dotnet PerformanceCalculator.dll simulate catch ./cache/1113356.osu -j will return a json object which includes a beatmap field with value: "Various Artists - The Seven Deadly Sins Series Maps Compilation (CLSW) [Chapter II. Leviathan, The "Invidia" (Pet Peeve)]"

The difficulty name contains unescaped double quotes. Because of this, the entire json is invalid

Simulate command has inconsistent comma usage

I am getting this response when running the simulate command:

Usage of commas and dots does not make any sense at all. In the pp and accuracy fields the comma is a thousands separator, while in all other fields it's used as a decimal separator. Max combo will never have decimals so it's irrelevant there.

As a sidenote it would be cool if accuracy and accuracy pp could have different labels instead of both being labeled "accuracy".

Lazer mods aren't being passed through to diffcalc

Commands such as dotnet run -- simulate osu 165967 -m BL don't work correctly at the moment, since mods are trimmed by LegacyHelper.

I'm getting around this locally at the moment by removing the relevant method. Smoogi seemed certain that this would break calculation however I can confirm that osu-tools functions just fine without the method? I can PR the linked branch however I really doubt that this is the correct way to solve this.

Memory leak while calculating some mania beatmaps

The beatmap was https://osu.ppy.sh/beatmapsets/331833#mania/745327
I ran dotnet .\PerformanceCalculator.dll difficulty "C:\Users\yinmi\Downloads\331833 Electric Joy Ride & Fusk Asker - Coco\Electric Joy Ride & Fusk Asker - Coco (c36098651) [BPM0].osu" in pwsh and PerformanceCalculator was going to eat all my memory, not stopping. I had to stop it using Ctrl+C.

Profile Calculator Downloads Empty .osu File

I ran the profile command on Mismagius's profile, and I ran into an error after 1 of the maps downloaded. The last map that was downloaded was this map which seems to be an empty .osu file Upon Inspection:

The error that was given was this as a result:

Unhandled Exception: System.Reflection.TargetInvocationException: Exception has been thrown by the target of an invocation. ---> System.IO.IOException: Unknown file format (null)
   at osu.Game.Beatmaps.Formats.Decoder.GetDecoder[T](StreamReader stream) in A:\Users\oykxf\Documents\osu-tools\osu\osu.Game\Beatmaps\Formats\Decoder.cs:line 60
   at PerformanceCalculator.ProcessorWorkingBeatmap.readFromFile(String filename) in A:\Users\oykxf\Documents\osu-tools\PerformanceCalculator\ProcessorWorkingBeatmap.cs:line 44
   at PerformanceCalculator.ProcessorWorkingBeatmap..ctor(String file, Nullable`1 beatmapId) in A:\Users\oykxf\Documents\osu-tools\PerformanceCalculator\ProcessorWorkingBeatmap.cs:line 25
   at PerformanceCalculator.Profile.ProfileCommand.Execute() in A:\Users\oykxf\Documents\osu-tools\PerformanceCalculator\Profile\ProfileCommand.cs:line 63
   at PerformanceCalculator.ProcessorCommand.OnExecute(CommandLineApplication app, IConsole console) in A:\Users\oykxf\Documents\osu-tools\PerformanceCalculator\ProcessorCommand.cs:line 26
   --- End of inner exception stack trace ---
   at System.RuntimeMethodHandle.InvokeMethod(Object target, Object[] arguments, Signature sig, Boolean constructor)
   at System.Reflection.RuntimeMethodInfo.UnsafeInvokeInternal(Object obj, Object[] parameters, Object[] arguments)
   at McMaster.Extensions.CommandLineUtils.Conventions.ExecuteMethodConvention.Invoke(MethodInfo method, Object instance, Object[] arguments) in C:\projects\commandlineutils\src\CommandLineUtils\Conventions\ExecuteMethodConvention.cs:line 86
   at McMaster.Extensions.CommandLineUtils.Conventions.ExecuteMethodConvention.<OnExecute>d__1.MoveNext() in C:\projects\commandlineutils\src\CommandLineUtils\Conventions\ExecuteMethodConvention.cs:line 64
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at McMaster.Extensions.CommandLineUtils.Conventions.ExecuteMethodConvention.<>c__DisplayClass0_0.<<Apply>b__0>d.MoveNext() in C:\projects\commandlineutils\src\CommandLineUtils\Conventions\ExecuteMethodConvention.cs:line 25
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at McMaster.Extensions.CommandLineUtils.CommandLineApplication.<>c__DisplayClass126_0.<OnExecute>b__0() in C:\projects\commandlineutils\src\CommandLineUtils\CommandLineApplication.cs:line 505
   at McMaster.Extensions.CommandLineUtils.CommandLineApplication.Execute[TApp](CommandLineContext context) in C:\projects\commandlineutils\src\CommandLineUtils\CommandLineApplication.Execute.cs:line 31
   at PerformanceCalculator.Program.Main(String[] args) in A:\Users\oykxf\Documents\osu-tools\PerformanceCalculator\Program.cs:line 27

Add buttons that can open the file path directly.

As it shown in the below picture, but I can't make it look good. Can anyone help me? ^_^

Issue with JSON output

I gave a try locally to the simulate tool and ran into a problem while simulating a play on a map (here named map.osu).
The JSON output is incorrect because - I believe - some attributes get overriden by each other.

Here, take a look at the normal command WITHOUT --json flag:

dotnet run --project PerformanceCalculator.csproj --configuration Release -- simulate osu map.osu -m:HD -m:HR -G:5

xi - FREEDOM DiVE (Nakagawa-Kanon) [FOUR DIMENSIONS]
Accuracy       : 99.83190452176837%
Combo          : 2385 (100%)
Great          : 1978
Ok             : 5
Meh            : 0
Miss           : 0
Mods           : HD, HR
Aim            : 282.549316567955
Speed          : 382.89578323239095
Accuracy       : 222.7765006385657
Flashlight     : 0
OD             : 10
AR             : 10
Max Combo      : 2385
pp             : 902.472286786258

We can see that there are two Accuracy values, but as JSON requires key unicity, when I add the --json flag, the output becomes:

dotnet run --project PerformanceCalculator.csproj --configuration Release -- simulate osu map.osu -m:HD -m:HR -G:5 --json

{
  "Beatmap": "xi - FREEDOM DiVE (Nakagawa-Kanon) [FOUR DIMENSIONS]",
  "Accuracy": 222.7765006385657,
  "Combo": 2385.0,
  "Great": 1978.0,
  "Ok": 5.0,
  "Meh": 0.0,
  "Miss": 0.0,
  "Mods": "HD, HR",
  "Aim": 282.549316567955,
  "Speed": 382.89578323239095,
  "Flashlight": 0.0,
  "OD": 10.0,
  "AR": 10.0,
  "Max Combo": 2385.0,
  "pp": 902.472286786258
}

And I feel like the first key Accuracy (99.83190452176837%) got overriden by the second Accuracy key (222.7765006385657) which ends up in an absurd result that is > 100%.

Readme is outdated

Last month the project switched to .NET 6.0 and the only Visual Studio version that supports that is VS 2022. The readme still states .NET 5.0 as a requirement and still refers to "Visual Studio 2017+".