Persistent mod sound sources: start, update, stop with generations, click-free voices, loop sections, voice budget and virtual loops (API 20)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-30 16:10:23 +03:00
committed by airdef
parent 4cb83fcc9b
commit b809f5eed0
14 changed files with 1636 additions and 10 deletions
+37
View File
@@ -553,6 +553,41 @@ Particles to spawn on this client (AirDef fork).
| `color` | `u32` | 0xRRGGBB for dust and coloured types (0: white). |
| `scale` | `f32` | Dust size (0.01 to 4). |
### enum `source-op-kind`
What a `sound-sources` entry does.
| Case | |
| --- | --- |
| `start` | Starts source `id` (one that is already running restarts: the old one releases, the new one attacks). |
| `update` | Sets everything of a running source: pose, velocity, gain, pitch, looping and the rest. An id that is not running is ignored. |
| `stop` | Releases source `id` (fading over its `release`). Only `id` is read. |
### record `source-op`
One change of a persistent sound source (AirDef fork, API level 20): a sound that goes on, follows a pose and has a lifetime, over the game's own mixer. Unlike `play-sound` events they are not repeated; a source is started, updated as often as the mod likes (a tick) and stopped. The ids are the mod's own numbers (per mod, up to 256 running).
| Field | Type | |
| --- | --- | --- |
| `kind` | `source-op-kind` | |
| `id` | `u32` | |
| `event` | `string` | The sound event (`<mod>:<name>`), read by `start`: the same variant is chosen for the whole life of the source. |
| `x` | `f64` | Where it is, in the world as the listener hears it (the listener stays at the player; a mod that shows another place moves the source by the offset itself). |
| `y` | `f64` | |
| `z` | `f64` | |
| `vx` | `f32` | Blocks a second. The mixer carries the source on along it between calls (at most 0.15 s), so a source updated once a tick moves without steps. Also what Doppler reads. |
| `vy` | `f32` | |
| `vz` | `f32` | |
| `gain` | `f32` | 0 to 16, times the event's volume and the category sliders; above 1 it only widens the distance it is heard from, as in vanilla. |
| `pitch` | `f32` | 0.5 to 2, the sound's own pitch (Doppler is added by `doppler`). |
| `looping` | `bool` | A looping source goes on until stopped; a source that is not looping plays once and is gone. |
| `priority` | `f32` | More important sources keep their voice when there are not enough (0.1 to 10, 1 usually). Sources are ranked by priority times what the listener would hear, 24 get a voice; the others stay virtual (silent but alive, a loop only) and are heard when they rank again. |
| `attack` | `f32` | Seconds to fade in (0 to 5; 0 is 5 ms, so there is no click). |
| `release` | `f32` | Seconds to fade out after `stop` (0 to 5; 0 is 5 ms). |
| `doppler` | `f32` | How much of the Doppler shift of the velocity is applied, 0 (none, the usual choice) to 1, bounded to a change of pitch of 12%. The velocity is taken against a listener at rest. Leave 0 when the pitch already follows the speed. |
| `loop-from` | `f32` | A looping source repeats the part of its sound from `loop-from` to `loop-to` seconds into it (both 0: all of it), the join crossfaded over 50 ms: for sounds that fade in and die away at their ends. |
| `loop-to` | `f32` | |
### enum `policy`
What a block is to a query (AirDef fork): the three policies differ on purpose, so a sensor and a missile may disagree about a pane of glass.
@@ -767,6 +802,8 @@ Where a capture is.
| `set-models-by-id` | `func(generation: u32, models: list<model-instance-id>) -> bool` | `set-models` with handles instead of names: the same models, limits and interpolation, fewer bytes across the boundary. `generation` is the `model-generation` the handles were asked under; if it is not the current one the call is ignored and returns false (re-ask the handles and call again). Handles the game doesn't know draw nothing. |
| `spawn-particles` | `func(particles: list<particle-spawn>)` | Spawns particles on this client only: no command, no server. At most 512 spawns a call. |
| `play-sound` | `func(event: string, x: f64, y: f64, z: f64, volume: f32, pitch: f32)` | Plays a sound event (`minecraft:entity.generic.explode`, `<mod>:<name>`) at a point on this client. |
| `sound-source-generation` | `func() -> u32` | Moves on whenever the game released every source of every mod (the world closed, the session ended, a film began or ended, the sounds reloaded). A mod reads it before `sound-sources` and starts its sources again when it changed. |
| `sound-sources` | `func(generation: u32, ops: list<source-op>) -> bool` | Starts, updates and stops persistent sound sources. `generation` is the `sound-source-generation` the mod's sources belong to; if it is not the current one the call is ignored and returns false (read the generation, forget the sources, start them again). Stops are never dropped by a limit: only new sources beyond 256 running are, and at most 512 entries a call count. Every source of a mod that stops or is reloaded is released by the game. |
| `query-ground` | `func(columns: list<tuple<s32, s32>>)` | Asks for the ground height of these columns (x, z): at most 512 a tick, answered by `ground` from the next tick on. |
| `ground` | `func() -> list<tuple<s32, s32, s32>>` | The answers to the last tick's `query-ground`: (x, z, y), y one above the highest block that blocks motion or holds a fluid, as the motion blocking heightmap; -64 where the chunk isn't loaded. |
| `query-rays` | `func(rays: list<ray>)` | Traces segments through the loaded blocks (AirDef fork): each is walked block by block on the host, against the real collision shapes (`policy`), and answered by `rays` from the next tick on. At most 256 segments a tick, each at most 512 blocks long (longer ones are answered `unknown` past that); over the budget they are answered `unknown` too, never `clear`. A game with no chunk at a place answers `unknown` for it. |