Implement land, terrain, environment, and sound managers (#70)

docs/land.md

@@ -0,0 +1,73 @@
+# Land, terrain, environment, and sound
+
+`GridClient` owns one lazily constructed `ParcelManager`, `TerrainManager`,
+`EnvironmentManager`, and `SoundManager`. Cloning a manager keeps the same
+registries and state; disposing it releases packet and capability
+subscriptions. Incoming state is committed before an event callback is run,
+and registries snapshot callbacks before invoking them so callbacks never run
+under a manager lock.
+
+## Parcels
+
+Parcel properties received from the capability event queue retain their
+request sequence, result, selection state, region-local coordinates, flags,
+permissions, media settings, and 512-byte occupancy bitmap. The bitmap is
+expanded to the simulator's four-metre parcel map. Overlay packets are four
+fixed 1 KiB segments: they may arrive out of order, duplicate sequence IDs do
+not advance completion, and the downloaded event is emitted only after all
+four unique segments are present.
+
+Requests select the reference LLUDP packet for property, access-list, dwell,
+owner, update, subdivision/join, purchase, reclaim, deed, release, auction,
+selection/return, and terraform operations. Remote parcel lookup and script
+resource summary/detail use their named capabilities. Resource replies,
+variable blocks, strings, bitmaps, and HTTP bodies are bounded before state is
+published. Bulk parcel discovery is cancellation-aware and skips cells already
+covered by received bitmaps.
+
+Parcel and estate mutation methods send real protocol operations. Applications
+must place user confirmation and authorization policy in front of destructive
+operations. Live-grid tests must remain ignored unless explicit credentials
+and opt-in configuration are supplied; the default tests use only synthetic
+packets and in-memory HTTP handlers.
+
+## Terrain and wind
+
+`TerrainCompressor` implements the 16×16 DCT patch format, including zig-zag
+coefficient order, quantization headers, normal and large-region coordinate
+encodings, end markers, and bounded layer construction. `TerrainManager`
+decodes land and wind layer packets, stores patches before emitting
+`LandPatchReceived`, and keeps width and height independent for rectangular
+variable regions. `Simulator::terrain_height_at_point` resolves a local metre
+coordinate through the stored patch grid.
+
+PBR terrain material overrides use the `ModifyRegion` capability. Exactly four
+slots are accepted. Empty maps remain empty slots; non-empty maps use the
+native `AssetMaterial` override codec. Capability and LLSD response bodies are
+limited to 16 MiB and operations honor cancellation.
+
+## Environment
+
+Extended environment requests use `ExtEnvironment`; parcel operations append
+the compatibility query key `parcelid`, while region operations leave the URI
+unchanged. GET, POST, and DELETE implement retrieval, update, and reset.
+`EnvironmentSettings` provides the legacy LLSD path. Parsed region and legacy
+state is installed before update events, and all request/response bodies are
+limited to 16 MiB.
+
+## Sound
+
+The sound manager emits typed events for attached sounds, attached gain
+changes, preload queues, and positional sound triggers. UUID identity, gain,
+region handle, position, and `SoundFlags` (including queueing) are retained.
+Outgoing triggers validate IDs and finite values, clamp gain to the protocol
+range, and select the current or explicitly supplied simulator and region
+handle.
+
+## Focused validation
+
+The native tests cover terrain golden round trips and bounds, rectangular
+region addressing, parcel bitmap and overlay correlation, capability parcel
+state publication, environment LLSD shapes, sound packet identity/queueing, and
+state-before-callback ordering. The translated compatibility cases cover
+extended-environment HTTP selection and all four terrain-material slots.