BMS Ruleset English

BMS Ruleset (English)

中文 | English

What This Is

The BMS ruleset enables loading and playing external .bms/.bme/.bml/.pms libraries in Ez2Lazer.

It relies on Ez2Lazer extension interfaces (external library sync, analysis writeback, keysound preview, and ruleset extensions), so use a compatible Ez2Lazer build.

BMS UI strings follow the same language as osu! (Chinese when CurrentUICulture is zh*, English otherwise). Wiki quotes in-game labels in backticks.

Setup Steps and Entry Points

Entry Points

• Settings -> BMS: library paths and BMS behavior; includes Build BMS analytics database / 构建 BMS 分析库 and Open BMS library path wizard / 打开 BMS 曲库设置向导.
• Settings -> Ez: analysis/extended behavior toggles (affects xxySR and analysis visibility).
• Standard BMS song select (Carousel): footer Refresh library only.
• BMS song select (tables / Qwilight layout): three panes (tables·folders·filters | chart list | detail); footer Refresh library, Build analytics, Add table URL, Open tables folder.

Difficulty tables (independent of favorites)

• Table files live under EzBMS/tables/ (.bmt or beatoraja-compatible JSON). They do not write osu collections and are not mixed with Raja FAVORITE SQL filters.
• Import by:
  • Sync built-in tables in Settings / song select (fetches the curated SP/DP/PMS table URL catalog);
  • dropping files into EzBMS/tables;
  • or pasting a table URL into the search box and tapping Add table URL.
• Matching uses chart content MD5/SHA256. After upgrading, run Refresh library at least once. Missing charts show as not imported; if the table entry has a download URL, use footer Open download / D / Enter to open the publisher page (charts are not redistributed).

Recommended Setup Order

1. In Settings -> BMS, use 打开 BMS 曲库设置向导 to add one or more BMS root folders (you can also maintain the path list outside the wizard).
2. Open any BMS song select screen and run 刷新曲库 (scan + sync metadata; also writes content hashes).
3. Run 构建 BMS 分析库 in settings, or 构建分析库 on the dedicated song select screen (updates stars, xxySR, KPS, etc.).
4. (Optional) Import difficulty tables, then browse table → level → chart in the left pane.
5. Switch several charts and confirm loading and metrics look correct.

Initialization Notes

• After path changes, run 刷新曲库 again.
• After upstream merge/rebase, run 刷新曲库, then 构建 BMS 分析库 (or Raja 构建分析库) so indexes stay current.
• If you moved data folders manually, back up realm / sqlite files before rebuilding indexes.

File Management Framework (After BMS Library Path Setup)

After the BMS library path wizard (or equivalent path configuration), on-disk folders are converted into unified metadata shared by song select, difficulty, and gameplay. Core flow: scan -> sync -> load.

flowchart LR
  pathSetup[PathSetup] --> scanIndex[BMSBeatmapManagerScan]
  scanIndex --> realmSync[BMSOsuLibrarySynchronizerSync]
  realmSync --> realmMeta["RealmMetadata extSet FilesMap"]
  realmMeta --> workingBeatmap[WorkingBeatmapCacheLoad]
  workingBeatmap --> decoder[BMSBeatmapDecoder]
  decoder --> panelAndPlay[SongSelectPanelAndGameplay]

Loading

User Perspective

• Configured paths are scanned and indexed.
• Index results sync into game-readable beatmap sets and file mappings.
• Song switching, difficulty calculation, and gameplay loading all use the same mapping.

Developer Perspective (Brief)

• Scan layer: BMSBeatmapManager + sqlite index.
• Sync layer: BMSOsuLibrarySynchronizer writes Realm (ext:set, ExternalContentRoot, relative Files paths).
• Load layer: BeatmapManager.GetWorkingBeatmap -> WorkingBeatmapCache -> ExternalBeatmapCompositeFileStore -> Decoder.

Which Capabilities Reuse Mania After Load

Mania-Reused Components

• Main difficulty calculation path (mania difficulty pipeline).
• Core judgement/score components from mania (with BMS ruleset extensions on top).
• BMS charts convert to mania structures when a shared pipeline requires it.

BMS-Specific Components

