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

package/README.md

@@ -67,3 +67,220 @@ In this case, there is no problem with when each PR is merged. It's recommendabl
 ## Comms
 
 TODO
+
+---
+
+# Bitwise Serialization Plugin (`protoc-gen-bitwise`)
+
+A custom protoc plugin that generates C# partial classes with typed float
+accessors for quantized `uint32` fields in high-frequency MMO networking
+messages (position deltas, player input, etc.).  It runs alongside
+`--csharp_out` in the same protoc invocation; the two output files coexist
+via C# `partial class`.
+
+## How it works
+
+Protobuf encodes `uint32` values as varints, which are already compact for
+small values: a value up to 2¹⁴−1 costs 2 bytes, up to 2²¹−1 costs 3 bytes.
+Rather than a separate binary packing layer, the plugin leverages this:
+
+1. Declare quantized fields as `uint32` in the `.proto` schema and annotate
+   them with `[(decentraland.common.quantized)]` to specify the float range
+   and bit resolution.
+2. `--csharp_out` generates the standard protobuf class with the raw `uint32`
+   property (e.g. `PositionX`).
+3. `--bitwise_out` (this plugin) generates a `partial class` extension with a
+   computed float accessor (e.g. `PositionXQuantized`) that encodes/decodes
+   transparently via `Quantize.Encode` / `Quantize.Decode` on every access —
+   the raw `uint32` property remains the single source of truth (no cache to
+   go stale when the raw field is mutated directly).
+
+The wire representation is a standard protobuf message — any protobuf-capable
+client can read it without knowledge of the plugin.
+
+## Prerequisites
+
+| Requirement | Version |
+|---|---|
+| Node.js | 16+ |
+| `protoc` | 3.19+ |
+
+The plugin is a dependency-free Node script — no `npm install` or extra
+packages are required to run it.
+
+## Step 1 — Annotate your `.proto` file
+
+Declare quantized fields as `uint32` and import `options.proto`:
+
+```protobuf
+syntax = "proto3";
+
+import "decentraland/common/options.proto";
+
+package decentraland.kernel.comms.v3;
+
+message PositionDelta {
+  // Float range [-100, 100] quantized to 16 bits ≈ 0.003-unit precision.
+  // Stored as uint32 on the wire; protobuf encodes it as a 3-byte varint.
+  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 }];
+
+  // Unannotated uint32: protobuf varint encodes small values compactly by default.
+  uint32 entity_id = 4 [(decentraland.common.bit_packed) = { bits: 20 }];
+}
+```
+
+### Annotation reference
+
+| Annotation | Target type | Parameters | Effect |
+|---|---|---|---|
+| `[(decentraland.common.quantized)]` | `uint32` | `min`, `max`, `bits` | Plugin emits a `float {Name}Quantized` accessor and a `{Name}QuantizedStep` const |
+| `[(decentraland.common.quantized_power)]` | `uint32` | `max`, `pow`, `bits` | Power-law quantizer over `[-max, max]`: `(bits-1)`-bit magnitude (high bits) + sign (LSB), decoded as `sign·max·u^pow`. Exact zero; `pow>1` gives fine resolution near zero, coarse near `±max`; sign in the LSB keeps small magnitudes one varint byte. `float {Name}Quantized` accessor (`Quantize.EncodePower`/`DecodePower`) |
+| `[(decentraland.common.bit_packed)]` | `uint32` | `bits` | Documents the value range; protobuf handles varint compaction automatically |
+
+### Wire cost at worst-case (all bits set)
+
+| Quantization bits | Max value | Varint bytes | Tag (field ≤ 15) | Total per field |
+|---|---|---|---|---|
+| 8 | 255 | 2 | 1 | 3 B |
+| 12 | 4 095 | 2 | 1 | 3 B |
+| 14 | 16 383 | 2 | 1 | 3 B |
+| 16 | 65 535 | 3 | 1 | 4 B |
+| 20 | 1 048 575 | 3 | 1 | 4 B |
+
+Proto3 omits fields equal to their default value (0), so average cost is lower.
+
+## Step 2 — Run protoc
+
+```bash
+protoc \
+  --proto_path=proto \
+  --proto_path=/path/to/google/protobuf/include \
+  --csharp_out=generated/cs \
+  --plugin=protoc-gen-bitwise=protoc-gen-bitwise/plugin.js \
+  --bitwise_out=generated/cs \
+  proto/decentraland/kernel/comms/v3/comms.proto
+```
+
+> `plugin.js` carries a `#!/usr/bin/env node` shebang. On Windows, protoc
+> cannot exec a `.js` directly, so point `--plugin` at a small `.cmd` wrapper
+> that runs `node plugin.js`; on unix an equivalent shell script is used. Both
+> consumer repos (Pulse, unity-explorer) generate this wrapper automatically.
+
+The plugin emits one `*.Bitwise.cs` file (PascalCase, flat in the output
+directory) for each `.proto` file that contains at least one `[(quantized)]`
+field.
+
+## Step 3 — Copy the runtime
+
+Copy `Quantize.cs` into your project:
+
+```
+Assets/
+└── Scripts/
+    └── Networking/
+        └── Bitwise/
+            └── Quantize.cs   ← protoc-gen-bitwise/runtime/cs/Quantize.cs
+```
+
+`Quantize.cs` lives in the `Decentraland.Networking.Bitwise` namespace and
+provides the static encode/decode methods used by the generated accessors:
+
+```csharp
+public static class Quantize
+{
+    public static uint  Encode(float value, float min, float max, int bits);
+    public static float Decode(uint encoded, float min, float max, int bits);
+    public static uint  EncodePower(float value, float max, float pow, int bits);
+    public static float DecodePower(uint encoded, float max, float pow, int bits);
+}
+```
+
+## Step 4 — Use the generated code
+
+The plugin emits a `partial class` that adds float accessors on top of the
+standard protobuf-generated `uint32` properties:
+
+```csharp
+using Decentraland.Kernel.Comms.V3;
+
+// --- Build and send ---
+var delta = new PositionDelta();
+delta.DxQuantized = 3.14f;   // encodes to uint32, stored in delta.Dx
+delta.DyQuantized = 0f;
+delta.DzQuantized = -7.5f;
+delta.EntityId    = 42u;
+
+byte[] bytes = delta.ToByteArray();   // standard protobuf serialization
+SendOnChannel1(bytes);
+
+// --- Receive and read ---
+var received = PositionDelta.Parser.ParseFrom(receivedBytes);
+if (!received.AreQuantizedFieldsInRange()) return;   // reject malformed/hostile codes
+float x = received.DxQuantized;   // decoded from the stored uint32 on each access
+float y = received.DyQuantized;
+float z = received.DzQuantized;
+```
+
+## Generated file example
+
+For the `comms.proto` file above the plugin emits `Comms.Bitwise.cs` (one file
+per `.proto`, named after the proto file). Each quantized field gets a
+`{Name}QuantizedStep` const and a float accessor; each message gets an
+`AreQuantizedFieldsInRange()` guard for validating inbound wire codes:
+
+```csharp
+// <auto-generated>
+//   Generated by protoc-gen-bitwise. DO NOT EDIT.
+//   Source: decentraland/kernel/comms/v3/comms.proto
+// </auto-generated>
+
+using Decentraland.Networking.Bitwise;
+
+namespace Decentraland.Kernel.Comms.V3
+{
+    public partial class PositionDelta
+    {
+        /// <summary>Coarsest quantization step of <see cref="DxQuantized"/>. Safe as an equality tolerance.</summary>
+        public const float DxQuantizedStep = 0.0030518044f;
+        /// <summary>Float accessor for <see cref="Dx"/>. Range [-100.0f, 100.0f], 16 bits, step ≈ 0.0030518.</summary>
+        public float DxQuantized
+        {
+            get => Quantize.Decode(Dx, -100.0f, 100.0f, 16);
+            set => Dx = Quantize.Encode(value, -100.0f, 100.0f, 16);
+        }
+
+        /// <summary>Coarsest quantization step of <see cref="DyQuantized"/>. Safe as an equality tolerance.</summary>
+        public const float DyQuantizedStep = 0.0030518044f;
+        /// <summary>Float accessor for <see cref="Dy"/>. Range [-100.0f, 100.0f], 16 bits, step ≈ 0.0030518.</summary>
+        public float DyQuantized
+        {
+            get => Quantize.Decode(Dy, -100.0f, 100.0f, 16);
+            set => Dy = Quantize.Encode(value, -100.0f, 100.0f, 16);
+        }
+
+        /// <summary>Coarsest quantization step of <see cref="DzQuantized"/>. Safe as an equality tolerance.</summary>
+        public const float DzQuantizedStep = 0.0030518044f;
+        /// <summary>Float accessor for <see cref="Dz"/>. Range [-100.0f, 100.0f], 16 bits, step ≈ 0.0030518.</summary>
+        public float DzQuantized
+        {
+            get => Quantize.Decode(Dz, -100.0f, 100.0f, 16);
+            set => Dz = Quantize.Encode(value, -100.0f, 100.0f, 16);
+        }
+
+        /// <summary>
+        ///     True when every quantized field holds a wire code within its declared bit width
+        ///     (<c>0 .. 2^bits-1</c>). The encoder never emits a code above this bound, so a larger
+        ///     value is a malformed/hostile message: decoding it would land far outside the field's
+        ///     <c>[min, max]</c> and, since the server relays raw codes verbatim, poison every observer.
+        ///     Reject before storing or relaying. Pure integer comparison — no decode.
+        /// </summary>
+        public bool AreQuantizedFieldsInRange() =>
+            Dx <= 65535u
+            && Dy <= 65535u
+            && Dz <= 65535u;
+    }
+
+} // namespace Decentraland.Kernel.Comms.V3
+```

