Performance API

The public calculation API build a Beatmap, then compute difficulty or performance.

Builders

Public calculation API: the Beatmap, Difficulty and Performance builders.

exception parsecore.Performance.api.RulesetNotImplementedError(mode, stage)

Bases: NotImplementedError

Raised when a ruleset does not implement the requested calculation stage.

Parameters:

• mode (GameMode)

• stage (str)

Return type:

None

class parsecore.Performance.api.Beatmap(pm)

Bases: object

A beatmap prepared for calculation, wrapping a parsed map.

Create one with from_path() or from_user_beatmap(), then pass it to Difficulty or Performance.

Parameters:

pm (PerformanceBeatmap)

classmethod from_path(path)

Load and prepare a beatmap from a .osu file.

Parameters:

path (str) – Path to the .osu file.

Return type:

Beatmap

Returns:

The prepared beatmap in its native mode.

classmethod from_user_beatmap(user_beatmap, override_mode=None)

Prepare a beatmap from an already-parsed map, optionally converting it.

Parameters:

• user_beatmap (Any) – A parsed parsecore.Beatmap.beatmap.Beatmap.

• override_mode (GameMode | None, default: None) – The target ruleset to convert to, or None to keep the map’s native mode.

Return type:

Beatmap

Returns:

The prepared beatmap.

property mode: GameMode

Return the (possibly converted) game mode of this beatmap.

property inner: PerformanceBeatmap

Return the underlying performance beatmap.

class parsecore.Performance.api.Difficulty

Bases: object

Builder for a star-rating (difficulty) calculation.

Configure mods, clock rate and difficulty overrides with the chaining methods, then call calculate().

mods(mods)

Set the mods.

Parameters:

mods (Any) – Legacy bitflags, an acronym string, or a mods object.

Return type:

Difficulty

Returns:

self for chaining.

clock_rate(cr)

Override the clock rate directly.

Parameters:

cr (float) – The clock-rate multiplier (e.g. 1.5 for DT).

Return type:

Difficulty

Returns:

self for chaining.

lazer(lazer)

Choose lazer or stable scoring semantics.

Parameters:

lazer (bool) – True for osu!lazer, False for osu!(stable).

Return type:

Difficulty

Returns:

self for chaining.

ar(ar, fixed=False)

Override the approach rate.

Parameters:

• ar (float) – The AR value.

• fixed (bool, default: False) – If True use as-is; if False mods and clock rate still adjust it.

Return type:

Difficulty

Returns:

self for chaining.

cs(cs, fixed=False)

Override the circle size (see ar() for fixed).

Parameters:

• cs (float) – The CS value.

• fixed (bool, default: False) – Whether to use the value as-is.

Return type:

Difficulty

Returns:

self for chaining.

hp(hp, fixed=False)

Override the HP drain rate (see ar() for fixed).

Parameters:

• hp (float) – The HP value.

• fixed (bool, default: False) – Whether to use the value as-is.

Return type:

Difficulty

Returns:

self for chaining.

od(od, fixed=False)

Override the overall difficulty (see ar() for fixed).

Parameters:

• od (float) – The OD value.

• fixed (bool, default: False) – Whether to use the value as-is.

Return type:

Difficulty

Returns:

self for chaining.

passed_objects(n)

Only consider the first n hit objects (partial map).

Parameters:

n (int) – The number of objects to include.

Return type:

Difficulty

Returns:

self for chaining.

calculate(beatmap)

Run the difficulty calculation.

Parameters:

beatmap (Beatmap | PerformanceBeatmap | Any) – The beatmap to evaluate (a Beatmap or compatible object).

Return type:

Any

Returns:

The ruleset’s difficulty attributes (including stars and max_combo).

class parsecore.Performance.api.Performance(beatmap)

Bases: object

Builder for a performance (pp) calculation.

Configure mods and the score state with the chaining methods, then call calculate(). Unset counts are generated from the accuracy/miss count.

Parameters:

