`game/schemas`

(no submodules)

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

import { GameAudioPluginOptionsSchema } from "@suaveplan/audio-plugins-fx/game";

const parsed = GameAudioPluginOptionsSchema.parse({
    listenerPosition: { x: 0, y: 0, z: 0 },
});

Usage: Advanced Example

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.

3.5 KiB Raw Blame History

game/schemas