package/out-js/decentraland/kernel/comms/rfc4/comms.gen.d.ts

@@ -120,6 +120,22 @@ export interface PlayerEmote {
     incrementalId: number;
     urn: string;
     timestamp: number;
+    /** true means the emote has been stopped in the sender's client */
+    isStopping?: boolean | undefined;
+    /** true when it is not the first time the looping animation plays */
+    isRepeating?: boolean | undefined;
+    /** identifies an interaction univocaly, established when the start animation is triggered */
+    interactionId?: number | undefined;
+    /** -1 means it does not use an outcome animation */
+    socialEmoteOutcome?: number | undefined;
+    /** to a social emote started by other user */
+    isReacting?: boolean | undefined;
+    /** wallet address of the user that initiated social emote */
+    socialEmoteInitiator?: string | undefined;
+    /** wallet address of the user whose avatar is the target of a directed emote */
+    targetAvatar?: string | undefined;
+    /** mask for which bones an animation applies to. */
+    mask?: number | undefined;
 }
 export interface SceneEmote {
     sceneEntityId: string;
@@ -139,6 +155,11 @@ export interface ProfileResponse {
 export interface Chat {
     message: string;
     timestamp: number;
+    /**
+     * Extension: optional forwarded_from to identify the original sender when
+     * messages are forwarded through an SFU
+     */
+    forwardedFrom?: string | undefined;
 }
 export interface Scene {
     sceneId: string;

package/out-js/decentraland/kernel/comms/rfc4/comms.gen.js

@@ -1073,7 +1073,19 @@ var MovementCompressed;
     MovementCompressed.fromPartial = fromPartial;
 })(MovementCompressed || (exports.MovementCompressed = MovementCompressed = {}));
 function createBasePlayerEmote() {
-    return { incrementalId: 0, urn: "", timestamp: 0 };
+    return {
+        incrementalId: 0,
+        urn: "",
+        timestamp: 0,
+        isStopping: undefined,
+        isRepeating: undefined,
+        interactionId: undefined,
+        socialEmoteOutcome: undefined,
+        isReacting: undefined,
+        socialEmoteInitiator: undefined,
+        targetAvatar: undefined,
+        mask: undefined,
+    };
 }
 var PlayerEmote;
 (function (PlayerEmote) {
@@ -1087,6 +1099,30 @@ var PlayerEmote;
         if (message.timestamp !== 0) {
             writer.uint32(29).float(message.timestamp);
         }
+        if (message.isStopping !== undefined) {
+            writer.uint32(32).bool(message.isStopping);
+        }
+        if (message.isRepeating !== undefined) {
+            writer.uint32(40).bool(message.isRepeating);
+        }
+        if (message.interactionId !== undefined) {
+            writer.uint32(48).int32(message.interactionId);
+        }
+        if (message.socialEmoteOutcome !== undefined) {
+            writer.uint32(56).int32(message.socialEmoteOutcome);
+        }
+        if (message.isReacting !== undefined) {
+            writer.uint32(64).bool(message.isReacting);
+        }
+        if (message.socialEmoteInitiator !== undefined) {
+            writer.uint32(74).string(message.socialEmoteInitiator);
+        }
+        if (message.targetAvatar !== undefined) {
+            writer.uint32(82).string(message.targetAvatar);
+        }
+        if (message.mask !== undefined) {
+            writer.uint32(88).uint32(message.mask);
+        }
         return writer;
     }
     PlayerEmote.encode = encode;
@@ -1115,6 +1151,54 @@ var PlayerEmote;
                     }
                     message.timestamp = reader.float();
                     continue;
+                case 4:
+                    if (tag !== 32) {
+                        break;
+                    }
+                    message.isStopping = reader.bool();
+                    continue;
+                case 5:
+                    if (tag !== 40) {
+                        break;
+                    }
+                    message.isRepeating = reader.bool();
+                    continue;
+                case 6:
+                    if (tag !== 48) {
+                        break;
+                    }
+                    message.interactionId = reader.int32();
+                    continue;
+                case 7:
+                    if (tag !== 56) {
+                        break;
+                    }
+                    message.socialEmoteOutcome = reader.int32();
+                    continue;
+                case 8:
+                    if (tag !== 64) {
+                        break;
+                    }
+                    message.isReacting = reader.bool();
+                    continue;
+                case 9:
+                    if (tag !== 74) {
+                        break;
+                    }
+                    message.socialEmoteInitiator = reader.string();
+                    continue;
+                case 10:
+                    if (tag !== 82) {
+                        break;
+                    }
+                    message.targetAvatar = reader.string();
+                    continue;
+                case 11:
+                    if (tag !== 88) {
+                        break;
+                    }
+                    message.mask = reader.uint32();
+                    continue;
             }
             if ((tag & 7) === 4 || tag === 0) {
                 break;
@@ -1129,6 +1213,14 @@ var PlayerEmote;
             incrementalId: isSet(object.incrementalId) ? Number(object.incrementalId) : 0,
             urn: isSet(object.urn) ? String(object.urn) : "",
             timestamp: isSet(object.timestamp) ? Number(object.timestamp) : 0,
+            isStopping: isSet(object.isStopping) ? Boolean(object.isStopping) : undefined,
+            isRepeating: isSet(object.isRepeating) ? Boolean(object.isRepeating) : undefined,
+            interactionId: isSet(object.interactionId) ? Number(object.interactionId) : undefined,
+            socialEmoteOutcome: isSet(object.socialEmoteOutcome) ? Number(object.socialEmoteOutcome) : undefined,
+            isReacting: isSet(object.isReacting) ? Boolean(object.isReacting) : undefined,
+            socialEmoteInitiator: isSet(object.socialEmoteInitiator) ? String(object.socialEmoteInitiator) : undefined,
+            targetAvatar: isSet(object.targetAvatar) ? String(object.targetAvatar) : undefined,
+            mask: isSet(object.mask) ? Number(object.mask) : undefined,
         };
     }
     PlayerEmote.fromJSON = fromJSON;