beatmap (Beatmap | PerformanceBeatmap | Any)

mods(mods)

Set the mods from a bitflag, acronym string or mods object; returns self.

Return type:

Performance

Parameters:

mods (Any)

clock_rate(cr)

Override the clock-rate multiplier; returns self.

Return type:

Performance

Parameters:

cr (float)

lazer(lazer)

Select lazer or stable scoring semantics; returns self.

Return type:

Performance

Parameters:

lazer (bool)

accuracy(acc)

Set the target accuracy in percent (generates a matching state); returns self.

Return type:

Performance

Parameters:

acc (float)

combo(c)

Set the achieved max combo; returns self.

Return type:

Performance

Parameters:

c (int)

misses(m)

Set the miss count; returns self.

Return type:

Performance

Parameters:

m (int)

n300(n)

Set the number of 300s (great hits); returns self.

Return type:

Performance

Parameters:

n (int)

n100(n)

Set the number of 100s (ok hits); returns self.

Return type:

Performance

Parameters:

n (int)

n50(n)

Set the number of 50s (meh hits); returns self.

Return type:

Performance

Parameters:

n (int)

n_geki(n)

Set the number of gekis (mania perfects / max hits); returns self.

Return type:

Performance

Parameters:

n (int)

n_katu(n)

Set the number of katus (mania good / catch tiny-droplet misses); returns self.

Return type:

Performance

Parameters:

n (int)

large_tick_hits(n)

Set the number of large tick hits (lazer sliders); returns self.

Return type:

Performance

Parameters:

n (int)

small_tick_hits(n)

Set the number of small tick hits (lazer); returns self.

Return type:

Performance

Parameters:

n (int)

slider_end_hits(n)

Set the number of slider ends hit (lazer sliders); returns self.

Return type:

Performance

Parameters:

n (int)

passed_objects(n)

Only consider the first n objects (fails/partial plays); returns self.

Return type:

Performance

Parameters:

n (int)

legacy_total_score(score)

Set the stable total score for score-based miss estimation; returns self.

Return type:

Performance

Parameters:

score (int)

ar(ar, fixed=False)

Override AR (see Difficulty.ar() for fixed); returns self.

Return type:

Performance

Parameters:

• ar (float)

• fixed (bool)

cs(cs, fixed=False)

Override CS (see Difficulty.ar() for fixed); returns self.

Return type:

Performance

Parameters:

• cs (float)

• fixed (bool)

hp(hp, fixed=False)

Override HP (see Difficulty.ar() for fixed); returns self.

Return type:

Performance

Parameters:

• hp (float)

• fixed (bool)

od(od, fixed=False)

Override OD (see Difficulty.ar() for fixed); returns self.

Return type:

Performance

Parameters:

• od (float)

• fixed (bool)

calculate(attrs=None)

Run the performance calculation.

Parameters:

attrs (Any | None, default: None) – Pre-computed difficulty attributes to reuse, or None to compute them from the configured settings.

Return type:

Any

Returns:

The ruleset’s performance attributes (including pp).

Score state

The score state (hit-result counts) and the hit-result value types.

class parsecore.Performance.data.score_state.ScoreState(max_combo=0, osu_large_tick_hits=0, osu_small_tick_hits=0, slider_end_hits=0, n_geki=0, n_katu=0, n300=0, n100=0, n50=0, misses=0, legacy_total_score=None)

Bases: object

A complete set of hit-result counts describing one play.

Parameters:

• max_combo (int)

• osu_large_tick_hits (int)

• osu_small_tick_hits (int)

• slider_end_hits (int)

• n_geki (int)

• n_katu (int)

• n300 (int)

• n100 (int)

• n50 (int)

• misses (int)

• legacy_total_score (int | None)

max_combo: int

osu_large_tick_hits: int

osu_small_tick_hits: int

slider_end_hits: int

n_geki: int

n_katu: int

n300: int

n100: int

n50: int

misses: int

legacy_total_score: int | None

