音游源码：谱面、判定时机与新增歌曲
Riffvolt 如何存放 12 首曲目和 48 张谱面，判定和计分在哪里决定，以及加入一首自己的歌需要做什么。
音游源码其实包含两部分：判定时机的代码，以及规定每个音符何时到来的数据。买家几乎总想改第二部分，因为新歌才是让一款节奏游戏真正属于自己的关键。我们的四轨摇滚节奏模板 Riffvolt 把歌曲列表放在一个清单文件里，每张谱面都有自己的文件，所以新增歌曲是一项有明确清单可循的数据工作。
这篇指南带你走一遍整个包：玩法是什么，判定和计分放在哪里，如何新增歌曲，如何重新构建和部署，授权允许做什么，以及这个版本不包含什么。文中的文件名都出自随游戏附带的买家指南。
有一点要从一开始就记住：和我们的部分模板不同，Riffvolt 修改源码或新增歌曲后需要重新构建。部署随附的游戏文件夹只需要一个静态网站主机。
这套节奏游戏源码的玩法
Riffvolt 是一款完整的浏览器四轨摇滚节奏游戏。玩家要踩准时机击打音符，长音符要按到结束，可以用 whammy（摇杆）压弯音符，还要攒满 ROCK 能量条来触发 overdrive——一场不加分的灯光秀，任何一次失误都会让它结束。判定越准，分数和连击就越高。
- 12 首完整曲目，每首都有 Easy、Normal 和 Hard 谱面，外加巡演结束后开放的 Rock God：共 48 张谱面。
- 巡演经过四个场地（Garage、The road、Festival 和 Arena），每个场地三首歌。前两首拿到星星即可开放安可曲，完成安可后开放下一个场地，过程中有剧情场景和拖尾、边框等外观奖励。
- 自由模式：任意歌曲、任意难度，个人纪录按歌曲保存在浏览器中。
- 操作：默认按键为 D、F、J 和 K，触屏上直接点击轨道，也支持手柄。按键绑定在 Settings（设置）里修改。
- 舒适性：音频偏移校准（对蓝牙耳机有帮助）、减弱动态效果，以及降低闪光和闪电效果的光敏模式。
- 14 种界面语言。
文件是怎样组织的
下载包里有 game/（可部署文件）、source/（TypeScript 工程）、documentation/（英文和葡萄牙文的图文手册）和 licenses/（第三方声明）。在 source/ 里，歌曲数据和游戏逻辑分得很清楚。
- public/manifest.json：歌曲目录，包括每首歌的时长、音频版本和谱面路径。
- public/charts/：48 张谱面。
- public/audio/：曲目录音。
- src/core/chartValidate.ts：谱面结构和时间校验。
- src/core/judge.ts：时机判定。
- src/core/scoring.ts：分数和连击规则。
- src/game/campaign.ts：巡演进度。
- src/game/session.ts：一首歌的生命周期和结算计算。
- src/i18n/locales.ts：14 种界面语言词典。
- src/net/localRecords.js：本地个人纪录。
- src/ui/style.css：界面和响应式布局。
判定和计分是分开的文件，所以你可以把判定窗口调得更严或更宽松，而不影响分数的累加方式，反之亦然。挑选任何节奏游戏代码时，都应该看有没有这种拆分。
新增一首歌：分步说明
这是节奏游戏买家最先问的修改。包里没有谱面编辑器，谱面以数据形式编写，手册列出了每个文件需要的确切内容。
- 把录音放进 public/audio/。只使用你拥有最终产品使用权的音频。
- 在 public/charts/ 中为每个支持的难度各建一张谱面。每张谱面都需要对应的 songId、difficulty、audioVersion、offset，以及按顺序排列的音符。
- 在 public/manifest.json 中加入这首歌，填写唯一的 id、时长、BPM、主题、audioVersion 和谱面路径。
- 用 chartValidate.ts 中的校验器检查每张谱面。
- 每个难度都完整打一遍，确认同步。校验器检查的是结构和时间规则，而不是某个音符手感对不对。
- 重新构建，然后上传新的构建版本。
如果你想要的是一整套新原声，而不只是多加一首歌，就按谱面来规划工作量：12 首歌、4 个难度就是 48 张谱面，每一张在发布前都值得完整打一遍。
重新构建，以及其他可改的内容
推荐使用 Node.js 24 LTS。在 source/ 中运行 npm ci，然后运行 npm run typecheck 和 npm run build，只发布 dist/ 里的内容。npm run preview 可以在本地预览构建结果。不要上传 node_modules/。Vite 使用相对 base，所以构建结果放在子文件夹里也能运行。交付的运行时代码已格式化以便阅读；手册要求重新构建时保持 minify:false 和 cssMinify:false，让下一个接手的人也能读懂。
- 品牌：在 src/ui/style.css 中修改颜色和布局，再换上你的 Logo。允许白标，你的品牌可以替换我们的。
- 文本：src/i18n/locales.ts，改你要上线的语言。
- 巡演：在 campaign.ts 中调整场地顺序和解锁关系。
- 难度：先改 judge.ts 中的判定窗口，再改 scoring.ts 中的分数和连击规则。
- 歌曲：最后再加，因为每张新谱面都需要完整打一遍。
编辑前先备份，一次只改一项功能，每次改完都测试菜单、一首歌、暂停、结算界面和刷新。保持物品 id 和存档键名不变，老玩家的纪录才能保留。
部署上线，或嵌入游戏平台
把 game/ 的内容上传到 HTTP(S) 主机上的一个文件夹，保持相对路径，然后打开地址。不需要 PHP、数据库或账号。不要通过 file:// 打开 index.html；本地测试时，在 game/ 里运行 python -m http.server 8765。
- 浏览器要求：JavaScript、ES 模块、Canvas 2D 和 Web Audio。
- 浏览器只有在第一次点击或触摸后才会解锁音频，所以第一屏没有声音是正常的。
- 在 iframe 中需允许 fullscreen 和 autoplay。
- 以 JavaScript MIME 类型发送 .js，绝不能是 text/plain。
- 所有运行时资源、字体和库都在构建包内。不强制依赖 CDN，但这不是可安装的离线应用。
存档归属于浏览器的源（origin），所以把游戏迁到另一个域名后，玩家要从头开始。此版本使用自己的存档键名，与我们平台上的版本互不相干。不包含原生 App 工程；上架应用商店是另外的工作。
这个版本不包含什么
Riffvolt 是本地浏览器版本。没有在线房间或多人模式，没有在线排名或共享排行榜，没有广告 SDK 或账号，没有谱面编辑器，没有原生 App，也不含托管服务。个人纪录和巡演进度都保存在玩家的浏览器里。
如果音乐游戏适合你的产品目录，我们另外两款基于时机的模板也可以一起搭配。
授权与价格
Riffvolt 标价 49 美元。在 2026 年 11 月 30 日之前，黑色星期五促销立减 15%，价格为 41.65 美元；一次订单购买两个及以上模板，还可享受 5% 到 20% 的组合折扣。授权为永久、非独占，可用于一个最终产品，你自己的或某一位客户的。你可以修改代码、美术和音频，用你的品牌替换我们的，并免费或带广告提供游戏。附带的曲目可以作为该最终产品的一部分使用；不能单独转售模板、其代码或其素材。包含六个月技术支持，购买延长服务为十二个月；新歌曲、功能集成和托管需另行报价。
常见问题
我能往这套节奏游戏源码里加自己的歌吗？
可以。加入音频、每个难度一张谱面，并在 public/manifest.json 中添加条目，校验谱面、完整试玩，然后重新构建。不包含谱面编辑器。
使用 Riffvolt 需要 Node.js 吗？
部署随附的游戏文件夹不需要。只有修改 TypeScript 或新增歌曲后重新构建时，才推荐使用 Node.js 24 LTS。
支持触屏和手柄吗？
支持。玩家可以点击轨道或使用手柄，操作在 Settings 中设置。性能取决于设备，请在目标设备上测试。
蓝牙耳机和延迟怎么办？
Settings 里有音频校准功能，可以设置音频偏移，对蓝牙耳机有帮助。
有在线排行榜吗？
没有。个人纪录按歌曲和难度保存在玩家的浏览器中。没有远程对手，也没有共享排名。
适合谁购买
Riffvolt 适合想在目录里加入一款音乐游戏的平台或网站，为单个客户交付品牌节奏游戏的工作室，以及想读懂 Canvas 2D 加 Web Audio 游戏如何用 TypeScript 判定时机的开发者。如果你需要给非开发人员使用的可视化谱面编辑器，或者需要在线竞技，它就不太合适；这两项都属于定制开发。