@@ -1137,6 +1229,14 @@ var PlayerEmote;
         message.incrementalId !== undefined && (obj.incrementalId = Math.round(message.incrementalId));
         message.urn !== undefined && (obj.urn = message.urn);
         message.timestamp !== undefined && (obj.timestamp = message.timestamp);
+        message.isStopping !== undefined && (obj.isStopping = message.isStopping);
+        message.isRepeating !== undefined && (obj.isRepeating = message.isRepeating);
+        message.interactionId !== undefined && (obj.interactionId = Math.round(message.interactionId));
+        message.socialEmoteOutcome !== undefined && (obj.socialEmoteOutcome = Math.round(message.socialEmoteOutcome));
+        message.isReacting !== undefined && (obj.isReacting = message.isReacting);
+        message.socialEmoteInitiator !== undefined && (obj.socialEmoteInitiator = message.socialEmoteInitiator);
+        message.targetAvatar !== undefined && (obj.targetAvatar = message.targetAvatar);
+        message.mask !== undefined && (obj.mask = Math.round(message.mask));
         return obj;
     }
     PlayerEmote.toJSON = toJSON;
@@ -1145,11 +1245,19 @@ var PlayerEmote;
     }
     PlayerEmote.create = create;
     function fromPartial(object) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
         const message = createBasePlayerEmote();
         message.incrementalId = (_a = object.incrementalId) !== null && _a !== void 0 ? _a : 0;
         message.urn = (_b = object.urn) !== null && _b !== void 0 ? _b : "";
         message.timestamp = (_c = object.timestamp) !== null && _c !== void 0 ? _c : 0;
