crowdypy 0.7.0.dev1__tar.gz → 0.9.0.dev1__tar.gz

{crowdypy-0.7.0.dev1 → crowdypy-0.9.0.dev1}/AGENTS.md

@@ -60,7 +60,9 @@ python tools/parity/parity.py --crowdyjs ../CrowdyJS --write docs/parity-matrix.
 ```
 
 then port what changed, refresh `tests/fixtures/` from the same commit, and classify or
-cover every new difference. Build CrowdyJS at the new pin (`npm ci && npm run build`) and run
+cover every new difference. `tests/unit/test_fixture_provenance.py` holds each copied fixture
+to its CrowdyJS source, and `exec-client-frames.json` and `voice-frames.json` to the vendored
+CrowdyCPP copies too. Build CrowdyJS at the new pin (`npm ci && npm run build`) and run
 `node tools/fixtures/player_host.mjs ../CrowdyJS`: it rewrites the player-host schemas and
 their fixture, and `tests/unit/test_player_host.py` refuses either one from another commit. Moving the CrowdyCPP pin:
 
@@ -145,5 +147,24 @@ The replication system saturates the local network stack, so the binding
 - Sends are batched, and the GIL is released while a batch is encoded and sent.
 - An asyncio loop is woken through `Config::onEventsReady` and a socket pair, never by a
   sleep-poll.
+- While a World Stores session is attached it owns the connection's handlers. What its stores
+  do not keep (audio, video, text, opcode 140, channel audio) is forwarded into the batch
+  rows; voxel updates are forwarded only once Python watches them (`watch_voxels`, set by
+  `session.on("voxel_update")`), since the chunk store already merges every one.
 - Every change to the hot path reruns `benchmarks/bench_replication.py` and CrowdyCPP's
   `bench_send` on the same machine, and updates `benchmarks/README.md`.
+
+## The native session and its chunk store
+
+- The session is built without host election and with native write-back off. Both are
+  GraphQL work the Python facade does on its timers.
+- Its chunk source, `StagedChunks` in `native/session_binding.cpp`, only applies what the
+  facade loaded. `ChunkStore.hydrate()` and `prune_beyond()` hand a chunk to it through
+  `WorldSession.hydrate`, so stored edits follow CrowdyCPP's overlay rules: an edit the
+  16x16x16 one-byte grid cannot hold goes to `ChunkData::overlay`.
+- Do not write voxel types or states into the dense grid from Python. That bypasses the
+  overlay, and the echo matching of local edits.
+- The voice helpers (`native/voice_binding.cpp`) bind CrowdyCPP's `voice_frames.hpp`.
+  `crowdypy.media` checks every argument as CrowdyJS does first, because CrowdyCPP clamps the
+  options CrowdyJS refuses.
+- `CROWDY_WITH_OPUS` stays `OFF` in `pyproject.toml`: the wheels link no audio codec.

{crowdypy-0.7.0.dev1 → crowdypy-0.9.0.dev1}/CMakeLists.txt

@@ -59,6 +59,7 @@ nanobind_add_module(_native
   native/module.cpp
   native/replication_binding.cpp
   native/session_binding.cpp
+  native/voice_binding.cpp
   native/wire_binding.cpp
 )
 target_include_directories(_native PRIVATE native)

{crowdypy-0.7.0.dev1 → crowdypy-0.9.0.dev1}/MIGRATION.md

@@ -3,6 +3,128 @@
 CrowdyPy is pre-1.0. Within a minor line, patch releases keep source compatibility; each
 new minor may change the API. Read the section for every minor you skip.
 
+## 0.9.0
+
+CrowdyJS 18.8.0 and CrowdyCPP 0.61.0. Additive, with one floor: the build documents select
+`ExecBuild.sdkVersion`, so `exec.build`, `build_status`, `wait_for_build`, `mod_build`,
+`mod_client_build`, `mod_build_status` and `wait_for_mod_build` need ck-api v2.40.2 (an older
+one refuses the selection).
+
+- **`ExecBuild.sdk_version`**: the version of `ckx-sdk` the platform compiled the build against
+  (`crowdy-client-sdk` for a CLIENT half), from the toolchain of the API instance that ran it. The
+  platform points a crate at its own copy of the SDK whatever version the crate names, so this,
+  not your manifest, says what your code was checked against. `None` until the build starts.
+
+## 0.8.0
+
+CrowdyJS 18.7.0 and CrowdyCPP 0.60.0. Additive, with reads that change for values they used to
+get wrong (wide voxels) and one new floor: every token mutation (`portal.mint_app_token`,
+`exchange_code`, `refresh`) selects `runtimeGate`, so 0.8.0 needs the ck-api release after
+v2.39.0 that serves it; an older one refuses the selection. Channel audio and the echo of your
+own voxel edits need replication server v0.37.0.
+
+- **Voice helpers** (`crowdypy.media`), an optional convention for what an audio payload
+  carries: a 10-byte little-endian header in front of each codec frame (version 1, codec 0 raw,
+  1 Opus 48 kHz mono or 2 G.711 µ-law 8 kHz, `u16` seq, `u32` timestamp in codec samples,
+  the frame's duration in ms, and the talk-spurt flags `VoiceFlag.SPURT_START` and
+  `SPURT_END`).
+  - `encode_voice_header(VoiceHeader(...))` and `encode_voice_packet(header, frame)` write it;
+    `decode_voice_packet(packet)` returns `None` for a packet shorter than 10 bytes or of
+    another version, and never raises on bytes from the network.
+  - `VoicePacketizer(codec, frame_ms, *, seq=0, timestamp=0)` numbers one sender's frames
+    across the seq and timestamp wraps (`packetize(frame, last=)`, `skip(frames)` for
+    silence).
+  - `VoiceJitterBuffer(target_delay_ms=60, max_frames=64, reset_after_ms=200)`:
+    `push(key, packet, now_ms)` answers `"buffered"`, `"late"`, `"duplicate"` or
+    `"malformed"`, and `pull(key, now_ms)` / `poll(now_ms)` return the due `VoicePlayout`s in
+    seq order, a gap (`frame` `None`) for each frame that never came.
+  - CrowdyCPP's implementation runs natively. Arguments are checked as CrowdyJS checks them, so
+    an option or field out of range raises `ValueError` where CrowdyCPP would clamp it.
+  - The helpers replay CrowdyJS's `voice-frames.json` byte for byte.
+  - No codec ships, and the wheel links none: which codec an app uses, and the library that
+    encodes it, is the app's choice.
+- **Channel audio** (party and guild voice).
+  - `client.udp.send_channel_audio(channel_id, uuid, payload)` sends message type 35, the
+    channel message's layout and signing with its own type byte, at most 1,024 bytes. It needs
+    the channel's `send_voice` and the player's `use_voice_chat`; without them the server
+    answers `UNAUTHORIZED` for the returned sequence. The sender gets no echo.
+  - Members receive message type 36, standalone or bundled, on the new `channel_audio` handler
+    of `udp.subscribe` (`notification.channel_id`, the sender's `uuid`, `payload`).
+  - In the World Stores it is `session.on("channel_audio", ...)`; the channel inbox does not
+    get it. Key a jitter buffer by channel and sender, so one player in two channels is two
+    streams.
+  - `channels.create`, `grids.create_channel` and `GridScope.channels.create` take
+    `members_can_speak` (default false), which gives the member role `send_voice`.
+    `GridScope.channels.send_audio(channel_id, uuid, payload)` sends on the grid's channels.
+  - Underneath are `ReplicationConnection.send_channel_audio`, and
+    `crowdypy.wire.encode_channel_audio` and `ChannelAudioNotification` (from `parse_datagram`)
+    for a custom transport.
+- **App-defined spatial messages** (`GENERIC_SPATIAL_1`, 140) reach
+  `session.on("generic_spatial", ...)` while a World Stores session is attached
+  (CrowdyCPP's `onGenericSpatial`). Without a session, `udp.subscribe`'s `generic_spatial`
+  already received them.
+- **`session.on("voxel_update", ...)`** fires for every inbound voxel edit after
+  `session.chunks` merged it, with its sender, voxel and state: CrowdyCPP's `onVoxel`, for a
+  game that keeps its own world. It includes the echo of your own edits; compare the uuid and
+  sequence with your send's.
+- **`ChunkStore` keeps wide voxel types and other addresses.** Positions and types are the app's
+  signed 16-bit values, which the platform does not check.
+  - An edit the 16x16x16 one-byte grid cannot hold (a type outside 0-255, a position outside
+    0-15) is kept whole in the chunk's overlay. That covers a realtime update, a hydrated
+    `voxelStates` entry and a local `set_voxel`.
+  - `ChunkStore.overlay(chunk)` returns the overlay as `ChunkOverlayVoxel(x, y, z,
+    voxel_type, state)` values keyed by `voxel_key(x, y, z)` (`"x:y:z"`), and `voxel_type_at`
+    and `voxel_state_at` read it first.
+  - What changes: hydration no longer stores a type outside 0-255 truncated (300 used to read
+    as 44), and keeps an entry outside 0-15 instead of skipping it. `voxels()` holds 0 under
+    an in-grid voxel whose type is in the overlay.
+  - `set_voxel` keeps a position outside 0-15 in the overlay and sends it, where it used to be
+    refused. It raises `ValueError`, before anything changes or is sent, for a position or type
+    outside 16 bits or a state over 1,024 bytes (`crowdypy.wire.assert_voxel_edit`,
+    `VOXEL_STATE_MAX_BYTES`).
+  - `udp.send_voxel_update` and `ReplicationConnection.send_voxel_update` refuse a state over
+    1,024 bytes (`CrowdyReplicationError`, `InvalidArgument`); the server refuses one with
+    `INVALID_REQUEST`.
+- **The echo of your own voxel edit.** Replication server v0.37.0 delivers every accepted edit
+  back to its sender. `ChunkStore` matches the echo to the `set_voxel` that sent it (sender,
+  sequence, voxel) and does not apply it again, so a local edit fires `on_chunk_changed` once.
+  The echo is applied only when another client's edit of the voxel arrived in between (the
+  server ordered yours last).
+- **Hydration goes through the native store.** `ChunkStore.hydrate()` hands each loaded chunk
+  to CrowdyCPP's `ChunkStore`, which puts the entries the grid cannot hold in the overlay. An
+  entry without a state now clears the voxel's state, also one a local `set_voxel` gave it (0.5.1
+  kept that until the next realtime update). `voxel_state_at` reads the native cache only, and
+  `prune_beyond` keeps a dirty chunk's states and overlay as well as its grid.
+- **UDP error 33, `APP_PAUSED`** (`crowdypy.wire.ErrorCode.APP_PAUSED`): the replication
+  server refuses a paused app's sends.
+- **Pause and access refusals.**
+  - `crowdypy.is_app_paused(gate)` reads `AppTokenResponse.runtime_gate` (`AppRuntimeGate`,
+    `status` and `reason`) and the `runtimeGate` of `server_status.game_client_bootstrap`.
+    Anything but `ACTIVE` is paused. A paused app still mints, so check before entering the
+    world.
+  - `crowdypy.app_paused_of(error)` reads `APP_PAUSED` (`reason`).
+  - `crowdypy.access_refusal_of(error)` reads `ACCESS_REVOKED`, `ACCESS_SUSPENDED`
+    (`suspended_until`) or `ACCESS_NOT_GRANTED`.
+  - `crowdypy.actor_exists_of(error)` reads `ACTOR_EXISTS` (`owned_by_caller`).
+  - Each reader takes a raised `CrowdyGraphQLError` or one raw error entry. The `*_CODE`
+    constants name the codes.
+- **New API wraps.**
+  - `users.player_profile(user_id)` and `users.player_profiles(user_ids)` return the public
+    `userId`, `gamertag` and `disambiguation`. `player_profiles` takes at most
+    `PLAYER_PROFILES_MAX` (100) ids, raises `ValueError` above that, and sends nothing for
+    none. `users.get` documents that another user's private fields come back `None`.
+  - `app_access.suspend(app_id, user_id, until, idempotency_key=None)` takes a timezone-aware
+    `datetime` or an ISO-8601 string. With it come `unsuspend` and
+    `resync_tier_grid_permissions` (`manage_access_tiers`), and `suspendedUntil` on every
+    access record.
+  - `exec.restart_type(app_id, node_type)` returns `ExecRestartResult(node_type, stopped)`
+    (`manage_compute`). `ExecAppStatus` gains `budget_pause_reason`, `max_instances`,
+    `max_reserved_mb`, `instance_limit`, `instances` and `reserved_mb`.
+  - `apps.get` and `apps.update` carry `claimOwnerKeys`, chunk reads `voxelStatesTruncated`,
+    and `game_client_bootstrap` `runtimeGate` and `wildernessWritesOpen`.
+- The keyframe and heartbeat defaults stay. Idle players on different servers meet at the first
+  full update after joining (replication server v0.37.0).
+
 ## 0.7.0
 
 CrowdyJS 18.6.0 and CrowdyCPP 0.59.0. Additive.

{crowdypy-0.7.0.dev1 → crowdypy-0.9.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crowdypy
-Version: 0.7.0.dev1
+Version: 0.9.0.dev1
 Summary: Official Python SDK for Crowded Kingdoms: typed GraphQL clients and a native UDP replication core
 Keywords: crowded-kingdoms,multiplayer,replication,graphql,sdk,udp
 Author: Crowded Kingdoms
@@ -51,20 +51,29 @@ CrowdyPy follows the [CrowdyJS](https://github.com/CrowdedKingdoms/CrowdyJS) API
 client, bound with [nanobind](https://github.com/wjakob/nanobind) and shipped inside the
 wheel. Python never touches a datagram.
 
-**v0.7.0: the input log (CrowdyJS 18.6.0, CrowdyCPP 0.59.0).**
-- `client.input_log.sessions(app_id)` and `messages(app_id, game_token_id)` read the client
-  inputs recorded for an app with replay logging on (`replayLoggingEnabled`, now on every app
-  read and set with `client.apps.update`). A player reads their own; `manage_apps` reads every
-  session. Keep paging while `pageInfo.hasNextPage` is true: a messages page can be short.
-
-**v0.6.0: distance-limited channel messages and the terms gate (CrowdyJS 18.5.0, CrowdyCPP 0.58.0).**
-- `client.udp.send_ranged_channel_message(..., chunk=, max_distance=)` publishes to a channel
-  but reaches only the members whose own actor is within `max_distance` chunks of `chunk`,
-  by straight-line distance. Members receive the ordinary `channel_message`.
-- `client.auth.record_player_consents()` and `player_legal_acceptance()`, `register`'s
-  `accept_legal` and `attest_age_of_majority`, and `is_legal_acceptance_required_error`: a
-  gameplay token now waits for the player's agreement to the legal documents and age
-  attestation.
+**v0.9.0: builds report the SDK they compiled against (CrowdyJS 18.8.0, CrowdyCPP 0.61.0).** See the 0.9.0
+bullet below.
+
+**v0.8.0: voice, channel audio, wide voxels, and pause and access refusals (CrowdyJS 18.7.0, CrowdyCPP 0.60.0).**
+- Voice: `crowdypy.media`'s voice helpers (an optional 10-byte header per codec frame,
+  `VoicePacketizer`, `VoiceJitterBuffer`), and `client.udp.send_channel_audio()` with the
+  `channel_audio` handler, which reaches every member of a channel wherever they are (party
+  and guild voice).
+- World Stores: `ChunkStore` keeps voxel edits the 16x16x16 one-byte grid cannot hold in an
+  overlay, and applies the echo of your own edit once. `session.on("voxel_update")` and
+  `session.on("generic_spatial")` reach a game that keeps its own world.
+- Refusals: `crowdypy.is_app_paused()` reads the runtime gate that tokens and the bootstrap
+  carry, and `app_paused_of`, `access_refusal_of` and `actor_exists_of` read the new refusals.
+- New calls: `users.player_profile(s)`, `app_access.suspend` and `unsuspend`, and
+  `exec.restart_type`.
+- 0.9.0: every build (`exec.build`, `build_status`, `wait_for_build` and the mod builds) carries
+  `sdk_version`, the `ckx-sdk` (CLIENT half: `crowdy-client-sdk`) version the platform compiled it
+  against, whatever the crate names. It needs ck-api v2.40.2, since the build documents select it.
+- 0.8.0 needs the ck-api release after v2.39.0, since the token mutations select
+  `runtimeGate`. Channel audio and the voxel echo need replication server v0.37.0.
+- 0.7.0 brought the input log (`client.input_log.sessions()` and `messages()`, and
+  `replayLoggingEnabled`). 0.6.0 brought distance-limited channel messages
+  (`udp.send_ranged_channel_message()`) and the terms gate (`auth.record_player_consents()`).
 - 0.5.1 made `ChunkStore.hydrate()` keep every recorded voxel edit (`voxelStates`) and
   `ensure_around()` keep a chunk it already loaded.
 - 0.5.0 brought the ck-exec gateway check (`client.exec.connect()` sends the connect token
@@ -180,6 +189,13 @@ is not serving) and `CrowdyUserCodeFaultError` (a player module faulted;
 `player_fault_of(error)` reads the fault) mirror CrowdyJS. A `WRONG_DATACENTER` refusal
 moves the client to the app's datacenter and retries once, by itself.
 
+A paused app (its organization ran out of funds, hit a spend cap, or let a subscription
+lapse) still mints a token, so check `crowdypy.is_app_paused(minted.runtime_gate)` before
+entering the world, and tell the player it is paused. Replication then refuses sends with UDP
+error 33 (`APP_PAUSED`). `crowdypy.app_paused_of(error)`, `access_refusal_of(error)`
+(`ACCESS_REVOKED`, `ACCESS_SUSPENDED` with `suspended_until`, `ACCESS_NOT_GRANTED`) and
+`actor_exists_of(error)` read those refusals. None of them clears by retrying.
+
 ## Replication
 
 ```python
