Pulse Designer 手册：Builder 高级设置

**角色定位：**这是给制作、整理和交付 .pulse 音乐包的 Pulse 设计师看的操作手册，不是购买者试听说明，也不是游戏 SDK 接入文档。
不确定自己该读哪份文档时，先回到按角色选择文档。
本手册适合第一次接触互动音乐、音频中间件和 .pulse 的内容制作者。
本文描述的是当前 v0.1 的真实行为，不把未来规划当成已经实现的功能。

这份文档很长，我应该从哪里开始

• 只想知道高级设置要不要碰：先看决策树。
• 正在使用 Template_No.1：直接看最简操作教程。
• 不理解 Layer：看第一部分：分层音轨。
• 不理解参数和声音处理：看第二部分：游戏参数。
• 准备交给开发者：看第三部分：游戏接入合同和交付检查清单。
• 准备商业交付：看第四部分：导出信息和第五部分：技术标识。
• 只想快速查答案：看一页速查表。

本文操作步骤默认以 Desktop 桌面版为主：

• Desktop 的“保存 / 另存为”会写出 .pulse 文件；
• Web 版的“保存”只保存到浏览器本地，只有“导出”才会生成 .pulse 文件。

先放心：大多数项目根本不用改高级声音设置

Builder 现在把设计师工具分成两个作者专用区域，试听者和购买者不会看到这些表单：

1. 高级声音设置（可选）：分层音轨和游戏参数。大多数项目不需要修改。
2. 交付与游戏接入（导出前确认）：游戏接入合同、项目元数据、授权与技术标识。准备交付时才需要逐项确认。

它们不是一套必须从头填到尾的表格：

• 分层音轨：让主音乐和额外的鼓、贝斯、氛围等分轨同时播放。
• 游戏参数：给游戏程序一个可以连续调节的声音旋钮。
• 游戏接入合同：决定开发者能调用哪些状态和参数。
• 导出信息：告诉别人这个包叫什么、是什么、允许怎样使用。

如果你正在使用 Template_No.1，最安全的做法是：

• 分层音轨保持空白；
• 保留现有的 volume 参数，不增不删；
• 准备交给开发者时，逐项确认“游戏接入合同”，不要不看就公开全部内容；
• 只有准备导出或交付时才检查“项目元数据”；
• 不修改“技术标识”，除非你正在建立一个全新的独立产品。

先看决策树：我到底要不要碰它

你只是想试听、修改状态或导出 Template_No.1 吗？
├─ 是
│  └─ 不需要添加分层音轨，也不要改游戏参数。
│     如果要对外交付，再检查“交付与游戏接入”。
│
└─ 不是
   │
   ├─ 你有单独导出的鼓、贝斯、氛围等同步分轨吗？
   │  ├─ 有 → 可以考虑“分层音轨”
   │  └─ 没有 → 不要添加 Layer
   │
   ├─ 游戏需要在不切换状态的情况下连续改变声音吗？
   │  例如危险度从 0% 慢慢升到 100%
   │  ├─ 需要 → 可以定义“游戏参数”
   │  └─ 不需要 → 只使用状态切换
   │
   ├─ 这个包要交给别人、上传或出售吗？
   │  ├─ 是 → 确认游戏接入合同，再填写标题、描述、授权和标签
   │  └─ 否 → 导出信息可以暂时不改
   │
   └─ 这是全新的独立产品，而不是原包的更新吗？
      ├─ 是 → 在接入前建立一次新的模块 ID 和 Slug
      └─ 否 → 不要修改技术标识

先记住：这里有“提交设置”和“保存文件”两层

表单里改完内容，不代表磁盘上的 .pulse 已经更新。

最简单的记法：

第一层：把当前表单提交给工程
第二层：把整个工程写成 .pulse 文件

一分钟理解 Builder 里的几个词

可以把一个 .pulse 理解成：

音频素材
  ↓ 切成可播放片段
状态及转场
  ↓ 可选：分层音轨、游戏参数
游戏接入合同
  ↓
项目元数据与授权
  ↓
一个可播放、可接入、可交付的 .pulse 文件

第一部分：分层音轨

一句话解释

