@combos-fun/plugin-sound 0.0.6 → 0.0.7

package/README.md

@@ -1,3 +1,27 @@
 # @combos-fun/plugin-sound
 
-Internal workspace package (Combos Fun monorepo).
+@combos-fun/plugin-sound — part of the Combos Fun engine monorepo.
+
+Keywords: `sound`, `audio`, `playback`, `volume`, `web-audio`, `sfx`, `bgm`.
+
+## Documentation
+
+- Per-package agent / developer notes: [`agent-skill.md`](./agent-skill.md)
+- Machine-readable manifest: [`combos-plugin.json`](./combos-plugin.json)
+  (validated against `schemas/combos-plugin.schema.json` in the repo
+  root)
+- Entry skill (single source of truth for AI agents working with this
+  monorepo): `skills/combos-engine-development/SKILL.md`
+
+When consumed from npm, the manifest and agent notes are exposed as
+stable subpaths:
+
+```ts
+import manifest from '@combos-fun/plugin-sound/plugin-manifest';
+// or fetch the markdown directly:
+// require.resolve('@combos-fun/plugin-sound/agent-skill')
+```
+
+## License
+
+Internal workspace package, part of the Combos Fun engine monorepo.

package/agent-skill.md

@@ -0,0 +1,122 @@
+# `@combos-fun/plugin-sound` — Agent notes
+
+Audio playback for Combos Fun. Web Audio internally
+(`AudioContext` + `AudioBufferSourceNode` + `GainNode`). Shared between 2D
+and 3D — there is no spatial / 3D-positional audio in this package.
+
+## When to read
+
+Read for any audio task: SFX, BGM, autoplay, loop, mute, volume, pause /
+resume integration with `Game.pause()` / `Game.resume()`, touch-to-unlock
+on mobile.
+
+## Public API
+
+```ts
+import { Sound, SoundSystem } from '@combos-fun/plugin-sound';
+import { resource, RESOURCE_TYPE } from '@combos-fun/engine';
+```
+
+### `Sound` Component params
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `resource` | `string` | Engine resource name registered with `RESOURCE_TYPE.AUDIO` |
+| `autoplay` / `loop` / `muted` | `boolean?` | |
+| `volume` | `number?` | `0` – `1` |
+| `seek` / `duration` | `number?` | |
+| `onEnd` | `() => void?` | Fires when playback ends naturally |
+
+Methods: `play()`, `pause()`, `stop()`. Read-only fields: `playing`,
+`state` (`'unloaded' | 'loading' | 'loaded'`), `muted`, `volume`.
+
+### `SoundSystemParams`
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `onError` | `(error: unknown) => void` | **Required** — TypeScript will fail without it |
+| `autoPauseAndStart` | `boolean?` | Pause / resume audio along with `Game` |
+
+System API: `resumeAll()`, `pauseAll()`, `stopAll()`, `muted`, `volume`,
+`audioLocked` (true until first user gesture). Decoded `AudioBuffer`s are
+cached per resource.
+
+### Audio resource registration
+
+```ts
+resource.addResource([
+  { name: 'bgm', src: { audio: { type: 'audio', url: '/bgm.mp3' } }, preload: true },
+]);
+```
+
+The loader configures `mp3` / `wav` / `aac` / `ogg` as `arrayBuffer`. The
+audio buffer is decoded once and reused.
+
+## Required setup
+
+- Add `SoundSystem` after the renderer system. Order does not affect
+  audio correctness, but keeping it consistent helps debugging.
+- Always pass `onError` — this is enforced by TypeScript.
+- Audio is locked until the first user gesture (browser autoplay policy).
+  Either start audio inside an event-driven Component (e.g. on tap) or
+  show a "tap to start" UI on first paint.
+
+## Runtime behaviour
+
+- `Sound.play()` resolves to a fresh `AudioBufferSourceNode` per call;
+  re-`play()` after `stop()` works.
+- `SoundSystem` listens to the unlock gesture once and sets
+  `audioLocked = false`. Subsequent plays succeed without user gesture.
+- `autoPauseAndStart: true` calls `pauseAll()` on `Game.pause()` and
+  `resumeAll()` on `Game.resume()`.
+
+## Common pitfalls
+
+| Symptom | Fix |
+|---------|-----|
+| TS: `onError` missing | `new SoundSystem({ onError: (e) => console.warn(e) })` |
+| No sound on page load | Browser autoplay policy — call `play()` from a user-gesture Component |
+| `state === 'unloaded'` | Resource not registered, or component `resource` name doesn't match |
+| `state === 'loading'` forever | Resource URL 404 or CORS — check network tab |
+| Stuck loud after pause | `volume` is per Sound; use `SoundSystem.volume` for global mute |
+
+## Minimal example
+
+```ts
+import { Game, GameObject, resource } from '@combos-fun/engine';
+import { RendererSystem } from '@combos-fun/plugin-renderer';
+import { Sound, SoundSystem } from '@combos-fun/plugin-sound';
+
+resource.addResource([
+  { name: 'tap-sfx', src: { audio: { type: 'audio', url: '/tap.mp3' } }, preload: true },
+]);
+
+new Game({
+  systems: [
+    new RendererSystem({ canvas, width: 750, height: 1334 }),
+    new SoundSystem({ onError: (e) => console.warn(e) }),
+  ],
+  onSystemsBootstrapComplete: (game) => {
+    const audio = new GameObject('tap-audio');
+    audio.addComponent(new Sound({ resource: 'tap-sfx' }));
+    game.getScene().addChild(audio);
+
+    // Trigger from a tap Component:
+    // gameObject.getComponent(Sound)?.play()
+  },
+});
+```
+
+## Video
+
+`RESOURCE_TYPE.VIDEO` is supported by `@combos-fun/engine`'s loader for
+`{ video: { type: 'mp4', url: '...' } }`, but on-canvas video playback is
+app- or plugin-specific. After `getResource(name)`, use the resolved
+`instance` in your video plugin or a DOM `<video>` element.
+
+## Verification
+
+- `pnpm --filter @combos-fun/plugin-sound run build`
+- Run an example with audio on touch / click: verify autoplay-locked state
+  unlocks after the first user gesture and the buffer is cached for
+  subsequent plays.