+        message.isStopping = (_d = object.isStopping) !== null && _d !== void 0 ? _d : undefined;
+        message.isRepeating = (_e = object.isRepeating) !== null && _e !== void 0 ? _e : undefined;
+        message.interactionId = (_f = object.interactionId) !== null && _f !== void 0 ? _f : undefined;
+        message.socialEmoteOutcome = (_g = object.socialEmoteOutcome) !== null && _g !== void 0 ? _g : undefined;
+        message.isReacting = (_h = object.isReacting) !== null && _h !== void 0 ? _h : undefined;
+        message.socialEmoteInitiator = (_j = object.socialEmoteInitiator) !== null && _j !== void 0 ? _j : undefined;
+        message.targetAvatar = (_k = object.targetAvatar) !== null && _k !== void 0 ? _k : undefined;
+        message.mask = (_l = object.mask) !== null && _l !== void 0 ? _l : undefined;
         return message;
     }
     PlayerEmote.fromPartial = fromPartial;
@@ -1421,7 +1529,7 @@ var ProfileResponse;
     ProfileResponse.fromPartial = fromPartial;
 })(ProfileResponse || (exports.ProfileResponse = ProfileResponse = {}));
 function createBaseChat() {
-    return { message: "", timestamp: 0 };
+    return { message: "", timestamp: 0, forwardedFrom: undefined };
 }
 var Chat;
 (function (Chat) {
@@ -1432,6 +1540,9 @@ var Chat;
         if (message.timestamp !== 0) {
             writer.uint32(17).double(message.timestamp);
         }
+        if (message.forwardedFrom !== undefined) {
+            writer.uint32(26).string(message.forwardedFrom);
+        }
         return writer;
     }
     Chat.encode = encode;
@@ -1454,6 +1565,12 @@ var Chat;
                     }
                     message.timestamp = reader.double();
                     continue;
