@spawnite/engine 0.1.0-beta.15

package/dist/vite.d.ts

@@ -0,0 +1,123 @@
+import { Plugin as Plugin_2 } from 'vite';
+import { PluginOption } from 'vite';
+import { Rolldown } from 'vite';
+
+/** Builds the game at `root` for production, as a deploy does, into a
+ *  folder it removes, and fails where the build breaks the platform's
+ *  rules: code over {@link standaloneBuildCeilingBytes}, or zod's
+ *  classic API in any chunk. Returns every file the build wrote, for the
+ *  game's own checks. */
+export declare function checkGameBuild(root: string, { env, plugins }?: GameBuildCheckOptions): Promise<Rolldown.OutputBundle>;
+
+/** What a game's recorded video clips, from the dev tools' Record button,
+ *  are held to. A game's config changes either with
+ *  `spawnite({ clips: { … } })`. */
+export declare interface ClipSettings {
+    /** Seconds after which a recording stops by itself. */
+    maxSeconds: number;
+    /** Clips the game keeps: past it, Record is refused with the reason,
+     *  and nothing is deleted on its own. */
+    keep: number;
+}
+
+/** What a game's config sets through the engine's plugin. */
+export declare interface EnginePluginOptions {
+    /** What the game's dev replay keeps, each over its default: the
+     *  budget, the marks' share of it, the saved clips' warning, and the
+     *  rolling screenshots' interval and width. */
+    replay?: Partial<ReplaySettings>;
+    /** What the dev tools' recorded video clips are held to, each over its
+     *  default: the seconds a recording stops at, and the clips kept. */
+    clips?: Partial<ClipSettings>;
+    /** Whether the plugin writes the loading screen into the page, which
+     *  Game takes down. `false` for a page that is not a game, such as a
+     *  tool that mounts a model viewer, as Game's own `loadingScreen`
+     *  prop leaves out its cover.
+     *  @defaultValue true */
+    loadingScreen?: boolean;
+}
+
+export declare interface GameBuildCheckOptions {
+    /** Environment variables the build sees, as a deploy sets them, such
+     *  as `ROOMS_DOMAIN`. Each is put back afterwards. */
+    env?: Record<string, string>;
+    /** Plugins laid over the game's own config, such as one that reads a
+     *  written file in `writeBundle` before the folder is removed. */
+    plugins?: PluginOption[];
+}
+
+/** The files a page downloads before it draws its first frame: the page,
+ *  its entry chunk, what that imports statically and their stylesheets. */
+export declare function readFirstLoadFiles(bundle: Rolldown.OutputBundle): Set<string>;
+
+/** What a game's replay keeps. Each has a default; a game's config
+ *  changes any of them with `spawnite({ replay: { … } })`. */
+export declare interface ReplaySettings {
+    /** Megabytes a game's sessions may take together, pages, rooms and
+     *  shots: past it, the oldest minute no mark protects goes first. */
+    budgetMegabytes: number;
+    /** Share of the budget the minutes marks protect may fill: past it, a
+     *  new mark still tags and shoots but protects nothing. */
+    markShare: number;
+    /** Megabytes of saved clips past which the tools warn. */
+    savedWarningMegabytes: number;
+    /** Seconds between the rolling screenshots; 0 takes none. */
+    shotIntervalSeconds: number;
+    /** The rolling screenshot's width in pixels, at the canvas's shape. */
+    shotWidth: number;
+}
+
+/** The page's content policy, in a build that names the rooms domain, as
+ *  the deploy does: fetches and sockets reach the page's own origin, the
+ *  blob URLs a model's textures load through, the shared assets site a
+ *  shared file loads from, and a room on any machine under the rooms
+ *  domain. A build with no rooms domain, as on a
+ *  laptop, sets none, so the page dials a room on localhost. */
+export declare function roomsContentPolicy(roomsDomain: string | undefined): Plugin_2;
+
+/** The engine's plugin, which every game's Vite config loads once. It
+ *  inlines `#include "lygia/…"` in each shader fragment when the game
+ *  builds, so the bundle holds only the files its fragments name and a
+ *  shader needs nothing from the network. An unknown path fails the build.
+ *  It also defines `__GAME_ENGINE_DEV__`, the game's own mode, which the
+ *  engine's `Game` reads to mark a dev world: every game loads this
+ *  plugin, and the engine's library build fixes `import.meta.env.DEV` to
+ *  false for every game that installs the built package. And it points
+ *  three's default Draco decoder at the glTF one the engine loads, so the
+ *  game's build copies one decoder, and writes each sound as a file. And
+ *  where the game's `public/assets` holds a file a `?url` import names,
+ *  byte for byte, the build ships the game's copy alone and points the
+ *  import at it. It warns when a built stylesheet still holds an `@theme`. On the
+ *  dev server, it keeps each page's replay in the game's `.replays` folder,
+ *  trimmed to `replay`'s budget, and serves a playback its window; its
+ *  `api.replay` holds the settings, for the cli to read. And it bundles
+ *  Rapier as the dev server starts, so a cold cache reloads no page, and
+ *  throttles the errors the page forwards to the terminal. It serves ui's
+ *  entry without its stylesheet, which the game imports itself, so a hot
+ *  update loads no second engine. And
+ *  it writes the loading screen into the page, so a player sees it from the
+ *  first paint rather than an empty field while the scripts load; Game
+ *  takes it over. A page that is not a game leaves it out with
+ *  `loadingScreen: false`. And it writes the game's build into a built
+ *  page's HTML, the build `api.readBuild` reads, where the page's room
+ *  connection finds it: in the HTML, since a published page runs a release
+ *  of the engine built once for every game. A dev server's page names none,
+ *  since the server changes its modules under it after it loads: it names
+ *  the engine's own build instead, and the server answers at
+ *  `engineBuildPath` with the one it serves now, so a tool can tell a page
+ *  that runs older engine code. */
+export declare function spawnite(options?: EnginePluginOptions): Plugin_2;
+
+/** A game's own wiki pages and the engine's on its dev server, and never in
+ *  its build. It answers `wikiPagesRoute` and a page's path from the game's
+ *  folder, such as `/__spawnite/wiki/index.md`, with that file's markdown,
+ *  read on each request, or 204 where the game has no such page. It
+ *  answers `wikiPagesRoute` and a wiki route under `/engine/`, such as
+ *  `/__spawnite/engine/behaviours/stats/`, with the engine's page there, as
+ *  `findEngineWikiPage` finds it, so the page matches the engine the game
+ *  runs. And when a file under the game's `wiki/` folder is added, changed
+ *  or removed, the page fires `wikiPageSaved` on its window with the file's
+ *  path, so the devtools read the open page again. */
+export declare function wikiPages(): Plugin_2;
+
+export { }

