Architecture Overview English

Architecture Overview (English)

中文 | English

Overview

As Ez2Lazer's judgement modes, score comparison features, and HUD components grew beyond what the official lazer architecture could handle, we introduced a parallel service layer that injects judgement, timeline replay, and local multi-score comparison capabilities into the game runtime as loosely-coupled services — without modifying official modules.

For players this means decoupled features, flexible configuration, and better performance — adding a new judgement mode no longer requires touching the entire scoring pipeline.

Three Service Layers

Game Runtime (OsuGame / EzOsuGame)
  │
  ├── [Mania Judgement Framework]  →  Judgement registry, HitMode switching, strategy selection
  ├── [Timeline Service]           →  Score timeline building, O(log n) query, sub-frame correction
  └── [Tournament Service]         →  Ghost comparison, Three-Pillar HUD, leaderboard

Each is independently usable:

• Mania Judgement Framework: Decouples judgement logic from the scoring pipeline into a pluggable strategy registry. When a player switches HitMode, the framework automatically swaps the underlying judgement strategy.
• Timeline Service: Converts a score replay into a binary-searchable snapshot array, which the Tournament Service queries in real-time against the game clock. Also includes sub-frame correction to reduce timing errors caused by frame rate fluctuations.
• Tournament Service: Pre-loads historical scores in song select, builds timeline caches, and drives ghost comparison via the Three-Pillar HUD or leaderboard during gameplay. It is a local lightweight racing system — no network connection needed.

Differences from Official Lazer

Aspect	Official Lazer	Ez2Lazer New Architecture
Judgement System	Hardcoded in scoring pipeline	Judgement Framework: Strategy registry, pluggable HitMode (BMS/O2Jam/EZ2AC/Malody)
Score Timeline	No independent timeline, aggregated at results screen only	Timeline Service: Pre-built O(log n) snapshot array, query any moment in real-time
Multi-score Comparison	Online spectate only	Tournament Service: Local ghost comparison, pre-loaded in song select, Three-Pillar/Leaderboard HUD
Frame Rate Compensation	None	Sub-frame correction: Key press timestamp minus FSC clock update wall clock delta
Cache Strategy	None	Timeline cached by hitMode:healthMode:judgePrecedence — different judgement modes don't pollute each other

Coexistence with Official Lazer

• All new services are mounted via EzOsuGame, without modifying official OsuGame or its Screen lifecycle
• Official rulesets (osu/taiko/catch) remain completely untouched
• Only the Mania ruleset receives the Ez judgement framework injection
• The Tournament Service uses GameplayClockContainer as its reference clock — pause/resume syncs naturally with the official gameplay pipeline

Player Perspective

• Switch HitMode → the judgement framework automatically swaps strategies; scoring and HUD follow accordingly
• Side-by-side comparison bars in-game → Three-Pillar HUD driven by the Tournament Service
• Sub-frame correction enabled by default → more accurate judgement at high frame rates, less drift at low frame rates
• Timeline cache → near-zero loading time on second play of the same map

From Player to Developer

• Players: Know that switching HitMode or enabling Three-Pillar comparison is backed by independent services, not scattered file changes
• Skin creators: Tournament HUD components (Three-Pillar, Leaderboard) are adjustable in the skin editor like regular HUDs
• Mod developers: New judgement modes just register with ManiaJudgementRegistry; new timeline data sources just bridge to EzScoreTimelineBridge

Related

• Ez Client Realm architecture (中文): single-file Realm extension, dual schema versions, Skills/analysis placement
• Mania Skills System: SSR / CSI / ChartDan / DualPanel player surface