分层音轨是在某个状态的主音乐已经播放时，再让另一段独立声音一起播放。

例如：

战斗状态
├─ 主音乐：基础战斗循环
├─ Layer：独立鼓组
└─ Layer：独立高强度旋律

进入战斗状态时，三段声音会同时开始。离开战斗状态时，这些 Layer 也会停止。

它不是什么

• 不是设置主音乐的地方。 主音乐属于状态本身。
• 不是把两首完整歌曲混在一起。 两首完整混音通常会互相打架。
• 不是 Stinger。 Stinger 是事件发生时盖在当前音乐上的一次性短句。
• 不是游戏音效触发器。 它会在进入状态时自动开始，不会等待击杀、升级等事件。

什么时候才应该使用

只有下面条件都满足时才考虑添加：

• 你确实有单独导出的鼓、贝斯、旋律或氛围分轨；
• 所有分轨 BPM（音乐速度）相同；
• 所有分轨从同一个拍点或小节起点导出；
• 长度和循环点能够对齐；
• 同时播放时已经人工试听，不会削波（音量过载失真）或混成一团。

如果拿到的是已经混好的 intro.wav、verse.wav、combat.wav，就不要使用 Layer。

界面里的项目分别是什么

真要使用时，照着这几步做

1. 先在资源区上传真正的独立分轨，例如 combat-drums.wav。
2. 确认它已经生成可播放片段。
3. 点击要编辑的状态，例如“战斗”，并确认播放器的“当前状态”已经真正显示为战斗；如果转场仍在等待，先等它完成。
4. 展开“高级声音设置”。
5. 在“战斗的音轨”中点击“添加音轨”。
6. 把名字改成“鼓组”，然后按 Enter 或点击输入框外面。
7. 只选择一个循环片段。
8. 先用较低音量试听，例如 20%–30%，再逐渐增加。
9. 停止后重新播放，或离开再进入该状态，让新定义真正重新启动。
10. 从其他状态切入战斗，再从战斗切出，确认起点和小节对齐。
11. Desktop 点击“保存 / 另存为”；Web 点击“导出”，写出 .pulse。

Template_No.1 应该怎样处理

Template_No.1 的 intro、verse、build up、bridge、outro 是完整混音，不是同步 Stem（独立分轨）。

因此：

分层音轨保持空白，不要为了“填满高级声音设置”而添加内容。

第二部分：游戏参数

一句话解释

游戏参数是游戏程序能够实时转动的虚拟旋钮。

例如，游戏可以不断把危险度传给音乐：

危险度 0   → 音色较暗
危险度 50  → 音色开始变亮
危险度 100 → 音色最明亮、最紧张

它和状态切换不同：

参数不会自动做什么

定义一个 tension 参数后，它不会：

• 自动读取玩家血量；
• 自动知道敌人数量；
• 自动判断是否进入战斗；
• 自动控制 Layer 音量；
• 在没有游戏代码调用时自己变化。

参数的默认值会在播放初始化时使用，状态预设或状态效果器也可能覆盖它。如果希望参数跟随玩家血量、敌人数量等玩法数据连续变化，游戏开发者仍然必须主动调用这个参数，并传入合法数值。

每个字段的人话解释

“控制内容”每个选项是什么意思

自定义 DSP 范围到底是什么

最简单的比喻是“翻译表”。

游戏和界面喜欢使用容易理解的范围：

0% → 50% → 100%

但音频引擎可能需要：

0.0 → 0.5 → 1.0

于是可以设置：

参数范围：0–100
DSP 范围：0–1

再举一个音色明暗的例子：

参数范围：0–100
DSP 范围：900–6200 Hz

游戏只需要理解“危险度 70”，引擎会把它换算成对应的滤波频率。

真要添加参数时，照着这几步做

