最近在B站刷到不少FNFFriday Night Funkin的二次创作视频尤其是那些基于QT引擎的模组Mod视觉效果和玩法都让人眼前一亮。很多开发者包括一些刚接触游戏开发的朋友都很好奇一个完整的FNF QT模组从零到一到底是怎么做出来的为什么网上有些演示视频看起来丝滑流畅而自己动手时却总是遇到各种奇怪的Bug比如角色动画错位、音符判定不准甚至游戏直接崩溃本文将从一个完整的实战项目出发为你拆解FNF QT模组的开发全流程。我们将制作一个包含两个版本的模组一个是“失误版本”模拟开发中常见的错误和问题另一个是“完美版本”展示修复后的正确实现。通过这种对比你不仅能掌握QT引擎如Psych Engine模组开发的核心技术栈更能深刻理解那些“坑”在哪里以及如何系统性地规避和解决。无论你是想为FNF制作自己的原创角色和歌曲还是想深入学习Haxe语言和游戏Mod开发这篇文章都能提供一条清晰的路径。1. 背景与核心概念什么是FNF与QT模组在开始敲代码之前我们有必要厘清几个核心概念这能帮助你更好地理解整个开发框架。Friday Night Funkin‘ (FNF)是一款使用Haxe语言和HaxeFlixel框架开发的开源节奏游戏。玩家需要根据屏幕上落下的音符在正确的时机按下对应方向键让游戏角色“说唱”并击败对手。其开源特性和强大的社区支持催生了海量的玩家自制模组。“QT模组”通常指的是基于Psych Engine的模组。Psych Engine是一个为FNF社区开发的高级、优化过的游戏引擎分支俗称“QT引擎”它提供了比原版更强大的功能例如更灵活的动画系统、内置的关卡编辑器、复杂的脚本事件支持等。因此现在社区提到“做QT模组”大多是指基于Psych Engine进行二次开发。一个完整的模组Mod通常包含以下几个部分资产Assets图像角色精灵图、背景、声音音乐、音效、字体等。数据Data定义每周Week、歌曲Song、角色Character的JSON配置文件。代码Code用Haxe编写的游戏逻辑可能包括新的游戏机制、UI、特殊效果等。脚本ScriptsPsych Engine支持使用Haxe脚本.hx文件或类Lua脚本.lua文件在运行时动态修改游戏行为这是实现复杂效果的关键。本次实战我们将创建一个名为“TutorialMod”的模组包含一首原创歌曲和一个自定义角色并分别实现“失误”与“完美”两个版本。2. 环境准备与版本说明工欲善其事必先利其器。搭建一个稳定、版本匹配的开发环境是成功的第一步。核心环境要求操作系统Windows 10/11 macOS 或 Linux。本文以Windows为例。编程语言Haxe 4.2.5。这是Psych Engine使用的稳定版本不推荐使用最新的Haxe 4.3可能存在兼容性问题。游戏引擎Psych Engine 0.7.1h。这是社区广泛使用且文档相对齐全的一个稳定版本。集成开发环境IDEVisual Studio Code “Haxe Extension Pack”插件。这是最主流的Haxe开发环境。版本控制Git可选但强烈推荐用于管理你的模组项目。详细安装与配置步骤2.1 安装Haxe与Haxelib下载Haxe访问Haxe官网下载Haxe 4.2.5的Windows安装程序。安装运行安装程序记得勾选“将Haxe添加到系统环境变量”选项。验证安装打开命令提示符CMD或PowerShell输入以下命令haxe -version haxelib version如果正确显示版本号如4.2.5说明安装成功。2.2 安装Psych Engine依赖Psych Engine通过HaxelibHaxe的包管理器管理依赖。打开命令行依次安装以下关键库。请严格按照顺序和指定版本安装这是避免后续编译错误的关键。haxelib install lime 8.0.1 haxelib install openfl 9.2.1 haxelib install flixel 5.4.1 haxelib install flixel-tools 1.5.2 haxelib install flixel-ui 2.7.1 haxelib install hscript 2.5.0 haxelib install polymod 1.6.0 haxelib install discord_rpc 2.0.0运行haxelib list检查所有库是否已正确安装。2.3 获取Psych Engine源代码使用Git克隆Psych Engine仓库到本地如果没有Git可以直接下载ZIP包解压git clone https://github.com/ShadowMario/FNF-PsychEngine cd FNF-PsychEngine建议切换到0.7.1h标签以确保版本一致git checkout 0.7.1h2.4 配置VSCode与项目用VSCode打开FNF-PsychEngine文件夹。安装扩展搜索并安装 “Haxe Extension Pack”。首次打开项目VSCode可能会提示你选择Haxe版本。选择你安装的4.2.5。在项目根目录下你应该能看到project.xml、export、source等关键文件夹。至此基础环境搭建完成。接下来我们将在mods目录下创建我们的模组。3. 模组项目结构与核心文件解析一个标准的Psych Engine模组其文件结构是高度规范化的。理解这个结构是组织代码和资源的基础。在我们的FNF-PsychEngine/mods/目录下创建名为TutorialMod的文件夹。结构如下TutorialMod/ ├── _append/ # (可选) 用于向游戏原有列表追加内容 ├── _core/ # (可选) 核心代码覆盖 ├── characters/ # 角色定义文件 │ └── tutorial-bf.json # 我们的自定义角色定义 ├── data/ # 歌曲和每周数据 │ ├── tutorial-song/ # 歌曲专属文件夹 │ │ ├── tutorial-song.json # 歌曲配置文件 │ │ └── tutorial-song.mp3 # 歌曲音频文件 │ └── weeks.json # 每周列表定义 ├── images/ # 图像资源 │ ├── characters/ # 角色精灵图 │ │ └── tutorial-bf.png │ ├── stages/ # 舞台背景 │ │ └── tutorial-stage.png │ └── icons/ # 角色图标用于选歌界面 │ └── tutorial-bf-icon.png ├── sounds/ # 音效如打击音效 ├── videos/ # 过场视频 ├── scripts/ # Haxe或Lua脚本 ├── mods-list.txt # 模组列表文件需手动添加 └── pack.json # 模组元数据描述文件核心配置文件详解pack.json模组的“身份证”。{ name: Tutorial Mod, description: A mod to demonstrate common mistakes and fixes., version: 1.0.0, releasestate: stable, tags: [tutorial], characters: [ { name: tutorial-bf, icon: icons/tutorial-bf-icon.png, color: 0x31b0d5 } ], songs: [ { name: Tutorial Song, character: tutorial-bf, color: 0x31b0d5, difficulties: [easy, normal, hard], week: 1 } ] }characters和songs数组定义了本模组引入的内容游戏会根据这个列表加载。角色JSON文件 (characters/tutorial-bf.json)定义角色的所有属性。{ animations: [ { anim: idle, name: BF IDLE, fps: 24, loop: true, indices: [], offsets: [0, 0] }, { anim: singLEFT, name: BF LEFT NOTE, fps: 24, loop: false, indices: [], offsets: [0, 0] } // ... 其他动画定义 ], image: characters/tutorial-bf, scale: 1.0, sing_duration: 4, healthicon: tutorial-bf, position: [770, 450], camera_position: [0, 0], flip_x: false, healthbar_colors: [0x31b0d5, 0x31b0d5] }animations每个动画对应一个精灵图帧序列。indices为空表示使用所有帧。offsets动画的偏移量用于微调角色在舞台上的位置。这里是“失误版本”的常见雷区。歌曲JSON文件 (data/tutorial-song/tutorial-song.json)定义歌曲的元数据和谱面。{ song: { song: Tutorial Song, notes: [ { sectionNotes: [ [0, 0, 0], [500, 2, 0], [1000, 1, 0] ], sectionBeats: 4, typeOfSection: 0, mustHitSection: true, bpm: 150, changeBPM: false, altAnim: false } // ... 更多小节 ], events: [], bpm: 150, needsVoices: true, player1: tutorial-bf, player2: dad, speed: 2.5, stage: tutorial-stage } }sectionNotes谱面数据。[时间戳(ms), 轨道(0-3), 音符类型(0普通, 1长按开始, 2长按结束)]。时间戳错误是“失误版本”的另一个重灾区。speed音符滚动速度。stage对应的舞台背景名称。4. 实战案例从“失误版本”到“完美版本”现在我们开始实际创建模组内容。我们将故意在“失误版本”中埋下几个典型错误然后在“完美版本”中修复。4.1 创建基础模组结构按照第3节的目录结构在mods/TutorialMod/下创建所有必要的文件夹和文件。确保你的图像和音频文件已放入正确位置。精灵图如tutorial-bf.png需要是包含所有动画帧的横向或纵向图集Psych Engine支持XML或TXT格式的图集描述文件但最简单的方式是使用等间距帧并在JSON中通过indices或留空来定义。4.2 “失误版本”实现与问题复现在这个版本中我们故意制造三个常见问题。问题一角色动画偏移错误在tutorial-bf.json中我们为singLEFT动画设置一个离谱的偏移量{ anim: singLEFT, name: BF LEFT NOTE, fps: 24, loop: false, indices: [], offsets: [150, -100] // 错误示范偏移过大 }后果当角色向左唱歌时精灵图会严重偏离其基准位置可能飞到屏幕外或与音符位置不匹配。问题二谱面时间戳计算错误在tutorial-song.json中我们错误地计算了时间戳。假设BPM是150那么每拍的时间是60000 / 150 400ms。如果我们想在第2拍索引为1因为从0开始的“右”轨道轨道2放置一个音符正确时间戳是400 * 1 400ms。但我们错误地写成了sectionNotes: [ [400, 2, 0], // 意图第2拍右箭头 [800, 0, 0], // 意图第3拍左箭头 错误 [1200, 1, 0] ],实际上如果BPM是150第3拍的时间戳应该是400 * 2 800ms但这里[800, 0, 0]从数值上看是800ms如果这是第3拍左箭头那它是对的。但常见的错误是忘记将音乐编辑软件中的节拍数从1开始转换为以0开始的时间索引或者在变速BPM Change段落计算错误。更典型的错误是直接使用秒数而不是毫秒。问题三资源路径或名称拼写错误在pack.json中我们将角色图标路径写错icon: icons/tutorial-bf-ico.png // 错误实际文件是 tutorial-bf-icon.png后果在游戏自由模式Freeplay中该角色的图标无法加载显示为默认的“”图标或导致游戏崩溃。4.3 编译、测试与问题现象添加模组到列表在mods/mod-list.txt文件中添加一行TutorialMod确保游戏能识别它。编译游戏在VSCode中按F5或根据你的配置选择“Debug”模式编译并运行Psych Engine。你也可以在命令行执行lime test windows或其他目标平台。进入游戏测试在主菜单进入“自由模式Freeplay”。你应该能看到“Tutorial Song”但角色图标可能显示错误问题三。选择歌曲并开始游戏。观察问题一当按下左方向键时tutorial-bf角色的动画会“跳”到一个奇怪的位置。观察问题二音符的下落节奏与音乐节拍对不上感觉要么太快要么太慢或者根本不在拍子上。玩家会感觉游戏“手感”极差。4.4 “完美版本”修复方案现在我们逐一修复上述问题。修复一校正动画偏移动画偏移offsets的[x, y]用于微调该动画帧在角色position基础上的最终显示位置。通常需要通过反复测试来调整。对于对称的角色很多动画的偏移可能是[0, 0]。我们可以先设为[0, 0]然后在游戏中观察如果向左唱歌时手臂位置不对再慢慢调整例如[10, 5]。{ anim: singLEFT, name: BF LEFT NOTE, fps: 24, loop: false, indices: [], offsets: [0, 0] // 修正先归零再根据视觉微调 }最佳实践使用Psych Engine内置的“角色编辑器”Character Editor或第三方工具如“Friday Night Funkin‘ Character Editor”来可视化地调整偏移和位置这比手动修改JSON高效准确得多。修复二精确计算谱面时间戳确保你理解时间戳单位是毫秒ms。计算时间戳的公式是时间戳 (节拍数 * (60000 / BPM))。节拍数从0开始计数。第1小节第1拍是0第1小节第2拍是1以此类推。如果歌曲中有BPM变化计算会复杂很多。强烈建议使用专业的谱面编辑器如Psych Engine 内置的关卡编辑器在游戏调试菜单按7中开启这是最原生、最准确的方式。第三方工具如“FNF Chart Editor”可以导入音频可视化地放置音符并导出为Psych Engine兼容的JSON。使用编辑器生成的sectionNotes会是绝对正确的例如sectionNotes: [ [0, 0, 0], // 第0拍左箭头 [400, 1, 0], // 第1拍下箭头 [800, 2, 0], // 第2拍上箭头 [1200, 3, 0] // 第3拍右箭头 ],修复三严格核对资源路径与名称养成严格一致的文件命名习惯并使用编辑器的“复制路径”功能来避免手动输入错误。icon: icons/tutorial-bf-icon.png // 修正与文件名完全一致同时检查所有JSON文件中引用的图像、声音键名是否与文件名不含扩展名匹配。例如image: characters/tutorial-bf对应images/characters/tutorial-bf.png。4.5 最终测试与效果对比修复所有问题后重新编译并运行游戏。自由模式现在可以看到正确的角色图标和歌曲信息。游戏过程角色动画流畅唱歌时动作与音符方向匹配位置稳定。音符精准地落在音乐节拍上游戏体验丝滑。没有崩溃或资源缺失错误。至此你已经成功将一个充满Bug的“失误版本”模组修复成了一个可正常游玩的“完美版本”。这个对比过程深刻揭示了模组开发中细节的重要性。5. 常见问题与排查思路在模组开发中你肯定会遇到各种报错和异常。下面是一个快速排查清单。问题现象可能原因排查步骤与解决方案编译失败Haxe报错1. Haxe或Haxelib版本不对。2. 依赖库缺失或版本冲突。3. 源代码语法错误。1. 确认Haxe为4.2.5用haxelib list检查核心库版本是否与上文一致。2. 运行haxelib upgrade更新所有库或删除~/.haxelib缓存重新安装。3. 检查VSCode的错误提示定位到具体文件行。游戏能编译但启动后黑屏/闪退1. 模组JSON格式错误。2. 资源文件路径错误或格式不支持。3. 脚本.hx/.lua语法错误。1. 使用JSON验证工具检查所有JSON文件。2. 检查控制台输出如果可用看是否有“Failed to load image/sound”错误。3. 暂时移除scripts/文件夹内的脚本看是否正常。角色/背景不显示1. JSON中image路径错误。2. 图片文件损坏或格式不对。3. 图片尺寸过大非2的幂次方。1. 确认路径是相对于images/文件夹的且不带扩展名。2. 尝试用其他图片替换测试。3. 将图片尺寸调整为如1024x1024、512x512等。音符与音乐不同步1. 歌曲JSON中的bpm值错误。2.sectionNotes时间戳计算错误。3. 音频文件本身有空白开头。1. 用音频软件如Audacity准确测量歌曲BPM。2.务必使用内置关卡编辑器制作谱面。3. 修剪音频文件确保第一个节拍从文件开头开始。动画播放错乱或偏移1. JSON中animations的indices定义错误。2.offsets值不合理。3. 精灵图帧顺序或尺寸不统一。1. 确认indices数组与精灵图帧数匹配。留空[]表示使用所有帧。2. 使用角色编辑器进行可视化调整。3. 确保精灵图每一帧的尺寸相同。在自由模式中看不到模组歌曲1.pack.json中songs未定义或格式错误。2.mods-list.txt中没有添加模组名。3. 歌曲JSON文件不在正确的data/子文件夹内。1. 仔细检查pack.json语法特别是引号和逗号。2. 确认mods-list.txt中有TutorialMod区分大小写。3. 确保歌曲文件夹和JSON文件命名符合规范。6. 最佳实践与工程建议掌握了基础之后遵循一些好的实践能让你的模组开发更高效、更专业也更容易被社区接受。版本控制与备份务必使用Git管理你的模组项目。为每个新功能或修复创建分支。定期提交Commit并写好清晰的提交信息。将代码仓库托管到GitHub或GitLab便于协作和版本回溯。资源管理命名规范使用小写、短横线分隔的命名方式如my-cool-character.png。图像优化使用工具如TinyPNG压缩PNG图片减少游戏加载时间和内存占用。确保尺寸为2的幂次方。音频格式音乐使用OGG Vorbis格式.ogg音效使用WAV格式。OGG格式体积小且支持流式播放。代码与脚本模块化如果你的模组有复杂逻辑不要把所有代码塞进一个脚本。按功能拆分成不同的.hx或.lua文件。注释与文档在JSON配置和脚本中添加注释说明关键参数的作用。为你的模组编写一个简单的README.md说明安装方法、功能特性。错误处理在Haxe脚本中使用try-catch处理可能出错的操作避免游戏崩溃。测试流程分阶段测试每完成一个角色、一首歌或一个功能就立即进行测试。多难度测试确保“简单”、“普通”、“困难”三个难度的谱面都经过测试。性能测试在低配电脑上测试模组确保动画和特效不会导致严重卡顿。发布与分享清理无用文件发布前删除开发过程中的临时文件、备份文件。创建发布包将TutorialMod文件夹打包成ZIP文件。遵守社区规范如果使用了他人的资产音乐、图像务必取得授权并在发布说明中注明出处。7. 总结与学习路线通过这个“失误vs完美”双版本模组的实战我们系统性地走完了FNF Psych Engine模组开发的核心流程从环境搭建、结构解析、资源创建、配置编写到问题排查与修复。关键在于理解JSON配置与游戏资源的对应关系以及利用好引擎提供的工具如关卡编辑器来保证基础数据的准确性。你的下一步学习路线可以这样规划巩固基础尝试为你的模组添加第二个角色、第二首歌曲或者创建一个全新的舞台背景。学习脚本深入研究Psych Engine的脚本系统。从修改UI颜色、添加简单的镜头晃动事件开始逐步学习如何使用Haxe脚本创建全新的游戏机制如“健康值流失”、“弹幕音符”。研究源码阅读Psych Engine的源代码source/目录这是理解其工作原理和实现高级修改的最强途径。重点关注PlayState.hx游戏主逻辑和Character.hx角色逻辑。参与社区加入FNF模组开发社区如Discord服务器、相关论坛阅读其他人的模组源码向有经验的开发者提问这是快速提升的最佳方式。模组开发是创意与技术的结合。一开始的“失误”并不可怕它正是通往“完美”的必经之路。希望这篇教程能为你打下扎实的基础助你创造出属于自己的精彩模组。如果在实践中遇到新的问题不妨回头看看“常见问题”部分或者带着具体的错误信息去社区寻找答案。祝你开发顺利 
长河君 · 2026/8/18 6:13:19 · 阅读 1.2k FNF QT模组开发实战：从环境搭建到避坑指南
最近在B站刷到不少FNFFriday Night Funkin的二次创作视频尤其是那些基于QT引擎的模组Mod视觉效果和玩法都让人眼前一亮。很多开发者包括一些刚接触游戏开发的朋友都很好奇一个完整的FNF QT模组从零到一到底是怎么做出来的为什么网上有些演示视频看起来丝滑流畅而自己动手时却总是遇到各种奇怪的Bug比如角色动画错位、音符判定不准甚至游戏直接崩溃本文将从一个完整的实战项目出发为你拆解FNF QT模组的开发全流程。我们将制作一个包含两个版本的模组一个是“失误版本”模拟开发中常见的错误和问题另一个是“完美版本”展示修复后的正确实现。通过这种对比你不仅能掌握QT引擎如Psych Engine模组开发的核心技术栈更能深刻理解那些“坑”在哪里以及如何系统性地规避和解决。无论你是想为FNF制作自己的原创角色和歌曲还是想深入学习Haxe语言和游戏Mod开发这篇文章都能提供一条清晰的路径。1. 背景与核心概念什么是FNF与QT模组在开始敲代码之前我们有必要厘清几个核心概念这能帮助你更好地理解整个开发框架。Friday Night Funkin‘ (FNF)是一款使用Haxe语言和HaxeFlixel框架开发的开源节奏游戏。玩家需要根据屏幕上落下的音符在正确的时机按下对应方向键让游戏角色“说唱”并击败对手。其开源特性和强大的社区支持催生了海量的玩家自制模组。“QT模组”通常指的是基于Psych Engine的模组。Psych Engine是一个为FNF社区开发的高级、优化过的游戏引擎分支俗称“QT引擎”它提供了比原版更强大的功能例如更灵活的动画系统、内置的关卡编辑器、复杂的脚本事件支持等。因此现在社区提到“做QT模组”大多是指基于Psych Engine进行二次开发。一个完整的模组Mod通常包含以下几个部分资产Assets图像角色精灵图、背景、声音音乐、音效、字体等。数据Data定义每周Week、歌曲Song、角色Character的JSON配置文件。代码Code用Haxe编写的游戏逻辑可能包括新的游戏机制、UI、特殊效果等。脚本ScriptsPsych Engine支持使用Haxe脚本.hx文件或类Lua脚本.lua文件在运行时动态修改游戏行为这是实现复杂效果的关键。本次实战我们将创建一个名为“TutorialMod”的模组包含一首原创歌曲和一个自定义角色并分别实现“失误”与“完美”两个版本。2. 环境准备与版本说明工欲善其事必先利其器。搭建一个稳定、版本匹配的开发环境是成功的第一步。核心环境要求操作系统Windows 10/11 macOS 或 Linux。本文以Windows为例。编程语言Haxe 4.2.5。这是Psych Engine使用的稳定版本不推荐使用最新的Haxe 4.3可能存在兼容性问题。游戏引擎Psych Engine 0.7.1h。这是社区广泛使用且文档相对齐全的一个稳定版本。集成开发环境IDEVisual Studio Code “Haxe Extension Pack”插件。这是最主流的Haxe开发环境。版本控制Git可选但强烈推荐用于管理你的模组项目。详细安装与配置步骤2.1 安装Haxe与Haxelib下载Haxe访问Haxe官网下载Haxe 4.2.5的Windows安装程序。安装运行安装程序记得勾选“将Haxe添加到系统环境变量”选项。验证安装打开命令提示符CMD或PowerShell输入以下命令haxe -version haxelib version如果正确显示版本号如4.2.5说明安装成功。2.2 安装Psych Engine依赖Psych Engine通过HaxelibHaxe的包管理器管理依赖。打开命令行依次安装以下关键库。请严格按照顺序和指定版本安装这是避免后续编译错误的关键。haxelib install lime 8.0.1 haxelib install openfl 9.2.1 haxelib install flixel 5.4.1 haxelib install flixel-tools 1.5.2 haxelib install flixel-ui 2.7.1 haxelib install hscript 2.5.0 haxelib install polymod 1.6.0 haxelib install discord_rpc 2.0.0运行haxelib list检查所有库是否已正确安装。2.3 获取Psych Engine源代码使用Git克隆Psych Engine仓库到本地如果没有Git可以直接下载ZIP包解压git clone https://github.com/ShadowMario/FNF-PsychEngine cd FNF-PsychEngine建议切换到0.7.1h标签以确保版本一致git checkout 0.7.1h2.4 配置VSCode与项目用VSCode打开FNF-PsychEngine文件夹。安装扩展搜索并安装 “Haxe Extension Pack”。首次打开项目VSCode可能会提示你选择Haxe版本。选择你安装的4.2.5。在项目根目录下你应该能看到project.xml、export、source等关键文件夹。至此基础环境搭建完成。接下来我们将在mods目录下创建我们的模组。3. 模组项目结构与核心文件解析一个标准的Psych Engine模组其文件结构是高度规范化的。理解这个结构是组织代码和资源的基础。在我们的FNF-PsychEngine/mods/目录下创建名为TutorialMod的文件夹。结构如下TutorialMod/ ├── _append/ # (可选) 用于向游戏原有列表追加内容 ├── _core/ # (可选) 核心代码覆盖 ├── characters/ # 角色定义文件 │ └── tutorial-bf.json # 我们的自定义角色定义 ├── data/ # 歌曲和每周数据 │ ├── tutorial-song/ # 歌曲专属文件夹 │ │ ├── tutorial-song.json # 歌曲配置文件 │ │ └── tutorial-song.mp3 # 歌曲音频文件 │ └── weeks.json # 每周列表定义 ├── images/ # 图像资源 │ ├── characters/ # 角色精灵图 │ │ └── tutorial-bf.png │ ├── stages/ # 舞台背景 │ │ └── tutorial-stage.png │ └── icons/ # 角色图标用于选歌界面 │ └── tutorial-bf-icon.png ├── sounds/ # 音效如打击音效 ├── videos/ # 过场视频 ├── scripts/ # Haxe或Lua脚本 ├── mods-list.txt # 模组列表文件需手动添加 └── pack.json # 模组元数据描述文件核心配置文件详解pack.json模组的“身份证”。{ name: Tutorial Mod, description: A mod to demonstrate common mistakes and fixes., version: 1.0.0, releasestate: stable, tags: [tutorial], characters: [ { name: tutorial-bf, icon: icons/tutorial-bf-icon.png, color: 0x31b0d5 } ], songs: [ { name: Tutorial Song, character: tutorial-bf, color: 0x31b0d5, difficulties: [easy, normal, hard], week: 1 } ] }characters和songs数组定义了本模组引入的内容游戏会根据这个列表加载。角色JSON文件 (characters/tutorial-bf.json)定义角色的所有属性。{ animations: [ { anim: idle, name: BF IDLE, fps: 24, loop: true, indices: [], offsets: [0, 0] }, { anim: singLEFT, name: BF LEFT NOTE, fps: 24, loop: false, indices: [], offsets: [0, 0] } // ... 其他动画定义 ], image: characters/tutorial-bf, scale: 1.0, sing_duration: 4, healthicon: tutorial-bf, position: [770, 450], camera_position: [0, 0], flip_x: false, healthbar_colors: [0x31b0d5, 0x31b0d5] }animations每个动画对应一个精灵图帧序列。indices为空表示使用所有帧。offsets动画的偏移量用于微调角色在舞台上的位置。这里是“失误版本”的常见雷区。歌曲JSON文件 (data/tutorial-song/tutorial-song.json)定义歌曲的元数据和谱面。{ song: { song: Tutorial Song, notes: [ { sectionNotes: [ [0, 0, 0], [500, 2, 0], [1000, 1, 0] ], sectionBeats: 4, typeOfSection: 0, mustHitSection: true, bpm: 150, changeBPM: false, altAnim: false } // ... 更多小节 ], events: [], bpm: 150, needsVoices: true, player1: tutorial-bf, player2: dad, speed: 2.5, stage: tutorial-stage } }sectionNotes谱面数据。[时间戳(ms), 轨道(0-3), 音符类型(0普通, 1长按开始, 2长按结束)]。时间戳错误是“失误版本”的另一个重灾区。speed音符滚动速度。stage对应的舞台背景名称。4. 实战案例从“失误版本”到“完美版本”现在我们开始实际创建模组内容。我们将故意在“失误版本”中埋下几个典型错误然后在“完美版本”中修复。4.1 创建基础模组结构按照第3节的目录结构在mods/TutorialMod/下创建所有必要的文件夹和文件。确保你的图像和音频文件已放入正确位置。精灵图如tutorial-bf.png需要是包含所有动画帧的横向或纵向图集Psych Engine支持XML或TXT格式的图集描述文件但最简单的方式是使用等间距帧并在JSON中通过indices或留空来定义。4.2 “失误版本”实现与问题复现在这个版本中我们故意制造三个常见问题。问题一角色动画偏移错误在tutorial-bf.json中我们为singLEFT动画设置一个离谱的偏移量{ anim: singLEFT, name: BF LEFT NOTE, fps: 24, loop: false, indices: [], offsets: [150, -100] // 错误示范偏移过大 }后果当角色向左唱歌时精灵图会严重偏离其基准位置可能飞到屏幕外或与音符位置不匹配。问题二谱面时间戳计算错误在tutorial-song.json中我们错误地计算了时间戳。假设BPM是150那么每拍的时间是60000 / 150 400ms。如果我们想在第2拍索引为1因为从0开始的“右”轨道轨道2放置一个音符正确时间戳是400 * 1 400ms。但我们错误地写成了sectionNotes: [ [400, 2, 0], // 意图第2拍右箭头 [800, 0, 0], // 意图第3拍左箭头 错误 [1200, 1, 0] ],实际上如果BPM是150第3拍的时间戳应该是400 * 2 800ms但这里[800, 0, 0]从数值上看是800ms如果这是第3拍左箭头那它是对的。但常见的错误是忘记将音乐编辑软件中的节拍数从1开始转换为以0开始的时间索引或者在变速BPM Change段落计算错误。更典型的错误是直接使用秒数而不是毫秒。问题三资源路径或名称拼写错误在pack.json中我们将角色图标路径写错icon: icons/tutorial-bf-ico.png // 错误实际文件是 tutorial-bf-icon.png后果在游戏自由模式Freeplay中该角色的图标无法加载显示为默认的“”图标或导致游戏崩溃。4.3 编译、测试与问题现象添加模组到列表在mods/mod-list.txt文件中添加一行TutorialMod确保游戏能识别它。编译游戏在VSCode中按F5或根据你的配置选择“Debug”模式编译并运行Psych Engine。你也可以在命令行执行lime test windows或其他目标平台。进入游戏测试在主菜单进入“自由模式Freeplay”。你应该能看到“Tutorial Song”但角色图标可能显示错误问题三。选择歌曲并开始游戏。观察问题一当按下左方向键时tutorial-bf角色的动画会“跳”到一个奇怪的位置。观察问题二音符的下落节奏与音乐节拍对不上感觉要么太快要么太慢或者根本不在拍子上。玩家会感觉游戏“手感”极差。4.4 “完美版本”修复方案现在我们逐一修复上述问题。修复一校正动画偏移动画偏移offsets的[x, y]用于微调该动画帧在角色position基础上的最终显示位置。通常需要通过反复测试来调整。对于对称的角色很多动画的偏移可能是[0, 0]。我们可以先设为[0, 0]然后在游戏中观察如果向左唱歌时手臂位置不对再慢慢调整例如[10, 5]。{ anim: singLEFT, name: BF LEFT NOTE, fps: 24, loop: false, indices: [], offsets: [0, 0] // 修正先归零再根据视觉微调 }最佳实践使用Psych Engine内置的“角色编辑器”Character Editor或第三方工具如“Friday Night Funkin‘ Character Editor”来可视化地调整偏移和位置这比手动修改JSON高效准确得多。修复二精确计算谱面时间戳确保你理解时间戳单位是毫秒ms。计算时间戳的公式是时间戳 (节拍数 * (60000 / BPM))。节拍数从0开始计数。第1小节第1拍是0第1小节第2拍是1以此类推。如果歌曲中有BPM变化计算会复杂很多。强烈建议使用专业的谱面编辑器如Psych Engine 内置的关卡编辑器在游戏调试菜单按7中开启这是最原生、最准确的方式。第三方工具如“FNF Chart Editor”可以导入音频可视化地放置音符并导出为Psych Engine兼容的JSON。使用编辑器生成的sectionNotes会是绝对正确的例如sectionNotes: [ [0, 0, 0], // 第0拍左箭头 [400, 1, 0], // 第1拍下箭头 [800, 2, 0], // 第2拍上箭头 [1200, 3, 0] // 第3拍右箭头 ],修复三严格核对资源路径与名称养成严格一致的文件命名习惯并使用编辑器的“复制路径”功能来避免手动输入错误。icon: icons/tutorial-bf-icon.png // 修正与文件名完全一致同时检查所有JSON文件中引用的图像、声音键名是否与文件名不含扩展名匹配。例如image: characters/tutorial-bf对应images/characters/tutorial-bf.png。4.5 最终测试与效果对比修复所有问题后重新编译并运行游戏。自由模式现在可以看到正确的角色图标和歌曲信息。游戏过程角色动画流畅唱歌时动作与音符方向匹配位置稳定。音符精准地落在音乐节拍上游戏体验丝滑。没有崩溃或资源缺失错误。至此你已经成功将一个充满Bug的“失误版本”模组修复成了一个可正常游玩的“完美版本”。这个对比过程深刻揭示了模组开发中细节的重要性。5. 常见问题与排查思路在模组开发中你肯定会遇到各种报错和异常。下面是一个快速排查清单。问题现象可能原因排查步骤与解决方案编译失败Haxe报错1. Haxe或Haxelib版本不对。2. 依赖库缺失或版本冲突。3. 源代码语法错误。1. 确认Haxe为4.2.5用haxelib list检查核心库版本是否与上文一致。2. 运行haxelib upgrade更新所有库或删除~/.haxelib缓存重新安装。3. 检查VSCode的错误提示定位到具体文件行。游戏能编译但启动后黑屏/闪退1. 模组JSON格式错误。2. 资源文件路径错误或格式不支持。3. 脚本.hx/.lua语法错误。1. 使用JSON验证工具检查所有JSON文件。2. 检查控制台输出如果可用看是否有“Failed to load image/sound”错误。3. 暂时移除scripts/文件夹内的脚本看是否正常。角色/背景不显示1. JSON中image路径错误。2. 图片文件损坏或格式不对。3. 图片尺寸过大非2的幂次方。1. 确认路径是相对于images/文件夹的且不带扩展名。2. 尝试用其他图片替换测试。3. 将图片尺寸调整为如1024x1024、512x512等。音符与音乐不同步1. 歌曲JSON中的bpm值错误。2.sectionNotes时间戳计算错误。3. 音频文件本身有空白开头。1. 用音频软件如Audacity准确测量歌曲BPM。2.务必使用内置关卡编辑器制作谱面。3. 修剪音频文件确保第一个节拍从文件开头开始。动画播放错乱或偏移1. JSON中animations的indices定义错误。2.offsets值不合理。3. 精灵图帧顺序或尺寸不统一。1. 确认indices数组与精灵图帧数匹配。留空[]表示使用所有帧。2. 使用角色编辑器进行可视化调整。3. 确保精灵图每一帧的尺寸相同。在自由模式中看不到模组歌曲1.pack.json中songs未定义或格式错误。2.mods-list.txt中没有添加模组名。3. 歌曲JSON文件不在正确的data/子文件夹内。1. 仔细检查pack.json语法特别是引号和逗号。2. 确认mods-list.txt中有TutorialMod区分大小写。3. 确保歌曲文件夹和JSON文件命名符合规范。6. 最佳实践与工程建议掌握了基础之后遵循一些好的实践能让你的模组开发更高效、更专业也更容易被社区接受。版本控制与备份务必使用Git管理你的模组项目。为每个新功能或修复创建分支。定期提交Commit并写好清晰的提交信息。将代码仓库托管到GitHub或GitLab便于协作和版本回溯。资源管理命名规范使用小写、短横线分隔的命名方式如my-cool-character.png。图像优化使用工具如TinyPNG压缩PNG图片减少游戏加载时间和内存占用。确保尺寸为2的幂次方。音频格式音乐使用OGG Vorbis格式.ogg音效使用WAV格式。OGG格式体积小且支持流式播放。代码与脚本模块化如果你的模组有复杂逻辑不要把所有代码塞进一个脚本。按功能拆分成不同的.hx或.lua文件。注释与文档在JSON配置和脚本中添加注释说明关键参数的作用。为你的模组编写一个简单的README.md说明安装方法、功能特性。错误处理在Haxe脚本中使用try-catch处理可能出错的操作避免游戏崩溃。测试流程分阶段测试每完成一个角色、一首歌或一个功能就立即进行测试。多难度测试确保“简单”、“普通”、“困难”三个难度的谱面都经过测试。性能测试在低配电脑上测试模组确保动画和特效不会导致严重卡顿。发布与分享清理无用文件发布前删除开发过程中的临时文件、备份文件。创建发布包将TutorialMod文件夹打包成ZIP文件。遵守社区规范如果使用了他人的资产音乐、图像务必取得授权并在发布说明中注明出处。7. 总结与学习路线通过这个“失误vs完美”双版本模组的实战我们系统性地走完了FNF Psych Engine模组开发的核心流程从环境搭建、结构解析、资源创建、配置编写到问题排查与修复。关键在于理解JSON配置与游戏资源的对应关系以及利用好引擎提供的工具如关卡编辑器来保证基础数据的准确性。你的下一步学习路线可以这样规划巩固基础尝试为你的模组添加第二个角色、第二首歌曲或者创建一个全新的舞台背景。学习脚本深入研究Psych Engine的脚本系统。从修改UI颜色、添加简单的镜头晃动事件开始逐步学习如何使用Haxe脚本创建全新的游戏机制如“健康值流失”、“弹幕音符”。研究源码阅读Psych Engine的源代码source/目录这是理解其工作原理和实现高级修改的最强途径。重点关注PlayState.hx游戏主逻辑和Character.hx角色逻辑。参与社区加入FNF模组开发社区如Discord服务器、相关论坛阅读其他人的模组源码向有经验的开发者提问这是快速提升的最佳方式。模组开发是创意与技术的结合。一开始的“失误”并不可怕它正是通往“完美”的必经之路。希望这篇教程能为你打下扎实的基础助你创造出属于自己的精彩模组。如果在实践中遇到新的问题不妨回头看看“常见问题”部分或者带着具体的错误信息去社区寻找答案。祝你开发顺利