1. 项目概述：什么是PsychEngine蓝图？

如果你是一个对《Friday Night Funkin'》（FNF）这款节奏游戏着迷，并且不止一次想过“要是能自己做一首歌、一个角色，甚至一个完整的故事周目该多好”的玩家或创作者，那么你找对地方了。今天要聊的，不是什么简单的换皮教程，而是一份从零开始，带你彻底吃透FNF社区最强大、最流行的模组引擎——PsychEngine的终极创作蓝图。

简单来说，PsychEngine是FNF原版游戏的一个开源重制版引擎。它最初由社区开发者ShadowMario等人创建，目的是为了提供一个比原版HaxeFlixel代码库更稳定、功能更丰富、对创作者更友好的开发环境。经过几年的迭代，它已经成为了FNF模组创作的“事实标准”。你看到的绝大多数高质量、玩法复杂的模组，比如《VS. Whitty》、《Mid-Fight Masses》、《Funkin' at Freddy's》等，其底层几乎都是基于PsychEngine或其衍生版本。

这份“蓝图”的核心价值，就是帮你绕过我当年踩过的无数个坑，直接掌握从环境搭建、美术资源制作、谱面编写、代码修改到最终打包发布的完整工作流。它不仅仅是一系列操作的罗列，更会深入解释每个环节背后的设计逻辑：为什么PsychEngine的代码要这么组织？为什么你的角色动画总是对不上拍子？如何让自定义的机制既炫酷又不卡顿？我们将一起，把创作一个模组从“魔法黑箱”变成一项清晰、可控的工程。

2. 蓝图核心：PsychEngine的模块化设计哲学

在动手装软件之前，我们必须先理解PsychEngine的“心法”。它与原版FNF最大的区别在于其高度模块化和数据驱动的设计。原版代码很多逻辑是硬编码在游戏状态里的，改起来牵一发而动全身。而PsychEngine把几乎所有的内容都“外部化”了。

2.1 核心目录结构解析

当你下载并解压PsychEngine的源码后，会看到一堆文件夹。别慌，我们只需要重点关注几个：

• source/: 这是游戏逻辑的核心，所有Haxe代码都在这里。但作为创作者，你大部分时间不需要深挖这里，除非你要添加全新的游戏机制。
• assets/: 这才是你的主战场。所有图像、声音、数据都存放在这里。它的结构清晰对应着游戏内容：
  • assets/images/: 所有角色、背景、UI、图标等图片资源。
  • assets/sounds/: 音效、人声采样。
  • assets/songs/:每一首歌曲都是一个独立的文件夹。这里面包含了最重要的几个文件：.ogg或.mp3格式的伴奏音乐、.json格式的谱面数据、以及对手和玩家的人声采样文件。
  • assets/data/: 存放角色、对话、全局设置的.json文件。比如，每个角色的动画帧信息、对话文本、一周目的歌曲列表都在这里定义。
  • assets/shared/: 跨周目共享的资源，如菜单UI、字体等。
• mods/: 这是PsychEngine 0.6版本后引入的模组加载系统。你可以把自己的创作（包括assets里的内容和source里的代码修改）打包成一个.mod文件，放在这里。游戏启动时会自动扫描并加载，实现了真正的“即插即用”，无需替换游戏本体文件。

这种设计的精妙之处在于，它将内容创作与引擎开发分离。你作为内容创作者，90%的工作都在assets文件夹里，通过编辑图片、音频和JSON文本文件来完成创作。只有当你需要突破引擎现有功能时，才需要去碰source里的代码。

2.2 数据驱动：JSON文件是如何控制一切的

PsychEngine的灵魂是JSON。几乎所有的游戏内容都由JSON文件定义。理解这些文件的结构，是高效创作的关键。