1. 先和游戏开发者确认是否真的需要连续变化的旋钮，以及固定调用名称。
2. 展开“高级声音设置”，在“游戏参数”中点击“添加参数”。
3. 先填写必填的“游戏调用名称”和“英文名称”。
4. 调用名称必须以小写字母开头，只使用小写字母、数字、短横线或下划线，例如 tension、player_health。
5. 填写最小值、最大值、步长和默认值；默认值必须位于范围内。
6. 选择“控制内容”。如果选择“仅传递游戏数据”，它不会直接发声。
7. 当界面范围与声音处理需要的范围不同时，勾选“自定义 DSP 范围”并填写翻译范围。
8. 点击“保存参数”。这一步只提交到当前工程，不等于保存 .pulse 文件。
9. 在主界面的参数滑块上分别试听最小值、默认值和最大值，确认没有静音、爆音或过强效果。
10. Desktop 再点击“保存 / 另存为”；Web 点击“导出”。

参数首次保存后，当前界面不能直接修改游戏调用名称。如果名称写错，只能在尚未接入时删除后重建；接入开始后不要改名。

仅供已有明确接入需求时参考的参数模板

默认不要为了“让高级声音设置看起来完整”而添加参数。只有游戏已经决定怎样计算和传入紧张度时，才参考下面的模板。

如果游戏确实需要一个连续的“紧张度”旋钮，可以从下面开始：

游戏调用名称：tension
英文名称：Tension
中文名称：紧张度
最小值：0
最大值：100
步长：1
默认值：20
单位：%
控制内容：音色明暗
自定义 DSP 范围：900–6200

但在真实游戏代码决定怎样计算 tension 之前，不要仅仅为了展示而添加它。

Template_No.1 的现有 volume 参数

当前模板已经有一个可工作的总音量参数：

游戏调用名称：volume
范围：0–100
步长：1
默认值：80
单位：%
控制内容：总音量
DSP 范围：0–1

人话解释：界面显示 50%，引擎实际收到 0.5。

如果你还没有明确的新接入需求，保留它，不要增删。

第三部分：游戏接入合同

一句话解释

游戏接入合同是一张由 Pulse 设计师确认的“开发者可调用清单”。

一个包里可能有很多为了编排而存在的状态和参数，但游戏开发者通常只需要很少几个稳定入口。例如：

包内实际内容
├─ exploration      公开：游戏可调用
├─ combat           公开：游戏可调用
├─ combat-tail      内部：只用于音乐编排
├─ tension          公开：游戏可调用
└─ debug-filter     内部：只用于制作试听

过去开发者只能看到一长串 ID，再猜哪些该用。接入合同把这件事变成设计师的一次明确选择：勾选的才是公开 API，没勾选的都属于包内实现。

它解决什么问题

• 开发者只看到真正需要调用的少量状态和参数；
• 包内可以保留过渡状态、调试参数等制作细节；
• Desktop 帮助页能自动生成可复制的 pulseContract、参数范围和最小接入代码；
• 以后修改包内编排时，只要公开合同不变，游戏代码就不需要跟着改。

它不会改变声音，也不会替你设计游戏事件。游戏里的 encounter:start、boss:defeated 等事件名仍由游戏项目决定；合同只说明这些事件最终可以调用哪些 Pulse state/parameter ID。

界面上的两组勾选框

在“交付与游戏接入”中打开“游戏接入合同”，会看到：

素材、片段和 Layer 不会出现在合同选择里，因为它们永远是包内实现。

为什么第一个状态不能取消

runtime 加载后必须有一个确定的起点。当前 v0.1 把模块列表中的第一个状态当作初始状态，因此它必须包含在公开状态中，界面会固定勾选。

如果第一个状态不适合作为游戏起点，应先回到状态编排，调整模块本身的第一个状态，而不是试图在合同里隐藏它。合同至少会有这一个公开状态；公开参数则可以为空。

旧包警告是什么意思

旧版 .pulse 没有接入合同。打开这种包时，界面会显示警告，并把当前全部状态和参数先勾上，作为一个待确认的起点。

这不表示“全部公开”已经是正确答案。请逐项检查：

1. 保留第一个初始状态；
2. 取消勾选仅用于过渡、测试或内部编排的状态；
3. 取消勾选游戏不需要主动控制的参数；
4. 点击“保存接入合同”；
5. 再执行 Desktop 保存/另存为或 Web 导出。

为了兼容旧文件，只是打开或普通保存旧包时，系统不会偷偷把推断结果写成正式合同。必须由设计师主动点击“保存接入合同”，这份选择才算得到确认。