package/dist/vite.js

@@ -0,0 +1 @@
+import{a as e,i as t,o as n,s as r,t as i}from"./CZV99t6a.js";export{i as checkGameBuild,t as readFirstLoadFiles,e as roomsContentPolicy,n as spawnite,r as wikiPages};

package/dist/weapons.d.ts

@@ -0,0 +1 @@
+export { AimedShot, Authority, CharacterCapsule, CharacterCapsuleTrait, ClientMessageType, CollisionLayerHandle, CollisionMask, CoreLayers, CoverTest, Disposer, FiredShot, FiredShotRecord, FiredShotsTrait, HeldWeaponsTrait, HitData, HitZone, HitZonesTrait, LatencyTrait, MeasuredLatency, ModelName, OriginRuleOptions, PelletFan, Phase, PhaseName, PointerButton, ProjectileLaunch, ProjectileSettings, RateRuleOptions, Register, RewindBounds, RewindHistory, RewindSend, RewindTrait, SendsAround, ShotAim, ShotCheck, ShotClaimAim, ShotCredit, ShotHit, ShotJudge, ShotJudgedEvent, ShotMessage, ShotRefusal, ShotResult, ShotRule, ShotRules, ShotSend, ShotSettings, ShotTest, Snapshot, StateDump, SystemHandle, TargetSearch, Weapon, WeaponKind, WeaponNumber, WeaponProps, WeaponSettings, WeaponStats, WeaponsTrait, aimShot, castCoverRay, claimShotHits, clearSentShots, defaultProjectileSpeed, fanPellet, findDrawnTarget, findRayHit, findRewindSends, heldRule, holdsWeapon, keptLags, launchProjectile, measureLatency, measureMiss, measureShotDistance, originRule, rateRule, readAimAt, readPastPlace, readPastTraits, readSentPlace, readSentZones, readWeaponNumber, recordRefusedShot, recordSentShot, registerShotSettings, registerWeapon, rewindCeilingSeconds, rewindRule, rewindStep, scaleZoneDamage, setRewindStep, weapons } from "./public.js";

package/dist/weapons.js

