@dcl/protocol 1.0.0-29286492043.commit-0010e70 → 1.0.0-29287211316.commit-e44c721

package/proto/decentraland/pulse/pulse_server.proto

@@ -0,0 +1,144 @@
+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

@@ -0,0 +1,57 @@
+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 }];
+}

package/proto/decentraland/sdk/components/avatar_shape.proto

@@ -42,3 +42,8 @@ message PBAvatarShape {
   optional bool show_only_wearables = 12; // hides the skin + hair + facial features (default: false)
 }
 
+// Mask for which bones an animation applies to.
+enum AvatarEmoteMask {
+  AEM_FULL_BODY = 0;
+  AEM_UPPER_BODY = 1;
+}

package/proto/decentraland/sdk/components/light_source.proto

@@ -25,4 +25,4 @@ message PBLightSource {
     optional float inner_angle = 9;   // default = 21.8. Inner angle can't be higher than outer angle, otherwise will default to same value. Min value is 0. Max value is 179.
     optional float outer_angle = 10;  // default = 30. Outer angle can't be lower than inner angle, otherwise will inner angle will be set to same value. Max value is 179.
   }
-}
+}

package/proto/decentraland/sdk/components/virtual_camera.proto

@@ -10,7 +10,9 @@ option (common.ecs_component_id) = 1076;
 // an 'instant' transition (like using speed/time = 0)
 // * The lookAtEntity defines to which entity the Camera has to look at constantly (independent from 
 // the holding entity transform).
+// * The fov defines the Field of View of the virtual camera
 message PBVirtualCamera {
   optional common.CameraTransition default_transition = 1;
   optional uint32 look_at_entity = 2;
+  optional float fov = 3; // default: 60
 }

package/protoc-gen-bitwise/generator_csharp.js

