first commit

docs/media/audio-fx/audio-fx-plugin-game-audio/src/schemas/schemas.md

@@ -0,0 +1,72 @@
+# `game/schemas`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Zod schemas validating the construction-time options, vector types, voice-chat configuration, game-state enum, and preset payload of `GameAudioPlugin`. These run on the public boundary so any malformed object is rejected with `AUDIO_FX.INVALID_OPTIONS` / `AUDIO_FX.INVALID_PRESET` before it can corrupt runtime state.
+
+Separating schemas from the plugin module lets `index.ts` re-export them so callers can introspect the option surface (for forms, RPC validation, or storybook controls) without importing the audio implementation.
+
+## Features
+
+- `Vector3Schema` — `{ x, y, z: finite }`. Reused by every position/velocity/orientation field in the package.
+- `ListenerOrientationSchema` — `{ forward, up: Vector3 }`.
+- `ProximityVoiceChatConfigSchema` — `{ minDistance, maxDistance, rolloffFactor }` with documented ranges.
+- `GameStateSchema` — `z.enum(["exploration", "combat", "victory", "menu"])`.
+- `GameAudioPluginOptionsSchema` — optional listener position, orientation, and voice-chat config.
+- `GameAudioPresetDataSchema` — `.strict()` object with all four persistent state fields (voice-chat nullable for the disabled state).
+
+## Usage: Basic Example
+
+```ts
+import { GameAudioPluginOptionsSchema } from "@suaveplan/audio-plugins-fx/game";
+
+const parsed = GameAudioPluginOptionsSchema.parse({
+    listenerPosition: { x: 0, y: 0, z: 0 },
+});
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    GameAudioPresetDataSchema,
+    ProximityVoiceChatConfigSchema,
+    Vector3Schema,
+} from "@suaveplan/audio-plugins-fx/game";
+
+function isPosition(blob: unknown): boolean {
+    return Vector3Schema.safeParse(blob).success;
+}
+
+function isVoiceConfig(blob: unknown): boolean {
+    return ProximityVoiceChatConfigSchema.safeParse(blob).success;
+}
+
+function safeApplyPreset(plugin: GameAudioPlugin, payload: unknown) {
+    const parsed = GameAudioPresetDataSchema.safeParse(payload);
+    if (!parsed.success) return false;
+    plugin.applyPreset({ version: 1, parameters: {}, presetData: parsed.data });
+    return true;
+}
+```
+
+## API Reference
+
+- `Vector3Schema: z.ZodObject<{ x, y, z }>`
+- `ListenerOrientationSchema: z.ZodObject<{ forward, up }>`
+- `ProximityVoiceChatConfigSchema: z.ZodObject<{ minDistance, maxDistance, rolloffFactor }>`
+- `GameStateSchema: z.ZodEnum<["exploration", "combat", "victory", "menu"]>`
+- `GameAudioPluginOptionsSchema: z.ZodObject<{ listenerPosition?, listenerOrientation?, voiceChat? }>`
+- `GameAudioPresetDataSchema: z.ZodObject<{ listenerPosition, listenerOrientation, voiceChat, gameState }, "strict">`
+
+## Implementation Notes
+
+`Vector3Schema` is exported as a named schema and reused throughout the file. That guarantees every position/velocity/orientation field in the package agrees on the legal vector shape — a finite 3-tuple — and downstream code that wants to validate a vector independently (e.g., a network message carrying position updates) can pull the same schema.
+
+`GameAudioPresetDataSchema` uses `.strict()` so unknown fields are rejected. `voiceChat` is `.nullable()` rather than `.optional()` because a disabled voice-chat state is a meaningful value the preset must round-trip; making it optional would lose the distinction between "absent" and "explicitly disabled".
+
+The numeric ranges on `ProximityVoiceChatConfigSchema` match the `SpatialAudioPlugin` bounds (`minDistance` 0.01..1000, `maxDistance` 0.01..100 000, `rolloffFactor` 0..10) so a developer migrating from one plugin to the other can copy values directly without re-scaling.