@dcl/protocol 1.0.0-29276634715.commit-82dbfb0 → 1.0.0-29286492043.commit-0010e70

package/proto/decentraland/common/quantization_example.proto

@@ -1,164 +0,0 @@
-syntax = "proto3";
-
-package decentraland.common;
-
-import "decentraland/common/options.proto";
-
-// High-frequency player state messages sent on Channel 1 (unreliable sequenced).
-//
-// Every message below uses the protoc-gen-bitwise annotations to minimise
-// wire size.  Wire costs are listed per-message so the trade-offs are clear.
-//
-// Annotation cheat-sheet:
-//   [(decentraland.common.quantized)  = { min: F, max: F, bits: N }]
-//       → stores a float as a uint32 quantized to N bits over [min, max].
-//       → protobuf encodes the uint32 as a varint: values ≤ 2^14-1 cost 2 bytes,
-//         values ≤ 2^21-1 cost 3 bytes; the generated partial class adds a
-//         float {Name}Quantized accessor that encodes/decodes transparently.
-//   [(decentraland.common.quantized_power) = { max: F, pow: F, bits: N }]
-//       → stores a signed float over [-max, max] as an (N-1)-bit linear unorm
-//         magnitude (high bits) plus a sign (LSB), reconstructed as sign·max·u^pow.
-//         Zero is exact, and pow>1 buys fine resolution near zero at the cost of
-//         coarse near ±max. Putting the sign in the LSB keeps a small |value| of
-//         either direction in one varint byte. Same generated float {Name}Quantized
-//         accessor as the linear option.
-//   [(decentraland.common.bit_packed) = { bits: N }]
-//       → documents that this uint32 uses at most N bits; protobuf encodes it
-//         as a varint (same savings, no generated accessor needed).
-//   (no annotation)
-//       → standard protobuf encoding (bool/double/etc. at natural width).
-//
-// Varint byte costs at worst-case (all bits set):
-//   ≤ 7 bits  → 1 byte   (max 127)
-//   ≤ 14 bits → 2 bytes  (max 16 383)
-//   ≤ 21 bits → 3 bytes  (max 2 097 151)
-// Proto3 omits fields equal to their default value (0), so average cost is lower.
-
-// ---------------------------------------------------------------------------
-// PositionDelta — Δ position relative to last acknowledged full snapshot.
-//
-// Sent every client tick (~10 Hz) on Channel 1.
-//
-//  Field       | Type   | Range          | Q bits | Wire worst-case
-//  ------------|--------|----------------|--------|-----------------------
-//  dx          | uint32 | [-100, 100]    |   16   | tag 1B + varint 3B = 4B
-//  dy          | uint32 | [-100, 100]    |   16   | tag 1B + varint 3B = 4B
-//  dz          | uint32 | [-100, 100]    |   16   | tag 1B + varint 3B = 4B
-//  entity_id   | uint32 | [0, 1 048 575] |   20   | tag 1B + varint 3B = 4B
-//  sequence    | uint32 | [0,     4 095] |   12   | tag 1B + varint 2B = 3B
-//  ---------------------------------------------------------------------------
-//  Worst-case: 19 B  (vs. 20 B raw: 3×float + 2×uint32)
-//  Step: dx/dy/dz ≈ 0.003 units
-// ---------------------------------------------------------------------------
-message PositionDelta {
-  uint32 dx        = 1 [(decentraland.common.quantized)  = { min: -100.0, max: 100.0, bits: 16 }];
-  uint32 dy        = 2 [(decentraland.common.quantized)  = { min: -100.0, max: 100.0, bits: 16 }];
-  uint32 dz        = 3 [(decentraland.common.quantized)  = { min: -100.0, max: 100.0, bits: 16 }];
-  uint32 entity_id = 4 [(decentraland.common.bit_packed) = { bits: 20 }];
-  uint32 sequence  = 5 [(decentraland.common.bit_packed) = { bits: 12 }];
-}
-
-// ---------------------------------------------------------------------------
-// PlayerInput — client input snapshot for server-side reconciliation.
-//
-// Sent every client frame (~30 Hz) on Channel 1.
-//
-//  Field       | Type   | Range          | Q bits | Wire worst-case
-//  ------------|--------|----------------|--------|-----------------------
-//  move_x      | uint32 | [-1, 1]        |    8   | tag 1B + varint 2B = 3B
-//  move_z      | uint32 | [-1, 1]        |    8   | tag 1B + varint 2B = 3B
-//  yaw         | uint32 | [-180, 180]    |   12   | tag 1B + varint 2B = 3B
-//  buttons     | uint32 | bitmask        |    8   | tag 1B + varint 2B = 3B
-//  sequence    | uint32 | [0, 4 095]     |   12   | tag 1B + varint 2B = 3B
-//  ---------------------------------------------------------------------------
-//  Worst-case: 15 B  (vs. 20 B raw: 3×float + 2×uint32)
-//  Step: move_x/move_z ≈ 0.008; yaw ≈ 0.088°
-// ---------------------------------------------------------------------------
-message PlayerInput {
-  // Normalised joystick axes in [-1, 1].
-  uint32 move_x   = 1 [(decentraland.common.quantized)  = { min: -1.0,   max: 1.0,   bits:  8 }];
-  uint32 move_z   = 2 [(decentraland.common.quantized)  = { min: -1.0,   max: 1.0,   bits:  8 }];
-
-  // Horizontal look direction in degrees.
-  uint32 yaw      = 3 [(decentraland.common.quantized)  = { min: -180.0, max: 180.0, bits: 12 }];
-
-  // Bitmask of active buttons (see ButtonFlags below).
-  uint32 buttons  = 4 [(decentraland.common.bit_packed) = { bits:  8 }];
-
-  // Rolling input sequence number used by the server for reconciliation.
-  uint32 sequence = 5 [(decentraland.common.bit_packed) = { bits: 12 }];
-}
-
-// ---------------------------------------------------------------------------
-// VelocityState — per-axis velocity, demonstrating the power-law quantizer.
-//
-// Velocity needs an exact zero (a stopped avatar must read 0, not a quantization
-// residual, or it drifts) and fine resolution at locomotion speeds, but only
-// coarse resolution near the ±50 m/s extremes. The linear quantizer can give
-// none of these from 8 bits: its codes straddle zero (±0.196) and spend uniform
-// resolution on speeds that never occur. quantized_power solves all three.
-//
-//  Field  | Type   | Range      | pow | bits | Wire worst-case
-//  -------|--------|------------|-----|------|-----------------------
-//  vx     | uint32 | [-50, 50]  |  2  |  8   | tag 1B + varint 1–2B = 2–3B
-//  vy     | uint32 | [-50, 50]  |  2  |  8   | tag 1B + varint 1–2B = 2–3B
-//  vz     | uint32 | [-50, 50]  |  2  |  8   | tag 1B + varint 1–2B = 2–3B
-//  ---------------------------------------------------------------------------
-//  Step: ≈ 0.003 m/s near zero, ≈ 0.78 m/s near ±50 (vs. 0.392 uniform linear)
-//  Wire: sign in the LSB, so |v| ≲ 12.5 m/s (magnitude code ≤ 63) costs a single
-//        varint byte regardless of direction; only faster axes spill to 2 bytes.
-// ---------------------------------------------------------------------------
-message VelocityState {
-  uint32 vx = 1 [(decentraland.common.quantized_power) = { max: 50.0, pow: 2.0, bits: 8 }];
-  uint32 vy = 2 [(decentraland.common.quantized_power) = { max: 50.0, pow: 2.0, bits: 8 }];
-  uint32 vz = 3 [(decentraland.common.quantized_power) = { max: 50.0, pow: 2.0, bits: 8 }];
-}
-
-// Bitmask values for PlayerInput.buttons.
-enum ButtonFlags {
-  BF_NONE      = 0;
-  BF_JUMP      = 1;   // bit 0
-  BF_SPRINT    = 2;   // bit 1
-  BF_INTERACT  = 4;   // bit 2
-  BF_EMOTE     = 8;   // bit 3
-  BF_CROUCH    = 16;  // bit 4
-  // bits 5-7 reserved
-}
-
-// ---------------------------------------------------------------------------
-// AvatarStateSnapshot — full authoritative state, sent on Channel 0 (reliable)
-// or on resync requests.  Demonstrates wider ranges and mixed encodings.
-//
-//  Field            | Type   | Range            | Q bits | Wire worst-case
-//  -----------------|--------|------------------|--------|-----------------------
-//  x                | uint32 | [-4096, 4096]    |   16   | tag 1B + varint 3B = 4B
-//  y                | uint32 | [-256,   256]    |   14   | tag 1B + varint 2B = 3B
-//  z                | uint32 | [-4096, 4096]    |   16   | tag 1B + varint 3B = 4B
-//  pitch            | uint32 | [-90,    90]     |   10   | tag 1B + varint 2B = 3B
-//  yaw              | uint32 | [-180,  180]     |   12   | tag 1B + varint 2B = 3B
-//  entity_id        | uint32 | [0, 1 048 575]   |   20   | tag 1B + varint 3B = 4B
-//  animation_state  | uint32 | [0,       63]    |    6   | tag 1B + varint 1B = 2B
-//  is_grounded      | bool   | —                |   —    | tag 1B + varint 1B = 2B
-//  timestamp        | double | —                |   —    | tag 1B + fixed64  8B = 9B
-//  ---------------------------------------------------------------------------
-//  Worst-case: 34 B  (vs. 45 B raw: 5×float + 2×uint32 + bool + double)
-//  Step: x/z ≈ 0.125 units; y ≈ 0.031 units; pitch ≈ 0.176°; yaw ≈ 0.088°
-// ---------------------------------------------------------------------------
-message AvatarStateSnapshot {
-  // World-space position.
-  uint32 x               = 1 [(decentraland.common.quantized)  = { min: -4096.0, max: 4096.0, bits: 16 }];
-  uint32 y               = 2 [(decentraland.common.quantized)  = { min:  -256.0, max:  256.0, bits: 14 }];
-  uint32 z               = 3 [(decentraland.common.quantized)  = { min: -4096.0, max: 4096.0, bits: 16 }];
-
-  // View angles.
-  uint32 pitch           = 4 [(decentraland.common.quantized)  = { min:  -90.0,  max:   90.0, bits: 10 }];
-  uint32 yaw             = 5 [(decentraland.common.quantized)  = { min: -180.0,  max:  180.0, bits: 12 }];
-
-  // Identity and animation state.
-  uint32 entity_id       = 6 [(decentraland.common.bit_packed) = { bits: 20 }];
-  uint32 animation_state = 7 [(decentraland.common.bit_packed) = { bits:  6 }];
-
-  // Un-annotated fields — encoded at their natural width.
-  bool   is_grounded     = 8;
-  double timestamp       = 9;   // server epoch milliseconds
-}