@@ -0,0 +1,248 @@
+'use strict'
+
+/**
+ * C# code generator for the protoc-gen-bitwise plugin.
+ *
+ * For every proto message that contains at least one uint32 field annotated
+ * with [(quantized)], this module emits a C# partial class that adds a computed
+ * float property named {FieldName}Quantized. The getter decodes the stored
+ * uint32 to a float; the setter encodes a float back to a uint32. Standard
+ * protobuf handles serialization of the uint32 wire field; this class adds a
+ * typed float accessor on top.
+ *
+ * Only uint32 fields are supported. bit_packed and unannotated fields are
+ * passed through without generating any accessor.
+ *
+ * Port of the original generator_csharp.py — output is intended to be
+ * byte-for-byte identical.
+ */
+
+const { getFieldOptions } = require('./options')
+
+// FieldDescriptorProto type/label constants.
+const TYPE_UINT32 = 13
+const LABEL_REPEATED = 3
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Mirrors Python str.capitalize(): upper-first, lowercase the rest. */
+function capitalize(word) {
+  if (word.length === 0) return ''
+  return word[0].toUpperCase() + word.slice(1).toLowerCase()
+}
+
+/** position_x -> PositionX */
+function snakeToPascal(name) {
+  return name.split('_').map(capitalize).join('')
+}
+
+/** decentraland.kernel.comms.v3 -> Decentraland.Kernel.Comms.V3 */
+function packageToNamespace(pkg) {
+  if (!pkg) return 'Generated'
+  return pkg.split('.').map(capitalize).join('.')
+}
+
+/**
+ * Format a number with C printf %g semantics at `precision` significant digits:
+ * shortest of fixed/scientific, with trailing zeros and a trailing dot removed.
+ * Reproduces Python's `f'{value:.{precision}g}'`.
+ */
+function formatG(value, precision) {
+  if (precision <= 0) precision = 1
+  if (value === 0) return '0'
+  if (!Number.isFinite(value)) return value > 0 ? 'inf' : 'nan'
+
+  const negative = value < 0
+  const v = Math.abs(value)
+
+  // Correctly-rounded scientific form yields the decimal exponent X (handling
+  // carry such as 9.999 -> 1.0e+1).
+  const sci = v.toExponential(precision - 1)
+  const eIdx = sci.indexOf('e')
+  const X = parseInt(sci.slice(eIdx + 1), 10)
+
+  let result
+  if (X >= -4 && X < precision) {
+    // Fixed notation with (precision - 1 - X) fraction digits.
+    const fractionDigits = precision - 1 - X
+    result = v.toFixed(fractionDigits >= 0 ? fractionDigits : 0)
+    if (result.indexOf('.') !== -1) {
+      result = result.replace(/0+$/, '').replace(/\.$/, '')
+    }
+  } else {
+    // Scientific notation; printf prints at least two exponent digits.
+    let mantissa = sci.slice(0, eIdx)
+    if (mantissa.indexOf('.') !== -1) {
+      mantissa = mantissa.replace(/0+$/, '').replace(/\.$/, '')
+    }
+    const expSign = X < 0 ? '-' : '+'
+    let expDigits = String(Math.abs(X))
+    if (expDigits.length < 2) expDigits = '0' + expDigits
+    result = mantissa + 'e' + expSign + expDigits
+  }
+
+  return (negative ? '-' : '') + result
+}
+
+/** Format a value as a C# float literal (e.g. -100.0f). */
+function formatFloat(value) {
+  let text = formatG(value, 8)
+  if (text.indexOf('.') === -1 && text.indexOf('e') === -1 && text.indexOf('E') === -1) {
+    text += '.0'
+  }
+  return text + 'f'
+}
+
+/** Format a quantization step size for a doc comment (e.g. "≈ 0.003"). */
+function formatStep(step) {
+  return '≈ ' + formatG(step, 6)
+}
+
+// ---------------------------------------------------------------------------
+// Per-message code generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a C# partial class for a proto message, or null if it has no
+ * quantized uint32 fields. Returns an array of lines (no trailing newline).
+ */
+function generateMessage(msgProto, indent) {
+  const i = indent || '    '
+  const props = []
+
+  for (const field of msgProto.field) {
+    // Repeated/map fields are not supported.
+    if (field.label === LABEL_REPEATED) continue
+    // Only uint32 fields are candidates for quantized accessors.
+    if (field.type !== TYPE_UINT32) continue
+
+    const { quantized, quantizedPower } = getFieldOptions(field.optionsRaw)
+    const propName = snakeToPascal(field.name)
+
+    let doc, getExpr, setExpr, step, bits
+    if (quantized !== null) {
+      const mn = formatFloat(quantized.min)
+      const mx = formatFloat(quantized.max)
+      bits = quantized.bits
+      // Uniform quantizer — the step is constant across the whole range.
+      step = (quantized.max - quantized.min) / ((1 << bits) - 1)
+      doc = `Range [${mn}, ${mx}], ${bits} bits, step ${formatStep(step)}.`
+      getExpr = `Quantize.Decode(${propName}, ${mn}, ${mx}, ${bits})`
+      setExpr = `Quantize.Encode(value, ${mn}, ${mx}, ${bits})`
+    } else if (quantizedPower !== null) {
+      const mx = formatFloat(quantizedPower.max)
+      const pw = formatFloat(quantizedPower.pow)
+      bits = quantizedPower.bits
+      // Power curve is non-uniform: the finest step sits next to zero (first magnitude code),
+      // the COARSEST at the top of the range. The coarsest step upper-bounds the error for any
+      // value, so that's what the exposed {Name}QuantizedStep const carries (safe as a tolerance).
+      const magSteps = (1 << (bits - 1)) - 1
+      const nearZeroStep = quantizedPower.max * Math.pow(1 / magSteps, quantizedPower.pow)
+      step = quantizedPower.max * (1 - Math.pow((magSteps - 1) / magSteps, quantizedPower.pow))
+      doc =
+        `Range [-${mx}, ${mx}], power ${pw}, ${bits} bits ` +
+        `(sign + ${bits - 1}-bit magnitude), near-zero step ${formatStep(nearZeroStep)}.`
+      getExpr = `Quantize.DecodePower(${propName}, ${mx}, ${pw}, ${bits})`
+      setExpr = `Quantize.EncodePower(value, ${mx}, ${pw}, ${bits})`
+    } else {
+      continue
+    }
+
+    // Highest code the encoder can emit for this field. Both the linear quantizer (top code
+    // `2^bits - 1`) and the power quantizer (`(magnitude << 1) | sign` with an `bits-1`-bit
+    // magnitude, so top code `((2^(bits-1)-1) << 1) | 1 == 2^bits - 1`) share this bound.
+    const maxCode = 2 ** bits - 1
+
+    props.push({ propName, doc, getExpr, setExpr, step, maxCode })
+  }
+
+  if (props.length === 0) return null
+
+  const lines = []
+  lines.push(`public partial class ${msgProto.name}`)
+  lines.push('{')
+
+  // Decode on every get, encode on every set — no backing cache. The raw uint32 property is the
+  // single source of truth, so the float accessor can never disagree with the code on the wire
+  // (get-after-set returns the on-grid value a receiver decodes) and there is no stale-cache
+  // hazard when the raw field is mutated directly. Decode is a multiply-add; only power fields
+  // pay a MathF.Pow.
+  for (const { propName, doc, getExpr, setExpr, step } of props) {
+    lines.push(`${i}/// <summary>Coarsest quantization step of <see cref="${propName}Quantized"/>. Safe as an equality tolerance.</summary>`)
+    lines.push(`${i}public const float ${propName}QuantizedStep = ${formatFloat(step)};`)
+    lines.push(`${i}/// <summary>Float accessor for <see cref="${propName}"/>. ${doc}</summary>`)
+    lines.push(`${i}public float ${propName}Quantized`)
+    lines.push(`${i}{`)
+    lines.push(`${i}${i}get => ${getExpr};`)
+    lines.push(`${i}${i}set => ${propName} = ${setExpr};`)
+    lines.push(`${i}}`)
+    lines.push('')
+  }
+
+  lines.push(`${i}/// <summary>`)
+  lines.push(`${i}///     True when every quantized field holds a wire code within its declared bit width`)
+  lines.push(`${i}///     (<c>0 .. 2^bits-1</c>). The encoder never emits a code above this bound, so a larger`)
+  lines.push(`${i}///     value is a malformed/hostile message: decoding it would land far outside the field's`)
+  lines.push(`${i}///     <c>[min, max]</c> and, since the server relays raw codes verbatim, poison every observer.`)
+  lines.push(`${i}///     Reject before storing or relaying. Pure integer comparison — no decode.`)
+  lines.push(`${i}/// </summary>`)
+  lines.push(`${i}public bool AreQuantizedFieldsInRange() =>`)
+  props.forEach(({ propName, maxCode }, idx) => {
+    const prefix = idx === 0 ? '' : '&& '
+    const suffix = idx === props.length - 1 ? ';' : ''
+    lines.push(`${i}${i}${prefix}${propName} <= ${maxCode}u${suffix}`)
+  })
+
+  lines.push('}')
+  return lines
+}
+
+// ---------------------------------------------------------------------------
+// Per-file code generation (public entry point)
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a C# source file for a FileDescriptorProto, or null if the file
+ * contains no quantized uint32 fields.
+ * @returns {{name: string, content: string} | null}
+ */
+function generateCsharp(fileProto) {
+  const namespace = packageToNamespace(fileProto.package)
+
+  const protoFile = fileProto.name.split('/').pop()
+  const stem = snakeToPascal(protoFile.replace('.proto', ''))
+  const outName = `${stem}.Bitwise.cs`
+
+  const header = [
+    '// <auto-generated>',
+    '//   Generated by protoc-gen-bitwise. DO NOT EDIT.',
+    `//   Source: ${fileProto.name}`,
+    '// </auto-generated>',
+    '',
+    'using Decentraland.Networking.Bitwise;',
+    '',
+    `namespace ${namespace}`,
+    '{',
+  ]
+  const footer = ['', `} // namespace ${namespace}`]
+
+  const body = []
+  for (const msg of fileProto.messageType) {
+    const msgLines = generateMessage(msg)
+    if (msgLines === null) continue
+    // Indent each line by 4 spaces (inside the namespace block).
+    for (const line of msgLines) {
+      body.push(line ? '    ' + line : '')
+    }
+    body.push('')
+  }
+
+  if (body.length === 0) return null
+
+  const content = header.concat(body, footer).join('\n') + '\n'
+  return { name: outName, content }
+}
+
+module.exports = { generateCsharp }

