Runtime constraint: Decentraland runs in a QuickJS sandbox. No Node.js APIs (

fs

,

http

,

path

,

process

). Use

fetch()

and

WebSocket

for network communication. See the scene-runtime skill for async patterns.

syncEntity

MessageBus

fetch

signedFetch

WebSocket

1. Does every player need to see the same state, including late joiners? -->

   syncEntity

2. Is it a fire-and-forget event only for players currently in the scene? -->

   MessageBus

3. Do you need the information to be persisted even after all players leave, or to run secure validations on that information? -->

   fetch

   or

   signedFetch

4. Do you need continuous real-time server communication? -->

   WebSocket

5. Combine approaches freely: use

   syncEntity

   for world state,

   MessageBus

   for effects, and

   fetch

   for persistence.

import { engine, Transform, MeshRenderer, Material } from '@dcl/sdk/ecs'
import { syncEntity } from '@dcl/sdk/network'
import { Vector3, Color4 } from '@dcl/sdk/math'

syncEntity(entity, componentIds[], syncId?)

• entity

  — the entity to synchronize

• componentIds[]

  — array of component IDs to keep in sync (e.g.,

  [Transform.componentId]

  )

• syncId

  — unique numeric identifier (required for predefined entities, optional for player-spawned entities)

enum SyncIds {
	DOOR = 1,
	ELEVATOR = 2,
	SCOREBOARD = 3,
}

const door = engine.addEntity()
Transform.create(door, { position: Vector3.create(8, 1, 8) })
MeshRenderer.setBox(door)
syncEntity(
	door,
	[Transform.componentId, MeshRenderer.componentId],
	SyncIds.DOOR
)

Best practice — always give singletons a stable sync ID. Auto IDs derive identity from the creating peer + its local engine entity number (which the engine recycles). A singleton synced entity that is destroyed and recreated repeatedly with an auto ID is fragile over real network comms: it may fail to reconcile on remote clients (they see only default component data) even though it works perfectly in local single-process preview. Assign any singleton or small fixed set of well-known synced entities a STABLE explicit sync ID from a reserved enum. Reserve auto IDs for genuinely dynamic, many-instance, create-and-forget entities. Also: never

removeEntity

a fixed-ID synced entity and recreate it with the same ID in the SAME frame — the internal

NetworkEntity

survives until a later CRDT flush, so recreating immediately throws

id provided is already in use

; defer the re-spawn to a later tick. See

{baseDir}/references/networking-patterns.md

(syncEntity identity section) for the full failure-mode signature, fix, and the optimistic-prediction companion pattern.

function createProjectile() {
	const projectile = engine.addEntity()
	Transform.create(projectile, { position: Vector3.create(4, 1, 4) })
	MeshRenderer.setSphere(projectile)
	syncEntity(projectile, [Transform.componentId])
	return projectile
}

Some visuals are inherently per-player, not shared. A

Billboard

(camera-facing) is recomputed locally in each explorer, so every player sees it facing themselves — this is not synced and needs no

syncEntity

. The exception is a

Billboard

with a

targetEntity

: because the target's position is scene state, all players see that billboard oriented the same way. Use

targetEntity

when you need a shared, consistent orientation (e.g. a sign that points at a shared object). See the

player-avatar

/

sdk-scenes

component reference for Billboard details.

import { engine, Schemas } from '@dcl/sdk/ecs'
import { syncEntity } from '@dcl/sdk/network'

const ScoreBoard = engine.defineComponent('scoreBoard', {
	score: Schemas.Int,
	playerName: Schemas.String,
	lastUpdated: Schemas.Int64,
})

const board = engine.addEntity()
ScoreBoard.create(board, { score: 0, playerName: '', lastUpdated: 0 })
syncEntity(board, [ScoreBoard.componentId])

function addScore(points: number) {
	const data = ScoreBoard.getMutable(board)
	data.score += points
	data.lastUpdated = Date.now()
}

Use

Schemas.Int64

for timestamps and other large numbers.

Schemas.Number

/

Schemas.Int

corrupt values over 13 digits (like

Date.now()

) — always store such values in

Schemas.Int64

(as

lastUpdated

above does).

import { MessageBus } from '@dcl/sdk/message-bus'

const bus = new MessageBus()

bus.on('hit', (data: { damage: number }) => {
	console.log('Took damage:', data.damage)
})

bus.emit('hit', { damage: 10 })

Authoritative-server scenes:

MessageBus

is client-only — the headless server runtime does not implement the legacy comms event it relies on, and a module-scope

new MessageBus()

(as above) fails on the server with

RemoteError: not implemented

. In those scenes construct it only inside the client branch (

if (!isServer())

); see the

authoritative-server

skill.

• syncEntity

  : late joiners get current state, automatic conflict resolution — CRDT last-write-wins, so if two players change the same component simultaneously the last write wins. The state persists as long as at least one player remains in the scene

• MessageBus

  : fire-and-forget, late joiners miss past messages, good for transient effects

MessageBus

Uint8Array

syncEntity

• You are emitting many messages per second (e.g., continuous movement streams, particle triggers in tight loops)
• Payload size matters (binary encoding is more compact than JSON)
• You already have binary data (e.g., pre-encoded buffers, CRDT deltas)

MessageBus

import { sendBinary } from '~system/CommunicationsController'
import { executeTask } from '@dcl/sdk/ecs'

// Send a binary message to all peers (or a specific subset via peerData)
executeTask(async () => {
	const payload = new Uint8Array([1, 2, 3, 4]) // your encoded data
	const response = await sendBinary({
		data: [payload],
		peerData: undefined, // optional: target specific peers
	})
	// response.data is a Uint8Array[] of messages received from other peers
	for (const incoming of response.data) {
		handleBinaryMessage(incoming)
	}
})

Uint8Array

DataView

TextEncoder

TextDecoder

sendBinary

Profile not initialized. Call syncEntity inside main()

syncEntity

syncEntity

main()

syncEntity

engine.addSystem()

syncEntity()

syncEntity(entity, [ComponentId1, ComponentId2])

if (!isStateSyncronized()) return

syncEntity

Need guaranteed consistency, server-side validation, or anti-cheat?

syncEntity

and

MessageBus

are not entirely reliable — if it's important that all players see the same state change, see the authoritative-server skill for the headless server pattern. For a complete competitive game architecture (anti-cheat with server-side proximity validation, checkpoint-only Storage persistence, atomic component splits by change rate), see the Gem Rush reference scene (

92,-9-authoritative-server-gem-rush

).

syncEntity

MessageBus

• https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/90,-9-authoritative-server-leaderboard — authoritative (NOT serverless): only the server calls

  syncEntity

  , and synced components are locked with

  validateBeforeChange

  so clients can only read them and send messages. If you instead want any client to mutate shared state directly (the pattern this skill documents), each client calls

  syncEntity

  on its own and there is no

  validateBeforeChange

  . See the authoritative-server skill for that scene's full breakdown.