本说明书面向要在 Web / HTML5 游戏中接入一个已交付 .pulse 音乐包的游戏开发者。
第一次接入请先完成游戏开发者 5 分钟接入，再回到本文处理预加载、事件、部署和错误降级。不确定该读哪份文档时，请从角色导航开始。
它只描述当前已实现、可验证的能力：加载包含内嵌音频的 .pulse、播放、状态切换、参数控制、预加载、事件监听和释放。当前生产接入边界是 @clxgame/pulse-game；Unity、Godot、Unreal 尚没有可作为生产承诺的 runtime/插件。
一个 .pulse 文件是一份可运行的互动音乐包，包含：
- 音频 bytes（通常为内嵌 wav/mp3/ogg）；
- 状态、片段、layer、转场和参数定义；
- 可选的授权、兼容性 metadata 与开发者接入合同。
游戏侧只应依赖包内 metadata.publicInterface 明确公开的 和 。未列出的状态和参数，以及所有 resource、segment、layer ID，都属于音乐包内部编排，后续内容更新时可能变化。
state ID
parameter ID
在开始前，用 Pulse Desktop 打开最终 .pulse，从帮助页复制自动生成的 TypeScript 合同。例如：
export const pulseContract = {
source: "declared",
initialStateId: "exploration",
states: {
exploration: "exploration",
combat: "combat",
},
parameters: {
tension: {
id: "tension",
min: 0,
max: 1,
defaultValue: 0.2,
unit: null,
},
},
} as const;
生成结果还包含 state/parameter 的字面量类型，可直接放进项目的 pulse-contract.ts。每次更新音乐包时，同时更新这份生成文件，不要手写第二套 ID 清单。
- 新包明确声明合同时，模块第一个状态就是公开的
initialStateId，参数清单可以为空；SDK 只公开合同允许的 ID，内部 ID 即使存在也不能通过游戏 facade 调用；
- 旧包缺少合同时，SDK 会推断全部状态和参数并显示警告，以保证旧内容仍能运行；请先让内容方确认，不要把警告当作正式合同；
- 已声明但损坏或版本不受支持的合同不会退回「全部公开」，因此不会意外泄露内部 ID；加载或代码生成会给出明确错误。
旧包的推断结果只存在于接入工具中，不会在普通保存时被静默写回。必须由 Pulse 设计师在 Builder 的「游戏接入合同」中主动确认并保存。
pnpm add @clxgame/pulse-game
游戏代码从 @clxgame/pulse-game 导入 runtime。除非需要读取 manifest metadata、检查包内容或实现自定义资源管线，否则不需要直接依赖 @clxgame/pulse-engine。
把文件作为游戏静态资源发布。例如 Vite/Web 项目可以放在：
public/packs/forest-combat.pulse
它会以 /packs/forest-combat.pulse 提供。
推荐入口会替你完成下载、HTTP 状态检查、严格校验、runtime 创建和音频解码，但不会自动播放：
import {
loadPulseGame,
type PulseGameRuntime,
} from "@clxgame/pulse-game";
export async function loadSceneMusic(
url = "/packs/forest-combat.pulse",
): Promise<PulseGameRuntime> {
return loadPulseGame(url);
}
loadPulseGame() 默认执行严格校验；初始化失败时会自动释放未完成的 runtime。把错误上报到游戏日志/监控，并回退到静态 BGM 或静音即可。只有已有二进制资源管线或自定义 loader 的进阶 host 才需要后文的低阶 factory。
如果项目使用 Vite，可以用 @clxgame/pulse-game/vite 的开发插件把 Desktop 写出的 .pulse 暴露给游戏。它只添加本地开发路由，不会进入生产服务器：
import { createPulseGameLiveSyncPlugin } from "@clxgame/pulse-game/vite";
createPulseGameLiveSyncPlugin({
livePackPath: "/absolute/path/to/live-sync.pulse",
fallbackPackPath: "/absolute/path/to/forest-combat.pulse",
contract: gameSyncContract,
});
gameSyncContract 的字段是完整必填的：协议版本、游戏 ID/名称、adapter、runtime API 版本、必需 state、必需/可选 parameter 和 capabilities。SDK 会在 TypeScript 编译期检查；Desktop 连接时还会把网络响应当作不可信数据再次严格校验，缺字段就不会写包。
游戏侧在开发模式轮询 /__pulse-sync/status，版本变化后从 /__pulse-sync/pack 创建一个候选 runtime；只有候选包完成合同校验和预加载后，才释放旧 runtime。这样错误的编辑不会打断当前音乐。生产模式仍加载固定的静态 .pulse URL。
同一个开发桥还提供 /__pulse-sync/telemetry。游戏同源页面可以上报只读运行快照和一小段因果事件，Pulse Desktop 则显示：游戏心跳、当前公开 state、公开 parameter、正在发声的 layer、待执行转场，以及 game signal -> Pulse action -> runtime event。遥测是设计师调试信息，不是新的游戏控制 API；layer ID 也不是可依赖的稳定接入合同。
在 Pulse Desktop 中打开「让游戏驱动本地预览」后，Desktop 会用当前游戏的公开 state/parameter 驱动正在编辑的工程。所有输入都会再次经过 .pulse 的 metadata.publicInterface allowlist 与参数范围校验；信号断开、数据畸形或目标不匹配时不会继续控制本地引擎。游戏暂停或旁路不会自动停止 Desktop，因此可以静音游戏标签页里的 Pulse，只听本地工程做 A/B 对比。这里是两路独立输出：如需只听游戏原始 SFX，还要同时关闭 Desktop 的「让游戏驱动本地预览」。
出于内容保护，/__pulse-sync/status 和 /__pulse-sync/pack 只允许游戏同源访问；不能被任意网页跨域读取。遥测只接受同协议、同主机游戏页面的受限 JSON 上报，并且只有精确白名单中的 Desktop origin 可以读取；请求体、字段数量、时间戳和事件历史都有上限。/__pulse-sync/target 默认也只额外允许 Pulse Desktop 的本地开发/Tauri origin。若你的 Desktop 壳运行在其他可信 origin，可显式传 allowedTargetOrigins，不要使用通配符 *。
仓库内可以直接运行 pnpm dev:underrun-live 查看完整范例。这个命令同时启动 Pulse Desktop、SDK watcher 和 UNDERRUN；在 Desktop 的 工具 → 游戏联调面板 中先连接游戏，再点 同步到游戏。具体操作见 examples/underrun-pulse。
浏览器通常禁止在没有用户手势时恢复音频。下载和预加载可以早做，但 play() 必须放在 Start、Continue、点击画面等用户操作之后。
import { pulseContract } from "./pulse-contract";
const music = await loadSceneMusic();
startButton.disabled = false;
startButton.addEventListener("click", async () => {
music.setGameState(pulseContract.initialStateId);
await music.play();
});
在加载页或场景准备阶段先完成 loadSceneMusic()，成功后再启用开始按钮。play() 只负责从用户手势恢复并开始播放；若它失败，music.state.playing 会保持 false。
把游戏事件集中映射到生成合同里的 pack state，不要把裸字符串分散在业务代码中。
import { pulseContract } from "./pulse-contract";
const musicStates = {
exploration: pulseContract.states.exploration,
combat: pulseContract.states.combat,
} as const;
function onEncounterStarted() {
music?.setGameState(musicStates.combat, {
transitionMode: "immediate",
});
}
function onEncounterEnded() {
music?.setGameState(musicStates.exploration, {
transitionMode: "nextBar",
});
}
| mode | 行为 |
|---|
immediate | 立即切换，使用 pack 定义的交叉淡入淡出时长或默认值。 |
nextBar | 在下一个小节边界切换。 |
nextEnd | 在当前片段结束时切换。 |
sameTime | 保持当前时间位置切换。 |
不传 transitionMode 时，runtime 优先使用 pack 内对应 transition 的 mode；若 pack 没有这条 transition，则使用 immediate。同一时刻只有一个延迟转场有效，后一次请求会替换前一次 pending 请求。
传入不存在或未公开的 state ID 会同步抛出 RangeError，并保留当前可听状态。因此应在开发环境把它视为合同错误，而不是吞掉。旧包没有显式合同时，为兼容历史内容，推断出的所有状态暂时都视为公开。
trigger() 目前是 setGameState() 的别名，用于兼容接入层命名；当前 P0 没有独立的 stinger/trigger 语义。请不要把它当作通用音效触发器。
参数 ID 和数值范围由 pack 定义。未知 parameter ID、NaN 和无穷值会立即抛错；有限数值超出范围时，游戏 runtime 会自动限制到 pack 声明的最小值或最大值。游戏侧仍应按业务含义归一化并适度节流。
const tensionParameter = pulseContract.parameters.tension;
function updateMusicPressure(playerHealth: number, maxHealth: number, enemyCount: number) {
const healthPressure = 1 - playerHealth / maxHealth;
const enemyPressure = Math.min(enemyCount / 6, 1);
const tension = Math.max(0, Math.min(1, Math.max(healthPressure, enemyPressure)));
music?.setGameParameter(tensionParameter.id, tension);
}
let previousTension = -1;
function tickMusic(tension: number) {
if (Math.abs(tension - previousTension) < 0.02) return;
previousTension = tension;
music?.setGameParameter(tensionParameter.id, tension);
}
参数是否有实际听感取决于 pack 的 dspTarget。dspTarget: "none" 可用于游戏状态记录，但不会改变音频。生成合同会带上公开参数的 min、max、defaultValue 和 unit；游戏 UI 与调试工具应复用这些值，不要另抄一份范围。
loadPulseGame() 返回时已经完成整个包的音频解码，推荐路径不需要再调用预加载方法。
只有使用 createPulseGameRuntime() / createPulseGameRuntimeFromPackage() 的自定义加载流程，才可能需要在自己的加载阶段按公开 state 提前准备资源：
async function prepareCombat() {
await music?.preloadGameState("combat");
}
preloadGameState() 会对未知或未公开的 state ID 返回 reject。PulseGameRuntime 不暴露按 resource ID 预载；确实需要底层资源诊断的自定义工具应明确使用 AudioCore，不要把这条依赖带进普通游戏代码。
一个场景、关卡或音乐所有者通常只创建一个 runtime。不要在每次游戏事件时重新下载和创建。
const offs: Array<() => void> = [];
function attachMusicDebug(music: PulseGameRuntime) {
offs.push(
music.on("state-change", ({ fromStateId, toStateId }) => {
console.debug("[music] state", fromStateId, "->", toStateId);
}),
music.on("transition-executed", ({ toStateId, mode }) => {
console.debug("[music] transition", mode, "->", toStateId);
}),
);
}
function disposeSceneMusic() {
for (const off of offs.splice(0)) off();
music?.stop();
music?.dispose();
music = null;
}
游戏 facade 只提供 playback-start、playback-stop、state-change、transition-scheduled、transition-executed 和 parameter-change。事件与 runtime.state.parameterValues 都会按接入合同过滤；resource、segment、隐藏参数和底层音频上下文不会出现在普通游戏 API 中。
subscribe() 适合调试 HUD：它只提供精简后的公开 runtime state；生产逻辑更适合订阅明确的 typed event。
小项目可直接调用 setGameState / setGameParameter。若游戏已有统一事件总线，可使用可选的 mapping helper。Pulse Desktop 帮助页和 buildIntegrationExample() 都会只依据接入合同生成 starter mapping；下面是对应形式：
import { applyGameEvent, type GameEventMapping } from "@clxgame/pulse-game";
import { pulseContract } from "./pulse-contract";
const mappings: GameEventMapping[] = [
{
gameEvent: "encounter:start",
pulseAction: {
type: "setGameState",
stateId: pulseContract.states.combat,
},
},
{
gameEvent: "encounter:end",
pulseAction: {
type: "setGameState",
stateId: pulseContract.states.exploration,
},
},
{
gameEvent: "player:danger",
pulseAction: {
type: "setGameParameter",
parameterId: pulseContract.parameters.tension.id,
value: 0.8,
},
},
];
gameEvents.on((eventName) => {
if (music) applyGameEvent(music, mappings, eventName);
});
未匹配事件是安全的 no-op。示例里的游戏事件名只是占位符，应替换成项目自己的事件名；真正受合同约束的是 pulseAction 里的 state/parameter ID。这个 helper 不携带 transition mode；需要 nextBar、nextEnd 等特殊规则时，直接调用 setGameState。
import {
buildIntegrationExample,
buildPulseContractSnippet,
} from "@clxgame/pulse-game";
const generated = buildIntegrationExample(module, {
packageUrl: "/packs/forest-combat.pulse",
});
console.log(generated.contract);
console.log(generated.contractSnippet);
console.log(generated.snippet);
console.warn(generated.warnings);
console.log(buildPulseContractSnippet(module));
正式 Web 部署不依赖开发期 /__pulse-sync/* 路由。把 .pulse 一并发布到静态站点或 CDN，并从实际 URL fetch。
- 推荐使用带版本或 hash 的文件名，例如
/packs/forest-combat.v3.pulse；
- 更新内容时同步更新游戏配置，避免 CDN 长缓存拿到旧包；
- 跨域 CDN 需要允许游戏域名的 CORS；
- 保持二进制原样传输，不要把
.pulse 当 JSON 转码；
- 建议为下载失败准备静态 BGM 或无音乐回退。
仓库的 HTML5 示例在 production 下加载 /packs/forest-combat.pulse；只有 pnpm dev:html5-game 的开发服务器提供 live-sync 路由。
只在需要读取 license/兼容性 metadata，或音频由游戏自己的资源系统管理时，才安装 core：
pnpm add @clxgame/pulse-game @clxgame/pulse-engine
import { loadPulsePackage } from "@clxgame/pulse-engine";
const pack = loadPulsePackage(packageBytes, { validate: true });
console.log(pack.manifest.metadata?.license);
console.log(pack.manifest.metadata?.compatibility);
console.log(pack.manifest.metadata?.publicInterface);
若资源不内嵌在 .pulse 中，而由游戏资源系统提供：
import { createPulseGameRuntime } from "@clxgame/pulse-game";
import {
loadPulsePackage,
type Resource,
type ResourceLoader,
} from "@clxgame/pulse-engine";
class GameAssetLoader implements ResourceLoader {
load(resource: Resource): Promise<ArrayBuffer> {
return gameAssets.loadArrayBuffer(resource.src);
}
}
const pack = loadPulsePackage(packageBytes, { validate: true });
const music = createPulseGameRuntime(pack.module, {
loader: new GameAssetLoader(),
});
metadata.compatibility 目前是交付提示，不会自动阻止 runtime。游戏应在下载/安装阶段决定是否接受 license、codec、最低版本和 feature 要求。不要绕过 PulseGameRuntime 直接用 publicInterface 调底层内部状态；游戏 facade 才负责执行公开边界。
仓库内的 HTML5 项目包含合同校验、调试 UI 和 Desktop Live Sync，因此是进阶联调参考，不是应该整段复制的最小代码：
download -> strict package load -> ready -> user gesture play
-> setGameState -> setGameParameter -> dispose
Live Sync 属于交付检查，因此比普通 runtime 的旧包兼容更严格：没有经过设计师保存确认的旧包合同会被阻止同步，而不是把推断出的全部内部 ID 直接交给游戏。
当前可作为生产接入承诺的是 Web Audio / HTML5 host。以下内容不应作为当前包的承诺写入游戏计划：
- Unity、Godot、Unreal 的正式 runtime 或插件；
- 独立 stinger/trigger 模型；
- Wwise/FMOD 级复杂中间件、节点图或完整 DAW；
- runtime 内置订单、授权或 entitlement 校验。
如果接入过程中遇到 state、parameter、资源加载或部署问题，优先记录：pack 版本、state/parameter 合同、loadPulseGame() 的错误、浏览器网络请求和 music.state 快照。这些信息足以定位绝大多数接入故障。