package/protoc-gen-bitwise/options.js

@@ -0,0 +1,139 @@
+'use strict'
+
+/**
+ * Parser for the custom bitwise field options defined in options.proto.
+ *
+ * The descriptor decoder hands us the raw serialized FieldOptions bytes (it
+ * declares `options` as opaque bytes). We walk those bytes looking for the
+ * custom extension field numbers — protobuf preserves unknown/unregistered
+ * extension bytes, so they are always present even though no runtime here knows
+ * the extension schema. This mirrors the original options_pb2.py.
+ *
+ * Wire format: tag = (field_number << 3) | wire_type
+ *   wire_type 0 = varint, 1 = 64-bit, 2 = length-delimited, 5 = 32-bit
+ */
+
+const { readVarint, skipField } = require('./wire')
+
+// Extension field numbers as defined in options.proto.
+const QUANTIZED_FIELD_NUMBER = 50001
+const BIT_PACKED_FIELD_NUMBER = 50002
+const QUANTIZED_POWER_FIELD_NUMBER = 50003
+
+/** Parse a serialized QuantizedFloatOptions message: { min, max, bits }. */
+function parseQuantized(data) {
+  const opts = { min: 0.0, max: 0.0, bits: 0 }
+  let pos = 0
+  while (pos < data.length) {
+    let tag
+    ;[tag, pos] = readVarint(data, pos)
+    const fieldNum = tag >>> 3
+    const wireType = tag & 0x7
+    if (fieldNum === 1 && wireType === 5) {
+      // min (float)
+      opts.min = data.readFloatLE(pos)
+      pos += 4
+    } else if (fieldNum === 2 && wireType === 5) {
+      // max (float)
+      opts.max = data.readFloatLE(pos)
+      pos += 4
+    } else if (fieldNum === 3 && wireType === 0) {
+      // bits (uint32)
+      ;[opts.bits, pos] = readVarint(data, pos)
+    } else {
+      pos = skipField(data, pos, wireType)
+    }
+  }
+  return opts
+}
+
+/** Parse a serialized QuantizedPowerFloatOptions message: { max, pow, bits }. */
+function parseQuantizedPower(data) {
+  const opts = { max: 0.0, pow: 0.0, bits: 0 }
+  let pos = 0
+  while (pos < data.length) {
+    let tag
+    ;[tag, pos] = readVarint(data, pos)
+    const fieldNum = tag >>> 3
+    const wireType = tag & 0x7
+    if (fieldNum === 1 && wireType === 5) {
+      // max (float)
+      opts.max = data.readFloatLE(pos)
+      pos += 4
+    } else if (fieldNum === 2 && wireType === 5) {
+      // pow (float)
+      opts.pow = data.readFloatLE(pos)
+      pos += 4
+    } else if (fieldNum === 3 && wireType === 0) {
+      // bits (uint32)
+      ;[opts.bits, pos] = readVarint(data, pos)
+    } else {
+      pos = skipField(data, pos, wireType)
+    }
+  }
+  return opts
+}
+
+/** Parse a serialized BitPackedOptions message: { bits }. */
+function parseBitPacked(data) {
+  const opts = { bits: 0 }
+  let pos = 0
+  while (pos < data.length) {
+    let tag
+    ;[tag, pos] = readVarint(data, pos)
+    const fieldNum = tag >>> 3
+    const wireType = tag & 0x7
+    if (fieldNum === 1 && wireType === 0) {
+      // bits (uint32)
+      ;[opts.bits, pos] = readVarint(data, pos)
+    } else {
+      pos = skipField(data, pos, wireType)
+    }
+  }
+  return opts
+}
+
+/**
+ * Extract custom bitwise options from raw FieldOptions bytes.
+ *
+ * @param {Buffer|null} optionsRaw serialized FieldOptions, or null when unset.
+ * @returns {{quantized: object|null, bitPacked: object|null, quantizedPower: object|null}}
+ */
+function getFieldOptions(optionsRaw) {
+  if (!optionsRaw || optionsRaw.length === 0) {
+    return { quantized: null, bitPacked: null, quantizedPower: null }
+  }
+
+  let quantized = null
+  let bitPacked = null
+  let quantizedPower = null
+  let pos = 0
+
+  while (pos < optionsRaw.length) {
+    let tag
+    ;[tag, pos] = readVarint(optionsRaw, pos)
+    const fieldNum = tag >>> 3
+    const wireType = tag & 0x7
+
+    if (wireType === 2) {
+      let len
+      ;[len, pos] = readVarint(optionsRaw, pos)
+      const valueBytes = optionsRaw.subarray(pos, pos + len)
+      pos += len
+      if (fieldNum === QUANTIZED_FIELD_NUMBER) {
+        quantized = parseQuantized(valueBytes)
+      } else if (fieldNum === BIT_PACKED_FIELD_NUMBER) {
+        bitPacked = parseBitPacked(valueBytes)
+      } else if (fieldNum === QUANTIZED_POWER_FIELD_NUMBER) {
+        quantizedPower = parseQuantizedPower(valueBytes)
+      }
+      // else: unknown length-delimited field — already consumed.
+    } else {
+      pos = skipField(optionsRaw, pos, wireType)
+    }
+  }
+
+  return { quantized, bitPacked, quantizedPower }
+}
+
+module.exports = { getFieldOptions }