@@ -207,6 +223,47 @@ async for batch in conn.batches():
 `crowdypy.replication.ReplicationConnection` is the same for code without an event loop:
 `wait()` and then `poll()` from your own loop.
 
+Voxel positions and types are the app's signed 16-bit values, and a voxel state is at most
+1,024 bytes (`InvalidArgument` otherwise, nothing sent). Replication server v0.37.0 echoes
+every accepted voxel edit back to its sender as a `voxel_update`.
+
+## Voice
+
+`send_audio_packet` reaches players near a chunk and carries whatever bytes it is given; a game
+with a voice format of its own keeps it. The voice helpers in `crowdypy.media` are an optional
+format that every Crowded Kingdoms SDK shares, byte for byte. Each packet is a 10-byte header
+(version 1, the codec, a `u16` seq, a `u32` timestamp in codec samples, the frame's duration
+and two talk-spurt flags) followed by one codec frame. `VoicePacketizer` numbers one sender's
+frames. `VoiceJitterBuffer` puts each sender's packets back in order and plays them out 60 ms
+after the first packet of a talk spurt arrived. It reports a frame that never came as a gap,
+drops one that arrives after its playout time, and holds at most 64 frames a sender.
+
+`send_channel_audio` reaches every member of a channel wherever they are (party or guild
+voice), at most 1,024 bytes a packet. The sender needs the channel's `send_voice`
+(`members_can_speak=True` on creation gives it to the member role) and the player's
+`use_voice_chat`. There is no echo, and members receive `channel_audio`:
+
+```python
+from crowdypy.media import VoiceCodec, VoiceJitterBuffer, VoicePacketizer
+
+party = VoicePacketizer(VoiceCodec.OPUS, 20)
+# Every 20 ms while the player talks (`opus_frame` from your own encoder):
+await game.udp.send_channel_audio(channel_id, my_uuid, party.packetize(opus_frame, last=released))
+# ...and party.skip() for every 20 ms of silence that is not sent.
+
+voices = VoiceJitterBuffer()
+game.udp.subscribe({"channel_audio": lambda n: voices.push(f"{n.channel_id}:{n.uuid}", n.payload)})
+for slot in voices.poll():  # at least once a frame, from your audio clock
+    if slot.gap:
+        conceal(slot.key, slot.frame_ms)  # the frame never came
+    else:
+        play(slot.key, slot.codec, slot.frame)
+```
+
+No codec ships with CrowdyPy, and the wheel links none: which codec an app uses (Opus, or
+G.711 µ-law where it has no Opus), and the library that encodes and decodes it, is the app's
+choice. Where a voice sits in the world (panning, distance attenuation) is the game's too.
+
 ## World Stores
 
 ```python
@@ -223,6 +280,12 @@ snapshot = session.actors.snapshot()  # once a frame: every actor at once
 states = pose.decode_many(snapshot.state_offsets, snapshot.state_data)  # numpy, no loop
 ```
 
