.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必须等于 manifeststates数组的第一项，且必须出现在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 手册。