package/proto/decentraland/pulse/pulse_client.proto

@@ -1,79 +0,0 @@
-syntax = "proto3";
-
-package decentraland.pulse;
-
-import "decentraland/pulse/pulse_shared.proto";
-import "decentraland/common/options.proto";
-
-message HandshakeRequest {
-	bytes auth_chain = 1;
-  int32 profile_version = 2;
-  optional PlayerInitialState initial_state = 3;
-}
-
-// Describes the initial state of the player if (re-)connected in the middle of the session
-message PlayerInitialState {
-  PlayerState state = 1;
-  optional string emote_id = 2;
-  optional uint32 emote_duration_ms = 3;
-  // Indicates how many milliseconds ago the emote was started
-  optional uint32 emote_start_offset_ms = 4;
-  // Non-empty realm identifier. Rejected if empty.
-  string realm = 5;
-  optional int32 emote_mask = 6;
-}
-
-// Similarly to the LiveKit pipeline, a peer announces the version of its profile but
-// it only does it when it's changed as it's sent reliably and stored on the server for other peers
-message ProfileVersionAnnouncement {
-  int32 version = 1;
-}
-
-// Since the server doesn't simulate the scenes state, it trusts the values from the client
-message PlayerStateInput {
-  PlayerState state = 1;
-}
-
-// Client sends resync request if it has a gap in the known sequences and, thus, can't apply a delta.
-// It's sent reliably to prevent further desynchronization
-message ResyncRequest {
-  uint32 subject_id = 1;
-  // highest seq the client actually has for this subject
-  uint32 known_seq = 2;
-}
-
-// Client → Server. Client requests to start an emote.
-message EmoteStart {
-  string emote_id = 1;
-  optional uint32 duration_ms = 2;
-  PlayerState player_state = 3;
-  optional int32 mask = 4;
-}
-
-// Client → Server. Client requests to stop a looping emote.
-// One-shot emotes are terminated by the server timer.
-message EmoteStop {
-}
-
-// Client → Server. Also announces the peer's realm; peers in different realms never see each
-// other. Must be the first gameplay message after handshake. Same-realm re-teleports are valid.
-message TeleportRequest {
-  int32 parcel_index = 1;
-  uint32 position_x = 2 [(decentraland.common.quantized) = { min: 0, max: 16, bits: 8 }];
-  uint32 position_y = 3 [(decentraland.common.quantized) = { min: 0, max: 200, bits: 13 }];
-  uint32 position_z = 4 [(decentraland.common.quantized) = { min: 0, max: 16, bits: 8 }];
-  // Non-empty realm identifier. Rejected if empty.
-  string realm = 5;
-}
-
-message ClientMessage {
-  oneof message {
-    HandshakeRequest handshake = 1;
-    PlayerStateInput input = 2;
-    ResyncRequest resync = 3;
-    ProfileVersionAnnouncement profile_announcement = 4;
-    EmoteStart emote_start = 5;
-    EmoteStop emote_stop = 6;
-    TeleportRequest teleport = 7;
-  }
-}