新增或删除内容后怎样处理

• 已经保存过明确合同后，新添加的状态或参数默认仍是内部内容，不会自动公开；
• 想让开发者使用新内容时，回来勾选并再次保存合同；
• 删除或重命名已公开内容后，界面会显示合同引用失效的警告；
• 检查并保存后，系统只保留当前仍然存在的 ID；
• 如果一个状态都没有，合同无法保存。请先创建至少一个状态。

这种“默认不公开”的行为是为了避免一次内部编辑意外扩大游戏 API。

交付前照着这几步做

1. 完成状态、转场、Layer 和参数制作，并把第一个状态设为合理的默认起点。
2. 展开“交付与游戏接入”。
3. 在“游戏接入合同”里逐项勾选开发者真正需要调用的状态。
4. 确认带“初始状态”标记的第一项正确。
5. 只勾选需要由游戏实时传值的参数；没有也完全正常。
6. 点击“保存接入合同”。
7. Desktop 再点击“保存 / 另存为”；Web 点击“导出”。
8. 用 Pulse Desktop 重新打开最终文件，在帮助页查看生成的 pulseContract 和接入示例。
9. 确认帮助页没有旧包、损坏合同或不支持版本的警告。
10. 把这一个最终 .pulse 与生成的合同一起交给开发者。

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

Template_No.1 应该怎样选择

不要因为界面最初全部勾选，就直接把五个状态和 volume 全部公开。

1. 第一项状态会固定公开，因为它是初始状态。
2. 对其余 intro、verse、build up、bridge、outro 对应状态，逐个问：“游戏是否真的需要主动切到这里？”需要才勾选。
3. 只有开发者确实要控制总音量时才公开 volume；如果游戏使用自己统一的音量系统，可以不公开它。
4. 保存合同后，到帮助页确认开发者最终只看到你有意公开的清单。

这里没有一份适合所有游戏的固定答案。合同表达的是这个具体商品的游戏用法，应由内容设计和接入需求共同决定。

第四部分：导出信息

一句话解释

导出信息不负责播放音乐，只负责告诉别人这个 .pulse 包叫什么、是什么、允许怎样使用。

每个字段是什么

如果项目会在中文界面展示，建议同时填写中文标题和中文描述。当前留空可能保存成空字符串，而不是自动回退到英文。

买家使用授权栏必须知道的事

在输入框里写下授权文字，不会自动产生版权，也不会替代合同。它只是把已经真实存在的授权记录进包里。

这里必须先分清两个不同问题：

1. 项目方拿到的素材权利：项目方是否有权商业使用和制作再分发包。
2. 最终用户拿到的许可：购买或收到 .pulse 的人被允许怎样使用、能否继续转售或再分发。

当前已经确认的是第一项：项目方对 Template_No.1 音乐拥有商业使用和再分发权。这份来源记录保存在仓库的 ASSETS_LICENSE.md。

“买家使用授权”输入框用于填写随 .pulse 交付给最终用户的许可摘要。除非合同明确允许最终用户继续再分发，否则不要直接复制一句没有主语的“redistribution authorized”，以免把项目方拥有的权利误写成买家拥有的权利。

如果真实合同包含地域、平台、项目数量、二次编辑或转售限制，应使用合同中的准确文字，不要自行扩大权利范围。拿不准时，先保留内部权利记录，再让实际授权条款确定这个字段的最终文案。

标签怎样填写

使用英文逗号或换行分隔：

interactive-music, game, technology

系统会去掉首尾空格和重复标签。中文顿号 、 不会被当作分隔符。

“保存导出信息”不等于保存文件

这是最容易误解的地方：

1. 点击“保存导出信息”只是把表单内容应用到当前工程，并把工程标记为有修改。
2. Desktop 还要点击应用级“保存”或“另存为”，才能真正写入磁盘上的 .pulse。
3. Web 的“保存”只写入浏览器本地；必须点击“导出”才会生成 .pulse 文件。
4. 导出信息不进入 AudioCore 的 Undo 历史；误保存后需要手动改回。
5. 如果表单还没点击“保存导出信息”，直接保存整个工程不会带上这些未提交草稿。

可以记成：