total_hits(mode)

Return the total number of judged objects for a mode.

Parameters:

mode (GameMode) – The ruleset (its object types decide which counts contribute).

Return type:

int

Returns:

The sum of the relevant hit-result counts.

class parsecore.Performance.data.score_state.HitResult(*values)

Bases: Enum

A single hit-result kind (great, ok, meh, miss, ticks, slider ends, …).

NONE = 1

MISS = 2

MEH = 3

OK = 4

GOOD = 5

GREAT = 6

PERFECT = 7

SMALL_TICK_MISS = 8

SMALL_TICK_HIT = 9

LARGE_TICK_MISS = 10

LARGE_TICK_HIT = 11

SMALL_BONUS = 12

LARGE_BONUS = 13

IGNORE_MISS = 14

IGNORE_HIT = 15

COMBO_BREAK = 16

SLIDER_TAIL_HIT = 17

LEGACY_COMBO_INCREASE = 18

base_score(mode)

Return the base score value of this result in a ruleset.

Parameters:

mode (GameMode) – The ruleset.

Return type:

int

Returns:

The unscaled score contribution of one such judgement.

class parsecore.Performance.data.score_state.HitResultPriority(*values)

Bases: Enum

Whether to prefer more or fewer great hits when generating a score state.

BEST_CASE = 1

WORST_CASE = 2

classmethod default()

Return the default priority.

Return type:

HitResultPriority

Returns:

The priority used when none is specified.

Difficulty attributes

class parsecore.Performance.rulesets.osu.difficulty.OsuDifficultyAttributes(aim=0.0, aim_difficult_slider_count=0.0, speed=0.0, flashlight=0.0, reading=0.0, slider_factor=1.0, aim_top_weighted_slider_factor=0.0, speed_top_weighted_slider_factor=0.0, speed_note_count=0.0, aim_difficult_strain_count=0.0, speed_difficult_strain_count=0.0, reading_difficult_note_count=0.0, nested_score_per_object=0.0, legacy_score_base_multiplier=1.0, maximum_legacy_combo_score=0.0, ar=0.0, hp=0.0, great_hit_window=0.0, ok_hit_window=0.0, meh_hit_window=0.0, n_circles=0, n_sliders=0, n_large_ticks=0, n_spinners=0, stars=0.0, max_combo=0, od=0.0)

Bases: object

Difficulty attributes of an osu! beatmap (aim, speed, reading, flashlight, …).

Parameters:

• aim (float)

• aim_difficult_slider_count (float)

• speed (float)

• flashlight (float)

• reading (float)

• slider_factor (float)

• aim_top_weighted_slider_factor (float)

• speed_top_weighted_slider_factor (float)

• speed_note_count (float)

• aim_difficult_strain_count (float)

• speed_difficult_strain_count (float)

• reading_difficult_note_count (float)

• nested_score_per_object (float)

• legacy_score_base_multiplier (float)

• maximum_legacy_combo_score (float)

• ar (float)

• hp (float)

• great_hit_window (float)

• ok_hit_window (float)

• meh_hit_window (float)

• n_circles (int)

• n_sliders (int)

• n_large_ticks (int)

• n_spinners (int)

• stars (float)

• max_combo (int)

• od (float)

aim: float

aim_difficult_slider_count: float

speed: float

flashlight: float

reading: float

slider_factor: float

aim_top_weighted_slider_factor: float

speed_top_weighted_slider_factor: float

speed_note_count: float

aim_difficult_strain_count: float

speed_difficult_strain_count: float

reading_difficult_note_count: float

nested_score_per_object: float

legacy_score_base_multiplier: float

maximum_legacy_combo_score: float

ar: float

hp: float

great_hit_window: float

ok_hit_window: float

meh_hit_window: float

n_circles: int

n_sliders: int

n_large_ticks: int

n_spinners: int

stars: float

max_combo: int

od: float

n_objects()

Return the total object count (circles plus sliders plus spinners).

Return type:

int

