docs: add the 1.10 guides

guides/Camera and sound/audio.md

@@ -27,7 +27,7 @@ function thunderAt(x, y, z) {
 
 The server sends a sound once, to the players in range as it starts. A player who arrives or joins afterwards does not hear it, and a player still on a loading screen misses it.
 
-Sounds ignore [virtual worlds](/guides/core-concepts/virtual-worlds/#what-ignores-worlds): a player within range hears a sound whatever world they are in. To keep a sound to one world, send it to that world's players and [play it on their clients](#playing-sounds-on-the-client).
+`Audio.playSoundOnPlayer` reaches only players who share that player's [virtual world](/guides/core-concepts/virtual-worlds/) and map. `Audio.playSoundAt` reaches players in any world unless you give it a `virtualWorld`, a `map` (an [`areaId`](/guides/core-concepts/virtual-worlds/#worlds-and-maps)) or both; the one you leave out is world 0 or Overland. Then only players in that world of that map hear it, and a `range` of 0 reaches every one of them.
 
 ## Sounds that keep playing
 
@@ -48,14 +48,12 @@ On the server, `Audio.stopAllSounds()` stops every sound on every client, the ga
 
 A client's `Audio.playSoundAt(event, x, y, z, options)` plays a sound only its own player hears, from a point. `Audio.playSound(event, options)` plays one on the player's own character, at full volume. Both take `duration` and `stopEvent`, and return an id for `Audio.stopSound`, or 0 when the game refused the sound. `Audio.stopOnSelf()` stops everything playing on the player's character.
 
-This pair plays a sound for the players in one world only:
+This pair plays a sound from a point for the players you pick, such as one team:
 
 ```js
 // server/main.js
-function playInWorld(world, event, x, y, z) {
-  for (const player of PlayerManager.getAll()) {
-    if (player.virtualWorld === world) player.emit("sound:play", JSON.stringify({ event, x, y, z }));
-  }
+function playForTeam(team, event, x, y, z) {
+  for (const player of team) player.emit("sound:play", JSON.stringify({ event, x, y, z }));
 }
 ```
 

guides/Camera and sound/camera.md

@@ -1,6 +1,6 @@
 ---
 title: Camera
-description: Take over the player's view with a camera of your own, move it in shots, paths and orbits, fade the screen, and hand the view back.
+description: Take over the player's view with a camera of your own, move it in shots, paths and orbits, steer it with the mouse, fade the screen, and hand the view back.
 sidebar:
   order: 700
 ---
@@ -113,6 +113,34 @@ function circlePlayer() {
 
 An orbit, or `lookAt`, leaves the camera aimed at its point after the orbit stops, after `stop` and even after `restore`. The aim then overrides the rotation of every later shot until `Camera.clearLookAt()` lifts it, so clear it before you set up a new shot, as the samples above do.
 
+## Looking around with the mouse
+
+While your camera is active, the game's own camera stops reading the mouse, so the player cannot look around. `Camera.getLookInput()` returns how far the mouse has looked since the last call, as `pitch` and `yaw` in degrees, and starts counting again from zero. Positive `pitch` looks up and positive `yaw` turns right. Read it on a timer and turn your camera by it, for a free camera:
+
+```js
+// client/main.js
+function startFreeCamera() {
+  const view = Camera.capture();
+  if (!view) return;
+  Camera.clearLookAt();
+  Camera.activate(view, { duration: 0 });
+
+  const rotation = { ...view.rotation };
+  const timer = setInterval(() => {
+    if (!Camera.active) {
+      clearInterval(timer);
+      return;
+    }
+    const look = Camera.getLookInput();
+    rotation.yaw += look.yaw;
+    rotation.pitch = Math.max(-89, Math.min(89, rotation.pitch + look.pitch));
+    Camera.setPose({ position: Camera.pose.position, rotation });
+  }, 16);
+}
+```
+
+It reads zero while your camera is not active, while the cursor shows, as it does in chat, with a web view focused or with the [controls locked](/guides/user-interface/keys-and-menus/#locking-the-controls), and while a game menu is open. Movement in those moments is dropped, not saved for later, so the view does not jump when they end. Each read clears what it returns, so read it from one place.
+
 ## Lens
 
 `Camera.setLens(options)` changes the active camera's lens: `fov` is the horizontal field of view in degrees, between 0 and 180, and `focalLength`, `aperture` and `postProcessBlend` are there for cinematic shots. A view passed to `activate` or `animateTo`, or a keyframe, can carry a `lens` too. `Camera.lens` reads the lens back.

guides/Core concepts/events.md

@@ -158,24 +158,33 @@ The declarations type the handlers of the events in these tables, so an editor k
 | `playerDownedEnd` | `(player)` | A player recovers from the downed state or respawns |
 | `playerHoldEnded` | `(player, owner, reason)` | A server-owned hold ends; `reason` identifies why |
 | `playerHoldStrained` | `(player, owner, distanceCm)` | A held player continues reporting positions beyond the hold boundary |
+| `playerMoveEnded` | `(player, owner, reason)` | A `player.moveTo` or `player.follow` walk ends. See [Walking and seating players](/guides/players/walking-players/#when-a-walk-ends) |
 | `playerWandChanged` | `(player)` | The player's wand changes |
+| `playerSpellCast` | `(player, spell, cast)` | A player casts a [server-defined spell](/guides/players/custom-spells/#casting); `spell` is its id and `cast` its `aimYaw` and `wand` tip, as the caster's game reports them |
 | `playerGearChanged` | `(player)` | What the player wears changes |
 | `worldReady` | `(player)` | The player's world, pawn, and replication are ready |
 | `loadingFinished` | `(player)` | The player's load screen is dismissed after `worldReady` |
 | `playerInventoryChanged` | `(player, items)` | The player's reported native inventory changes; `items` is the full native inventory |
 | `playerInventoryNativeDelta` | `(player, delta)` | A positive native acquisition not yet represented by the authoritative inventory is reported; the first report after connecting establishes a baseline and does not fire this event |
-| `playerInventoryUpdated` | `(player, items, revision)` | The authoritative inventory model changes |
+| `playerInventoryUpdated` | `(player, items, revision)` | The authoritative inventory model changes, by a script or by gear and mounts the player changes in game |
 | `playerInventoryConsumed` | `(player, item, remaining)` | An accepted native consumable use updates authoritative inventory |
 | `playerAppearanceChanged` | `(player, look, revision)` | The server accepts a new look from the player's game or `player.setLook`; `look` is the checked [look](/guides/players/appearance/#the-look) and `revision` increases for the connection |
 | `playerTeleportComplete` | `(player, requestId, status, completion)` | A `player.teleport` request finishes; `completion` includes the normalized request, client-observed final transform, and ground-snap result |
 | `playerFastTravelComplete` | `(player, requestId, status)` | A `player.fastTravel` request finishes or times out |
+| `playerMapTravelComplete` | `(player, requestId, status, completion)` | A `player.travelToMap` or `player.travelToPlace` request finishes, once the player can play in the new map, or times out. See [Travel between places](/guides/players/travel/#loading-another-map) |
 | `npcDied` | `(npcId, enemyId, killerId, damagerIds)` | A server-spawned NPC dies; `killerId` is the last player to damage it, or `null`, and `damagerIds` every player who did. See [Fighting NPCs](/guides/pve/fighting-npcs/#damage-and-death) |
 | `npcDamaged` | `(npcId, attackerId, amount)` | A player reports damage to a server-spawned NPC |
+| `npcWaypoint` | `(npc, index, lap)` | An NPC on a path reaches `waypoints[index]`, before its wait; `lap` counts completed laps. See [Moving NPCs and creatures](/guides/npcs-and-creatures/movement/#path-events) |
+| `npcMoveEnded` | `(npc, reason)` | An NPC's path ends: `"arrived"`, `"stopped"`, `"replaced"` or `"unreachable"` |
 | `beastCared` | `(beast, player, kind)` | A player pets or feeds a beast; return `false` synchronously to refuse it |
 | `beastCaptureStart` | `(beast, player)` | A player's Nab-Sack starts drawing in a beast they may catch; return `false` synchronously to make it let go. See [Catching beasts](/guides/npcs-and-creatures/catching-beasts/#refereeing-a-catch) |
 | `beastCaptureRequest` | `(beast, player)` | A player's Nab-Sack finished on a beast and the catch waits for the server; return `false` synchronously to refuse it |
 | `beastCaptured` | `(player, captured)` | A catch landed: the beast is in the player's bag and has left the world |
 | `beastReleased` | `(player, released, at)` | A player released a beast from their Field Guide; `at` is where they stood |
+| `beastWaypoint` | `(beast, index, lap)` | A beast on a path reaches `waypoints[index]`, before its wait |
+| `beastMoveEnded` | `(beast, reason)` | A beast's path or follow ends: `"arrived"`, `"stopped"`, `"replaced"`, `"unreachable"` or `"targetGone"` |
+| `characterWaypoint` | `(character, index, lap)` | A character on a path reaches `waypoints[index]`, before its wait |
+| `characterMoveEnded` | `(character, reason)` | A character's path ends: `"arrived"`, `"stopped"` or `"replaced"` |
 | `campActivated` | `(campId)` | A [camp](/guides/encounters/camps/)'s enemies spawn |
 | `campCleared` | `(campId)` | Every enemy of an active camp is dead |
 | `worldEventStarted` | `(spotId, kind)` | A [world event](/guides/encounters/world-events/) starts |
@@ -185,6 +194,9 @@ The declarations type the handlers of the events in these tables, so an editor k
 | `zoneExit` | `(zone, entity, reason, entityId)` | An entity leaves a zone; `reason` is `"left"` or `"gone"` |
 | `doorUnlockRequest` | `(player, door)` | A player tries to open a lock the server holds shut, by key or Alohomora |
 | `lootableTaken` | `(player, lootableId, items)` | A player takes a server lootable; `items` is what it gave them |
+| `trainSpawned` | `(t)` | `World.hogwartsExpress.spawn` stands the [Hogwarts Express](/guides/world/hogwarts-express/) at `t` |
+| `trainStopped` | `(t)` | The train brakes to a stop at `t`, at the end of a `moveTo` or a `halt` |
+| `trainEnded` | `(reason)` | The train is gone; `reason` is `"end"` when a departure left the track, `"despawned"` after `despawn()` or a replacing `spawn()` |
 | `housePointsChange` | `(house, points, previous)` | A house's points change |
 | `housePointsRequest` | `(player, request)` | A player's game asks to change house points; return `false` synchronously to refuse it |
 | `sanctuaryChanged` | `(id, revision, editor)` | An editor changes a [Room of Requirement](/guides/room-of-requirement/rooms/) room |
@@ -225,7 +237,7 @@ These events are delivered only inside the client runtime. Receiving a native cl
 | `resourceStop` | `(resourceName)` | A client JavaScript resource is about to stop |
 | `chatMessage` | `({ author, text, color })` | A chat message arrives from the server |
 | `chatSend` | `(text)` | The local player submits text through the chat overlay |
-| `spellCast` | `(spellPath)` | The local player casts a spell; the path identifies its spell record |
+| `spellCast` | `(spellPath)` | The local player casts a spell; the path identifies its spell record, or is the id of a [server-defined spell](/guides/players/custom-spells/#casting) |
 | `playerRegionChanged` | `(region)` | The local player enters a named region |
 | `creatorOpened` | `({})` | The character creator opens |
 | `creatorConfirmed` | `({ first, last })` | The character creator closes after confirmation |
@@ -235,9 +247,12 @@ These events are delivered only inside the client runtime. Receiving a native cl
 | `spellAssignment` | `({ source, loadout, slot })` | A spell is assigned to a slot, from the game's menu or a script |
 | `spellLearningFinished` | `(result)` | A spell lesson the resource started finishes; it grants no spell |
 | `minimapChanged` | `(state, previous)` | The [minimap](/guides/user-interface/map-markers/#the-minimap) switches map, floor or tile |
+| `waypointChanged` | `(waypoint, previous)` | The local player places, moves or removes their [map waypoint](/guides/user-interface/map-markers/#the-players-waypoint); a removal reports `null` |
+| `mailRead` | `(key, sender)` | The local player reads an owl post letter, theirs or the game's; `sender` is the sender's id, not their display name. A letter that loads or arrives already read raises nothing |
 | `pvpRelationChanged` | `(relation)` | The local player's [PvP relation](/guides/pvp/rules-and-relations/) to another player is resolved or changes |
 | `localDowned` | `()` | The local player kneels after a PvP defeat |
 | `localDownedEnd` | `({ wasDead })` | The local player gets up, from a kneel or a respawn |
+| `anchorReleased` | `(reason, at)` | The local player's [seat anchor](/guides/players/walking-players/#seating-the-player) ends; `at` is the floor-level point they sat at |
 | `entityStateChange` | `(entity, key, value, previous)` | A replicated state write or removal arrives on the client; `value` is `undefined` for a removal |
 
 A `chatSend` handler may synchronously return `false` to prevent that line from being sent. An asynchronous return value cannot veto it.