• External library path and file-mapping sync.
• Keysound/background audio event handling. BMS has no separate main track: channel 01 BGM and note keysounds are both samples fired at a point in time, so the "main audio" is just the BGM events along the timeline. BmsKeysoundManager presents it: Prepare hands the whole sample batch to a background thread (PreloadTask), and both the player loader and the song-select preview wait for that task instead of blocking the update thread, then fire samples by event time. The chart's BGM events are also merged into the storyboard audio layer BMSBackgroundSamples.
• Legacy chart text-encoding detection (UTF-8 / GBK(936) / Shift-JIS(932) / system ANSI): decoded titles, artists and #WAV/#BMP filenames have to match the real file names on disk, or keysounds go silent. Candidates are ranked by evidence: first whether the chart's referenced media actually exists under a given decode, then mis-decode fingerprints (reading GBK as Shift-JIS turns Chinese into runs of half-width katakana and private-use characters), and only then the system code page preference. On a Chinese system that means GBK charts decode as 936.
  • Known limitation: on a CP936 system, a Japanese Shift-JIS chart whose #WAV list is pure ASCII leaves no usable evidence, so CP936 wins by preference. (Japanese filenames, or a decode that forces mis-decode artefacts on the alternative, still select Shift-JIS correctly.)
• BMS-side analysis aggregation (xxySR/KPS, etc.).

Common Issues and How to Fix Them

1) file xxx not found on disk at expected location while switching songs

Symptom: file-not-found logs when switching charts (often hashed path segments).
Cause: stale file mapping/index or changed folder layout.
Fix:

1. Run 刷新曲库 on a BMS song select screen.
2. Then run 构建 BMS 分析库 (settings or Raja song select).
3. If it still fails, verify the configured root exists and subfolders were not moved/renamed.

2) Library refresh fails (Realm / sync exceptions)

Symptom: 刷新曲库 fails with RealmResultsVisitor, NotSupportedException, NotImplementedException, etc.
Cause: old binaries or sync queries out of date after merge/rebase.
Fix:

1. Rebuild fully and run the latest binaries.
2. Run 刷新曲库 again and check import/skip logs.
3. If it still fails, provide a full stack trace (file + line) for diagnosis.

3) xxySR shows but official stars are missing

Symptom: xxySR appears, but official stars are empty or you see Failed to calculate beatmap difficulty.
Cause: beatmap load or difficulty pipeline did not enter the mania-reuse path.
Fix:

1. Run 刷新曲库, then 构建 BMS 分析库.
2. Switch several charts and watch for remaining difficulty errors.
3. If only some charts fail, check those folders and asset completeness.

4) Scheduler pending tasks pile up while idling in song select

Symptom: performance logs show many pending scheduler tasks.
Cause: preview scheduling load or rapid chart switching.
Fix:

1. Use a build that includes preview scheduling caps.
2. Leave and re-enter BMS song select.
3. If it persists, attach performance log snippets for maintainers.

5) Note sounds play but there is no BGM, or titles show as mojibake

Symptom: no BGM ("main audio") in gameplay and possibly a silent song-select preview; charts show garbled titles, artists or keysound filenames (typically Chinese destroyed while Japanese looks fine). Cause: BMS charts are authored in legacy encodings, and Chinese libraries are mostly GBK(936) or UTF-8. If keysounds are not preloaded, or the detected encoding disagrees with the real file names on disk, sample lookups fail and are skipped silently. Reading GBK bytes as Shift-JIS renders Chinese as half-width katakana that looks like Japanese; mojibake metadata already written to Realm can only be corrected by a rescan. Fix:

1. Run 刷新曲库: the first scan after this update re-parses every chart indexed by older parsing logic (a stale parse version forces a re-parse), rewriting imported titles/artists/filenames with the new encoding decision. That pass is slower than the usual incremental scan; later scans are incremental again.
2. Confirm AutoPreloadKeysounds is enabled in 设置 -> BMS (with it off, audio still plays but every lookup reads from disk on demand, which can stutter on entering a chart or starting a preview).
3. If only one chart is silent, check that the files its #WAV directives point at actually exist in the chart folder (including case and WAV/ / RES/ subfolders).
4. If it still fails, attach the chart filename and the [BMS]-prefixed runtime log for the maintainer.

Maintenance Checklist (After Upstream Merge/Rebase)

Minimal validation after each merge:

1. 刷新曲库 (sync completes without errors).
2. 构建 BMS 分析库 (analytics pipeline completes).
3. Switch multiple charts (load OK; official stars and xxySR both visible).