BeatSaber/HANDOFF.md

VR Beat Saber Handoff

Project Status

• Unity: 6000.3.12f1
• Branch: master
• Remote: origin = https://whdwo798.synology.me/whdwo798/BeatSaber.git
• Latest pushed commit before this document update: fb59fc3 feat: polish result screen UI
• Current focus: raise overall UI quality, starting from the result screen, then HUD, then song select.

Collaboration Rule

• Code changes should go through a Codex and Claude Code mutual review gate.
• A proposal should score at least 80/100 before implementation.
• Review criteria:
  • Correctness
  • Scope control
  • Unity scene/runtime risk
  • Maintainability
  • Verification plan

See COLLABORATION_RULES.md.

Unity / MCP Bridge

• Assets/Editor/UnityCodexBridgeServer.cs
  • Bridge now falls back across ports 19744-19748 when the default port is busy.
• tools/unity-mcp-server/index.mjs
  • MCP server probes the same fallback port range when UNITY_BRIDGE_URL is not explicitly set.
• This was added because Unity reported that the bridge socket address was already in use.

Game Scene HUD

ScoreCanvas Placement

Assets/Scenes/Game.unity

• ScoreCanvas was moved closer to the player:
  • Z: 17.8 -> 5
  • Scale: 0.005 -> 0.006
  • applyHudPlacement: true -> false
• This prevents HUD elements from collapsing visually near the center of the tunnel.

Runtime HUD

Assets/VRBeatsKit/Scripts/UI/ScoreManager.cs

• Left HUD:
  • Combo
  • Score
  • Accuracy
  • Current rank
• Right HUD:
  • Multiplier value
  • Multiplier ring and faint ring background
  • Song progress bar
  • Current time / total time
• Dynamic legacy Text labels lazily load LegacyRuntime.ttf to avoid missing-font rendering issues.
• The progress bar fills from 0 -> 1 as the song progresses.

Timing / Completion

Assets/VRBeatsKit/Scripts/Core/AudioManager.cs

• Song time now uses scheduled DSP time instead of reading AudioSource.time.
• This avoids the Unity warning about requesting time from an audio source whose resource is not a clip.

Assets/Script/SongController.cs

• Song duration falls back to metadata or last note time when clip.length is zero.
• Completion waits until the last note / known duration instead of ending early because of a bad clip length.
• Note layer Y positions were raised so low notes are easier to slice:

lineLayer 0: -0.12
lineLayer 1: +0.22
lineLayer 2: +0.56

Scoring / Rank Rules

Assets/VRBeatsKit/Scripts/UI/ScoreManager.cs

Score Formula

CurrentScore = 800000 * accuracyRatio + 200000 * comboRatio

• Max score: 1,000,000
• Accuracy contribution: 800,000
• Max combo contribution: 200,000

Judgement Points

Perfect = 1000
Great   = 900
Good    = 700
Miss    = 0

Timing Windows

Perfect <= 0.11s
Great   <= 0.20s
Good    <= 0.32s

Combo Multiplier

The multiplier is intentionally beginner-friendly:

0-4 combo      x1.0
5-14 combo     x1.1
15-29 combo    x1.2
30-49 combo    x1.35
50+ combo      x1.5

Rank Thresholds

• M: final score >= 1,000,000
• Other ranks use AccuracyPercent:

S+ >= 98%
S  >= 95%
A  >= 90%
B  >= 80%
C  >= 70%
D  >= 60%
F  < 60%

Rank Colors

M   #E8B7FF  prism / jewel tone
S+  #41F2FF  cyan neon
S   #FFD95C  gold
A   #B9FF72
B   #FFE06A
C   #FFB15C
D   #FF7C7C
F   #A9B7C0

Result Screen

Assets/VRBeatsKit/Scripts/UI/FinalScoreLabel.cs

The result screen is now the first major UI-quality target.

Current result layout is generated at runtime:

ResultLayoutRoot
  RankShadowText
  RankDepthText
  RankMainText
  ResultScoreText
  ResultAccuracyText
  ResultComboText

Implemented:

• Existing Title is hidden while result content is shown.
• Existing serialized scoreText is hidden and used as a font/material source.
• Rank uses layered TMP text for a more dimensional badge.
• Result info now shows:
  • SCORE
  • final score
  • ACCURACY
  • max combo
• Result popup and restart/back buttons were tinted toward a darker translucent cyan UI style.

Known follow-up:

• tmp.lineSpacing = -8.0f is aggressive and may need visual tuning if the SCORE label overlaps the score value.
• Button styling is improved by color, but does not yet have a dedicated neon border/glow treatment.
• The scene appears to contain both result and game-over popup/button sets; verify that shared color changes are intentional.

Visual Effects

Blue visibility improvements were made in:

• Assets/VRBeatsKit/Settings/Settings.asset
• Assets/VRBeatsKit/Scripts/Core/SaberTrailEffect.cs
• Assets/VRBeatsKit/Scripts/Core/SliceTrailEffect.cs
• Assets/VRBeatsKit/Scripts/Other/Spark.cs

Goal:

• Keep red strong.
• Make blue saber/trail/spark readable against the bright cyan tunnel.

UI Quality Direction

Current agreed direction:

1. Finish result screen polish first.
2. Then polish in-game HUD.
3. Then consider HUD migration from legacy UI.Text to TMP for sharper VR rendering.
4. Then redesign song select cards/details.

Design principles:

• Thin readable text.
• Dark translucent panels, not heavy opaque boxes.
• White/cyan baseline UI with rank color accents.
• Large values, small labels.
• Avoid clutter in the note highway.
• Add micro animations only after the static layout is readable.

Verification Notes

• git diff --check passed for the latest result UI changes.
• dotnet build beatSaber.slnx --no-incremental is not reliable for this Unity project in the current environment because regular .NET build cannot resolve many Unity/TMP/UI/XR assemblies.
• Prefer Unity Editor compile and Play Mode for final verification.

Recommended Next Checks

1. Play the Game scene and finish a song.
2. Check result screen layout for M, S+, S, and F.
3. Verify score, accuracy, and max combo do not overlap.
4. Confirm Restart and Back buttons remain clickable.
5. Check whether result popup and game-over popup color changes should both stay.
6. If result screen is stable, move to HUD polish and TMP migration discussion.