@@ -0,0 +1 @@
+import{Et as e,ar as t,as as n,cr as r,dr as i,ds as a,fr as o,gr as s,hr as c,ir as l,lr as u,ls as d,mr as f,nr as p,pr as m,rr as h,rs as g,sf as _,sr as v,ur as y,us as b}from"./-MLBVTaO.js";import{t as x,yn as S}from"./V70ADx0g.js";import{a as C,i as w,n as T,o as E,r as D,t as O}from"./UJDr3Nrd.js";import{C as k,S as A,_ as j,a as M,b as N,d as P,f as F,g as I,i as L,m as R,p as z,r as B,s as V,t as H,u as U,w as W,x as G,y as K}from"./DOeUeeKs.js";import{n as q,t as J}from"./DkKmurqu.js";export{_ as CharacterCapsuleTrait,S as CoreLayers,h as FiredShotsTrait,l as HeldWeaponsTrait,b as HitZonesTrait,t as LatencyTrait,x as Phase,J as PointerButton,v as RewindTrait,H as ShotJudge,r as ShotJudgedEvent,q as Weapon,u as WeaponKind,y as WeaponNumber,i as WeaponsTrait,A as aimShot,g as castCoverRay,k as claimShotHits,O as clearSentShots,o as defaultProjectileSpeed,W as fanPellet,n as findDrawnTarget,T as findRayHit,P as findRewindSends,B as heldRule,m as holdsWeapon,f as keptLags,p as launchProjectile,F as measureLatency,D as measureMiss,d as measureShotDistance,L as originRule,M as rateRule,w as readAimAt,z as readPastPlace,R as readPastTraits,I as readSentPlace,j as readSentZones,c as readWeaponNumber,C as recordRefusedShot,E as recordSentShot,V as registerShotSettings,s as registerWeapon,K as rewindCeilingSeconds,U as rewindRule,N as rewindStep,a as scaleZoneDamage,G as setRewindStep,e as weapons};

package/dist/wiki/engine/ai/metadata.md

