FNF模组开发实战：QT-rewired重置版谱面编辑器完整指南-平芜编程栈

最近在整理游戏模组开发笔记时，发现很多朋友对《Friday Night Funkin'》（FNF）的模组制作，特别是音游谱面编辑器“QT-rewired”的重置版非常感兴趣。网上的教程要么过于零散，要么版本老旧，导致新手在配置环境和上手制作时频频踩坑。本文将围绕FNF模组“QT-rewired”重置版，从核心概念、环境搭建、手打演示到最终发布，提供一套完整的闭环实操指南。无论你是想为自己喜欢的歌曲制作谱面，还是想深入学习FNF模组开发，都能从本文中找到可直接复用的代码、配置和避坑方案。

1. 背景与核心概念：什么是FNF与QT-rewired？

在深入实操之前，我们先厘清几个核心概念，这对于后续理解整个工作流程至关重要。

Friday Night Funkin‘ (FNF)是一款使用HaxeFlixel引擎开发的开源节奏音乐游戏。其最大的魅力在于其极高的可扩展性，玩家和开发者可以基于原版游戏，通过替换美术资源、编写新歌曲和谱面，创造出全新的游戏模组（Mod）。一个完整的FNF模组通常包含新的角色（Sprite）、背景（Stage）、歌曲（Music）以及最核心的谱面数据（Chart）。

QT-rewired正是为FNF谱面制作而生的专用编辑器。你可以把它理解为一个“音游谱面DAW（数字音频工作站）”。最初的版本由KadeDev开发，而“重置版”（Rewritten）通常指社区在原始基础上进行优化、修复Bug并增加新功能的版本。它提供了一个可视化的时间轴界面，让创作者可以直观地放置音符（Note）、定义对手的演唱段落（Sections），并实时预览谱面与音乐的同步效果。

为什么需要掌握QT-rewired？对于FNF模组开发者而言，直接编写JSON格式的谱面文件不仅效率低下，而且极易出错。QT-rewired将这个过程图形化、标准化：

可视化编辑：在时间轴上直接点击放置音符，支持缩放、多选、复制粘贴。
实时预览：编辑的同时可以播放音乐，确保每个音符都卡在节拍上。
数据导出：一键生成FNF游戏引擎可识别的标准.json谱面文件。
社区兼容：生成的谱面文件能与大多数主流FNF模组引擎（如Psych Engine, Kade Engine）兼容。

简单来说，QT-rewired是连接你的音乐创意与可游玩FNF模组之间的核心生产工具。

2. 环境准备与版本说明

工欲善其事，必先利其器。要运行QT-rewired重置版并进行模组开发，你需要配置一个完整的FNF开发环境。请注意，版本兼容性是成功的第一步。

2.1 基础运行环境

操作系统：Windows 10/11, macOS, 或 Linux (本文以Windows为例进行演示)。
存储空间：至少预留2-3GB可用空间用于存放游戏本体、编辑器及资源。

2.2 核心依赖安装

QT-rewired本身是一个Haxe项目，因此需要先搭建Haxe开发环境。

安装Haxe：
- 访问 Haxe 官网下载安装包。本文示例使用 Haxe 4.2.5 版本，这是一个长期稳定版本，对FNF生态兼容性最好。
- 安装时，务必勾选“Neko”和“Visual Studio Code 支持”等选项。
- 安装完成后，打开命令提示符（CMD）或 PowerShell，输入以下命令验证：
```
haxe -version
```
  应输出4.2.5或类似版本号。
安装HaxeLib库： FNF及其工具链依赖一系列Haxe库。通过Haxe的包管理器haxelib安装。逐一执行以下命令：
```
haxelib install lime haxelib install openfl haxelib install flixel haxelib install flixel-tools haxelib install hscript haxelib install polymod
```
安装过程中如果询问是否安装依赖，一律选择“Y”。安装完成后，使用haxelib list可以查看已安装的库。
安装Git：用于克隆项目代码。从 Git 官网下载并安装。

