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

ChartView

谱面元数据只读视图。由 GameplayContext 的 chartView() 提供，模组可读取当前谱面的标题、作者、难度、时长、BPM、音符数、轨道数、extensions 扩展段解析结果与谱面文件路径。

方法速览

方法	用途
`title()`	谱面标题
`author()`	谱面作者
`difficulty()`	难度名
`durationMs()`	谱面总时长（末音符）
`bpm()`	0ms 处主 BPM
`totalNoteCount()`	总音符数（Hold 算 1）
`laneCount()`	轨道数
`extensions()`	JSON `extensions` 解析结果
`chartPath()`	谱面主文件路径（可能为 `null`）

title()

java

String title();

行为：谱面标题；元数据缺失时为空串（宿主对 null 做了防御）。示例：

java

String title = chart.title();

author()

java

String author();

行为：谱面作者（metadata.charter）；缺失时为空串。示例：

java

String author = chart.author();

difficulty()

java

String difficulty();

行为：难度名；缺失时为空串。示例：

java

String diff = chart.difficulty();

durationMs()

java

long durationMs();

行为：谱面总时长（毫秒），取末个音符的结束时间（长音符取 endTime）；无音符时为 0。与 GameplayContext.chartDurationMs() 同源。示例：

java

long len = chart.durationMs();

bpm()

java

int bpm();

行为：谱面 0ms 处的主 BPM（四舍五入为 int）；无 BPM 信息时为 0。示例：

java

int bpm = chart.bpm();

totalNoteCount()

java

int totalNoteCount();

行为：谱面总音符数（Hold 算 1）。示例：

java

int total = chart.totalNoteCount();

laneCount()

java

int laneCount();

行为：谱面轨道数；谱面未加载时为 0。示例：

java

int lanes = chart.laneCount();

extensions()

java

Map<String, Object> extensions();

行为：谱面 JSON extensions 段的解析结果，不可变视图（宿主以 unmodifiableMap 零拷贝包装，无扩展段时为空 Map）。示例：

java

Object custom = chart.extensions().get("mymod");

chartPath()

java

Path chartPath();

行为：当前游玩谱面的主 JSON 文件路径（如 data/charts/xxx.json）。可据此定位谱面目录（getParent()）与文件基名，按约定读取同目录的 <基名>_mods.json（编辑器插件事件文件），或解析谱面相对路径的资源引用。路径不可用（或路径字符串非法）时返回 null，调用方必须判空。示例：

java

Path p = chart.chartPath();
Path mods = p != null ? p.resolveSibling(
        p.getFileName().toString().replaceFirst("\\.json$", "_mods.json")) : null;

完整签名

java

public interface ChartView {
    String title();
    String author();
    String difficulty();
    long durationMs();
    int bpm();
    int totalNoteCount();
    int laneCount();
    Map<String, Object> extensions();
    Path chartPath();
}

线程：源码未声明额外线程约束。

性能：源码未标注额外性能约束（extensions() 为不可变视图，chartPath() 为 null 或构造期解析的 Path）。

稳定性：2.0 起冻结：2.x 内只增不破。

上一页HudValues 下一页NoteView