1. 简介

1.1. 什么是 Sync？

Sync 是一套**模块化的节奏游戏引擎**，专为 Godot 4.x 游戏开发者打造。它将谱面数据模型与时间系统与具体游戏玩法解耦，让你可以自由构建自己的节奏游戏——包括自己的判定逻辑。

Sync 不是一个"游戏框架"——它不提供渲染、音频、输入映射、资源管线，更 不内置判定引擎。它是**数据 + 时间** 的核心，其余由你掌控。

0.5.0 起，Sync 以**单一 GDExtension** （addons/sync，19 个类，一个 DLL）发布，不再拆分多个包。数据层、编辑器组件与运行时全部由同一个扩展注册：

类别	类	定位
共享数据类（13 个）	SyncDocumentChart / SyncTrack / SyncNote / SyncBeat / SyncBpmAxis / SyncTimeSignatureMap / SyncFloatAxis / SyncVector2Axis / SyncVector3Axis / SyncVector4Axis / SyncSpeedAxis / SyncTrans / SyncEase	谱面数据模型、时间系统与动画轴
编辑器组件（3 个）	SyncProgressManager / SyncTimeline / SyncBeatGrid	制谱 / 预览工具链（坐标映射与节拍线数据，不做渲染）
运行时（2 个）	SyncChart / SyncChartPlayer	谱面编译与墙钟驱动播放
通用组件（1 个）	SyncNodePool	节点对象池

安装 addons/sync/ 一个包即可，无包间依赖、无加载顺序问题。

丰富的谱面数据模型 — SyncDocumentChart → SyncTrack → SyncNote 三级结构，支持子轨道嵌套
可变 BPM 时间轴 — 整谱任意位置插入 BPM 变化关键帧，所有时间计算实时跟随
多类型动画轴 — float / Vector2 / Vector3 / Vector4 / speed 五种轴，每轴独立关键帧与缓动曲线
可扩展的音符种类 — 引擎只保留 TAP（点）与 HOLD（区间）两种时间语义；任何游戏专属种类（CATCH / VOID / 长键 / 滑键 / 自定义）由你在 note.metadata 里打标记，并在自己的 GDScript 中实现判定
单一 GDExtension — 19 个类由同一个扩展注册（register_types.cpp），无跨扩展桥接、无加载顺序约束
JSON 序列化 — 谱面可与 JSON 互相转换，方便版本控制、脚本批处理、外部工具链
节点对象池 — SyncNodePool （0.5.0 回归）复用高频节点实例，编辑与游玩侧共用

Sync 有意不包含以下内容：

不包含判定引擎 — 没有内置判定。游戏写自己的判定，引擎提供判定所需的所有精确数据（见 Sync 包概览的"No judgement engine — by design"）。
不包含渲染 — 没有轨道绘制、没有音符精灵、没有连击显示。你用自己的 GDScript / shader 画。
不包含音频引擎 — 不管理 BGM 加载、不打音效。你用 Godot AudioServer 或 FMOD 自行管理。
不包含输入映射 — 不绑定触控区、不处理键盘布局。你的输入层读 player.get_chart_progress_ms() 并写自己的命中判定。
不包含资源管线 — 不管理 prefab、不含特效调度。节点复用可借助 SyncNodePool （0.5.0 回归的通用组件），其余资源管线由你的游戏自行实现。
不包含特定玩法约定 — 轨道布局、轨道几何、轴线含义绑定等属于具体作品的玩法层，不进入通用引擎。

当前版本 0.6.0（数据 + 时间，无判定）。addons/sync 是全部 19 个类的唯一注册处：13 个共享数据类 + 3 个编辑器组件 + 2 个运行时类 + 1 个通用组件（SyncNodePool 对象池）。

下一章介绍 Sync 的架构设计。