2.3 获取QT-rewired重置版源码

我们不推荐下载不明来源的编译后程序，从源码构建能确保安全并获得最新功能。

在你想存放项目的目录（例如D:\FNF_Dev）中打开命令行。
克隆一个社区维护较好的QT-rewired重置版仓库。例如：
```
git clone https://github.com/ShadowMario/FNF-PsychEngine.git --depth 1
```
注意：Psych Engine是一个流行的FNF模组引擎，其源码仓库的tools文件夹下通常包含了最新版的QT-rewired。你也可以直接搜索“fnf qt-rewired source”寻找独立仓库。
进入工具目录：
```
cd FNF-PsychEngine/tools
```
这里就是QT-rewired编辑器的源码目录。

2.4 安装并配置Visual Studio Code (推荐)

VSCode是Haxe开发的绝佳编辑器，拥有强大的代码提示和调试功能。

安装VSCode。
在VSCode扩展商店中搜索并安装Haxe Extension Pack。
用VSCode打开上一步的tools文件夹。

至此，你的开发环境已经就绪。

3. QT-rewired编辑器核心功能拆解

在构建和运行编辑器之前，我们先了解其界面和核心功能，这样在使用时能更有目的性。

一个典型的QT-rewired重置版界面包含以下区域：

菜单栏 (Menu Bar)：文件操作（新建、打开、保存）、编辑、视图设置和测试播放。
时间轴视图 (Timeline View)：核心工作区。水平轴是时间（以节拍和毫秒显示），垂直轴是音轨（对应游戏中的左、下、上、右四个按键）。
音符放置板 (Note Grid)：通常与时间轴关联，以网格形式辅助你对齐节拍。
属性面板 (Properties Panel)：选中一个音符或段落时，可以在此调整其详细属性，如音符类型（普通、长按）、对手演唱段落（Section）的BPM变化等。
音乐播放控制：播放、暂停、停止，以及跳转到特定时间点。

核心概念对应游戏机制：

Note (音符)：玩家需要按下的键。对应游戏中的左、下、上、右四个箭头。
Section (段落)：定义一段音乐的基本属性，包括：
- BPM：每分钟节拍数，决定游戏速度。
- 必须命中节拍：布尔值，开启后音符必须严格落在节拍线上。
- 换行符：改变对手演唱的歌词行。
事件 (Events)：高级功能，用于触发游戏内的特殊效果，如镜头移动、角色动画切换等。

4. 完整实战：构建、运行并制作你的第一张谱面

现在，让我们从零开始，创建一张属于你自己的简单谱面。

4.1 构建并启动QT-rewired编辑器

在VSCode中，打开终端（Terminal -> New Terminal），确保当前路径在tools目录下。

安装项目依赖：
```
haxelib install all
```
此命令会读取项目根目录的haxelib.json文件，并安装所有列出的依赖库。
编译并运行编辑器：
```
lime test windows -debug
```
如果你是macOS用户，将windows替换为mac；Linux用户替换为linux。首次编译会花费几分钟时间，成功后会自动弹出QT-rewired编辑器的窗口。

4.2 创建新谱面项目

在QT-rewired中，点击File -> New。
你需要关联一首音乐文件。准备一首.ogg格式的音频文件（FNF标准格式），例如my_song.ogg。点击Load Song并选择它。
编辑器会自动解析音频长度。你需要设置初始BPM（例如，120）。可以在右侧属性面板的第一个Section里设置。
点击File -> Save，将谱面项目保存为my_song.chart。注意，这只是编辑器项目文件。

4.3 手打演示：绘制基础谱面

我们以制作一段简单的4/4拍循环为例。

