API 参考 / 只读视图、场景、音频与文本

ResultSnapshot

结算快照（不可变）。宿主在结算界面每帧渲染前构造一份，随 UiCustomization.ResultOverlayRenderer#render 传给模组，是本局成绩的只读值快照。

方法速览

方法	用途
`chartFile()`	谱面主文件路径（可能为空串）
`title()` / `artist()` / `difficulty()` / `level()`	曲目与难度信息（未知为空串）
`bpm()` / `totalNotes()`	BPM / 总音符数（未知为 0）
`modeId()`	游玩模式 id（无模式为空串）
`storyMode()` / `internalChart()`	剧情模式 / 内部谱面
`score()` / `maxCombo()` / `accuracy()`	总分 / 最大连击 / 准度百分比 0-100
`grade()`	评级（未知为空串）
`cleared()` / `fullCombo()` / `newRecord()`	通关 / 全连 / 新纪录
`hp()`	结算时血量（满值 1000）
`perfects()` / `greats()` / `misses()`	三种内置判定计数
`customKindCounts()`	模组自定义判定计数（不可变 Map）
`builtinCounts()`	PERFECT / GREAT / MISS 计数列表
`equals(Object)` / `hashCode()` / `toString()`	记录类型默认值语义

chartFile()

java

public String chartFile();

行为：谱面主文件路径；入参为 null 时紧凑构造替换为空串。示例：

java

String file = snap.chartFile();

title()

java

public String title();

行为：曲目名，未知为空串。示例：

java

String title = snap.title();

artist()

java

public String artist();

行为：曲师，未知为空串。示例：

java

String artist = snap.artist();

difficulty()

java

public String difficulty();

行为：难度名，未知为空串。示例：

java

String diff = snap.difficulty();

level()

java

public String level();

行为：难度等级文本，未知为空串。示例：

java

String lv = snap.level();

bpm()

java

public int bpm();

行为：BPM，未知为 0。示例：

java

int bpm = snap.bpm();

totalNotes()

java

public int totalNotes();

行为：总音符数，未知为 0。示例：

java

int total = snap.totalNotes();

modeId()

java

public String modeId();

行为：游玩模式 id；入参为 null 时被紧凑构造替换为空串（不是 null）。示例：

java

boolean normal = "seecmd:normal".equals(snap.modeId());

storyMode()

java

public boolean storyMode();

行为：是否剧情模式。示例：

java

if (snap.storyMode()) { /* 剧情局附加展示 */ }

internalChart()

java

public boolean internalChart();

行为：是否内部谱面。示例：

java

boolean internal = snap.internalChart();

score()

java

public int score();

行为：总分。示例：

java

int score = snap.score();

maxCombo()

java

public int maxCombo();

行为：最大连击。示例：

java

int best = snap.maxCombo();

accuracy()

java

public double accuracy();

行为：准度百分比 0-100，与结算界面显示口径一致（注意与 GameplayContext.accuracy() 的 0-1 不同）。示例：

java

String accText = String.format("%.2f%%", snap.accuracy());

grade()

java

public String grade();

行为：评级（如 S / A / B）；入参为 null 时被紧凑构造替换为空串。示例：

java

String grade = snap.grade();

cleared()

java

public boolean cleared();

行为：是否通关。示例：

java

if (snap.cleared()) { /* 通关演出 */ }

fullCombo()

java

public boolean fullCombo();

行为：是否全连（无 MISS）。示例：

java

if (snap.fullCombo()) { /* FC 标记 */ }

newRecord()

java

public boolean newRecord();

行为：是否刷新个人最佳。示例：

java

if (snap.newRecord()) { /* NEW RECORD */ }

hp()

java

public int hp();

行为：结算时血量（满值 1000）。示例：

java

int hp = snap.hp();

perfects()

java

public int perfects();

行为：PERFECT 计数。示例：

java

int p = snap.perfects();

greats()

java

public int greats();

行为：GREAT 计数。示例：

java

int g = snap.greats();

misses()

java

public int misses();

行为：MISS 计数。示例：

java

int m = snap.misses();

customKindCounts()

java

public Map<String, Integer> customKindCounts();

行为：模组自定义判定计数（判定 id → 次数）。紧凑构造在入参为 null 时替换为 Map.of()，否则 Map.copyOf 成不可变副本；可能为空 Map，永不为 null。示例：

java

int mine = snap.customKindCounts().getOrDefault("mymod:slide", 0);

builtinCounts()

java

public List<Integer> builtinCounts();

行为：内置判定计数列表，顺序固定为 PERFECT / GREAT / MISS，供遍历渲染判定行。示例：

java

List<Integer> counts = snap.builtinCounts();
int perfectCount = counts.get(0);

equals(Object)

java

public boolean equals(Object obj);

行为：记录类型按全部 22 个组件逐值比较（自动生成）。示例：

java

boolean same = snap.equals(other);

hashCode()

java

public int hashCode();

行为：记录类型按全部 22 个组件生成哈希（自动生成）。示例：

java

int h = snap.hashCode();

toString()

java

public String toString();

行为：记录类型默认字符串形式，仅用于调试输出。示例：

java

System.out.println(snap);

完整签名

java

public record ResultSnapshot(
        String chartFile,
        String title,
        String artist,
        String difficulty,
        String level,
        int bpm,
        int totalNotes,
        String modeId,
        boolean storyMode,
        boolean internalChart,
        int score,
        int maxCombo,
        double accuracy,
        String grade,
        boolean cleared,
        boolean fullCombo,
        boolean newRecord,
        int hp,
        int perfects,
        int greats,
        int misses,
        Map<String, Integer> customKindCounts
) {
    public String chartFile();
    public String title();
    public String artist();
    public String difficulty();
    public String level();
    public int bpm();
    public int totalNotes();
    public String modeId();
    public boolean storyMode();
    public boolean internalChart();
    public int score();
    public int maxCombo();
    public double accuracy();
    public String grade();
    public boolean cleared();
    public boolean fullCombo();
    public boolean newRecord();
    public int hp();
    public int perfects();
    public int greats();
    public int misses();
    public Map<String, Integer> customKindCounts();
    public List<Integer> builtinCounts();
    public boolean equals(Object obj);
    public int hashCode();
    public String toString();
}

紧凑构造的 null 防御：chartFile / title / artist / difficulty / level / grade / modeId 为 null 时一律替换为空串；customKindCounts 为 null 时替换为 Map.of()，否则 Map.copyOf。

线程：源码未声明额外线程约束（记录为不可变值对象，组件集合亦被复制为不可变视图）。

性能：源码未标注额外性能约束（宿主每帧构造一份，customKindCounts 在构造时复制）。

稳定性：2.0 起冻结：2.x 内只增不破。builtinCounts() 为后加方法（纯增）。

上一页ResultLayout 下一页场景抽象（scene 包）