class parsecore.Performance.rulesets.taiko.difficulty.TaikoDifficultyAttributes(stamina=0.0, rhythm=0.0, color=0.0, reading=0.0, great_hit_window=0.0, ok_hit_window=0.0, mono_stamina_factor=0.0, mechanical_difficulty=0.0, consistency_factor=0.0, stars=0.0, max_combo=0, is_convert=False, clock_rate=1.0, ar=0.0, cs=0.0, hp=0.0, od=0.0)

Bases: object

Difficulty attributes of a taiko beatmap (stars, per-skill values, hit windows).

Parameters:

• stamina (float)

• rhythm (float)

• color (float)

• reading (float)

• great_hit_window (float)

• ok_hit_window (float)

• mono_stamina_factor (float)

• mechanical_difficulty (float)

• consistency_factor (float)

• stars (float)

• max_combo (int)

• is_convert (bool)

• clock_rate (float)

• ar (float)

• cs (float)

• hp (float)

• od (float)

stamina: float

rhythm: float

color: float

reading: float

great_hit_window: float

ok_hit_window: float

mono_stamina_factor: float

mechanical_difficulty: float

consistency_factor: float

stars: float

max_combo: int

is_convert: bool

clock_rate: float

ar: float

cs: float

hp: float

od: float

class parsecore.Performance.rulesets.catch.difficulty.CatchDifficultyAttributes(stars=0.0, preempt=0.0, n_fruits=0, n_droplets=0, n_tiny_droplets=0, is_convert=False, ar=0.0, cs=0.0, hp=0.0, od=0.0, clock_rate=1.0)

Bases: object

Difficulty attributes of a catch beatmap (stars, object counts, AR/CS/…).

Parameters:

• stars (float)

• preempt (float)

• n_fruits (int)

• n_droplets (int)

• n_tiny_droplets (int)

• is_convert (bool)

• ar (float)

• cs (float)

• hp (float)

• od (float)

• clock_rate (float)

stars: float

preempt: float

n_fruits: int

n_droplets: int

n_tiny_droplets: int

is_convert: bool

ar: float

cs: float

hp: float

od: float

clock_rate: float

property max_combo: int

Return the maximum achievable combo (fruits plus droplets).

class parsecore.Performance.rulesets.mania.difficulty.ManiaDifficultyAttributes(stars=0.0, n_objects=0, n_hold_notes=0, max_combo=0, great_hit_window=0.0, good_hit_window=0.0, is_convert=False, clock_rate=1.0, ar=0.0, cs=0.0, hp=0.0, od=0.0)

Bases: object

Difficulty attributes of a mania beatmap (stars, object/hold counts, hit windows).

Parameters:

• stars (float)

• n_objects (int)

• n_hold_notes (int)

• max_combo (int)

• great_hit_window (float)

• good_hit_window (float)

• is_convert (bool)

• clock_rate (float)

• ar (float)

• cs (float)

• hp (float)

• od (float)

stars: float

n_objects: int

n_hold_notes: int

max_combo: int

great_hit_window: float

good_hit_window: float

is_convert: bool

clock_rate: float

ar: float

cs: float

hp: float

od: float

Performance attributes

class parsecore.Performance.rulesets.osu.performance.OsuPerformanceAttributes(pp=0.0, pp_aim=0.0, pp_speed=0.0, pp_acc=0.0, pp_reading=0.0, pp_flashlight=0.0, effective_miss_count=0.0, speed_deviation=None, combo_based_estimated_miss_count=0.0, score_based_estimated_miss_count=None, aim_estimated_slider_breaks=0.0, speed_estimated_slider_breaks=0.0, stars=0.0, max_combo=0, difficulty=<factory>)

Bases: object

osu! performance result (total pp and its aim/speed/acc/reading/flashlight parts).

Parameters:

• pp (float)

• pp_aim (float)

• pp_speed (float)

• pp_acc (float)

• pp_reading (float)

• pp_flashlight (float)