package/proto/decentraland/pulse/pulse_server.proto

@@ -1,144 +0,0 @@
-syntax = "proto3";
-
-package decentraland.pulse;
-
-import "decentraland/common/options.proto";
-import "decentraland/pulse/pulse_shared.proto";
-
-message HandshakeResponse {
-  bool success = 1;
-  optional string error = 2;
-}
-
-message PlayerProfileVersionsAnnounced {
-  uint32 subject_id = 1;
-  int32 version = 2;
-}
-
-message PlayerStateDeltaTier0 {
-  uint32 subject_id = 1;
-
-  // Between two consecutive server simulation ticks, the subject may have sent multiple inputs, each incrementing Seq by 1. So
-  // the delta's NewSeq will naturally jump by more than 1 compared to the previous delta — even with zero packet loss.
-  // Without the "BaselineSeq" the client has no way to detect the package loss
-  uint32 baseline_seq = 2;
-  uint32 new_seq = 3;
-  uint32 server_tick = 4;
-
-  // While the player doesn't cross the parcel, this field is omitted from diff
-  optional int32 parcel_index = 5;
-
-  // X position inside the parcel
-  optional uint32 position_x = 6 [(decentraland.common.quantized) = { min:  0,  max:   16, bits: 8 }];
-
-  // Y position
-  optional uint32 position_y = 7 [(decentraland.common.quantized) = { min:  0,  max:   200, bits: 13 }];
-
-  // Z position inside the parcel
-  optional uint32 position_z = 8 [(decentraland.common.quantized) = { min:  0,  max:   16, bits: 8 }];
-
-  // Power-law quantized: a sign bit + 7-bit magnitude curve over [-50, 50]. Zero is exactly
-  // representable (a stopped peer reports an exact 0 instead of the linear quantizer's ±0.196
-  // residual that drove foreign-avatar drift), and pow=2 concentrates resolution at the low speeds
-  // where avatars actually move, leaving only the visually-irrelevant extremes coarse.
-  optional uint32 velocity_x = 9 [(decentraland.common.quantized_power) = { max: 50, pow: 2, bits: 8 }];
-  optional uint32 velocity_y = 10 [(decentraland.common.quantized_power) = { max: 50, pow: 2, bits: 8 }];
-  optional uint32 velocity_z = 11 [(decentraland.common.quantized_power) = { max: 50, pow: 2, bits: 8 }];
-
-  optional uint32 rotation_y = 12 [(decentraland.common.quantized) = { min:  0,  max:   360.0, bits: 7 }];
-  optional uint32 movement_blend = 13 [(decentraland.common.quantized) = { min:  0,  max:   3, bits: 5 }];
-  optional uint32 slide_blend = 14 [(decentraland.common.quantized) = { min:  0,  max:   1, bits: 4 }];
-  optional uint32 head_yaw = 15 [(decentraland.common.quantized) = { min:  0,  max:   360.0, bits: 7 }];
-  optional uint32 head_pitch = 16 [(decentraland.common.quantized) = { min:  0,  max:   360.0, bits: 7 }];
-
-  optional uint32 state_flags = 17;
-  optional GlideState glide_state = 18;
-
-  optional int32 jump_count = 19;
-
-  // Absolute world hit position the player is pointing at.
-  // Only meaningful when POINTING_AT is set in `state_flags`.
-  //
-  // X/Z use 17 bits over the world span (~±3000m, covers GenesisCity + border +
-  // raycast cutoff) which yields ~0.046m steps — at least as fine as the player's
-  // own parcel_index + position_x/z combined precision (0.0625m), so no separate
-  // parcel index is needed for point-at.
-  //
-  // Y uses 7 bits over the player altitude range (matches position_y), step ~1.6m.
-  // Point At is not supposed to change frequently so the wire overhead should be minimal
-  optional uint32 point_at_x = 20 [(decentraland.common.quantized) = { min: -3000.0, max: 3000.0, bits: 17 }];
-  optional uint32 point_at_y = 21 [(decentraland.common.quantized) = { min:     0.0, max:  200.0, bits:  7 }];
-  optional uint32 point_at_z = 22 [(decentraland.common.quantized) = { min: -3000.0, max: 3000.0, bits: 17 }];
-}
-
-// Full State is sent to the client when it is out of sync, and can't recover with a diff only
-message PlayerStateFull {
-  uint32 subject_id = 1;
-  uint32 sequence = 2;
-  uint32 server_tick = 3;
-  PlayerState state = 4;
-}
-
-// Notification to the client, that a peer has joined, it can mean connection or entering the area of interest, it's up to the server to decide
-message PlayerJoined {
-  string user_id = 1;
-  int32 profile_version = 2;
-  PlayerStateFull state = 3;
-  string realm = 4;
-}
-
-// Notification to the client, that a peer has left, it can mean disconnection or leaving the area of interest
-message PlayerLeft {
-  uint32 subject_id = 1;
-}
-
-enum EmoteStopReason {
-  COMPLETED = 0;  // one-shot timer expired on the server
-  CANCELLED = 1;  // client sent EmoteStop (looping emotes)
-}
-
-// Server → All Observers
-// Full player state is piggybacked to ensure the emote is played in the right place.
-// Observers use server_tick to scrub animation forward by transit latency.
-message EmoteStarted {
-  uint32 subject_id = 1;
-  uint32 sequence = 2;
-  uint32 server_tick = 3;
-  string emote_id = 4;
-  PlayerState player_state = 5;
-  optional int32 mask = 6;
-}
-
-// Server → All Observers
-// Client resumes MovementInput only after receiving this.
-// Carries full PlayerState so the client can snap to the correct position on resume.
-message EmoteStopped {
-  uint32 subject_id = 1;
-  uint32 server_tick = 2;
-  EmoteStopReason reason = 3;
-  uint32 sequence = 4;
-  PlayerState player_state = 5;
-}
-
-// Server → All Observers
-message TeleportPerformed {
-  uint32 subject_id = 1;
-  uint32 sequence = 2;
-  uint32 server_tick = 3;
-  PlayerState state = 4;
-  string realm = 5;
-}
-
-message ServerMessage {
-  oneof message {
-      HandshakeResponse handshake = 1;
-      PlayerStateFull player_state_full = 2;
-      PlayerStateDeltaTier0 player_state_delta = 3;
-      PlayerJoined player_joined = 4;
-      PlayerLeft player_left = 5;
-      PlayerProfileVersionsAnnounced player_profile_version_announced = 6;
-      EmoteStarted emote_started = 7;
-      EmoteStopped emote_stopped = 8;
-      TeleportPerformed teleported = 9;
-  }
-}