保存导出信息 = 把标签贴到当前工程
Desktop 保存 / 另存为 = 把整个工程真正写进 .pulse 文件
Web 导出 = 生成 .pulse 文件

第五部分：技术标识

把它理解成商品条形码

• 标题像商品名称，可以从“Template_No.1”改成“Minimal Tech”。
• 模块 ID 和 Slug 像商品条形码，用来证明它还是同一个产品。
• 游戏接入后修改条形码，可能让游戏或更新流程找不到原来的包。

模块 ID 和 Slug 的区别

当前 Builder 会在它们留空时，根据英文标题自动生成。自动生成后不要反复修改。

当前界面还没有完整校验 ID/Slug 的安全字符。手动填写时只使用小写英文字母、数字和短横线，例如 minimal-tech-pilot；不要使用空格、中文、斜杠或特殊符号。

什么时候可以改

只有一种安全情况：

你正在创建一个全新的独立产品，并且游戏开发者还没有开始接入。

例如，从内置模板制作一个新的对外商品时，可以先“另存为”，然后一次性设置：

模块 ID：minimal-tech-pilot
Slug：minimal-tech-pilot

之后无论修改标题、描述、音频还是版本，都保持这两个值不变。

什么时候绝对不要改

• 游戏已经使用这个 ID 接入；
• 已经发布过旧版本，准备发布更新；
• 只是想改一个更好看的标题；
• 不确定这个字段有什么用。

不确定时，答案永远是：保持原样。

Template_No.1 最简操作教程

情况一：我只想试听

1. 打开 Template_No.1。
2. 点击播放。
3. 依次点击 intro、build up、verse、bridge、outro。
4. 不需要打开高级声音设置。
5. 不需要添加 Layer，也不需要新增参数。

情况二：我要修改后保存自己的副本

1. Desktop 打开模板后先点击“另存为”；Web 则在完成编辑后使用“导出”。
2. 选择自己的文件名，避免误以为正在覆盖内置模板。
3. 修改状态、转场或其他主流程内容。
4. 高级声音设置中的分层音轨保持空白。
5. 保留现有 volume 参数。
6. 如果只是自己的制作副本、尚不交给开发者，接入合同可以等交付前再确认。
7. Desktop 点击“保存”；Web 点击“导出”生成自己的 .pulse。

情况三：我要制作一个可以对外交付的 .pulse

1. 先另存为独立副本。
2. 试听五个状态。 确认每个状态都有声音。
3. 分层音轨保持空白。 当前五段素材是完整混音。
4. 保留现有 volume 参数。 不随意删除或修改调用名称。
5. 确认游戏接入合同。
   • 第一个状态固定公开；先确认它适合作为初始状态。
   • 其余状态只公开游戏真正要主动切换的部分。
   • 只有开发者需要控制总音量时才公开 volume。
   • 点击“保存接入合同”。
6. 填写导出信息。
   • 英文标题：例如 Minimal Tech
   • 中文标题：例如 极简科技
   • 英文描述：说明它是怎样的互动游戏音乐
   • 中文描述：对应中文说明
   • 买家使用授权：填写准备授予最终使用者的真实许可摘要，不要把项目方自身拥有的素材权利原样照抄
   • 标签：interactive-music, game, technology
7. 决定一次技术标识。
   • 如果只是原产品更新：保持原样。
   • 如果这是首次创建独立商品，且尚未接入：设置一次新的 ID/Slug，之后不要再改。
8. 点击“保存导出信息”。
9. Desktop 再点击“保存 / 另存为”；Web 点击“导出”。
10. 关闭工程后重新打开刚保存的 .pulse。
11. 在帮助页检查生成的 pulseContract，再完成交付检查。

交付检查清单

• 文件能够重新打开，没有校验错误
• 每个状态都有声音
• 循环点没有明显断裂或爆音
• 每个已经定义的转场方向都逐一试听过；业务需要返回时，确认反向转场另有定义
• BPM 和每小节拍数正确
• 默认音量安全，没有明显削波
• 标题、描述、标签仍然存在
• 买家使用授权文字与真实合同一致
• 模块 ID 和 Slug 没有意外变化
• 游戏接入合同已由设计师主动保存，不是未确认的旧包推断
• 第一个状态是正确的初始状态，并且保持公开
• 只公开游戏真正需要调用的状态和参数，内部内容没有意外暴露
• 帮助页生成的 pulseContract 没有合同警告，参数范围正确
• 同一个最终 .pulse 被用于预览（Preview）、测试和游戏接入

