用 Sonolus.js 开发引擎（入门）

适合谁

• 有 JavaScript / TypeScript 基础的前端开发者
• 想复刻某个经典音游引擎，但不想从零开始写游戏
• 想体验一下"写一个音游引擎"是什么感觉

前置知识建议

• 会写基本的 JavaScript（变量、函数、数组、对象）
• 理解什么是 BPM 和节拍（音游基础概念）
• 愿意读 Sonolus 官方 Wiki 的引擎规格文档

Sonolus.js 是什么

Sonolus.js 是 Sonolus 最早支持的脚本语言，基于 JavaScript 语法。你可以用它编写：

• 音符判定规则（Tap / Hold / Flick 的判定窗口）
• 计分逻辑
• 轨道布局（几轨、多宽、判定线在哪）
• 视觉效果（粒子、连击动画）
• UI 选项（给玩家提供哪些游戏内选项）

开发环境

Sonolus.js 编译后生成 Sonolus 节点图。你需要：

1. 一个代码编辑器（VS Code 推荐，社区有 Sonolus.js 语法高亮插件）
2. Node.js 运行环境
3. Sonolus.js 官方模板项目（从 GitHub 克隆）

学习路径

建议按以下顺序入手：

1. 读官方 Wiki 的 Sonolus.js 指南——从概念到语法全覆盖
2. 阅读现有引擎源码——Chart Cyanvas 是最成熟的参考实现，直接抄结构改
3. 跑模板项目——把官方模板跑起来，然后一点点加功能
4. 自己试写一种音符类型——比如最基础的 Tap 音符的判定逻辑
5. 完善计分和 UI——功能完整后打包上传测试服务器

代码长什么样

Sonolus.js 的代码结构大致是：

// 定义引擎资源声明
export const engine = {
    skins: [/* 皮肤声明 */],
    effects: [/* 音效声明 */],
    options: [/* 选项声明 */],
    // ...
}

// 定义节点图：每个音符类型的判定逻辑
export const archetypes = {
    tap: { /* Tap 音符的判定和计分 */ },
    hold: { /* Hold 音符的判定 */ },
}

编译与测试

Sonolus.js 编译工具会把你的 JS 代码转成 Sonolus 可以识别的 JSON 节点图。编译完成后，你可以把生成的引擎资源上传到测试服务器，在 Sonolus 里加载调试。

相关阅读

• Sonolus.py 引擎开发——新引擎推荐用这个
• 脚本驱动系统——两种脚本语言的对比
• 引擎规格——完整引擎规格文档，外部链接可跳转 Sonolus Wiki