crowdypy 0.6.0.dev1__tar.gz → 0.8.0.dev1__tar.gz

{crowdypy-0.6.0.dev1 → crowdypy-0.8.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.6.0.dev1 → crowdypy-0.8.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.6.0.dev1 → crowdypy-0.8.0.dev1}/MIGRATION.md

@@ -3,6 +3,137 @@
 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.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.
+
+- **The input log.** An app with replay logging on has every client input the realtime
+  servers accept recorded. `client.input_log.sessions(app_id, *, first=, after=, filter=)`
+  lists the app's recorded sessions, newest first (`edges`, `pageInfo`, `totalCount`; a
+  session is one game token's inputs), and `client.input_log.messages(app_id, game_token_id,
+  *, first=, after=, filter=)` reads one session's inputs, oldest first. `body` is the client
+  message in base64 without its authentication tail (`decode_base64` gives the bytes), and
+  `sizeBytes` is what stored input logs are billed on. Keep paging while
+  `pageInfo.hasNextPage` is true: a page can be short, or empty, when it reached the server's
+  time or scan limit. Both are game plane (the app-scoped client). A player reads their own
+  sessions, and a holder of `manage_apps` reads every one; without it, listing another
+  user's sessions is `FORBIDDEN` and reading another user's session is `NOT_FOUND`. Both
+  answer `INPUT_LOG_UNAVAILABLE` on a deployment without input logging, and `messages` also
+  answers it, retryable with the same cursor, when the log cannot be read right now.
+- **`replayLoggingEnabled`** is selected on every app read. Turning it on with
+  `client.apps.update` is refused with `INPUT_LOG_FUNDS_NEEDED` unless the org's wallet has a
+  spendable balance or the org is exempt from billing.
+
 ## 0.6.0
 
 CrowdyJS 18.5.0 and CrowdyCPP 0.58.0. Additive.

{crowdypy-0.6.0.dev1 → crowdypy-0.8.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crowdypy
-Version: 0.6.0.dev1
+Version: 0.8.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,14 +51,23 @@ 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.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.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.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
@@ -174,6 +183,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
@@ -201,6 +217,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
@@ -217,6 +274,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.6.0.dev1 → crowdypy-0.8.0.dev1}/README.md

@@ -11,14 +11,23 @@ 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.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.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.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
@@ -134,6 +143,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
@@ -161,6 +177,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
@@ -177,6 +234,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.6.0.dev1 → crowdypy-0.8.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.6.0.dev1 → crowdypy-0.8.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.6.0`
+- CrowdyPy `0.8.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.6.0.dev1 → crowdypy-0.8.0.dev1}/docs/e2e-coverage.md

@@ -18,6 +18,7 @@ Unconfigured, every suite skips, so `pytest` in CI records skips, not live passe
 | `CROWDY_E2E_STUDIO_GRID_ID` | no | a grid in the app that the owner controls (Studio suite) |
 | `CROWDY_E2E_SLOW=1` | no | long-running suites |
 | `CROWDY_E2E_THROWAWAY_OWNER=1` | no | the open-grid suite registers a throwaway owner, org and app (archived afterwards) |
+| `CROWDY_E2E_PROVISIONING_TOKEN` | dev and test | dev and test are staff-only, so a new derived player is refused (`TIER_ACCESS_REQUIRED`) unless `register` carries a provisioning token covering its address. Use the `harness` token (Secrets Manager `infra-cp/<tier>/loadtest/provisioning-token-harness`, `token` key) with `CROWDY_E2E_EMAIL=crowdy-e2e@test.invalid`. Sent on `register` only; other tiers ignore it |
 
 ```bash
 pytest tests/e2e -q
@@ -54,6 +55,7 @@ player once and signs it in for the later suites.
 | 2026-10-01 | dev tier, app `96701660793088` | `crowdypy 0.4.1.dev1` from PyPI (`pip install crowdypy` in a clean Python 3.12; the first version published by trusted publishing) | 8 passed; Studio skipped |
 | 2026-10-01 | dev tier, app `96701660793088`; the open-grid suite in its own throwaway org and app (`CROWDY_E2E_THROWAWAY_OWNER=1`) | `crowdypy 0.5.0.dev1` from PyPI (`pip install crowdypy` in a clean Python 3.12) | 10 passed; Studio skipped |
 | 2026-10-08 | local stack: ck-api at the distance-limited channel branch (off `dev`), two replication servers serving message type 32, the 3-node Citus lab | 0.6.0 (branch) | identity, ranged channel, replication, world and world data suites: 10 passed |
+| 2026-10-09 | dev tier, app `96701660793088`, after replication server v0.35.0 and ck-api v2.38.0 reached dev | `crowdypy 0.6.0.dev1` from PyPI (installed into a clean Python 3.12 with uv) | identity (incl. the terms gate), ranged channel, replication, world and world data suites: 10 passed |
 
 ## Not covered here
 
@@ -69,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.