# `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.