package/combos-plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "@combos-fun/plugin-sound",
+  "pluginId": "sound",
+  "category": "audio",
+  "dimension": "shared",
+  "isCore": false,
+  "keywords": ["sound", "audio", "playback", "volume", "web-audio", "sfx", "bgm"],
+  "agentSkill": "./agent-skill.md",
+  "requires": ["@combos-fun/engine"],
+  "exports": ["Sound", "SoundSystem"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combos-fun/plugin-sound",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "@combos-fun/plugin-sound",
   "main": "index.js",
   "module": "dist/plugin-sound.esm.js",
@@ -8,8 +8,22 @@
   "unpkg": "dist/CombosFun.plugin.sound.min.js",
   "files": [
     "index.js",
-    "dist"
+    "dist",
+    "agent-skill.md",
+    "combos-plugin.json"
   ],
+  "exports": {
+    ".": {
+      "import": "./dist/plugin-sound.esm.js",
+      "require": "./index.js",
+      "types": "./dist/plugin-sound.d.ts"
+    },
+    "./plugin-manifest": "./combos-plugin.json",
+    "./agent-skill": "./agent-skill.md"
+  },
+  "combos": {
+    "pluginManifest": "./combos-plugin.json"
+  },
   "types": "dist/plugin-sound.d.ts",
   "keywords": [
     "combos-fun",
@@ -18,7 +32,7 @@
   "author": "sun668 <q947692259@gmail.com>",
   "dependencies": {
     "eventemitter3": "^5.0.4",
-    "@combos-fun/engine": "0.0.6"
+    "@combos-fun/engine": "0.0.7"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.mjs"