@@ -0,0 +1,143 @@
+---
+title: AI metadata
+description: How a behaviour and an Entity describe themselves in words, and how the AI tree gathers them for an agent.
+useCases:
+    - describe an entity for an AI agent
+    - actions an agent can take
+    - game state tree for an agent
+    - what can this character do
+    - accessibility tree for a game
+    - describe an npc's state in words
+    - list actions an entity supports
+sidebar:
+    order: 10
+---
+
+Every entity in a game can carry AI metadata: what it is, its state, and what can be done with it, in words. A behaviour writes its share from its own props, an `ai` prop on `Entity` adds to it or overrides it, and one util gathers every entity into the **AI tree** for one subject, the player or an NPC. The tree is a game's counterpart to a browser's accessibility tree: each node has a role, a name, a state and the actions it supports, and an agent picks one node and one action. An agent reads the tree as a game's state and its actions as what can be done.
+
+Declaring metadata is optional everywhere. An entity that declares nothing still gets a node from its row name, its behaviours and its place in the world.
+
+## What a node holds
+
+A node is an [`AiNode`](https://wiki.spawnite.com/reference/ai/ainode/):
+
+- `id`: the entity's key in `dump()`, the same one its devtools row carries, so the tree, the dump and `describe()` agree.
+- `name`: the entity's row name in the devtools tree, such as `Rock`, only where it differs from `is`. Where nothing else describes the entity, `is` is its row name, so the node never says one word twice.
+- `is`: what it is, in a noun phrase: `a coin`, `a slab across the lane`.
+- `facts`: its state now, each a short clause: `in the air`, `badly hurt`, and first, where it stands against the subject: `just ahead`, `in your path`.
+- `actions`: what the subject can do with it, each a verb phrase: `collect it`, `jump it`.
+
+The subject's own node comes first, then the rest nearest first.
+
+## Describing a behaviour
+
+A behaviour declares an `ai` beside its `description`: a function of its props that returns an [`AiMetadata`](https://wiki.spawnite.com/reference/ai/aimetadata/), the same shape the `Entity` prop takes. A flag is one expression. A kind is a table.
+
+```ts
+export const HealthBehaviour = defineBehaviour({
+    name: "health",
+    trait: HealthTrait,
+    description:
+        "Tracks damage, reaps an entity at zero, and downs a player's character or an entity with a respawn until it comes back.",
+    ai: ({ current, maximum }) => ({
+        facts: [current >= maximum / 2 ? "hurt" : "badly hurt"],
+    }),
+});
+
+const courseWords: Record<CourseKind, AiMetadata> = {
+    [CourseKind.Slab]: {
+        is: "a slab across the lane",
+        actions: ["jump it", "go round it"],
+    },
+    [CourseKind.Coin]: { is: "a coin", actions: ["collect it"] },
+};
+
+export const CourseBehaviour = defineBehaviour({
+    name: "course",
+    trait: CourseTrait,
+    ai: ({ kind }) => courseWords[kind],
+});
+```
+
+The function also receives an [`AiDescribeContext`](https://wiki.spawnite.com/reference/ai/aidescribecontext/): the entity, for a fact a sibling trait holds, and the subject the tree is built for, so a behaviour can write a fact relative to it.
+
+The tree reads every declared behaviour. The engine declares its own; a game's own is made with `defineBehaviour`, which declares it and also names its trait in `dump()`.
+
+## Describing an Entity
+
+The `ai` prop on `Entity` takes the same shape, as words rather than a function. Its `is` overrides what the behaviours say; its facts and actions add to theirs.
+
+```tsx
+import { Entity, Interact } from "@spawnite/engine";
+
+export function Chest({ onOpen }: { onOpen: () => void }) {
+    return (
+        <Entity
+            model="chest"
+            position={[4, 0, -6]}
+            ai={{ is: "a treasure chest", actions: ["open it"] }}
+        >
+            <Interact prompt="Open the chest" radius={2} onInteract={onOpen} />
+        </Entity>
+    );
+}
+```
+
+The words live on the entity's `AiTrait`, so a headless world and a room read them as they read any trait.
+
+## What the tree infers
+
+The tree fills in what nobody declared:
+
+- **The name and the id** come from the devtools row and the dump key.
+- **The subject** is the player: her character, else the track mover under the client's authority, else the first track mover.
+- **Where a thing stands against the subject** is measured, never declared. On a track, the subject's mover is measured against each track trigger on the same track, height included, so a trigger over or under the mover is `above you` or `below you` rather than in its path. Anywhere else, the subject's transform and facing are measured against each thing's transform, with its extent from its collider, turned as its body is, or from the radius its behaviour reaches. The speed is the subject's speed toward the thing, or its walking speed while it stands or moves away, so the band says how soon it could reach the thing.
+- **Which entities are in the tree**: any with a row name or any metadata. A camera rig or a ground has neither and stays out.
+
+## The words
+
+The rules every description follows:
+
+- **Relative to a subject.** A fact such as `in your path` is written for one entity, which the util takes as an argument.
+- **Distance as time.** Nearness is a band of the seconds to reach a thing at the subject's speed, measured to its near edge:
+
+    | Seconds   | Words                   |
+    | --------- | ----------------------- |
+    | under 0.5 | `reaching you now`      |
+    | under 1   | `right in front of you` |
+    | under 2   | `just ahead`            |
+    | under 4   | `further ahead`         |
+    | 4 or more | `far ahead`             |
+    | passed    | `behind you`            |
+
+- **Width, not centre.** A thing is `in your path` while the subject's line crosses its extent across. Otherwise it is `to your left` or `to your right`, and `close` within a metre of its edge or `well clear` beyond.
+- **Counting stays in code.** A count or a threshold becomes words before an agent sees it: a health of 30 in 100 reads `badly hurt`, never `30`.
+
+## Reading the tree
+
+Every reader gets the same words from the same call:
+
+```ts
+//  Headless, with no React: a test, a room, an ask.
+import { buildAiTree } from "@spawnite/engine/core";
+const tree = buildAiTree({ world });
+const guardsView = buildAiTree({ world, subject: guard });
+
+//  The devtools store, in the page, in simulate and in a test that mounts a scene.
+useDevtools.getState().readAiTree();
+useDevtools.getState().describe("7").ai;
+```
+
+In the browser, `window.__GAME_DEVTOOLS__.getState().readAiTree()` prints it from the console while the overlay is mounted. The tree is built when read, since its words change every step.
+
+From the command line, `spawnite simulate --ai` prints the tree after the steps and `spawnite play ai` prints the running playtest's; `--subject <id|name>` sees it from another entity. Both print it as JSON, one node a line:
+
+```sh
+spawnite simulate --scene run --seconds 1 --ai
+```
+
+Over the MCP, `simulate` takes `ai` and `subject` for the same tree, and `read_ai_tree` reads the running playtest's with an optional `subject`, taking no shot.
+
+## How other engines do it
+
+Godot's `set_meta` and Roblox's attributes and tags attach free-form data to a node or an instance. Unity, Unreal and PlayCanvas have no general equivalent. None of them describes a thing for a model, or lists what a player can do with it. The web's ARIA roles and its accessibility tree do both, and they are what browser agents read, so this follows the web.

package/dist/wiki/engine/audio/sound.md

@@ -0,0 +1,72 @@
+---
+title: Sound
+description: Plays a sound file, once or looping, from an entity or heard everywhere.
+useCases:
+    - play a sound effect
+    - 3d sound from an entity
+    - footstep sounds
+    - background ambience
+    - pickup sound
+    - looping sound
+    - sting at the end of a round
+    - sound that fades with distance
+sidebar:
+    order: 8
+---
+
+`<Sound url>` plays a sound file inside a [World](/engine/structure/world/) from when it mounts until the file ends or the component unmounts. Where you mount it decides where the player hears it from:
+
+- Inside an [Entity](/engine/entities/entity/), the sound comes from the entity and grows quieter with distance from the camera.
+- Anywhere else, the player hears it the same everywhere: an ambience, or a sting at the end of a round.
+
+Its props are in [`SoundProps`](https://wiki.spawnite.com/reference/sound/soundprops/).
+
+Roblox's `Sound` works the same way: parented to a part it plays from there, and parented anywhere else it plays everywhere. Unity's `AudioSource` and Godot's `AudioStreamPlayer3D` are the placed kind; Godot's `AudioStreamPlayer` is the everywhere kind.
+
+## When sound starts
+
+A browser, a phone's included, keeps a page silent until the player presses a key, clicks or touches the screen. A Sound mounted before that input starts playing on it. A one-off sound that a pickup or a footstep plays before that input does not play.
+
+An iPhone with its ring switch set to silent plays no page sound, a game's included, until the player sets it back to ring.
+
+A browser with no Web Audio, or one that cannot start it, runs the game silent rather than stopping it. Sound mounts nothing, and footsteps and pickups play nothing. The console says so once: `Web Audio is unavailable in this browser, so the game runs silent`, followed by the browser's own error. The game needs no change. Other players' voices still play, through an audio element, up to 100% volume, as [voice](/engine/audio/voice/) says.
+
+## Footsteps and pickups
+
+Two sounds need no Sound of their own:
+
+- `<CharacterSpawn footsteps>` takes a list of files and plays one of them at random for each stride she walks. A stride is 1.67 metres, a third of her top speed of 5 m/s, which matches the three steps a second of her run.
+- `<Pickup sound>` plays its file once, heard everywhere, as she takes the pickup. It does not play when the scene ends around a pickup nobody took.
+
+## The library's sounds
+
+[`sounds`](https://wiki.spawnite.com/reference/sound/sounds/) names the files in the shared asset library, which ship with the engine, and says what each one is for. [Assets](https://wiki.spawnite.com/platform/assets/#bring-in-an-asset-from-outside) says where to find more, and how to check a downloaded sound for hiss.
+
+## Sample
+
+```tsx
+import {
+    CharacterSpawn,
+    Entity,
+    Pickup,
+    Sound,
+    sounds,
+    World,
+} from "@spawnite/engine";
+
+export function Run() {
+    return (
+        <World map="meadow">
+            <CharacterSpawn />
+            <Sound url="/sounds/rain.mp3" loop volume={0.5} />
+            <Entity position={[0, 0, -3]}>
+                <Pickup reward={1} sound={sounds.pickup} />
+            </Entity>
+        </World>
+    );
+}
+```
+
+## Where it runs
+
+Client. Sound changes nothing in the world; each player hears their own. Removing a game's frame frees its audio with everything else it held, as [the trust boundary](https://wiki.spawnite.com/platform/trust-boundary/) says.

package/dist/wiki/engine/audio/voice.md

@@ -0,0 +1,153 @@
+---
+title: Voice
+description: How players talk in a room game, the settings each player has, and how a game shows who is speaking.
+useCases:
+    - voice chat in multiplayer
+    - push to talk
+    - open mic voice chat
+    - microphone permission
+    - noise suppression
+    - show who is speaking
+    - adjust another player's volume
+    - mute a player
+sidebar:
+    order: 9
+---
+
+A game that joins a room has voice chat with no code of its own. The room forwards each player's microphone to every other player, and the engine plays what each page hears. This page covers what the player controls, how a game shows who is speaking, and what the engine does to keep voice clear.
+
+## When the microphone is asked for
+
+The engine asks the browser for the microphone the first time the player uses the page, such as their click on Play, and never while the page loads. A game with no room never asks. The browser asks once per site and remembers the answer, so a player who allowed it is not asked again.
+
+A player who refuses still hears everyone else. Once they hear another player, a one-line notice in the bottom-left corner says for ten seconds that the others cannot hear them, and that Escape says how to fix it; a player alone in a room sees none, since nobody is missing their voice. The Escape menu and the Microphone row in Settings say how to allow the microphone from the address bar's site controls. When the player allows the microphone there, voice takes it at once, with no reload.
+
+## What the player sets
+
+The Audio tab of the [Settings panel](/engine/ui/settings/) holds the voice rows. The rows past Microphone show once the room opens voice.
+
+| Row                | Range                         | Default  | What it changes                                                                   |
+| ------------------ | ----------------------------- | -------- | --------------------------------------------------------------------------------- |
+| Microphone         | On or off                     | On       | Whether the room gets the microphone at all. Off, the page captures nothing.      |
+| Voice mode         | Open mic, Push to talk        | Open mic | When the microphone sends.                                                        |
+| Push-to-talk key   | Any key                       | V        | With push to talk, the key the player holds to send. Not shown on a touch screen. |
+| Microphone volume  | 0 to 100                      | 100      | The microphone's level before it is sent. A live meter under it shows the level.  |
+| Noise suppression  | On or off                     | On       | The browser's removal of steady noise, such as a fan.                             |
+| Automatic gain     | On or off                     | On       | The browser's leveling of the voice. It can change the system microphone level.   |
+| One row per player | 0% to 200%, and a mute button | 100%     | How loud that player is to this player alone. Past 100% plays them louder.        |
+
+The meter under Microphone volume shows the microphone's level in every mode, and turns green while the room gets the player's voice, so the player sees they are heard. Discord shows an input meter in its voice settings, and Roblox animates the microphone icon while the player speaks.
+
+## The two voice modes
+
+Open mic is the default on every device. It sends the player while they speak and holds a quiet room back: a gate opens the moment the microphone's level passes -60 dBFS, 20 ms early so the first sound goes through, and holds for 0.3 s after the last loud moment so pauses and quiet word endings go through. The threshold is fixed, and no row shows it. After the browser's noise suppression, a pause between words measures about -79 dBFS and speech about -26 dBFS, so the gate sits well clear of both.
+
+Push to talk sends while the player holds their key, and for 0.1 s after. A key that a text field or a button takes does not count, and the page does not hear a key while the browser tab is out of focus. On a touch screen, push to talk is a hold on the microphone button instead of a key. The device's main input decides which, never the window's size: a narrow desktop window keeps the key. A gamepad has no push-to-talk button.
+
+A player's saved choice holds across visits. A page that saved the older ungated open mic starts on the gate at its lowest threshold, -80 dBFS, which sends as much as it did; Reset audio moves it to the shipped threshold. A page that saved voice activity starts on open mic at the shipped threshold, since no row shows the one it had.
+
+### How the threshold was measured
+
+Two players in one room, each page running the engine's own gate on a steady tone from its microphone, the other page measuring what it plays after the room and the Opus codec. At -60 dBFS, a tone at -61 dBFS or quieter arrives as silence, 1 in 32,768, and a tone at -59 dBFS or louder arrives at its own level. A tone at -26 dBFS, speech after the browser's gain control, arrives whole. The hosted room's voice tests keep that check: speech passes, a quiet room at -70 dBFS does not, and the same quiet room passes at the lowest threshold.
+
+The same -60 passed every sentence of a recorded speech test and the first 100 ms of 89 to 100% of them, where -50 cut into the quiet first sound of one sentence in five.
+
+### What the others do
+
+| Product                | Modes listed                                                     | Default                                                    | Where the player mutes                                             | Notes                                                                                                                                                                                             | Source                                                                                                                                                                                         |
+| ---------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Roblox                 | None: the microphone on or off                                   | Open mic with a mute, on every device                      | A microphone icon in the fixed top-left controls, always on screen | A creator cannot hide or move it; `SetCoreGuiEnabled` covers other pieces. Green moves in the icon while the player speaks, a red slash while muted, and a speaker icon shows over others' heads. | [Roblox help 4405807645972](https://en.help.roblox.com/hc/en-us/articles/4405807645972); the developer forum's "Updated Experience Controls now live"                                          |
+| Fortnite               | Open Mic, Push to Talk                                           | Not published                                              | The voice controls in the profile panel                            | Settings are saved to the Epic account. The proximity speaker HUD element is mandatory, and the HUD Controller device cannot hide voice.                                                          | Epic help a000084783; Epic's HUD Controller device page                                                                                                                                        |
+| Valorant               | Party: push to talk or voice activation. Team: push to talk only | Push to talk, U and V                                      | Not listed                                                         |                                                                                                                                                                                                   | Riot support, Valorant voice chat troubleshooting                                                                                                                                              |
+| Overwatch 2            | Push to Talk, Open Mic                                           | Push to talk                                               | The Social menu                                                    |                                                                                                                                                                                                   | Blizzard help 31694, behind a login: unconfirmed                                                                                                                                               |
+| Apex Legends           | Push to Talk (PC only), Open Mic                                 | Push to talk on PC                                         | Not listed                                                         | Its "Open Mic" is a threshold gate, with an Open Mic Record Threshold slider.                                                                                                                     | [EA help, Apex voice chat](https://help.ea.com/en/help/apex-legends/apex-legends/voice-chat); EA's Apex accessibility page                                                                     |
+| Call of Duty           | Push to Talk, Open Mic                                           | Not listed; the PC key is V                                | Not listed                                                         | Open Mic Sensitivity runs 0 to 100.                                                                                                                                                               | Activision support, Black Ops Cold War accessibility                                                                                                                                           |
+| Rocket League          | Open mic, with a Push to Talk checkbox                           | Open mic                                                   | Not listed                                                         |                                                                                                                                                                                                   | Epic help a202300000015902                                                                                                                                                                     |
+| Rec Room               | Push-to-Talk, Always On                                          | Not listed                                                 | Not listed                                                         |                                                                                                                                                                                                   | Rec Room's help center: unconfirmed                                                                                                                                                            |
+| VRChat                 | Push to Talk, Toggle, Always On                                  | Push to talk on iOS                                        | The V key or the Quick Menu                                        | A microphone threshold, 5% by default, and a HUD microphone icon the player can drag.                                                                                                             | VRChat's iOS platform FAQ; its 2025.2.1 and 2026.2.2 release notes                                                                                                                             |
+| Call of Duty: Mobile   | Toggle button, push to talk, always on                           | Muted                                                      | An always-visible HUD microphone button                            |                                                                                                                                                                                                   | Activision's blog, October 2019 controls post                                                                                                                                                  |
+| Discord                | Voice Activity, Push to Talk                                     | Not listed                                                 | Not listed                                                         | Voice activity takes a slider or an automatic sensitivity, which Discord itself says cuts sentence ends. Its Social SDK defaults to -60 dB.                                                       | [Discord support 211376518](https://support.discord.com/hc/en-us/articles/211376518); [Social SDK](https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1VADThresholdSettings.html) |
+| Xbox and PlayStation 5 | None: an open mic with a mute                                    | Open mic                                                   | The PS5 controller's mute button; the Xbox headset's button        | Xbox offers a noise suppression switch.                                                                                                                                                           | Xbox Wire, 2022-09-07; PlayStation's DualSense support                                                                                                                                         |
+| Browsers               | Not a product with modes                                         | Echo cancellation, noise suppression and automatic gain on | Not applicable                                                     | Opus sends no discontinuous transmission unless asked.                                                                                                                                            | [W3C mediacapture-main, on Opus DTX](https://github.com/w3c/mediacapture-main/issues/777); [RFC 7587](https://www.rfc-editor.org/rfc/rfc7587)                                                  |
+
+Eight products list exactly two modes, three list a mute only, and two list three; none lists an ungated open mic and a gated voice activity as separate choices. Of the gates that publish a default, Discord's SDK sits at -60 dB and VRChat at 5%, about -29 dBFS if that share is linear, which VRChat does not document. The engine ships -60 dBFS, fixed rather than adaptive, since Discord's automatic sensitivity cuts sentence ends.
+
+## The microphone button
+
+A game with voice shows the engine's microphone button in the top-left corner, 44 px square, on every device, beside the Menu button on a touch screen and before the [performance overlay](/engine/ui/graphics-quality/#the-performance-overlay) when it shows. A tap mutes and unmutes the microphone, as the Microphone row does. The button shows the player's own voice: their level fills the microphone in green while the room gets it, and a red slash crosses it while muted. Under push to talk on a touch screen, the button sends while the player holds it, and sends nothing otherwise; while muted, a tap unmutes it first. With the Escape menu open, the button stays in its corner above the menu, so a player in a game that captures the cursor mutes there. Roblox keeps its microphone in the same corner, and VRChat's iPhone app holds to talk on its button.
+
+The button shows once the room opens voice, or once it says it runs none, as the development room does. It is the one place every player mutes in every game, so a creator cannot hide or move it:
+
+- **Restyle it** through the theme's colours: the button takes the menu's `--color-menu-surface` and `--color-menu-edge`, and its own `--color-voice-speaking` for the level and `--color-voice-muted` for the slash. A game sets them on `:root` in its stylesheet, as the [menus](/engine/ui/settings/) take theirs.
+- **Remove it** by turning voice off for the game, with `voice: false` on the room: `room={{ url, playerName, voice: false }}`. The page then asks for no microphone, shows no voice rows and draws no button.
+- **Start players on push to talk** with `defaultVoiceMode={VoiceMode.PushToTalk}` on `Game`, beside `defaultVolumes`. A mode the player saved on this device keeps its value, and Reset audio returns to the game's.
+
+`<HideSetting setting="microphone" />` hides the voice rows in Settings and leaves the button.
+
+## Showing who is speaking
+
+`useSpeaking(entity)` returns whether the player whose character is `entity` is speaking. The page's own player counts while their microphone sends speech; another player counts while this page plays their speech. It turns on with the first word and stays on for 0.3 s after the last, so a mark drawn from it does not flicker between words.
+
+```tsx
+import type { Entity } from "koota";
+import { Icon, useSpeaking } from "@spawnite/engine";
+
+function SpeakingMark({ entity }: { entity: Entity }) {
+    const speaking = useSpeaking(entity);
+    return speaking ? <Icon name="mic" className="size-3.5" /> : null;
+}
+```
+
+Holdfast draws it beside each warden's name in its scoreboard.
+
+## Each player's volume
+
+Each other player's row, under People on the Audio tab of Settings, runs from 0% to 200%, and starts at 100%, which plays them as they send. Past 100%, the row adds up to 6 dB, so 200% plays a quiet player at about twice their amplitude. The mute button beside it silences them for this player alone. Discord's per-user slider has the same range and curve, and Roblox's per-player volume runs from 0 to 2. The rows last as long as the page is in the room, since a player's key names someone else in the next room.
+
+The Voice volume row in Settings sets every voice at once, on the same 0% to 200% scale, and the two multiply.
+
+A game that draws its own player list, as Roblox's list offers each person's volume, puts the same controls beside each name with `usePlayerVoice(entity)`. It reads and sets the values the Settings rows show, and `playerVolumeRange` holds the row's bounds:
+
+```tsx
+import type { Entity } from "koota";
+import { playerVolumeRange, usePlayerVoice } from "@spawnite/engine";
+
+function VoiceControls({ entity }: { entity: Entity }) {
+    const { heard, volume, muted, setVolume, setMuted } =
+        usePlayerVoice(entity);
+    if (!heard) return null;
+    return (
+        <>
+            <input
+                type="range"
+                {...playerVolumeRange}
+                value={volume}
+                onChange={(event) => setVolume(Number(event.target.value))}
+            />
+            <button onClick={() => setMuted(!muted)}>
+                {muted ? "Unmute" : "Mute"}
+            </button>
+        </>
+    );
+}
+```
+
+The page plays each voice through a gain of its own on the page's audio context, then through one limiter so a boosted voice never clips, as LiveKit's Web Audio mix does. An audio element still plays each voice, muted, because Chrome hands a remote WebRTC stream to Web Audio only while an element plays it. Desktop Chrome's echo cancellation hears Web Audio's output as it hears an element's. A page with no Web Audio plays the element itself, up to 100%.
+
+`useVoice` holds the player's mute, which the microphone button writes, and whether the room takes the microphone. `useVoiceSession` holds the rest of voice as it runs: the browser's answer about the microphone, who is speaking, and the player's volume for each other player.
+
+## Voice in development
+
+Voice runs on the platform: the rooms a published game plays in forward each player's microphone. The development room, which `spawnite play` runs on your machine, runs no voice. It tells each page so, and the page asks for no microphone. The Microphone row in Settings says that voice runs when the game plays on the platform, and `useVoiceSession`'s `unavailable` reads `true`.
+
+A game's code needs nothing for this. `useVoice`, `useVoiceSession` and `useSpeaking` work as in any room where nobody speaks: the room never opens voice, nobody is heard, and nobody is speaking.
+
+## How the engine keeps voice clear
+
+The engine sends Opus in mono at up to 24 kbit/s in 20 ms packets, which keeps a room's bandwidth low. Three settings keep it clear on a real network:
+
+- In-band forward error correction is on. Each packet carries a rough copy of the one before, so a lost packet is rebuilt rather than guessed. This is the browser's own default, which the room's answer used to turn off.
+- Discontinuous transmission is on. A silent microphone sends one small packet every 400 ms instead of 50 a second.
+- Each player's audio starts with at least 120 ms in the receiving page's jitter buffer. WebRTC starts it at 80 ms and lets it shrink to about 20 ms on a quiet link, so the first late packets stutter while it grows back; with stalls of 60 to 120 ms in the first seconds, the floor keeps the first sentence as clear as on a clean link.
+
+The browser's echo cancellation is always on, so a player on speakers does not send the others their own voices back.