缩放与定位：使用鼠标滚轮缩放时间轴，拖动时间轴区域进行平移，找到开始位置（如第0秒）。
放置音符：
- 在工具栏选择“音符笔刷”。
- 在时间轴的第1拍（Beat 0.00）处，点击“左”箭头音轨，放置一个音符。
- 在第2拍（Beat 1.00）处，点击“下”箭头音轨。
- 在第3拍（Beat 2.00）处，点击“上”箭头音轨。
- 在第4拍（Beat 3.00）处，点击“右”箭头音轨。这样，一个最简单的四连音就完成了。你可以看到四个不同颜色的菱形标记出现在时间轴上。
播放测试：
- 点击播放按钮或按空格键。
- 编辑器会播放音乐，并有一个垂直的播放头随着时间移动。当播放头经过你放置的音符时，该音符会高亮。这是检查音符是否卡准节拍的关键步骤。
- 如果发现音符偏移，可以鼠标拖动音符微调其位置。

4.4 添加段落与BPM变化

让谱面更有变化。

添加新段落：在时间轴上方（Section行）的Beat 4.00处右键，选择“Add Section”。这会创建一个新的段落。
改变BPM：选中新创建的Section，在右侧属性面板，将BPM从120修改为150。你会注意到，从此Section往后，时间轴的网格密度发生了变化，表示节奏变快了。
在新段落放置音符：在新的、更快的节奏下，以半拍（Beat 4.00, 4.50, 5.00, 5.50）为间隔，放置一组交替的“左”和“右”音符。

4.5 导出为FNF游戏谱面文件

编辑器项目（.chart）不能被游戏直接读取，需要导出为游戏引擎识别的JSON格式。

点击File -> Export to JSON。
选择保存位置。通常，你需要将其保存到你的FNF模组歌曲目录中，例如：FNF-PsychEngine/assets/songs/my_song/。
文件应命名为my_song-hard.json（假设这是困难难度）。FNF支持多种难度，通常导出为-easy.json,-normal.json,-hard.json。

4.6 在游戏中测试

确保你的FNF游戏（如Psych Engine）已正确放置模组资源（歌曲音频Inst.ogg、人声Voices.ogg、图标等）。
将上一步导出的JSON文件放入对应的歌曲文件夹。
运行FNF游戏，在自由模式（Freeplay）或故事模式（Story Mode）中找到你的歌曲并播放。
实地游玩测试是最终检验标准，感受音符手感，记录下需要调整的地方。

5. 常见问题与排查思路

在实际操作中，你肯定会遇到各种问题。下表汇总了高频问题及其解决方案：

问题现象	可能原因	排查与解决思路
编译失败：`Class not found`	Haxe库未安装或版本冲突。	1. 在项目根目录执行`haxelib install all`。 2. 检查`haxelib.json`，确保所有库名正确。 3. 尝试`haxelib upgrade`更新库，或指定版本`haxelib install lib_name version`。
编辑器打开后闪退	图形驱动问题或项目路径包含中文/特殊字符。	1. 更新显卡驱动。 2. 将项目移动到纯英文路径下，如`D:\FNF\qt_rewired`。 3. 以管理员身份运行命令行进行编译。
音乐文件无法加载	音频格式不支持或文件损坏。	1. FNF及QT-rewired主要支持`.ogg`格式。使用格式工厂等工具将MP3等转换为OGG。 2. 确保音频文件没有损坏，可以在其他播放器中试听。
导出的谱面游戏不识别	JSON文件格式错误或存放路径不对。	1. 用文本编辑器打开JSON文件，检查是否为标准JSON格式（可使用在线JSON校验工具）。 2.确保JSON文件放在正确的歌曲目录下，且文件名与游戏代码中读取的命名规则一致（如`songName-hard.json`）。 3. 对比游戏原版谱面JSON的结构，检查是否有必填字段缺失。
音符播放时不同步	BPM设置错误或音频偏移未校准。	1.核对音乐的实际BPM。使用专业测速软件（如Mixxx, Ableton Live）或在线测速网站获取精确BPM。 2. 在QT-rewired的歌曲设置中，调整`Offset`（偏移量）值，单位毫秒。正值让音符提前，负值让音符延后。这是一个反复测试的微调过程。
长按音符（Hold Notes）无法正常绘制	编辑器模式未切换或重置版功能支持问题。	1. 检查编辑器是否有“长按音符”的绘制模式开关。 2. 部分重置版可能对长按音符支持不完善，查阅该版本QT-rewired的文档或Issues。
保存项目失败	文件被占用或无写入权限。	1. 关闭可能占用该文件的程序。 2. 尝试将项目保存到其他目录或桌面。

