Pulse Game 接入说明书 | Soundbook Docs

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;

pnpm add @clxgame/pulse-game

public/packs/forest-combat.pulse

import {
  loadPulseGame,
  type PulseGameRuntime,
} from "@clxgame/pulse-game";

export async function loadSceneMusic(
  url = "/packs/forest-combat.pulse",
): Promise<PulseGameRuntime> {
  return loadPulseGame(url);
}

import { createPulseGameLiveSyncPlugin } from "@clxgame/pulse-game/vite";

createPulseGameLiveSyncPlugin({
  livePackPath: "/absolute/path/to/live-sync.pulse",
  fallbackPackPath: "/absolute/path/to/forest-combat.pulse",
  contract: gameSyncContract,
});

import { pulseContract } from "./pulse-contract";

const music = await loadSceneMusic();
startButton.disabled = false;

startButton.addEventListener("click", async () => {
  music.setGameState(pulseContract.initialStateId);
  await music.play();
});

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`	保持当前时间位置切换。

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);
}

async function prepareCombat() {
  await music?.preloadGameState("combat");
}

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;
}

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);
});

import {
  buildIntegrationExample,
  buildPulseContractSnippet,
} from "@clxgame/pulse-game";

const generated = buildIntegrationExample(module, {
  packageUrl: "/packs/forest-combat.pulse",
});

console.log(generated.contract);        // 结构化公开合同
console.log(generated.contractSnippet); // 可复制的 pulseContract.ts
console.log(generated.snippet);         // 最小加载与事件示例
console.warn(generated.warnings);       // 包括旧包推断警告

// 只需要 TypeScript 合同时：
console.log(buildPulseContractSnippet(module));

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);

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(),
});

pnpm dev:html5-game

download -> strict package load -> ready -> user gesture play
-> setGameState -> setGameParameter -> dispose

Pulse Game 接入说明书 | Soundbook Docs