• effective_miss_count (float)

• speed_deviation (float | None)

• combo_based_estimated_miss_count (float)

• score_based_estimated_miss_count (float | None)

• aim_estimated_slider_breaks (float)

• speed_estimated_slider_breaks (float)

• stars (float)

• max_combo (int)

• difficulty (OsuDifficultyAttributes)

pp: float

pp_aim: float

pp_speed: float

pp_acc: float

pp_reading: float

pp_flashlight: float

effective_miss_count: float

speed_deviation: float | None

combo_based_estimated_miss_count: float

score_based_estimated_miss_count: float | None

aim_estimated_slider_breaks: float

speed_estimated_slider_breaks: float

stars: float

max_combo: int

difficulty: OsuDifficultyAttributes

n_objects()

Return the total object count.

Return type:

int

class parsecore.Performance.rulesets.taiko.performance.TaikoPerformanceAttributes(pp=0.0, pp_acc=0.0, pp_difficulty=0.0, estimated_unstable_rate=None, stars=0.0, max_combo=0)

Bases: object

Taiko performance result (pp plus the difficulty attributes used).

Parameters:

• pp (float)

• pp_acc (float)

• pp_difficulty (float)

• estimated_unstable_rate (float | None)

• stars (float)

• max_combo (int)

pp: float

pp_acc: float

pp_difficulty: float

estimated_unstable_rate: float | None

stars: float

max_combo: int

class parsecore.Performance.rulesets.catch.performance.CatchPerformanceAttributes(pp=0.0, stars=0.0, max_combo=0, state_n300=0, state_n100=0, state_n50=0, state_n_katu=0, state_misses=0, state_max_combo=0)

Bases: object

Catch performance result (pp plus the difficulty attributes used).

Parameters:

• pp (float)

• stars (float)

• max_combo (int)

• state_n300 (int)

• state_n100 (int)

• state_n50 (int)

• state_n_katu (int)

• state_misses (int)

• state_max_combo (int)

pp: float

stars: float

max_combo: int

state_n300: int

state_n100: int

state_n50: int

state_n_katu: int

state_misses: int

state_max_combo: int

class parsecore.Performance.rulesets.mania.performance.ManiaPerformanceAttributes(pp=0.0, pp_difficulty=0.0, stars=0.0, max_combo=0)

Bases: object

Mania performance result (pp plus the difficulty attributes used).

Parameters:

• pp (float)

• pp_difficulty (float)

• stars (float)

• max_combo (int)

pp: float

pp_difficulty: float

stars: float

max_combo: int

Gradual calculation (catch)

class parsecore.Performance.rulesets.catch.gradual.CatchGradualDifficulty(difficulty, beatmap)

Bases: object

Iterates catch difficulty attributes, revealing one more object each step.

Parameters:

• difficulty (Any)

• beatmap (Any)

next()

Reveal the next object and return its attributes, or None.

Return type:

CatchDifficultyAttributes | None

nth(n)

Skip ahead and return the attributes after the n-th next object.

Parameters:

n (int) – How many objects to advance (0 = the next object).

Return type:

CatchDifficultyAttributes | None

Returns:

The attributes at that point, or None if exhausted.

class parsecore.Performance.rulesets.catch.gradual.CatchGradualPerformance(difficulty, beatmap)

Bases: object

Feeds gradual difficulty into pp for object-by-object performance.

Parameters:

• difficulty (Any)

• beatmap (Any)

next(state)

Advance one object and return the pp for the given state.

Parameters:

state (CatchScoreState) – The score state so far.

Return type:

CatchPerformanceAttributes | None

Returns:

The performance attributes, or None if exhausted.

last(state)

Advance to the final object and return the pp for the state.

Return type:

CatchPerformanceAttributes | None

Parameters:

state (CatchScoreState)

nth(state, n)

Advance n objects and return the pp for the state.

Return type:

CatchPerformanceAttributes | None

Parameters:

• state (CatchScoreState)

• n (int)