Layer、参数和 Stinger 到底是什么关系

Layer    = 跟某个状态一起播放的附加循环分轨
参数     = 带默认值、也可以由状态或游戏实时改变的全局声音旋钮
Stinger  = 事件发生时覆盖在当前音乐上的一次性短句

当前版本：

• Layer 已实现，但主要适合固定音量的循环 Stem；
• 参数已实现并会应用默认值，但作用于整条输出；只有跟随玩法实时变化时才需要游戏代码持续传值；
• 真正的 Stinger 尚未实现；
• trigger() 当前只是状态切换的别名，不能当作通用音效触发器。

不要用非循环 Layer 假装 Stinger，也不要把一个完整状态误当成不会打断主音乐的叠加音效。

常见误区和正确答案

“高级设置每一项都必须填吗？”

不需要。“高级声音设置”是可选的；但准备交给开发者时，应在“交付与游戏接入”里主动确认一次接入合同和项目元数据。

“旧包已经把全部状态勾上了，是不是全部都要交给开发者？”

不是。那只是兼容旧包的待确认起点。取消勾选游戏不需要调用的内部状态和参数，再点击“保存接入合同”。

“没勾选的状态还会播放吗？”

会。接入合同不删除内容，也不改变包内转场和播放编排；它只阻止游戏代码把内部 ID 当成公开 API 直接调用。

“为什么初始状态不能取消勾选？”

当前模块的第一个状态就是 runtime 的确定起点，因此必须公开。如果起点选错，应先调整状态编排，而不是在合同中隐藏它。

“一个参数都不公开可以吗？”

可以。很多游戏只需要切换音乐状态，不需要连续参数。公开参数清单可以为空。

“我后来新建了状态，为什么开发者合同里没有自动公开？”

这是有意的安全行为。新内容默认是内部实现；只有设计师再次勾选并保存，才会扩大公开合同。

“状态没有主音乐，所以来 Layer 里添加吗？”

不是。主音乐应在状态的片段配置中设置。Layer 只负责额外叠加。

“把 intro 和 verse 同时勾进一个 Layer 会不会更丰富？”

不会。当前只播放第一个，而且两段完整混音也不适合叠加。

“添加 tension 参数后，它会自动读取玩家血量吗？”

不会。游戏代码必须自己计算危险度并调用 setGameParameter()。

“仅传递游戏数据会改变声音吗？”

不会。它只保存数值和产生事件。

“参数范围写 0–100，混响就能正确工作吗？”

不一定。混响实际需要 0–1，应设置 DSP 范围进行换算。

“我改了参数，为什么所有声音都变了？”

因为当前 DSP 参数作用于总输出，不是某个单独状态或 Layer。

“我删除参数后为什么导出失败？”

某个状态预设或效果器可能仍然引用旧参数。恢复该参数，或清理所有引用后再导出。

“保存导出信息后，文件为什么没更新？”

因为还没有执行最终文件操作：Desktop 使用“保存 / 另存为”，Web 使用“导出”。

“填写授权文字就证明我有版权了吗？”

不会。它只是文字记录，既不会创造授权，也不会自动证明授权；最终应以真实合同和权利文件为准。

“改标题时要顺便改 ID 吗？”

不要。标题可以改变，技术标识应保持稳定。

一页速查表

外行词汇表

最后只记住八句话

1. 不懂的高级设置可以不碰。
2. 完整混音不要添加 Layer。
3. 参数有默认值；只有跟随玩法实时变化时才需要游戏代码持续调用。
4. 参数影响总输出，不控制单独 Layer。
5. 交付前只公开开发者真正需要的状态和参数。
6. 第一个状态固定为公开初始状态；参数可以一个都不公开。
7. 保存表单后，Desktop 还要保存，Web 还要导出。
8. 技术标识像条形码，接入后绝对不要改。