package/proto/decentraland/pulse/pulse_shared.proto

@@ -1,57 +0,0 @@
-syntax = "proto3";
-
-package decentraland.pulse;
-
-import "decentraland/common/options.proto";
-
-enum PlayerAnimationFlags {
-  NONE = 0;
-  GROUNDED = 1;
-  LONG_JUMP = 2;
-  LONG_FALL = 4;
-  FALLING = 8;
-  STUNNED = 16;
-  HEAD_YAW = 32;
-  HEAD_PITCH = 64;
-  POINTING_AT = 128;
-}
-
-enum GlideState {
-  PROP_CLOSED = 0;
-  OPENING_PROP = 1;
-  GLIDING = 2;
-  CLOSING_PROP = 3;
-}
-
-// Quantized identically to PlayerStateDeltaTier0 so a full state and a stream of deltas land on the same grid.
-message PlayerState {
-  int32 parcel_index = 1;
-
-  // Position inside the parcel (X/Z) and world altitude (Y).
-  uint32 position_x = 2 [(decentraland.common.quantized) = { min: 0, max: 16, bits: 8 }];
-  uint32 position_y = 3 [(decentraland.common.quantized) = { min: 0, max: 200, bits: 13 }];
-  uint32 position_z = 4 [(decentraland.common.quantized) = { min: 0, max: 16, bits: 8 }];
-
-  uint32 velocity_x = 5 [(decentraland.common.quantized_power) = { max: 50, pow: 2, bits: 8 }];
-  uint32 velocity_y = 6 [(decentraland.common.quantized_power) = { max: 50, pow: 2, bits: 8 }];
-  uint32 velocity_z = 7 [(decentraland.common.quantized_power) = { max: 50, pow: 2, bits: 8 }];
-
-  uint32 rotation_y = 8 [(decentraland.common.quantized) = { min: 0, max: 360.0, bits: 7 }];
-
-  uint32 movement_blend = 9 [(decentraland.common.quantized) = { min: 0, max: 3, bits: 5 }];
-  uint32 slide_blend = 10 [(decentraland.common.quantized) = { min: 0, max: 1, bits: 4 }];
-
-  optional uint32 head_yaw = 11 [(decentraland.common.quantized) = { min: 0, max: 360.0, bits: 7 }];
-  optional uint32 head_pitch = 12 [(decentraland.common.quantized) = { min: 0, max: 360.0, bits: 7 }];
-
-  uint32 state_flags = 13;
-  GlideState glide_state = 14;
-
-  int32 jump_count = 15;
-
-  // Absolute world hit position the player is pointing at.
-  // Only meaningful when POINTING_AT is set in `state_flags`.
-  optional uint32 point_at_x = 16 [(decentraland.common.quantized) = { min: -3000.0, max: 3000.0, bits: 17 }];
-  optional uint32 point_at_y = 17 [(decentraland.common.quantized) = { min:     0.0, max:  200.0, bits:  7 }];
-  optional uint32 point_at_z = 18 [(decentraland.common.quantized) = { min: -3000.0, max: 3000.0, bits: 17 }];
-}