+`session.chunks` is a helper for 16x16x16 chunks with one byte per voxel. An edit that grid
+cannot hold (a type outside 0-255, a position outside 0-15) is kept in the chunk's
+`overlay()`, and `voxel_type_at` reads it first. The echo of your own `set_voxel` is not
+applied a second time. A game with other addressing reads every edit from
+`session.on("voxel_update", ...)`, which includes those echoes.
+
 ## Crowdy Studio
 
 ```python

{crowdypy-0.7.0.dev1 → crowdypy-0.9.0.dev1}/README.md

@@ -11,20 +11,29 @@ CrowdyPy follows the [CrowdyJS](https://github.com/CrowdedKingdoms/CrowdyJS) API
 client, bound with [nanobind](https://github.com/wjakob/nanobind) and shipped inside the
 wheel. Python never touches a datagram.
 
-**v0.7.0: the input log (CrowdyJS 18.6.0, CrowdyCPP 0.59.0).**
-- `client.input_log.sessions(app_id)` and `messages(app_id, game_token_id)` read the client
-  inputs recorded for an app with replay logging on (`replayLoggingEnabled`, now on every app
-  read and set with `client.apps.update`). A player reads their own; `manage_apps` reads every
-  session. Keep paging while `pageInfo.hasNextPage` is true: a messages page can be short.
-
-**v0.6.0: distance-limited channel messages and the terms gate (CrowdyJS 18.5.0, CrowdyCPP 0.58.0).**
-- `client.udp.send_ranged_channel_message(..., chunk=, max_distance=)` publishes to a channel
-  but reaches only the members whose own actor is within `max_distance` chunks of `chunk`,
-  by straight-line distance. Members receive the ordinary `channel_message`.
-- `client.auth.record_player_consents()` and `player_legal_acceptance()`, `register`'s
-  `accept_legal` and `attest_age_of_majority`, and `is_legal_acceptance_required_error`: a
-  gameplay token now waits for the player's agreement to the legal documents and age
-  attestation.
+**v0.9.0: builds report the SDK they compiled against (CrowdyJS 18.8.0, CrowdyCPP 0.61.0).** See the 0.9.0
+bullet below.
+
+**v0.8.0: voice, channel audio, wide voxels, and pause and access refusals (CrowdyJS 18.7.0, CrowdyCPP 0.60.0).**
+- Voice: `crowdypy.media`'s voice helpers (an optional 10-byte header per codec frame,
+  `VoicePacketizer`, `VoiceJitterBuffer`), and `client.udp.send_channel_audio()` with the
+  `channel_audio` handler, which reaches every member of a channel wherever they are (party
+  and guild voice).
+- World Stores: `ChunkStore` keeps voxel edits the 16x16x16 one-byte grid cannot hold in an
+  overlay, and applies the echo of your own edit once. `session.on("voxel_update")` and
+  `session.on("generic_spatial")` reach a game that keeps its own world.
+- Refusals: `crowdypy.is_app_paused()` reads the runtime gate that tokens and the bootstrap
+  carry, and `app_paused_of`, `access_refusal_of` and `actor_exists_of` read the new refusals.
+- New calls: `users.player_profile(s)`, `app_access.suspend` and `unsuspend`, and
+  `exec.restart_type`.
+- 0.9.0: every build (`exec.build`, `build_status`, `wait_for_build` and the mod builds) carries
+  `sdk_version`, the `ckx-sdk` (CLIENT half: `crowdy-client-sdk`) version the platform compiled it
+  against, whatever the crate names. It needs ck-api v2.40.2, since the build documents select it.
+- 0.8.0 needs the ck-api release after v2.39.0, since the token mutations select
+  `runtimeGate`. Channel audio and the voxel echo need replication server v0.37.0.
+- 0.7.0 brought the input log (`client.input_log.sessions()` and `messages()`, and
+  `replayLoggingEnabled`). 0.6.0 brought distance-limited channel messages
+  (`udp.send_ranged_channel_message()`) and the terms gate (`auth.record_player_consents()`).
 - 0.5.1 made `ChunkStore.hydrate()` keep every recorded voxel edit (`voxelStates`) and
   `ensure_around()` keep a chunk it already loaded.
 - 0.5.0 brought the ck-exec gateway check (`client.exec.connect()` sends the connect token
@@ -140,6 +149,13 @@ is not serving) and `CrowdyUserCodeFaultError` (a player module faulted;
 `player_fault_of(error)` reads the fault) mirror CrowdyJS. A `WRONG_DATACENTER` refusal
 moves the client to the app's datacenter and retries once, by itself.
 
+A paused app (its organization ran out of funds, hit a spend cap, or let a subscription
+lapse) still mints a token, so check `crowdypy.is_app_paused(minted.runtime_gate)` before
+entering the world, and tell the player it is paused. Replication then refuses sends with UDP
+error 33 (`APP_PAUSED`). `crowdypy.app_paused_of(error)`, `access_refusal_of(error)`
+(`ACCESS_REVOKED`, `ACCESS_SUSPENDED` with `suspended_until`, `ACCESS_NOT_GRANTED`) and
+`actor_exists_of(error)` read those refusals. None of them clears by retrying.
+
 ## Replication
 
 ```python
