BeatSaber/CLAUDE_REVIEW_HUD_PROPOSAL.md

# Claude Review Request: Game Scene HUD Polish

## Status

This proposal has mostly been implemented and superseded by the current UI-quality pass.

Implemented since this proposal:

- ScoreCanvas was moved closer to the player.
- Left/right HUD structure was created.
- Multiplier ring background and song progress bar were added.
- Song current time / total time is displayed.
- Result screen polish has become the current priority.

Remaining HUD follow-up:

- Verify HUD readability in Play Mode.
- Consider migrating HUD labels from legacy `UI.Text` to TMP after the result screen is stable.
- Add rank/multiplier micro animations only after static layout is approved.

## Goal

Match the Game scene HUD closer to the provided Beat Saber-style reference:

- Left side: combo, score, accuracy, current rank
- Right side: multiplier ring and remaining/elapsed song time
- Keep the center lane clear for notes and sabers
- Use thin, readable white/cyan text with minimal visual noise

## Current Scene Findings

Unity bridge reports active scene:

- Scene: `Game`
- Playing: `true`
- Main HUD root: `_UI/ScoreCanvas`
- Existing HUD items:
  - `_UI/ScoreCanvas/Combo`
  - `_UI/ScoreCanvas/Score`
  - `_UI/ScoreCanvas/Accuracy`
  - `_UI/ScoreCanvas/Rank`
  - `_UI/ScoreCanvas/Multiplier`
  - `_UI/ScoreCanvas/Image`
  - `_UI/ScoreCanvas/SongProgress`
  - `_UI/ScoreCanvas/Judgement`

Current `ScoreCanvas` world placement:

- Position: approximately `(5.8, 2.4, 17.8)`
- Rotation: approximately `(354.8, 18.7, 0)`
- Scale: `(0.005, 0.005, 0.005)`

## Proposed Direction

Prefer scene/UI layout polish first. Avoid gameplay logic changes.

1. Split HUD into stable left and right visual groups under `_UI/ScoreCanvas`.
2. Left group layout:
   - `COMBO`
   - combo number, larger
   - score
   - accuracy percent
   - rank, larger
3. Right group layout:
   - circular multiplier ring
   - multiplier value centered, e.g. `x4`
   - small time bar below
   - elapsed / total or remaining time text
4. Move `Judgement` away from persistent HUD, likely near center-top or temporarily shown and faded.
5. Keep HUD outside the note highway and saber swing area.

## Suggested Implementation Options

### Option A: Scene-only first

Adjust Game scene RectTransforms / world canvas placement and existing child positions without changing code.

Pros:
- Lowest risk
- Fast to evaluate visually in Unity
- Matches user request to polish Game scene first

Cons:
- Existing `ScoreManager.PrepareHud()` may overwrite some RectTransform values at runtime if `applyHudPlacement` or label setup runs.

Estimated score: 78/100 unless we confirm code does not overwrite the scene layout.

### Option B: Minimal code-supported layout

Make `ScoreManager` expose a stable Beat Saber HUD layout preset and only adjust positions/sizes of existing labels.

Pros:
- Runtime layout stays consistent
- Existing labels and score data remain unchanged
- Low gameplay risk

Cons:
- Requires code edit, so must pass the 80+ review gate.

Estimated score: 86/100 if scoped only to HUD placement/style and verified in Play mode.

## Codex Recommendation

Start with Option A in Unity scene if possible. If `ScoreManager.PrepareHud()` overwrites the layout during play, move to Option B with a narrow code change.

Codex preliminary score for Option B: 86/100.

Claude Code: please review this proposal and either approve with score >= 80 or suggest revisions before code changes proceed.