• 角色数据 (characters/目录下的.json)： 这里定义了角色的所有属性。一个典型的角色JSON文件会包含：

  { "animations": [ { "anim": "idle", // 动画名称 "name": "BF Idle Dance", // 在图像文件中的前缀名 "fps": 24, // 帧率 "loop": true, // 是否循环 "indices": [] // 可指定播放的帧序列，留空则播放全部 } // ... 更多动画定义 ], "image": "BOYFRIEND", // 对应的图像文件名称（不带路径和后缀） "scale": 1.0, // 缩放比例 "sing_duration": 4, // 演唱动画的保持帧数（值越大，动画回到idle状态越慢） "healthicon": "bf", // 血条旁的头像 "camera_position": [0, 0], // 镜头对该角色的偏移 "healthbar_colors": ["31B0D1", "31B0D1"] // 血条颜色 }

  实操心得：sing_duration这个参数至关重要。它控制角色在按下箭头键后，演唱动画会持续多少帧才切回闲置状态。如果设置得太小，动画会显得急促、鬼畜；太大则会导致动画反应迟钝。通常对手角色设为6-8，玩家角色设为4-6是比较舒服的区间，需要根据歌曲BPM和谱面密度微调。

• 谱面数据 (songs/目录下的.json)： 这是歌曲的核心。它精确记录了每个音符出现的时间、类型、长度以及歌词。

  { "song": { "notes": [ { "sectionNotes": [ // 一个小节内的所有音符 [158.4, 0, 0], // [出现时间(秒), 轨道(0-3对应左、下、上、右), 音符类型(0=普通，1=必须按住的音符头，2=必须按住音符的尾)] [159.4, 2, 0], [160.4, 1, 0], [161.4, 3, 0] ], "lengthInSteps": 16, // 小节长度（步数） "mustHitSection": true, // true表示该小节玩家演唱，false表示对手演唱 "bpm": 150 // 该小节的BPM } // ... 更多小节 ], "events": [], // 事件，如镜头移动、角色切换、特效触发 "bpm": 150, // 歌曲基础BPM "needsVoices": true, // 是否需要人声 "speed": 2.8 // 音符滚动速度 } }

  避坑指南：手动在JSON里敲音符时间是地狱级的体验。绝对不要这么做。我们会在下一章介绍专用的谱面编辑器，它是你创作流程中的“生产力倍增器”。

3. 环境搭建与核心工具链

工欲善其事，必先利其器。一套稳定、高效的工具链能让你专注于创作本身，而不是和莫名其妙的报错作斗争。

3.1 开发环境配置：不只是“下载PsychEngine”

很多人第一步就错了——他们直接去GitHub下载PsychEngine的ZIP压缩包。对于纯内容创作，这或许可行，但如果你想编译游戏、测试修改，或者使用最新的社区工具，你需要搭建完整的Haxe开发环境。

1. 安装Haxe和HaxeLib： 前往Haxe官网下载安装包。安装时，务必勾选“Neko”和“设置环境变量”。安装完成后，打开命令行（CMD或PowerShell），运行haxelib install lime和haxelib install openfl。这是PsychEngine所依赖的基础框架。
2. 获取PsychEngine源码： 使用Git（如果你没有，也需要安装）克隆仓库是最佳实践。在命令行中进入你打算存放项目的目录，运行：

   git clone https://github.com/ShadowMario/FNF-PsychEngine cd FNF-PsychEngine

   这样做的好处是，你可以随时用git pull命令获取引擎的更新和修复。
3. 安装项目依赖： 进入PsychEngine目录后，运行haxelib install。这会根据项目根目录下的haxelib.json文件，自动安装所有必需的库。
4. 测试编译： 运行lime test windows（如果你在Windows上）。如果一切顺利，这将启动一个编译过程，并最终运行游戏。第一次编译会下载更多依赖并构建很久，请耐心等待。如果成功运行，恭喜你，环境搭建完成。

注意事项：国内网络环境可能导致haxelib下载缓慢或失败。可以尝试配置代理或使用镜像源。另一个常见问题是路径包含中文或特殊字符，这可能导致编译失败，请确保你的项目路径是全英文的。

3.2 创作三件套：编辑器、画图软件、音频工具

• 谱面编辑器：Chart Editor： 这是PsychEngine内置的、最强大的谱面创作工具。在游戏主菜单，进入“选项” -> “调试菜单” -> “图表编辑器”，或者更简单，在歌曲选择界面按7键。它的界面分为时间轴、音符放置区、事件编辑区和属性面板。你可以在这里直观地放置音符、调整BPM变化、设置镜头移动和角色切换事件。强烈建议在创作任何谱面前，花半小时熟悉这个编辑器的所有快捷键和功能。

• 图像编辑：Aseprite / Photoshop / Krita： 角色和背景需要动画。PsychEngine使用精灵图（Sprite Sheet），也就是把一整套动画的所有帧排在一张长图上。Aseprite是像素动画和精灵图制作的行业标准，专为游戏美术设计，对图层、动画预览、导出精灵图的支持无与伦比。Photoshop和Krita功能更全面，适合绘制高分辨率、复杂光影的背景。无论用哪个，导出时请务必选择PNG格式，并确保背景透明（Alpha通道）。

• 音频处理：Audacity / FL Studio： 你需要处理三样东西：伴奏（Inst.）、人声（Voices）和音效（SFX）。Audacity是免费、开源的音频编辑器，非常适合进行简单的剪切、降噪、音量标准化和导出。FL Studio等数字音频工作站（DAW）则用于更专业的音乐制作和混音。一个关键步骤：确保你的人声音频与伴奏音频的BPM对齐，并且在Chart Editor中，人声轨道的偏移（Offset）设置正确，否则会出现“口型对不上”的尴尬情况。

4. 核心创作流程实战拆解

现在，让我们跟随一个最简单的目标来走一遍流程：创作一首包含一个新对手角色的歌曲。

4.1 第一步：角色设计与动画制作

假设我们要做一个叫“Glitch”的赛博朋克风格对手。

1. 设计稿与分镜： 先在纸上或绘图软件里画出角色的关键姿态：Idle（闲置）、Left/Right/Up/Down（四个方向的演唱）、Miss（失误时的表情）。确定动画风格是流畅的逐帧动画，还是只有两帧的“眨眼”式动画。
2. 绘制精灵图： 在Aseprite中，创建一个足够宽的画布（比如2000x500像素）。将Idle动画的每一帧水平排列，然后是Left动画的所有帧，以此类推。确保每个动画的每一帧尺寸完全相同。这是PsychEngine正确解析动画的基础。
3. 导出与命名： 将整张精灵图导出为PNG，命名为Glitch.png，放入assets/images/characters/。命名规则很重要，后续的JSON文件会引用这个名字。
4. 编写角色JSON： 在assets/data/characters/目录下，创建Glitch.json文件。参照第2.2节的格式，定义每个动画。
   • "anim": 内部调用名，如"idle","singLEFT"。
   • "name": 对应精灵图中的前缀。如果你的Idle动画帧在精灵图中被命名为Glitch Idle 0,Glitch Idle 1... 那么这里就填"Glitch Idle"。PsychEngine会自动寻找以这个名字开头、以数字结尾的帧。
   • "fps": 动画播放速度。24是电影标准，12是常见游戏帧率，6则会有明显的卡顿感，可用于表现机械或故障效果。
   • 关键技巧： 你可以利用"indices"字段制作非顺序播放的动画。比如[0, 1, 2, 1, 0]会让角色在0,1,2帧播放后，再倒着播放1,0帧，形成一种来回晃动的效果，让Idle动画更生动。

4.2 第二步：歌曲与谱面创作

1. 准备音频： 将你的伴奏音乐（Inst.ogg）和人声音频（Voices.ogg）放入assets/songs/your_song_name/文件夹。OGG格式比MP3拥有更好的压缩率和兼容性。
2. 创建谱面文件： 在同一文件夹下，创建your_song_name.json和your_song_name-easy.json等不同难度的谱面文件。最简单的方法是复制现有歌曲的JSON文件并修改。
3. 使用Chart Editor：
   • 在游戏中进入这首新歌（如果没在周目列表里，你可能需要暂时修改assets/data/freeplaySonglist.txt或通过调试菜单进入）。
   • 按7打开编辑器。首先在左侧属性面板设置歌曲的全局BPM和速度（Speed）。
   • 在时间轴上，通过右键菜单可以插入BPM变化事件。在音符放置区，单击或拖拽来放置音符。按住Shift可以放置长按音符。
   • 事件系统是灵魂： 在事件编辑区，你可以添加“添加摄像机目标”事件来让镜头在玩家和对手间切换，添加“播放动画”事件来触发角色的特殊动画（比如你的Glitch角色在某个节拍处突然“故障”一下）。这些事件让谱面从单纯的“按箭头”变成了有叙事感的演出。
4. 谱面设计的黄金法则：
   • 节奏贴合： 音符必须精准落在鼓点或旋律重音上。Chart Editor有网格对齐和节拍器功能，务必开启。
   • 难度曲线： 即使是最高难度，开头也要简单，让玩家热身。难度应随着歌曲情绪推进而上升，在副歌或高潮部分达到峰值。
   • 视觉提示： 长按音符、密集的箭头雨、突然的镜头切换，这些都要有音频上的对应，给玩家预判时间。纯粹为了难而难的谱面体验很差。

4.3 第三步：整合与测试

1. 修改周目数据： 如果你想将这首歌加入故事模式，需要编辑assets/data/week/目录下的周目JSON文件（如week1.json）。在其中添加你的歌曲名、角色名、对话脚本等。
2. 本地测试： 频繁使用lime test windows编译并测试。测试时，不仅要自己玩，还要开启Botplay（在调试菜单或按7在编辑器里开启），让AI自动玩一遍，检查是否有音符因为时间偏移等问题导致Bot也无法击中（这通常意味着谱面数据有问题）。
3. 性能与优化： 在低配电脑上运行你的模组。检查是否有卡顿。常见的性能杀手包括：过大的高清背景图（未压缩）、过于复杂的逐帧动画（帧数过多）、同一时间播放过多音效。优化方法包括压缩图片、减少动画帧数、合并音效。

5. 进阶技巧与深度定制

当你掌握了基础流程后，这些进阶技巧能让你的模组脱颖而出。

5.1 自定义游戏机制（Lua脚本）

PsychEngine从0.6版本开始，全面支持Lua脚本。这意味着你可以在不修改Haxe源代码（C++编译）的情况下，用Lua这种更简单的脚本语言为你的模组添加全新功能。

• 脚本放置： 在歌曲文件夹或模组根目录下创建scripts/文件夹，将.lua文件放在里面。游戏会自动加载。
• 能做什么：
  • 修改游戏逻辑： 创建新的音符类型（如需要同时按下的双键音符）、改变血量计算规则（连击加分、失误重罚）。
  • 创建视觉特效： 添加自定义的Shader（着色器）来实现模糊、色彩分离、像素化等屏幕效果。
  • 控制UI： 创建全新的HUD元素，比如连击计数器特效、自定义判定提示。
• 简单示例： 创建一个让屏幕随节奏震动的脚本。

  function onBeatHit() if curBeat % 4 == 0 then -- 每4拍一次 cameraShake('hud', 0.01, 0.1) -- 震动HUD摄像机 end end

  Lua脚本通过一系列预设的回调函数（如onCreate,onUpdate,onBeatHit,onStepHit）与游戏引擎交互。社区有完善的API文档，学习成本远低于直接修改Haxe。

5.2 动态加载与模组系统

利用mods/文件夹和模组列表功能，你可以制作真正独立的模组包。

1. 创建模组包结构： 在你的模组文件夹里，镜像assets/和source/（如果有修改）的目录结构。还可以包含一个_mod.json文件来定义模组名称、描述、版本和依赖。
2. 使用模组工具打包： 社区有工具（如PsychEngine Modding Tools）可以将你的文件夹打包成.mod文件。用户只需将此文件放入游戏的mods/文件夹，即可在游戏内模组菜单中启用它。
3. 资源动态加载： 在代码或Lua脚本中，使用Paths.getMods()路径前缀来加载你模组包内的资源，确保与游戏本体或其他模组不冲突。

5.3 视觉与音频特效集成

• Stage Editor（舞台编辑器）： 和Chart Editor一样，按8键可以进入舞台编辑器。你可以自由摆放背景元素、前景层、角色初始位置，并为其添加缩放、滚动等简单动画，所有这些都会保存到歌曲的JSON数据中，无需写代码。
• Shader（着色器）： PsychEngine支持GLSL着色器。你可以找到社区分享的各种炫酷的屏幕特效（如CRT扫描线、老电影效果、水波纹），将其片段着色器代码（.frag文件）放入assets/shaders/，然后在Lua脚本中通过setSpriteShader和setCamShader函数应用到精灵或摄像机上来实现高级视觉效果。

6. 调试、优化与发布指南

创作的最后阶段，是打磨和交付。

6.1 系统性调试清单

在发布前，请对照此清单逐项检查：

6.2 性能优化要点

1. 图像优化： 使用纹理打包器（Texture Packer）将多个小图合并成一张大图（图集），减少游戏渲染时的绘制调用（Draw Calls）。PsychEngine内部会处理一部分，但主动合并角色表情等静态资源仍有好处。
2. 音频优化： 将短促、频繁播放的音效（如按键声、判定音）转换为.ogg格式并确保是单声道，可以显著减少内存占用和加载时间。
3. 代码与脚本优化： Lua脚本中，避免在onUpdate（每帧调用）函数中执行复杂的计算或频繁创建临时对象。将结果缓存起来复用。

6.3 打包、发布与社区分享

1. 最终打包： 使用打包工具生成.mod文件。确保只包含必要的文件，删除开发中的测试文件、备份文件（如*.bak）和源代码（除非是开源模组）。
2. 撰写说明文档： 创建一个README.txt或如何安装.txt，用最简洁的语言说明将.mod文件放入mods文件夹即可。可以附上你的社交媒体或创作团队信息。
3. 选择发布平台： GameBanana是目前最大的FNF模组发布站。发布时，提供清晰的封面图、简介、视频预告片和详细的更新日志。
4. 社区互动： 积极在Discord社区、论坛回复玩家反馈。收集到的Bug报告和平衡性建议是让模组变得更好的宝贵财富。记住，一个模组的成功，一半在于质量，另一半在于创作者与社区的连接。

走到这一步，你已经从一个玩家，变成了一位真正的FNF世界创造者。PsychEngine提供的这套蓝图，其边界只取决于你的想象力。无论是复刻一首经典老歌，讲述一个原创的精彩故事，还是设计一个颠覆性的游戏模式，所有的工具和路径都已在你手中。剩下的，就是去创作，去测试，去分享，然后享受社区为你作品响起的“欢呼声”。