@dcl/ecs 7.7.3-13090257149.commit-df175f2 → 7.7.3-13092675740.commit-ba2dd71

package/README.md

@@ -1,10 +1,118 @@
-# ECS 7
+# @dcl/ecs
 
-## Installing dependencies
-Run `make install`, this will run the `npm install` and other dependencies
+Core Entity Component System (ECS) package for Decentraland scenes. Implements a CRDT-based ECS architecture for networked scene state.
 
-## Building
-Run `make build`
+## Installation
 
-## Testing
-Run `make test`, you can also debug the test in VS code, selecting the launch `Jest current file` or just `Jest` (this will run all test)
+```bash
+npm install @dcl/ecs
+```
+
+## Usage
+
+```typescript
+import { engine } from '@dcl/ecs'
+
+// Create entity
+const entity = engine.addEntity()
+
+// Define and add component
+const Health = engine.defineComponent(1, {
+  current: Number,
+  max: Number,
+  regeneration: Number
+})
+
+Health.create(entity, {
+  current: 100,
+  max: 100,
+  regeneration: 1
+})
+
+// Create system
+engine.addSystem((dt: number) => {
+  for (const [entity, health] of engine.mutableGroupOf(Health)) {
+    if (health.current < health.max) {
+      health.current = Math.min(health.max, health.current + health.regeneration * dt)
+    }
+  }
+})
+```
+
+## Technical Overview
+
+### Component Definition
+
+Components are defined with a unique ID and a schema. The schema is used to:
+
+- Generate TypeScript types
+- Create binary serializers/deserializers
+- Set up CRDT operations
+
+### CRDT Implementation
+
+The ECS uses CRDTs (Conflict-free Replicated Data Types) to enable deterministic state updates across multiple engine instances:
+
+- Component updates are CRDT operations with logical timestamps
+- Multiple engine instances can be synced by exchanging CRDT operations
+- Conflict resolution uses timestamps and entity IDs to ensure consistency
+- Binary transport format minimizes network overhead
+
+### Network Entities
+
+For multiplayer scenes, the `syncEntity` method marks entities that should be synchronized across peers.
+In the background it creates a NetworkEntity and a SyncComponents components with all the info necessary to synchronise the entity through the network.
+
+```typescript
+import { engine, NetworkEntity } from '@dcl/ecs'
+
+// Create a networked entity
+const foe = engine.addEntity()
+NetworkEntity.create(foe)
+
+// Components on this entity will be synced across peers
+Health.create(foe, { current: 100, max: 100, regeneration: 1 })
+```
+
+Each peer maintains its own engine instance. When using NetworkEntity:
+
+- The owner peer can modify the entity's components
+- Other peers receive read-only replicas
+- Updates are propagated through the network transport layer using CRDT operations
+
+Example transport message:
+
+```typescript
+{
+  entityId: number
+  componentId: number
+  timestamp: number
+  data: Uint8Array // Serialized component data
+}
+```
+
+### Performance Features
+
+- Zero-allocation component iteration
+- Dirty state tracking for efficient updates
+- Binary serialization for network transport
+- Batched component operations
+
+## Development
+
+```bash
+# Build
+make build
+
+# Test
+make test
+
+# Clean and reinstall
+make clean && make install
+```
+
+## Documentation
+
+- [ECS Guide](https://docs.decentraland.org/creator/development-guide/sdk7/entities-components/)
+- [Component Reference](https://docs.decentraland.org/creator/development-guide/sdk7/components/)
+- [ADR-117: CRDT Protocol](https://adr.decentraland.org/adr/ADR-117)

package/dist/systems/crdt/index.js

@@ -206,14 +206,22 @@ export function crdtSceneSystem(engine, onProcessEntityComponentChange) {
         // Send CRDT messages to transports
         const transportBuffer = new ReadWriteByteBuffer();
         for (const index in transports) {
+            // NetworkMessages can only have a MAX_SIZE of 13kb. So we need to send it in chunks.
+            const LIVEKIT_MAX_SIZE = 13;
+            const __NetworkMessagesBuffer = [];
             const transportIndex = Number(index);
             const transport = transports[transportIndex];
             const isRendererTransport = transport.type === 'renderer';
             const isNetworkTransport = transport.type === 'network';
+            // Reset Buffer for each Transport
             transportBuffer.resetBuffer();
             const buffer = new ReadWriteByteBuffer();
             // Then we send all the new crdtMessages that the transport needs to process
             for (const message of crdtMessages) {
+                if (isNetworkTransport && transportBuffer.toBinary().byteLength / 1024 > LIVEKIT_MAX_SIZE) {
+                    __NetworkMessagesBuffer.push(transportBuffer.toBinary());
+                    transportBuffer.resetBuffer();
+                }
                 // Avoid echo messages
                 if (message.transportId === transportIndex)
                     continue;
@@ -261,7 +269,10 @@ export function crdtSceneSystem(engine, onProcessEntityComponentChange) {
                 // Common message
                 transportBuffer.writeBuffer(message.messageBuffer, false);
             }
-            const message = transportBuffer.currentWriteOffset() ? transportBuffer.toBinary() : new Uint8Array([]);
+            if (isNetworkTransport && transportBuffer.currentWriteOffset()) {
+                __NetworkMessagesBuffer.push(transportBuffer.toBinary());
+            }
+            const message = isNetworkTransport ? __NetworkMessagesBuffer : transportBuffer.toBinary();
             await transport.send(message);
         }
     }

package/dist/systems/crdt/types.d.ts

@@ -21,7 +21,11 @@ export type TransportMessage = Omit<ReceiveMessage, 'data'>;
  * @public
  */
 export type Transport = {
-    send(message: Uint8Array): Promise<void>;
+    /**
+     *  For Network messages its an Uint8Array[]. Due too the LiveKit MAX_SIZE = 13kb
+     *  For Renderer & Other transports we send a single Uint8Array
+     */
+    send(message: Uint8Array | Uint8Array[]): Promise<void>;
     onmessage?(message: Uint8Array): void;
     filter(message: Omit<TransportMessage, 'messageBuffer'>): boolean;
     type?: string;

package/dist-cjs/systems/crdt/index.js

@@ -232,14 +232,22 @@ function crdtSceneSystem(engine, onProcessEntityComponentChange) {
         // Send CRDT messages to transports
         const transportBuffer = new ByteBuffer_1.ReadWriteByteBuffer();
         for (const index in transports) {
+            // NetworkMessages can only have a MAX_SIZE of 13kb. So we need to send it in chunks.
+            const LIVEKIT_MAX_SIZE = 13;
+            const __NetworkMessagesBuffer = [];
             const transportIndex = Number(index);
             const transport = transports[transportIndex];
             const isRendererTransport = transport.type === 'renderer';
             const isNetworkTransport = transport.type === 'network';
+            // Reset Buffer for each Transport
             transportBuffer.resetBuffer();
             const buffer = new ByteBuffer_1.ReadWriteByteBuffer();
             // Then we send all the new crdtMessages that the transport needs to process
             for (const message of crdtMessages) {
+                if (isNetworkTransport && transportBuffer.toBinary().byteLength / 1024 > LIVEKIT_MAX_SIZE) {
+                    __NetworkMessagesBuffer.push(transportBuffer.toBinary());
+                    transportBuffer.resetBuffer();
+                }
                 // Avoid echo messages
                 if (message.transportId === transportIndex)
                     continue;
@@ -287,7 +295,10 @@ function crdtSceneSystem(engine, onProcessEntityComponentChange) {
                 // Common message
                 transportBuffer.writeBuffer(message.messageBuffer, false);
             }
-            const message = transportBuffer.currentWriteOffset() ? transportBuffer.toBinary() : new Uint8Array([]);
+            if (isNetworkTransport && transportBuffer.currentWriteOffset()) {
+                __NetworkMessagesBuffer.push(transportBuffer.toBinary());
+            }
+            const message = isNetworkTransport ? __NetworkMessagesBuffer : transportBuffer.toBinary();
             await transport.send(message);
         }
     }

package/dist-cjs/systems/crdt/types.d.ts

@@ -21,7 +21,11 @@ export type TransportMessage = Omit<ReceiveMessage, 'data'>;
  * @public
  */
 export type Transport = {
-    send(message: Uint8Array): Promise<void>;
+    /**
+     *  For Network messages its an Uint8Array[]. Due too the LiveKit MAX_SIZE = 13kb
+     *  For Renderer & Other transports we send a single Uint8Array
+     */
+    send(message: Uint8Array | Uint8Array[]): Promise<void>;
     onmessage?(message: Uint8Array): void;
     filter(message: Omit<TransportMessage, 'messageBuffer'>): boolean;
     type?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dcl/ecs",
   "description": "Decentraland ECS",
-  "version": "7.7.3-13090257149.commit-df175f2",
+  "version": "7.7.3-13092675740.commit-ba2dd71",
   "author": "DCL",
   "bugs": "https://github.com/decentraland/ecs/issues",
   "files": [
@@ -33,5 +33,5 @@
   },
   "types": "./dist/index.d.ts",
   "typings": "./dist/index.d.ts",
-  "commit": "df175f269c65f9b03e9f43af8d306839a7480361"
+  "commit": "ba2dd71f5c68f8e432074a9fdca6fed2b1b1b863"
 }