@@ -167,6 +183,47 @@ async for batch in conn.batches():
 `crowdypy.replication.ReplicationConnection` is the same for code without an event loop:
 `wait()` and then `poll()` from your own loop.
 
+Voxel positions and types are the app's signed 16-bit values, and a voxel state is at most
+1,024 bytes (`InvalidArgument` otherwise, nothing sent). Replication server v0.37.0 echoes
+every accepted voxel edit back to its sender as a `voxel_update`.
+
+## Voice
+
+`send_audio_packet` reaches players near a chunk and carries whatever bytes it is given; a game
+with a voice format of its own keeps it. The voice helpers in `crowdypy.media` are an optional
+format that every Crowded Kingdoms SDK shares, byte for byte. Each packet is a 10-byte header
+(version 1, the codec, a `u16` seq, a `u32` timestamp in codec samples, the frame's duration
+and two talk-spurt flags) followed by one codec frame. `VoicePacketizer` numbers one sender's
+frames. `VoiceJitterBuffer` puts each sender's packets back in order and plays them out 60 ms
+after the first packet of a talk spurt arrived. It reports a frame that never came as a gap,
+drops one that arrives after its playout time, and holds at most 64 frames a sender.
+
+`send_channel_audio` reaches every member of a channel wherever they are (party or guild
+voice), at most 1,024 bytes a packet. The sender needs the channel's `send_voice`
+(`members_can_speak=True` on creation gives it to the member role) and the player's
+`use_voice_chat`. There is no echo, and members receive `channel_audio`:
+
+```python
+from crowdypy.media import VoiceCodec, VoiceJitterBuffer, VoicePacketizer
+
+party = VoicePacketizer(VoiceCodec.OPUS, 20)
+# Every 20 ms while the player talks (`opus_frame` from your own encoder):
+await game.udp.send_channel_audio(channel_id, my_uuid, party.packetize(opus_frame, last=released))
+# ...and party.skip() for every 20 ms of silence that is not sent.
+
+voices = VoiceJitterBuffer()
+game.udp.subscribe({"channel_audio": lambda n: voices.push(f"{n.channel_id}:{n.uuid}", n.payload)})
+for slot in voices.poll():  # at least once a frame, from your audio clock
+    if slot.gap:
+        conceal(slot.key, slot.frame_ms)  # the frame never came
+    else:
+        play(slot.key, slot.codec, slot.frame)
+```
+
+No codec ships with CrowdyPy, and the wheel links none: which codec an app uses (Opus, or
+G.711 µ-law where it has no Opus), and the library that encodes and decodes it, is the app's
+choice. Where a voice sits in the world (panning, distance attenuation) is the game's too.
+
 ## World Stores
 
 ```python
@@ -183,6 +240,12 @@ snapshot = session.actors.snapshot()  # once a frame: every actor at once
 states = pose.decode_many(snapshot.state_offsets, snapshot.state_data)  # numpy, no loop
 ```
 
