development.md

Development

Back to README

Design Plans

• Online leaderboard plan (中文): osu! OAuth, full replay uploads, and SQLite storage. Design only; not implemented.

Build Manually

Install Git and the .NET 10 SDK, then clone this repository and osu! into sibling directories. Sparse checkout skips the large test-song folder:

git clone --filter=blob:none --sparse https://github.com/QingQiz/BmsRuleset.git
git -C BmsRuleset sparse-checkout set --no-cone '/*' '!bms_test_songs'
git clone --filter=blob:none https://github.com/ppy/osu.git

Read OsuVersion in BmsRuleset/Directory.Build.props, then check out the matching osu! tag. For example, OsuVersion 2026.920.0 requires:

git -C osu checkout 2026.920.0-lazer

UseLocalOsu is enabled by default and references the sibling osu checkout. The ppy.osu.Game NuGet package can lag behind osu!lazer releases, so building against the matching tag keeps the API version in sync. Pass -p:OsuSourcePath=/absolute/path/to/osu to use a separate checkout when the sibling repository must remain read-only.

Release versions use <OsuVersion>-<RulesetRevision>, with the ruleset counter starting at zero for each official osu! version. Assembly and file versions use the same four components separated by dots.

Build the ruleset in Release configuration:

cd BmsRuleset
dotnet build osu.Game.Rulesets.BmsRuleset -c Release

The output is osu.Game.Rulesets.BmsRuleset/bin/Release/net10.0/osu.Game.Rulesets.BmsRuleset.dll. Install it using the README installation steps.

Mod Icons

The maintained icon generator is scripts/bms-icon-font-generator. Use the repository generator when updating the font.

Gameplay Performance

For reusable real Player profiling across charts, skins and long-note modes, see Gameplay performance template (中文).

dotnet test osu.Game.Rulesets.BmsRuleset.Tests/osu.Game.Rulesets.BmsRuleset.Tests.csproj -c Release --no-build --no-restore --filter 'FullyQualifiedName~TestSceneBmsInvertGameplay|FullyQualifiedName~TestSceneBmsReplayRewind|FullyQualifiedName~TestSceneBmsPauseRewind'

Not Yet Implemented

Area	What is missing	Priority
Audio	#WAVCMD (MacBeat) — pitch/volume/playback-time per WAV slot
Audio	#EXWAVxx (nanasi) — pan/volume/frequency per WAV file
Input	Turntable input — scratch currently behaves as a column key
Mods	DP only mods (FLIP / BATTLE / SP -> DP / SYNCHRONIZE RANDOM / SYMMETRY RANDOM)
Parser	#@BGAxx — 9-field BGA crop with destination width/height; only 7-field #BGAxx is parsed	2
Parser	#SWBGAxx — switchable BGA definition	3
Parser	#ARGBxx — ARGB color/alpha definition for BGA elements	3
Parser	#EXBMPxx — extended BMP definition slot	3
Parser	#POORBGAxx — per-slot POOR BGA crop definition (distinct from scalar #POORBGA mode)	2
Parser	#BGAEXPAND — global BGA scaling mode (0=stretch, 1=keep aspect, 2=no expand)	2
Parser	#BGAOFF — disable BGA for the chart	2
Parser	BMSON support	1
Parser	#BMPxx / #EXBMPxx — image definitions (non-resource-scan)
Parser	#CDDA — CD audio
Parser	#CHARFILE / #ExtChr — character / skin
Parser	#EXBPMxx — #BPMxx alias (BMSC parser bug workaround)
Parser	#EXWAVxx, #WAVCMD — advanced audio controls
Parser	#MATERIALS / #MATERIALSWAV / #MATERIALSBMP / #DIVIDEPROP — resource groups
Parser	#OCT/FP — octave / pedal
Parser	#OPTION — forced option
Parser	#PATH_WAV / #PATH_BMP — resource path prefixes
Parser	#MOVIE — metadata only
Parser	#STP — absolute STOP sequence
Parser	#VIDEOFILE / #VIDEOf/s / #VIDEOCOLORS / #VIDEODLY / #MOVIE / #SEEKxx — video
Parser	#CHARSET — character encoding specification
Parser	#ExtChr — BM98 extended character sprite display
Parser	Channel 17 / 27 — free-zone keys
Parser	Channel A6 / #CHANGEOPTIONxx — dynamic option changes
Renderer	Configurable POOR BGA duration — fixed at 500 ms; beatoraja uses misslayerDuration	3
Scoring	24KEYS / 24KEYS DOUBLE judgement profile matching beatoraja KEYBOARD	3
Skin	HitGreat → HitGreatSlow / HitGreatFast split images
Skin	E-POOR judgement image	3
UI	Lane cover / skin / movement	2
Perf	Frame spikes during mass gameplay object activation and pool return	4