dtxmania导入时谱面不显示？

Question

在使用DTXMania导入自制或第三方谱面时，常出现谱面不显示的问题。主要原因包括：谱面文件（.dtx）路径含有中文或特殊字符导致解析失败、INI配置文件中曲目路径未正确指向谱面位置、图像或音效资源缺失引发加载中断，以及DTXMania版本与谱面格式不兼容。此外，部分用户忽略“#BPM”、“#WAVxx”等关键指令的定义，也会造成谱面无法正常读取。建议检查文件编码是否为Shift-JIS，确认资源文件与谱面同目录，并通过日志窗口查看具体报错信息以定位问题。

Answer 1

1. 常见现象与初步排查

在使用DTXMania导入自制或第三方谱面时，用户常遇到谱面无法显示的问题。最直观的表现是：曲目列表中无该歌曲、加载后黑屏、或游戏直接跳过该曲目。这类问题通常源于文件路径、资源缺失或配置错误。

• 检查.dtx文件是否放置于Data/Songs/目录下
• 确认.dtx文件名不含中文、空格或特殊字符（如#、&、%）
• 查看主界面是否能识别到新添加的曲目缩略图
• 启动DTXMania时观察控制台是否有异常输出

2. 路径与编码问题深度分析

DTXMania对文件系统路径极为敏感，尤其是Windows环境下使用中文用户名或项目路径含有UTF-8字符时，极易导致解析失败。其底层采用C++标准库进行文件流读取，未做Unicode路径兼容处理。

路径类型	是否推荐	原因说明
C:\Users\张伟\Music\test.dtx	❌ 不推荐	含中文用户名，易引发fopen失败
D:/DTX/Song01/test.dtx	✅ 推荐	全英文路径，斜杠兼容性好
E:\Songs\new#song.dtx	❌ 不推荐	#符号被误认为BPM指令起始符

此外，.dtx文件必须保存为Shift-JIS编码格式。尽管UTF-8为现代主流编码，但DTXMania仅支持日文原生编码，否则将出现“Invalid command”报错。

3. INI配置与资源映射机制

DTXMania通过song.ini文件定义曲目元数据与资源路径映射关系。若INI中Folder字段未正确指向.dtx所在目录，则会导致资源加载中断。

[info]
Title=My Custom Chart
Artist=Tanaka
Folder=./charts/custom_song/

上述配置要求custom_song目录内包含对应的.dtx及所有WAV、BMP资源。常见错误包括：

1. #WAVxx指令引用的音频文件未存在于同级目录
2. 图像资源（如back.bmp）命名与#PATH_WAV指令不一致
3. 未定义#BPM指令，导致节拍引擎无法初始化

4. 版本兼容性与格式演进

不同版本DTXMania支持的谱面语法存在差异。例如v104.x系列引入了新的HS指令（Hidden Scroll），而旧版解析器会将其忽略甚至报错。

graph TD
    A[DTX File Loaded] --> B{Version Check}
    B -->|v103 or lower| C[Parse Legacy Syntax]
    B -->|v104+| D[Enable HS, LN, FX Commands]
    C --> E[Fail on Unknown Commands]
    D --> F[Render Successfully]

建议用户根据所用DTXMania版本选择对应规范编写谱面，避免使用超前指令。

5. 日志诊断与自动化检测流程

启用调试模式可在启动参数中加入-log生成详细日志。典型错误日志示例如下：

[ERROR] Failed to open WAV file: SE_A.wav
[WARNING] #BPM not defined at line 42
[FATAL] Invalid path encoding in D:\音乐\chart.dtx

基于此可构建自动化检测脚本，实现如下功能：

• 扫描目录中所有.dtx文件编码
• 验证#WAVxx与实际文件名匹配度
• 检查是否存在未定义的#BPM默认值（默认为120）