diff --git a/docs/Scripting/API/audio.md b/docs/Scripting/API/audio.md index 442567e..0532d00 100644 --- a/docs/Scripting/API/audio.md +++ b/docs/Scripting/API/audio.md @@ -6,7 +6,7 @@ Play engine-decoded WAV, MP3, AAC, FLAC, and OGG voices, adjust parameters and s These engine-owned services work in Lua 5.4, Luau, JavaScript, Python, C, C++, C#, Java, PHP, and HTML inline JavaScript. Follow [Use gameplay actions](/docs/guides/gameplay-actions) to create and attach a script, install external toolchains, and choose the correct language binding. PHP and HTML scripts belong under `ui/`; CSS alone runs no gameplay code. -The Calls section uses JavaScript signatures. The function examples below include native syntax for all ten script types, including SDK-specific alternatives and limitations. Attach a JavaScript Object Component script to the specified target and press **Play**. Globals are supplied by the engine. Schedule actions from `Start` or a callback, rather than at script top level. Native languages use typed options and their own builder conventions; see the guide's language bindings. +The signatures and complete example below use JavaScript. Attach a JavaScript Object Component script to the specified target and press **Play**. Globals are supplied by the engine. Schedule actions from `Start` or a callback, rather than at script top level. Native languages use typed options and their own builder conventions; see the guide's language bindings. ## Supported audio files @@ -91,8 +91,70 @@ The object methods and `Audio.load` are available in Lua 5.4 and Luau. Existing `Audio.play(source, options?)` and `Audio.playAt` in all languages still decode and play immediately; their voice controls continue to work. +## Choose audio devices + +The four device methods are available on `Audio` in every supported script +language (including HTML inline JavaScript). Native enumeration and output +selection currently work in the Windows player. Other platforms return an empty +list and report an unavailable-backend error when selecting a device. + +- `Audio.get_output_devices()` lists playback devices. +- `Audio.get_input_devices()` lists microphone/input devices. +- Each entry contains an opaque string `id` and a display `name`. Names can be + duplicated; use the ID to select a device. +- `Audio.set_output_device(id)` switches this scene's mixed audio to that output. +- `Audio.set_input_device(id)` validates and retains the scene's selected input + device. **Microphone recording/capture is not implemented**, so this call does + not produce microphone samples or route microphone sound to playback. +- Pass `null` (Lua/Luau `nil`, Python `None`, C `NULL`) to either setter to select + the current system default. Java requires an explicit `null` argument; other + bindings except C also allow omitting the argument. Setters return no value. +- Lists are snapshots. IDs belong to the current Play scene and the latest list + for that direction; listing that direction again invalidates older IDs. Do + not save IDs in project settings. Selection is shared by scripts in the scene + and resets on Stop/new Play. Output and input IDs are not interchangeable. +- Output switching retains mixer voices and their cursors but discards samples + queued on the previous device; a brief interruption is possible. A failed + switch keeps the previous output. Device removal is not automatically recovered; + list again and choose another device or the default. + +Create and attach a JavaScript Object Component script to an enabled scene +object as described above. Press **Play** on Windows: + +```javascript +globalThis.behavior = { + Start() { + const outputs = Audio.get_output_devices(); + if (outputs.length > 0) { + Audio.set_output_device(outputs[0].id); + } + const inputs = Audio.get_input_devices(); + if (inputs.length > 0) { + Audio.set_input_device(inputs[0].id); + } + } +}; +``` + +The scene uses the first listed output, and retains the first input when one is +available. Play an existing audio asset to hear the selected output. To restore +system output, call `Audio.set_output_device(null)` from a callback. + +Dynamic bindings return arrays/lists/tables of device records. C returns +`RusticAudioDevices` with `count` and `items[i].id` / `items[i].name`; these values +last until the next callback. C++ returns a `RusticValue` array (`.array()`); +C# returns a `JsonElement` array (`EnumerateArray()`); Java returns a JSON list +of maps; PHP returns an array of associative arrays. + +Unknown/stale IDs, IDs from the other direction, unavailable devices, missing +system defaults and native driver failures raise a script error. A non-string +argument also raises an error. Check the Console; list devices again after +plugging/unplugging hardware. Empty lists are valid on hosts without devices. + ## Calls +- `Audio.get_output_devices() / get_input_devices()` +- `Audio.set_output_device(id = null) / set_input_device(id = null)` - `Audio.load(source)` (Lua/Luau; returns a reusable audio handle) - `Audio.play(source, options?)` - `Audio.playAt(source, position, options?)` @@ -129,7 +191,7 @@ globalThis.behavior = { ## Behavior and limitations - Provide assets/music.ogg before Play. The voice fades in over two seconds, starts fading out at five seconds and stops at six. -- Windows player output uses the default audio device. Other platforms currently mix PCM headlessly, so successful playback may produce no device sound. +- Windows player output starts on the default audio device; `Audio.set_output_device` can change it. Other platforms currently mix PCM headlessly, so successful playback may produce no device sound. - FadeOut reaches zero volume but does not stop the voice; stop explicitly or allow natural completion. Crossfade fades the old voice to zero and the new voice from zero to one. - PlayAt attenuates distance relative to the active camera. The mixer renders 48 kHz stereo PCM with linear resampling for pitch. - Clock scaling changes source playback rate; Clock.pause and voice.pause retain their source cursors. Natural completion releases non-looping voice PCM; loaded audio handles retain PCM until unload or owner cleanup. Stopping cancels voice-targeting actions on the next scheduler tick. diff --git a/lib/api-docs.ts b/lib/api-docs.ts index 84bb1eb..8218ff8 100644 --- a/lib/api-docs.ts +++ b/lib/api-docs.ts @@ -9,7 +9,7 @@ const docs: Record = { gameplay: { title: "Shared gameplay actions (API 1.1)", summary: "Shared easing, tweens, movement, clip and procedural animation, timelines, timers, paths, cameras, physics, effects, audio and signals in all ten script types.", when: "Start an action during Start or an event callback. The scene advances it once per frame, even if the behavior has no Update function. Follow [Use gameplay actions](/docs/guides/gameplay-actions) for attachment, complete signatures and backend limits.", - calls: ["Tween.to / move / rotate / scale / value", "Movement.move / moveTo / rotateTo / lookAt / follow / orbit", "Animation.play / blend / transition / register / addMarker / value / ik", "Sequence / Timeline: move / to / wait / call / animation / parallel / play", "Timer.after / every", "Smooth / Interpolation: lerp / slerp / inverseLerp / remap / smoothDamp", "Path.create / follow", "Camera.moveTo / zoom / lookAt / follow / orbit / shake / transition", "Physics.raycast / sphereCast / overlap / force / impulse / explosion / knockback / launch", "Effects.fade / flash / shake / pulse", "Audio.load (Lua/Luau) / play / playAt / fadeIn / fadeOut / crossfade / volume / pitch", "rustic.game:startRecording / stopRecording / startHotMic / stopHotMic (Lua/Luau)", "Events.on / once / emit / connect / disconnect", "Clock.timeScale / pause / resume", "handle.state / pause / resume / cancel / reverse / onFinished"], + calls: ["Tween.to / move / rotate / scale / value", "Movement.move / moveTo / rotateTo / lookAt / follow / orbit", "Animation.play / blend / transition / register / addMarker / value / ik", "Sequence / Timeline: move / to / wait / call / animation / parallel / play", "Timer.after / every", "Smooth / Interpolation: lerp / slerp / inverseLerp / remap / smoothDamp", "Path.create / follow", "Camera.moveTo / zoom / lookAt / follow / orbit / shake / transition", "Physics.raycast / sphereCast / overlap / force / impulse / explosion / knockback / launch", "Effects.fade / flash / shake / pulse", "Audio.get_output_devices / get_input_devices / set_output_device / set_input_device / load (Lua/Luau) / play / playAt / fadeIn / fadeOut / crossfade / volume / pitch", "rustic.game:startRecording / stopRecording / startHotMic / stopHotMic (Lua/Luau)", "Events.on / once / emit / connect / disconnect", "Clock.timeScale / pause / resume", "handle.state / pause / resume / cancel / reverse / onFinished"], parameters: [p("entity", "stable entity ID / resolved path", true, "Transform target; use an anchored Part to avoid competing gravity."), p("duration", "finite non-negative seconds", true, "Time to completion. Movement and tween helpers also provide duration or speed options."), p("easing", "Ease identifier", false, "Linear by default; all 31 shared curves are available.")], returns: "An operation handle. Completion is queued during Update. Cancellation and destroyed targets do not invoke completion.", examples: { diff --git a/lib/docs-catalog.ts b/lib/docs-catalog.ts index 1eb28d5..8df16fc 100644 --- a/lib/docs-catalog.ts +++ b/lib/docs-catalog.ts @@ -63,6 +63,7 @@ const categoryGroups: DocGroup[] = [ { slug: "api/physics-actions/queries", title: "Physics queries", description: "Find primitive colliders with raycasts, sphere casts and overlaps.", source: "docs/Scripting/API/physics-actions/queries.md", parent: "api/physics-actions" }, { slug: "api/physics-actions/forces", title: "Physics forces", description: "Apply forces, impulses and velocity changes to simulated bodies.", source: "docs/Scripting/API/physics-actions/forces.md", parent: "api/physics-actions" }, { slug: "api/effects", title: "Effects", description: "Fade, flash, shake and pulse entity properties with shared easing.", source: "docs/Scripting/API/effects.md" }, + { slug: "api/audio", title: "Audio", description: "List and select Windows audio devices, load reusable audio in Lua/Luau, and play and fade WAV, MP3, AAC, FLAC, and OGG voices.", source: "docs/Scripting/API/audio.md" }, { slug: "api/audio", title: "Audio", description: "Record audio and read microphone PCM in Lua/Luau; play WAV, MP3, AAC, FLAC, and OGG voices and control fades.", source: "docs/Scripting/API/audio.md" }, { slug: "api/events", title: "Events and signals", description: "Communicate through queued global events and object-scoped signals across scripting languages.", source: "docs/Scripting/API/events.md" }, { slug: "api/clock", title: "Clock", description: "Scale or pause the shared scene clock for actions, animation, physics and audio.", source: "docs/Scripting/API/clock.md" },