# @dcl/ecs

> Decentraland ECS

Latest version **7.29.0** (published 2026-09-15) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @dcl/ecs
pnpm add @dcl/ecs
yarn add @dcl/ecs
bun add @dcl/ecs
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 7.29.0 |
| Published | 2026-09-15 |
| First published | 2022-05-06 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 2.3 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 40 |
| Author | DCL |
| Maintainers | decentralandbot, imazzara |
| Keywords | @dcl/sdk, dcl, ecs |

## Links

- npm: https://www.npmjs.com/package/@dcl/ecs
- Repository: https://github.com/decentraland/js-sdk-toolchain
- Homepage: https://github.com/decentraland/ecs#readme
- Issues: https://github.com/decentraland/ecs/issues
- npm.io page: https://npm.io/package/@dcl/ecs

## Recent versions

- 7.29.0 (latest) — 2026-09-15
- 7.29.1-36716815278.commit-ab46c81 (next) — 2026-09-30
- 7.29.1-36637355925.commit-d261ba1 (auth-server) — 2026-09-29
- 7.29.1-35901015152.commit-d1b7b96 (experimental-bevy) — 2026-09-23
- 7.27.1-34382248832.commit-ca3b679 (experimental) — 2026-09-09
- 7.25.1-30828532396.commit-0c215c3 (protocol-squad) — 2026-08-03
- 7.8.16 (ci) — 2025-07-07
- 7.29.1-36625469671.commit-2d5ffac — 2026-09-29
- 7.29.1-36624944101.commit-bb81ac6 — 2026-09-29
- 7.29.1-36591934525.commit-48aa9b5 — 2026-09-29
- 7.29.1-36041177279.commit-502e633 — 2026-09-24
- 7.29.1-35978346337.commit-823107b — 2026-09-24
- 7.29.1-35917671376.commit-046b268 — 2026-09-23
- 7.29.1-35862852104.commit-1f44e80 — 2026-09-23
- 7.29.1-35861881691.commit-e4e55e9 — 2026-09-23
- … 1318 more at https://npm.io/package/@dcl/ecs/versions

## README

# @dcl/ecs

Core Entity Component System (ECS) package for Decentraland scenes. Implements a CRDT-based ECS architecture for networked scene state.

## Installation

```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)

---
_Source: https://npm.io/package/@dcl/ecs · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._