.. _introduction:

========
简介
========

什么是 Sync？
=============

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

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

单一包架构
============

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

.. list-table::
   :header-rows: 1

   * - 类别
     - 类
     - 定位
   * - **共享数据类** （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 有意不包含以下内容：

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

谁适合使用 Sync？
==================

* **Godot 游戏开发者** — 想制作节奏游戏但不想从零实现谱面系统和时间管理
* **制谱工具开发者** — 需要一个标准化的谱面数据格式和时间系统
* **对节奏游戏引擎设计感兴趣的人** — 研究谱面编译、播放引擎、轴采样等通用机制

版本
====

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

:ref:`下一章 <architecture>` 介绍 Sync 的架构设计。