6. 最佳实践与工程建议

掌握了基础操作后，遵循一些最佳实践能让你的模组制作过程更高效，作品质量更高。

6.1 谱面设计原则

循序渐进：为同一首歌制作多难度谱面（Easy, Normal, Hard）。Easy难度应只使用基本的四分音符和八分音符，Hard难度再引入十六分音符、和弦（同时按多个键）和复杂节奏型。
贴合音乐：音符的排列应反映音乐的旋律、鼓点或人声亮点，让玩家有“演奏音乐”的感觉，而不是机械地击打。
休息与呼吸：不要在整首歌中塞满音符。适当的空拍能让玩家有喘息之机，并突出后续的密集段落。
可读性优先：避免在同一时间点放置过多音符（“叠键”），除非音乐本身是密集和弦。确保在快速段落中，音符的排列模式有规律可循。

6.2 项目文件管理规范

混乱的文件管理是协作和后期维护的噩梦。

你的模组项目根目录/ ├── assets/ │ ├── songs/ │ │ ├── my_song_1/ │ │ │ ├── Inst.ogg # 伴奏 │ │ │ ├── Voices.ogg # 人声 │ │ │ ├── my_song_1-easy.json │ │ │ ├── my_song_1-normal.json │ │ │ └── my_song_1-hard.json │ │ └── my_song_2/ │ │ └── ... │ └── images/ # 角色、背景等图片 ├── source/ # Haxe源代码 ├── tools/ # QT-rewired编辑器项目 └── README.md # 项目说明文档

命名一致：歌曲文件夹、音频文件、JSON文件的核心名称部分保持一致。
版本控制：使用Git管理你的模组源码和资源。将大的音频、视频文件添加到.gitignore，使用Git LFS或提供下载链接。
备份：定期备份你的QT-rewired项目文件（.chart），它是你所有编辑工作的原始文件，比JSON更易于二次编辑。

6.3 性能与兼容性优化

音频优化：确保OGG音频的比特率适中（通常128-192kbps即可），过高的比特率会增加游戏加载时间和内存占用。
JSON精简：虽然QT-rewired导出的JSON包含完整数据，但可以手动清理其中为null的字段或测试用的空事件数组，以轻微减小文件体积。
引擎特性：了解你目标模组引擎（如Psych Engine）的特有事件和功能，并在QT-rewired中合理利用（如果支持），但也要做好回退方案，以保持与其他引擎的基础兼容性。

6.4 协作与社区分享

文档化：在模组README中说明谱面作者、使用的工具版本、BPM、偏移量等关键信息。
测试反馈：发布前，邀请不同水平的玩家进行测试，收集关于难度梯度、同步准确性和趣味性的反馈。
遵守规范：尊重原版游戏和社区规则，使用原创或已获授权的素材，在发布时明确标注素材来源。

从环境搭建到谱面导出，整个流程涉及多个环节，任何一个步骤的疏漏都可能导致最终效果不如预期。关键在于耐心调试和反复测试——尤其是音符与音乐的同步，这直接决定了模组的游玩体验。建议从改编一首BPM稳定、结构简单的歌曲开始练手，逐步挑战更复杂的作品。

当你成功完成第一个可游玩的谱面后，后续学习可以转向更高级的方向：研究Psych Engine等高级模组引擎的源码，理解其如何解析和渲染你的JSON谱面数据；学习Haxe语言，尝试为QT-rewired编辑器添加自定义功能；甚至深入研究音乐理论，让你的谱面设计更具艺术性和专业性。FNF模组创作是一个融合了编程、音乐和设计的创造性领域，希望这篇指南能为你打开这扇门。