@dcl/ecs 7.7.2 → 7.7.3-13057502418.commit-f85e704

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dcl/ecs",
   "description": "Decentraland ECS",
-  "version": "7.7.2",
+  "version": "7.7.3-13057502418.commit-f85e704",
   "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": "024c250c134fec9c63fc229ca5dd67e07ce58d83"
+  "commit": "f85e70478683506f872234767a9473c6b1f4a796"
 }