+                case 3:
+                    if (tag !== 26) {
+                        break;
+                    }
+                    message.forwardedFrom = reader.string();
+                    continue;
             }
             if ((tag & 7) === 4 || tag === 0) {
                 break;
@@ -1467,6 +1584,7 @@ var Chat;
         return {
             message: isSet(object.message) ? String(object.message) : "",
             timestamp: isSet(object.timestamp) ? Number(object.timestamp) : 0,
+            forwardedFrom: isSet(object.forwardedFrom) ? String(object.forwardedFrom) : undefined,
         };
     }
     Chat.fromJSON = fromJSON;
@@ -1474,6 +1592,7 @@ var Chat;
         const obj = {};
         message.message !== undefined && (obj.message = message.message);
         message.timestamp !== undefined && (obj.timestamp = message.timestamp);
+        message.forwardedFrom !== undefined && (obj.forwardedFrom = message.forwardedFrom);
         return obj;
     }
     Chat.toJSON = toJSON;
@@ -1482,10 +1601,11 @@ var Chat;
     }
     Chat.create = create;
     function fromPartial(object) {
-        var _a, _b;
+        var _a, _b, _c;
         const message = createBaseChat();
         message.message = (_a = object.message) !== null && _a !== void 0 ? _a : "";
         message.timestamp = (_b = object.timestamp) !== null && _b !== void 0 ? _b : 0;
+        message.forwardedFrom = (_c = object.forwardedFrom) !== null && _c !== void 0 ? _c : undefined;
         return message;
     }
     Chat.fromPartial = fromPartial;