+`session.chunks` is a helper for 16x16x16 chunks with one byte per voxel. An edit that grid
+cannot hold (a type outside 0-255, a position outside 0-15) is kept in the chunk's
+`overlay()`, and `voxel_type_at` reads it first. The echo of your own `set_voxel` is not
+applied a second time. A game with other addressing reads every edit from
+`session.on("voxel_update", ...)`, which includes those echoes.
+
 ## Crowdy Studio
 
 ```python

{crowdypy-0.7.0.dev1 → crowdypy-0.9.0.dev1}/benchmarks/README.md

@@ -93,3 +93,23 @@ A 60 Hz asyncio loop sends 200 entities a frame (one batch) while about 60,000
 notifications a second arrive and are dispatched to a handler. Lateness of each frame
 against its schedule, ten seconds: p50 0.1 ms, p99 0.1 ms, max 0.2 ms. Receiving never
 holds the loop: it is woken once per batch, not per datagram.
+
+## Re-check, 0.8.0
+
+0.8.0 added handlers to the binding (channel audio, and the session's forwarding of
+app-defined spatial messages, channel audio and watched voxel updates) and re-vendored
+CrowdyCPP 0.60.0. Both builds below ran back to back on the CKS builder (the machine above),
+under CPython 3.12.3 and the system's shared OpenSSL 3.0.13 rather than the wheels' static
+3.5.9, so compare them with each other, not with the 0.2.0 tables.
+
+| | 0.7.0 (CrowdyCPP 0.59.0) | 0.8.0 (CrowdyCPP 0.60.0) |
+|---|---|---|
+| 1a. `send_actor_updates`, one batch of 200 | 647.1 ns/entity | 647.2 ns/entity |
+| 1a. `native.send_spatial` x200 | 838.1 ns/entity | 840.1 ns/entity |
+| 2. notifications delivered to Python, three interleaved runs | 1.774, 1.763, 1.765 million/s | 1.774, 1.762, 1.772 million/s |
+| 4. echo round trip, p50 | 74.8 µs | 74.8 µs |
+| 5. game-loop lateness, p99 | 0.3 ms | 0.2 ms |
+
+CrowdyCPP 0.60.0's own `bench_send` section 5 (`sendActorUpdate` x200, Release, same machine
+and OpenSSL) measured 623.9 ns/entity, so one batch costs 1.04x CrowdyCPP's send path per
+entity (1.06x at 0.2.0).

{crowdypy-0.7.0.dev1 → crowdypy-0.9.0.dev1}/docs/compatibility.md

@@ -5,7 +5,7 @@ are in `pyproject.toml` (`[project].version`, `[tool.crowdypy.crowdyjs]`,
 `[tool.crowdypy.crowdycpp]`); `tests/unit/test_release_versions.py` refuses this page when
 its version disagrees.
 
-- CrowdyPy `0.7.0`
+- CrowdyPy `0.9.0`
 - API surface: CrowdyJS (the pinned version and commit in `pyproject.toml`); the generated
   `docs/parity-matrix.md` lists every covered method, every native equivalent and every
   browser exclusion with its reason. The gate is strict: there are no portable gaps, and a
@@ -43,3 +43,12 @@ requirement names one exactly, the same way a caret never matches an npm prerele
   waits for both consents (`LEGAL_ACCEPTANCE_REQUIRED`).
 - `udp.send_ranged_channel_message` needs a replication server that serves message type 32
   (CHANNEL_MESSAGE_RANGED_REQUEST); one that does not delivers nothing.
+- 0.8.0 selects `runtimeGate` on every token mutation (`portal.mint_app_token`,
+  `exchange_code`, `refresh`) and on `game_client_bootstrap`, so it needs the ck-api release
+  after v2.39.0 that serves it; an older API refuses those calls with a GraphQL validation
+  error. The same release serves `playerProfile(s)`, the access suspension and
+  `execRestartType`.
+- Channel audio (message types 35 and 36) and the echo of your own voxel edits need replication
+  server v0.37.0; an older one drops message type 35 and echoes nothing.
+- The wheels link no audio codec (CrowdyCPP's optional libopus wrapper is built OFF): the
+  voice helpers carry an app's codec frames without reading them.

{crowdypy-0.7.0.dev1 → crowdypy-0.9.0.dev1}/docs/e2e-coverage.md

@@ -71,3 +71,10 @@ These CrowdyCPP suites have no CrowdyPy counterpart yet; the reason is in each r
 | `e2e_soak_two_clients`, `e2e_permission_refresh` | long-running; slated for `CROWDY_E2E_SLOW=1` suites |
 | `e2e_host_election`, `e2e_durable_stores`, `e2e_chunk_store_live` | the World Stores' host, save and chunk persistence run over GraphQL timers covered by unit suites against fakes; live coverage needs a dedicated app (chunk write-back closes the wilderness) |
 | `e2e_cross_app`, `e2e_cross_tenant`, `e2e_malicious_input` | platform isolation properties the CrowdyCPP suites already exercise against the same API |
+
+0.8.0's additions (channel audio, the echo of your own voxel edit, `APP_PAUSED`, access
+suspension, player profiles, `exec.restart_type`) have no live suite yet, in CrowdyPy or in
+CrowdyCPP. The unit suites cover them against a fake replication server and a mocked API. From
+0.8.0 every suite mints with `runtimeGate` selected, so run them only against a tier whose
+ck-api is the release after v2.39.0 or later; an older one refuses the mint as a GraphQL
+validation error. Channel audio and the voxel echo need replication server v0.37.0 as well.