.pulse 格式与交付要求

本文面向准备交付 .pulse 音乐包的 Pulse 设计师，说明一个合格的交付物需要满足什么要求。制作过程中的具体操作请看 Pulse Designer 手册。

💡 本文是设计师视角的交付要求摘要。.pulse 二进制容器的完整技术规范（字节布局、双解析器一致性测试等）面向格式实现者，见上游 PULSE_FORMAT.md。

一个 .pulse 文件里有什么

.pulse 是一个自包含的互动音乐包，一个文件带齐运行所需的全部内容：

• 音频数据：内嵌的 wav / mp3 / ogg 音频字节；
• 音乐结构：状态、片段、Layer、转场和参数定义；
• 元数据（可选）：授权信息、兼容性说明和开发者接入合同。

也就是说，交付时只需要交付一个 .pulse 文件，不需要附带散装音频或额外的配置文件。

三项交付要求

一个 Pulse Module 不是普通音乐包，也不是一组孤立的音频文件。合格的交付物必须同时满足三项要求：

1. 可运行（Runnable）

• 模块能直接在 Pulse Engine App 中加载；
• 能通过状态块播放和切换状态；
• loop、layer 和 transition 行为正确。

注意：当前版本没有真正的叠加式 Stinger，交付说明中不要把它宣传为已有能力。

2. 可试听（Previewable）

• 模块能导出 Web Preview，购买者不需要接入游戏就能试听状态切换；
• 预览必须展示状态按钮、当前状态和当前激活的 Layer。

3. 可接入（Integratable）

• 模块能导出为 .pulse 文件；
• 能生成最小接入示例；
• 能描述推荐的 game_event → pulse_action 映射。

游戏侧的接入界面保持简单，概念上只有六个动作：load(module)、play()、setState(state)、setParameter(parameter, value)、stop()、dispose()。

接入合同：决定开发者能调用什么

metadata.publicInterface 声明模块公开给游戏代码的状态和参数子集：

{
  "metadata": {
    "publicInterface": {
      "schemaVersion": 1,
      "initialStateId": "exploration",
      "stateIds": ["exploration", "combat"],
      "parameterIds": ["tension"]
    }
  }
}

填写规则（schema version 1）：

• initialStateId 必须等于 manifest states 数组的第一项，且必须出现在 stateIds 中；
• 列出的每个 ID 必须唯一，且指向真实存在的状态或参数；
• 未列出的状态和参数仍是有效的内部数据，但游戏侧代码生成器和 SDK 不会把它们当作公开 API。

没有声明接入合同的旧包是兼容的：工具可以推断全部状态和参数，但会明确标注为"推断结果"，因为其中可能混入内部制作用 ID。推断结果不会被静默写回文件——必须由设计师在 Builder 的「游戏接入合同」中主动确认并保存。

⚠️ 具体的游戏事件名（如 encounter:start）不属于接入合同。每个游戏自己把事件映射到你公开的 ID 上，你只负责公开干净、稳定的 ID。

在 Builder 中操作接入合同的完整步骤，见 Pulse Designer 手册第三部分。

兼容性元数据

metadata.compatibility 是给接入方的交付提示：

{
  "metadata": {
    "compatibility": {
      "minRuntimeVersion": "0.2.0",
      "supportedCodecs": ["wav", "mp3"],
      "requiredFeatures": ["embeddedAudio", "stateTransitions", "parameterMapping"],
      "optionalFeatures": ["barSyncTransitions", "dspParameters"],
      "targetEngines": [
        { "engine": "html5", "adapter": "web-audio" },
        { "engine": "custom", "adapter": "PulseGameRuntime" }
      ]
    }
  }
}

它只是交付与接入提示，不是商店授权系统，也不是完整的引擎插件清单。

版本边界

• 当前容器版本为 PULS v1；
• 解析器会拒绝 version > 1 的文件，接受 version <= 1，旧包随格式演进仍能打开；
• 三项交付要求是 v0.1 的产品与校验约束。Pulse Engine 不是完整 DAW，不是 Wwise/FMOD 替代品，也不是大型音频中间件——交付说明里不要做超出当前能力的承诺。

交付前检查

• 模块在 Pulse Engine App 中能加载、播放、切换全部公开状态；
• 循环、Layer、转场行为与制作预期一致；
• Web Preview 可用，状态按钮和 Layer 显示正常；
• 「游戏接入合同」已逐项确认，只公开游戏真正需要的 ID；
• 导出信息（名称、说明、授权）已填写完整；
• 交付说明没有承诺 Stinger、Unity/Unreal runtime 等当前不存在的能力。

更完整的交付检查清单见 Pulse Designer 手册。