> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/networking/authoritative-servers.md).

# Multiplayer Server

Crea escenas multijugador de Decentraland con un Multiplayer Server sin interfaz.

**📔 Nota**: El Multiplayer Server se llamaba anteriormente **Authoritative Server**. Solo cambió el nombre; la funcionalidad es la misma. La rama del SDK que debes instalar sigue llamándose `auth-server`, consulta [Configuración](#setup).

## Resumen

Decentraland ejecuta las escenas localmente en el dispositivo del jugador. De forma predeterminada, los jugadores pueden verse e interactuar directamente, pero cada uno interactúa con el entorno de forma independiente. De manera predeterminada, los cambios en el entorno no se comparten entre los jugadores.

Es muy importante que todos los jugadores vean una escena con el mismo contenido y en el mismo estado para que puedan interactuar de formas más significativas. Sin esto, si un jugador abre una puerta y entra en una casa, los demás jugadores verán que la puerta sigue cerrada, y parecerá que el primer jugador atraviesa directamente la puerta cerrada.

El **Multiplayer Server** es un proceso de servidor sin interfaz que ejecuta el código de tu escena, valida los cambios de estado y transmite el resultado a todos los jugadores conectados. Sigue una arquitectura de servidor autoritativo: en lugar de confiar en que cada cliente informe de sus propias acciones, el servidor actúa como la única fuente de verdad. Por ello, es la opción recomendada para sincronizar escenas multijugador.

El Multiplayer Server es ideal cuando la equidad es importante para la mecánica del juego, ya que puedes implementar validaciones antitrampas complejas que se ejecutan en el servidor. También puedes almacenar claves privadas y otra información confidencial en el servidor, sin tener que exponerlas directamente al usuario.

El Multiplayer Server también resuelve un problema real: en una configuración peer-to-peer, dos jugadores que controlan algo como una plataforma flotante pueden generar resultados contradictorios. Cada cliente establece la plataforma a una altura diferente y nadie tiene autoridad para decidir cuál es la correcta. El Multiplayer Server procesa cada cambio en un único lugar, de modo que todos los clientes convergen en el mismo estado.

También te ofrece un lugar donde **persistir datos entre sesiones**: tablas de clasificación, progreso de los jugadores, logros desbloqueados o cambios en el entorno, como puertas abiertas u objetos colocados. Cuando los jugadores regresan, el mundo refleja lo que ocurrió antes.

Decentraland aloja y despliega el servidor por ti. Al publicar tu escena mediante el proceso habitual, el servidor también se publica sin problemas, sin pasos adicionales ni necesidad de pagar por el alojamiento.

## Configuración

### 1. Instala la versión del SDK auth-server

Las API nativas del Multiplayer Server (`isServer`, `registerMessages`, `Storage`, `EnvVar`, etc.) están disponibles en una rama independiente del SDK.

**En Creator Hub**, abre la configuración de la escena y marca **Enable Multiplayer Server** en la sección **Advanced** de la pestaña **Settings** . Creator Hub instala el SDK adecuado y configura `scene.json` por ti. Consulta [Multiplayer Server en la configuración de la escena](https://docs.decentraland.org/creator/content-creator-es/scene-editor/configurar/scene-settings.md#multiplayer-server).

**Desde la línea de comandos**, ejecuta el siguiente comando para instalarlo en tu proyecto en lugar de la rama estándar del SDK:

```bash
npm install --save-exact @dcl/sdk@auth-server @dcl/js-runtime@auth-server
```

{% hint style="warning" %}
**📔 Nota**: Conserva `--save-exact`. Sin esta opción, npm guarda un rango de versiones como `^7.x.y-...` en `package.json`, y la siguiente versión normal del SDK también coincide con ese rango. Una ejecución posterior de `npm install` puede entonces reemplazar la compilación auth-server por una normal, que no incluye las API del servidor, y el código de tu servidor dejará de compilarse.
{% endhint %}

### 2. Configurar scene.json

El Multiplayer Server se habilita con la marca `"authoritativeMultiplayer": true` en `scene.json`, en el nivel raíz. No hace falta añadirla manualmente: al usar la rama auth-server del SDK, se añade automáticamente la primera vez que compilas o previsualizas la Scene. Solo asegúrate de no eliminarla; sin esta marca, el server nunca se ejecuta y `isServer()` siempre devuelve *false*.

También puedes añadir lo siguiente a tu `scene.json` en el nivel raíz:

```json
{
  "logsPermissions": ["0xYourWalletAddress"]
}
```

Añade `logsPermissions` para dar a estas wallets acceso a los logs y las métricas del server después del despliegue. En Creator Hub, la lista **Log Access & Storage** de la configuración de la Scene modifica este campo por ti. Los propietarios de Worlds y los colaboradores de despliegue que cumplan los requisitos también tienen acceso, al igual que los propietarios de Genesis City y los gestores de LAND delegados de la parcela base de la Scene. Consulta [Scene Insights](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/depuracion/scene-insights.md) para obtener información sobre permisos, inicio de sesión y comandos.

### 3. Ejecutar la previsualización

Usa el comando de previsualización estándar; no se necesitan pasos adicionales. Al usar la rama auth-server del SDK, la previsualización inicia automáticamente una versión local del Multiplayer Server en segundo plano.

La sesión local del server no está conectada a la versión en producción, así que puedes probar libremente sin afectar a los jugadores que están en tu Scene publicada.

## Ramificación entre Server y Client

El código de la Scene en la carpeta `src` del proyecto se ejecuta tanto en el server como en el client. Usa la función `isServer()` para separar las rutas de ejecución:

```typescript
import { isServer } from "@dcl/sdk/network"
import { initServer } from "./server/server"
import { initClient } from "./client/setup"
import { setupUi } from "./client/ui"

function main() {
  if (isServer()) {
    // Solo en el server: lógica del juego, validación, gestión del estado
    initServer()
    return
  } else {
    // Solo en el client: UI, gestión de la entrada, envío de mensajes
    initClient()
    setupUi()
  }
}
```

El server ejecuta tu Scene en modo headless, sin renderizado. Tiene acceso verificado a las posiciones de todos los jugadores, sus Wearables y otros datos mediante `PlayerIdentityData` y es la única autoridad sobre el estado del juego.

## Components sincronizados y validación

### Sincronizar Entities con todos los Clients

Usa `syncEntity` para difundir cualquier cambio en los Components indicados de esa Entity:

```typescript
import { isServer, syncEntity } from "@dcl/sdk/network"

if (isServer()) {
  syncEntity(
    entity,
    [Transform.componentId, GameState.componentId],
    /* enumId */ 1
  )
}
```

La sintaxis es idéntica a la que usa la [multijugador sin servidor](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/networking/serverless-multiplayer.md) característica, lo que facilita enormemente actualizar una escena que usa esta arquitectura al Multiplayer Server. Cuando una escena usa el Multiplayer Server, las actualizaciones de estado ya no se envían entre todos los jugadores; en su lugar, ahora se enrutan y validan a través del servidor.

{% hint style="warning" %}
**📔 Nota**: Con el Multiplayer Server, el patrón ideal es que solo el servidor llame a `syncEntity`. Así no tienes que preocuparte por la coherencia de los entity-id. En cambio, el servidor instancia y comparte la entidad, y todos los clientes se sincronizan con esa instancia. Protégelo siempre con `isServer()`. Esto es distinto de [la multijugador sin servidor](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/networking/serverless-multiplayer.md), donde cada cliente llama a `syncEntity` por su cuenta.
{% endhint %}

### Validar cambios

Usa `validateBeforeChange()` para restringir cualquier actualización de estado en un componente específico de una entidad. Te permite ejecutar una función de validación personalizada, y los cambios solo se aceptan si se cumple la condición de validación.

Si la validación devuelve el valor *true*, se acepta el cambio y se propaga a todos los jugadores. Si la validación devuelve el valor *false*, se rechaza el cambio. Un cambio rechazado no se transmite a los demás jugadores y se revierte para el jugador que intentó realizarlo.

#### Validar valores

El caso más sencillo consiste en validar que el nuevo *valor* que se escribe esté dentro de ciertos parámetros. Por ejemplo, aceptar cambios en un `Transform` solo cuando la nueva posición Y sea mayor que 0:

```typescript
import { engine, Transform } from "@dcl/sdk/ecs"
import { Vector3 } from "@dcl/sdk/math"
import { isServer } from "@dcl/sdk/network"

const entity = engine.addEntity()
Transform.create(entity, { position: Vector3.create(10, 2, 10) })

if (isServer()) {
  Transform.validateBeforeChange(entity, (value) => {
    // Reject any update that would place the entity at or below Y = 0
    return value.newValue.position.y > 0
  })
}
```

Como `validateBeforeChange()` solo tiene sentido en el servidor, protégelo siempre con `isServer()`. En el cliente, la llamada no resulta útil.

Puedes usar esto para impedir cambios que contradigan la lógica de tu juego, como mecanismo antitrampas.

#### Validar la proximidad al jugador

Puedes combinar `validateBeforeChange()` con posiciones de jugadores verificadas por el servidor para comprobar que un jugador esté lo bastante cerca de un objeto antes de permitirle interactuar con él. Por ejemplo, cuando un jugador intenta recoger un objeto cambiando su `Transform`, puedes rechazar el cambio si el objeto está a más de 5 metros del jugador:

```typescript
import { engine, Transform, PlayerIdentityData } from "@dcl/sdk/ecs"
import { Vector3 } from "@dcl/sdk/math"
import { isServer } from "@dcl/sdk/network"

const pickableEntity = engine.addEntity()
Transform.create(pickableEntity, { position: Vector3.create(8, 1, 8) })

if (isServer()) {
  Transform.validateBeforeChange(pickableEntity, (value) => {
    // Find the player who sent this change
    for (const [playerEntity, identity] of engine.getEntitiesWith(
      PlayerIdentityData
    )) {
      if (identity.address.toLowerCase() !== value.senderAddress.toLowerCase())
        continue

      const playerTransform = Transform.getOrNull(playerEntity)
      if (!playerTransform) return false

      // Get the current position of the object, before the change
      const objectTransform = Transform.getOrNull(pickableEntity)
      if (!objectTransform) return false

      const distance = Vector3.distance(
        playerTransform.position,
        objectTransform.position
      )

      // Only allow the change if the player is within 5 meters
      return distance <= 5
    }

    // Sender not found among connected players — reject
    return false
  })
}
```

Este patrón es útil como mecanismo antitrampas: impide que los jugadores alcancen objetos desde cualquier punto de la escena para agarrarlos si no deberían poder interactuar con ellos.

#### Permitir cambios solo a los administradores

También puedes validar según *quién* envía el cambio. Cada valor entrante incluye un campo `senderAddress` con la dirección de la wallet del remitente. Úsalo para permitir cambios solo a determinados jugadores. Por ejemplo, para permitir que solo los administradores de la escena modifiquen un componente `VideoPlayer` :

```typescript
import { engine, VideoPlayer } from "@dcl/sdk/ecs"
import { isServer } from "@dcl/sdk/network"
import { isPreview } from "@dcl/asset-packs/dist/admin-toolkit-ui/fetch-utils"
import { getSceneAdmins } from "@dcl/asset-packs/dist/admin-toolkit-ui/ModerationControl/api"

// Cache of admin wallet addresses, refreshed from the scene admin list
let adminAddresses = new Set<string>()

async function updateAdminAddresses() {
  if (isPreview()) return
  try {
    const [error, response] = await getSceneAdmins()
    if (error) {
      console.error("[SERVER] Error fetching admin list:", error)
      adminAddresses = new Set()
      return
    }
    adminAddresses = new Set(
      (response ?? []).map((admin) => admin.admin.toLowerCase())
    )
    console.log(
      "[SERVER] Updated admin addresses cache:",
      Array.from(adminAddresses)
    )
  } catch (error) {
    console.error("[SERVER] Error updating admin addresses:", error)
    adminAddresses = new Set()
  }
}

export async function main() {
  const videoEntity = engine.addEntity()
  VideoPlayer.create(videoEntity, { src: "videos/intro.mp4" })

  if (isServer()) {
    // Populate the cache before wiring up validation
    await updateAdminAddresses()

    VideoPlayer.validateBeforeChange(videoEntity, (value) => {
      // Always allow changes while running in preview, so local testing is easier
      if (isPreview()) return true

      const senderAddress = value.senderAddress.toLowerCase()
      if (!adminAddresses.has(senderAddress)) {
        console.log(
          "[SERVER] Unauthorized VideoPlayer change blocked from:",
          senderAddress
        )
        return false
      }
      return true
    })
  }
}
```

Consulta [Scene Admin](https://docs.decentraland.org/creator/content-creator-es/scene-editor/operar-en-vivo/scene-admin.md) para obtener más contexto sobre cómo los jugadores se convierten en administradores de una escena.

#### Envía intenciones, nunca resultados

Siempre que haya puntuaciones, premios o recursos compartidos en juego, diseña los mensajes del cliente en torno a lo que el jugador **intenta hacer**, no al resultado. Un cliente envía `claimPoint` o `harvest`. Nunca envía «mi puntuación ahora es 40».

Luego, el servidor verifica el mensaje: quién lo envió, si el juego está en una fase que lo permite, si el jugador está lo suficientemente cerca y si queda algo por reclamar. Solo entonces calcula el nuevo valor y lo escribe. El servidor es el único que puede escribir el estado del juego.

Un cliente que puede indicar su propia puntuación puede indicar cualquier puntuación.

#### Permite solo los cambios del servidor

El caso más estricto consiste en aceptar únicamente las escrituras que se originen en el propio servidor y rechazar cualquier cambio procedente de un cliente. Este es el patrón recomendado para los estados que deben tener autoridad total: puntuaciones, fase del juego, Entities generadas, etc.

Cada valor entrante incluye un campo `senderAddress` Cuando el remitente es el servidor, este campo coincide con la constante `AUTH_SERVER_PEER_ID`, exportada desde `@dcl/sdk/network/message-bus-sync`.

El ejemplo siguiente define una pequeña función auxiliar `protectServerEntity()` que aplica esta comprobación a uno o más Components de una Entity determinada. Es una forma práctica de proteger varios Components (como `Transform` y `GltfContainer`) en una sola llamada:

```typescript
import { engine, Entity, Transform, GltfContainer } from "@dcl/sdk/ecs"
import { Vector3 } from "@dcl/sdk/math"
import { isServer } from "@dcl/sdk/network"
import { AUTH_SERVER_PEER_ID } from "@dcl/sdk/network/message-bus-sync"

type ComponentWithValidation = {
  validateBeforeChange: (
    entity: Entity,
    cb: (value: { senderAddress: string }) => boolean
  ) => void
}

function protectServerEntity(
  entity: Entity,
  components: ComponentWithValidation[]
) {
  for (const component of components) {
    component.validateBeforeChange(entity, (value) => {
      return value.senderAddress === AUTH_SERVER_PEER_ID
    })
  }
}

if (isServer()) {
  // Después de crear una Entity gestionada por el servidor:
  const entity = engine.addEntity()
  Transform.create(entity, { position: Vector3.create(10, 5, 10) })
  GltfContainer.create(entity, { src: "assets/model.glb" })
  protectServerEntity(entity, [Transform, GltfContainer])
}
```

{% hint style="warning" %}
**📔 Nota**: Llama siempre a `protectServerEntity()` dentro de un bloque `isServer()` . Este envuelve `validateBeforeChange()`, que solo tiene sentido en el servidor; llamarlo en un cliente genera errores.
{% endhint %}

#### Componentes personalizados

También puedes aplicar `validateBeforeChange()` a los componentes personalizados definidos por la escena.

```typescript
import { engine, Schemas } from "@dcl/sdk/ecs"
import { isServer } from "@dcl/sdk/network"
import { AUTH_SERVER_PEER_ID } from "@dcl/sdk/network/message-bus-sync"

export const GameState = engine.defineComponent("game:State", {
  phase: Schemas.String,
  score: Schemas.Int,
  timeRemaining: Schemas.Int,
})

// Only the server can modify this component
if (isServer()) {
  GameState.validateBeforeChange((value) => {
    return value.senderAddress === AUTH_SERVER_PEER_ID
  })
}
```

## Mensajes

Los componentes sincronizados son ideales para el estado que todos los jugadores deberían ver continuamente: cosas como las posiciones, las puntuaciones o la fase del juego. Pero no todo encaja en ese modelo. A veces, un jugador solo necesita decirle al servidor «He hecho clic en este botón» o «Quiero unirme al juego», y el servidor debe responder con una respuesta puntual como «La ronda ha empezado» o «Aquí están tus estadísticas». Estos son eventos, no estados persistentes.

Para eso sirven los mensajes. Usa `registerMessages()` para la comunicación tipada y validada mediante esquemas entre los clientes y el servidor. Los mensajes se envían sin esperar respuesta: un cliente envía uno al servidor, el servidor lo procesa y, opcionalmente, envía otro de vuelta. Por sí solos, no crean ningún estado persistente.

### Definir mensajes

Define todos los mensajes en un archivo compartido que importen tanto el servidor como el cliente. Así, ambas partes siempre coinciden en los mensajes disponibles y los datos que contienen. Cada mensaje es un `Schemas.Map` que describe su carga útil:

```typescript
import { Schemas } from "@dcl/sdk/ecs"
import { registerMessages } from "@dcl/sdk/network"

export const Messages = {
  // Client → Server
  playerReady: Schemas.Map({ displayName: Schemas.String }),
  playerAction: Schemas.Map({ action: Schemas.String, targetId: Schemas.Int }),
  giveCoins: Schemas.Map({ to: Schemas.String, amount: Schemas.Int }),

  // Server → Client
  gameStarted: Schemas.Map({ roundNumber: Schemas.Int }),
  gameEnded: Schemas.Map({ winnerId: Schemas.String }),
}

export const room = registerMessages(Messages)
```

{% hint style="warning" %}
**📔 Nota**: Llama a `registerMessages()` una sola vez, en el nivel superior de un módulo compartido, como en el ejemplo anterior. Así se ejecuta cuando el módulo se carga por primera vez, tanto en el servidor como en el cliente. No lo llames de forma condicional ni dentro de funciones: ambas partes deben registrar siempre los mismos mensajes.
{% endhint %}

### Enviar mensajes

Los clientes solo pueden enviar mensajes al servidor. No hay comunicación directa entre clientes. El servidor puede transmitir mensajes a todos los clientes o dirigirlos a jugadores específicos mediante su dirección.

```typescript
import { room } from "./shared/messages"

// Client → Server (broadcast, server receives it)
room.send("playerReady", { displayName: "Alice" })

// Server → all clients
room.send("gameStarted", { roundNumber: 1 })

// Servidor → un cliente específico (por dirección de wallet)
room.send("gameEnded", { winnerId: "Alice" }, { to: [playerAddress] })
```

{% hint style="warning" %}
**📔 Nota**: Los mensajes tienen un tamaño máximo de aproximadamente 13 KB. El transporte descarta silenciosamente los mensajes más grandes, sin generar ningún error. Mantén los payloads pequeños; si necesitas compartir datos más grandes, divídelos en varios mensajes o usa componentes sincronizados.
{% endhint %}

### Recibir mensajes

```typescript
import { room } from "./shared/messages"

// El cliente recibe del servidor
room.onMessage("gameStarted", (data) => {
  console.log(`Round ${data.roundNumber} started!`)
})

// El servidor recibe del cliente
room.onMessage("playerReady", (data, context) => {
  if (!context) return
  const senderAddress = context.from // verified wallet address
  console.log(`[Server] ${data.displayName} is ready (${senderAddress})`)
})
```

En el servidor, cada mensaje recibido incluye un objeto `context` con la dirección de wallet verificada del remitente. Úsalo para saber qué jugador envió el mensaje (nunca confíes en una identidad declarada por el propio usuario en el payload).

`context.from` se recibe exactamente como la informa la red, sin cambios entre mayúsculas y minúsculas. Convierte el valor a minúsculas una sola vez (`context.from.toLowerCase()`) y usa ese valor en cada mapa, conjunto y llamada a Storage, para que los datos de un jugador no terminen divididos entre dos claves.

### Esperar a que se sincronice el estado antes de enviar

Los clientes deben esperar hasta que se sincronice el estado de la escena antes de enviar su primer mensaje, para evitar condiciones de carrera al unirse:

```typescript
import { engine } from "@dcl/sdk/ecs"
import { isStateSyncronized } from "@dcl/sdk/network"
import { room } from "./shared/messages"

engine.addSystem(() => {
  if (!isStateSyncronized()) return

  // Ahora es seguro enviar mensajes
  room.send("playerReady", { displayName: "Alice" })
})
```

{% hint style="info" %}
**💡 Consejo**: `isStateSyncronized()` solo indica que el estado del cliente está sincronizado; no garantiza que el servidor haya terminado de inicializarse. Para comprobar de forma más fiable que todo esté listo, haz que el servidor difunda un mensaje «ready» o de latido (heartbeat) y que los clientes esperen a recibirlo antes de enviar mensajes de juego.
{% endhint %}

### Tipos de esquema disponibles

Todos los payloads de mensajes y los componentes personalizados usan `Schemas` para la serialización binaria. Aquí tienes una referencia rápida de los tipos disponibles:

```typescript
import { Schemas } from "@dcl/sdk/ecs"

// Tipos básicos
Schemas.String // "hello"
Schemas.Int // 42
Schemas.Float // 3.14
Schemas.Boolean // true / false
Schemas.Int64 // Date.now()

// Tipos de vectores
Schemas.Vector3 // { x: 1, y: 2, z: 3 }
Schemas.Quaternion // { x, y, z, w }

// Tipos complejos
Schemas.Array(Schemas.String) // ["a", "b", "c"]
Schemas.Entity // referencia a Entity
Schemas.Optional(Schemas.String) // "hello" o undefined
Schemas.Optional(Schemas.Int) // 42 o undefined

// Objetos anidados
Schemas.Map({
  name: Schemas.String,
  health: Schemas.Int,
  position: Schemas.Vector3,
  playerId: Schemas.Optional(Schemas.String),
})
```

{% hint style="warning" %}
**📔 Nota**: Messages *deben* definirse mediante `Schemas.Map(...)`. No puedes enviar objetos JavaScript simples: fallará la serialización binaria.
{% endhint %}

## Lectura de las posiciones de los jugadores en el servidor

El servidor puede leer las **verificadas** posiciones de los jugadores; los clientes no pueden falsificarlas. Esta es la base de la protección contra trampas basada en la posición:

```typescript
import { engine, PlayerIdentityData, Transform } from "@dcl/sdk/ecs"

engine.addSystem(() => {
  for (const [entity, identity] of engine.getEntitiesWith(PlayerIdentityData)) {
    const transform = Transform.getOrNull(entity)
    if (!transform) continue

    const address = identity.address
    const position = transform.position
    // Esta posición está verificada por el servidor; nunca confíes en la posición informada por el cliente
  }
})
```

{% hint style="warning" %}
**📔 Nota**: Usa siempre `PlayerIdentityData` + `Transform` en el servidor para obtener las posiciones de los jugadores. Nunca confíes en los valores informados por el propio cliente.
{% endhint %}

## Almacenamiento de datos

Conserva los datos entre reinicios del servidor. El almacenamiento es **solo del servidor**; protege siempre las llamadas con `isServer()`. El servidor puede escribir y leer estos datos.

```typescript
import { Storage } from "@dcl/sdk/server"
```

Los datos se pueden almacenar en dos niveles:

* **World**: úsalo para datos relevantes para todos los jugadores, como las tablas de clasificación o los cambios persistentes en el entorno.
* **Player**: úsalo para datos específicos de un jugador, como guardar su progreso o sus preferencias.

{% hint style="info" %}
**💡 Consejo**: los valores de almacenamiento son JSON. Puedes almacenar un número, una cadena, una matriz o un objeto simple tal cual y recuperarlo con el mismo valor. No necesitas `JSON.stringify()` ni `JSON.parse()`. Hay dos excepciones: un `Date` se almacena como texto ISO (`"2026-10-27T13:05:12.000Z"`), y las propiedades de objeto cuyo valor es `undefined` se descartan. Un valor que guardaste anteriormente con `JSON.stringify()` es una cadena, así que se recupera como tal.

Durante el desarrollo local, los datos se escriben en `node_modules/@dcl/sdk-commands/.runtime-data/server-storage.json`.
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: Cómo informan de problemas las llamadas a Storage:

* `Storage.set()` y `Storage.player.set()` se resuelven en un valor **booleano**. `false` significa que el valor **no** se persistió, por ejemplo, debido a un error de red o cuando se ejecutan demasiadas solicitudes a la vez (consulta más abajo). Comprueba siempre el resultado: un `false` descartado es un guardado que se pierde sin aviso.
* `set()` lanza un `TypeError` cuando el valor no se puede almacenar como JSON sin cambios: `undefined`, `NaN` o `Infinity`, una función, un `Map` o un `Set`, entre otros. Para eliminar una clave, usa `delete()`.
* `get()` se resuelve con el valor almacenado o con `null` solo cuando la clave no existe. Si la lectura falla, se lanza una excepción, por lo que un fallo nunca se confunde con una clave inexistente.
* Las variantes de `delete()` lanzan una excepción cuando falla la solicitud. Se resuelven en `false` solo cuando la clave no existía.
  {% endhint %}

### Guarda en puntos de control, no con cada cambio

Storage ofrece persistencia duradera para los datos que deben sobrevivir a los reinicios y las nuevas implementaciones del servidor. No es un almacén de datos en tiempo real. Mantén el estado de juego activo en la memoria del servidor. Es más rápido y es el patrón adecuado para un servidor. Escribe en Storage solo cuando sea realmente necesario, en puntos de control importantes.

{% hint style="warning" %}
**⚠️ Advertencia**: El entorno de ejecución del servidor permite un máximo de **40 llamadas al host en curso** a la vez, compartidas entre *todo* lo que la escena le pide al entorno de ejecución: cada solicitud de almacenamiento, `signedFetch`y las demás API del entorno de ejecución cuentan para el mismo límite. Las llamadas que excedan el límite **no se ponen en cola**. Se rechazan inmediatamente con un error `too many concurrent host calls` El SDK captura el rechazo y resuelve el `Storage.set` promesa que devuelve `false` en lugar de lanzar una excepción. Si tu código descarta ese valor booleano, el fallo al guardar pasa inadvertido y los datos persistidos quedan desactualizados o se pierden. Comprueba el resultado de cada escritura (consulta la nota anterior).
{% endhint %}

Buenos momentos para guardar datos de forma persistente:

* Cuando termina el juego o una ronda.
* Cuando un jugador se va.
* Un guardado periódico con debounce (por ejemplo, una vez cada 30 segundos), no en cada frame.

Guarda de forma persistente solo los datos que deban sobrevivir a un reinicio o a un nuevo despliegue. Todo lo demás puede permanecer en memoria.

El siguiente ejemplo mantiene las puntuaciones en memoria y las escribe solo en un punto de control, en lugar de hacerlo cada vez que se anota un punto:

```typescript
import { Storage } from "@dcl/sdk/server"

// El estado de trabajo permanece en memoria y se actualiza con cada evento
const scores: Record<string, number> = {}

function onPointScored(address: string) {
  scores[address] = (scores[address] ?? 0) + 1
  // Aquí no se llama a Storage: solo se actualiza la memoria
}

// Guardar de forma persistente solo en un punto de control, como cuando un jugador se va
async function onPlayerLeave(address: string) {
  const saved = await Storage.player.set(address, "score", scores[address] ?? 0)
  if (!saved) {
    // La escritura no se guardó de forma persistente: conserva el valor en memoria y vuelve a intentarlo más tarde
    console.error(`Failed to save score for ${address}`)
  }
}
```

En escenas con muchos jugadores simultáneos, un enfoque más sólido consiste en llevar un registro de las claves que tienen cambios sin guardar (un «conjunto de elementos pendientes») y volver a intentar las escrituras fallidas en la siguiente operación de vaciado:

```typescript
import { engine } from "@dcl/sdk/ecs"
import { Storage } from "@dcl/sdk/server"

// Estado de trabajo en memoria, actualizado con cada evento
const scores: Record<string, number> = {}
const dirty = new Set<string>()

function onPointScored(address: string) {
  scores[address] = (scores[address] ?? 0) + 1
  dirty.add(address) // Marcar para vaciar más tarde; aquí no se llama a Storage
}

// Vaciar periódicamente las claves pendientes (p. ej., cada ~30 s) y en los puntos de control
async function flush() {
  for (const address of dirty) {
    const ok = await Storage.player.set(address, "score", scores[address])
    if (ok) {
      dirty.delete(address) // Se guardó correctamente
    }
    // Si ok es false, la clave sigue pendiente y se volverá a intentar en el siguiente vaciado
  }
}

// Ejecutar el vaciado con un temporizador que use un acumulador dt
let flushTimer = 0
engine.addSystem((dt) => {
  flushTimer += dt
  if (flushTimer > 30) {
    flushTimer = 0
    flush()
  }
})
```

### Almacenamiento de World: compartido por todos los jugadores

```typescript
import { Storage } from "@dcl/sdk/server"

type Entry = { name: string; score: number }

// Escritura: set() devuelve false si el valor NO se guardó de forma persistente
const ok = await Storage.set("leaderboard", [
  { name: "Alice", score: 100 },
  { name: "Bob", score: 85 },
])
if (!ok) {
  console.error("Failed to save leaderboard — retry later")
}

// Lectura: devuelve null cuando la clave no existe
const leaderboard = (await Storage.get<Entry[]>("leaderboard")) ?? []

// Eliminar
await Storage.delete("leaderboard")
```

También puedes administrar el almacenamiento de la escena mediante la línea de comandos con `npx sdk-commands storage scene`:

```bash
# Establecer un valor
npx sdk-commands storage scene set high_score --value 100

# Obtener un valor
npx sdk-commands storage scene get high_score

# Eliminar un valor
npx sdk-commands storage scene delete high_score

# Eliminar todos los datos de almacenamiento de la escena
npx sdk-commands storage scene clear --confirm
```

### Almacenamiento del jugador — por dirección de Wallet

```typescript
import { Storage } from "@dcl/sdk/server"

type Progress = { level: number; coins: number }

// Escritura: set() devuelve false si el valor NO se guardó de forma persistente
const ok = await Storage.player.set(playerAddress, "progress", {
  level: 5,
  coins: 250,
})
if (!ok) {
  console.error(`Failed to save progress for ${playerAddress} — retry later`)
}

// Leer: null cuando este jugador no tiene progreso guardado
const progress = (await Storage.player.get<Progress>(playerAddress, "progress")) ?? { level: 1, coins: 0 }

// Eliminar
await Storage.player.delete(playerAddress, "progress")
```

También puedes administrar el almacenamiento del jugador mediante la línea de comandos con `npx sdk-commands storage player`:

```bash
# Establecer un valor para un jugador específico
npx sdk-commands storage player set level --value 10 --address 0x1234...

# Obtener un valor para un jugador específico
npx sdk-commands storage player get level --address 0x1234...

# Eliminar un valor para un jugador específico
npx sdk-commands storage player delete level --address 0x1234...

# Eliminar todos los datos de un jugador específico
npx sdk-commands storage player clear --address 0x1234... --confirm

# Eliminar todos los datos de los jugadores
npx sdk-commands storage player clear --confirm
```

Cada valor de escena puede tener hasta 512 KB y todos los valores de escena de un World comparten 10 MB. Cada valor de jugador puede tener hasta 100 KB, con 1 MB por jugador.

{% hint style="warning" %}
**📔 Nota**: No hay forma de enumerar qué jugadores tienen datos almacenados. `Storage.player.getValues(address, { prefix, offset })` enumera las claves de un jugador que ya conoces, pero ni el SDK, ni los comandos `storage player` ni la [interfaz de almacenamiento](#access-stored-data) enumeran las direcciones de los jugadores. Si alguna vez necesitas recorrer todos tus jugadores, por ejemplo, para migrar sus partidas guardadas o crear una tabla de clasificación a partir de ellas, mantén también tu propio índice de direcciones en una clave de escena.
{% endhint %}

### Cargar una partida guardada sin sobrescribirla

Nunca asignes datos predeterminados cuando se une un jugador para luego guardarlos: si sus datos guardados existen, pero aún no se han cargado, los valores predeterminados los reemplazarán. Primero lee los datos y crea los valores predeterminados solo cuando `get()` se resuelva como `null`. Si la lectura genera un error, deja al jugador sin cargar e inténtalo de nuevo más tarde.

```typescript
import { Storage } from "@dcl/sdk/server"

type Save = { coins: number }
const saves: Record<string, Save> = {}

async function loadOrCreate(address: string): Promise<Save> {
  if (saves[address]) return saves[address] // Ya está cargado
  // Lanza un error si la lectura falla, para que un fallo nunca se convierta en un guardado nuevo
  const stored = await Storage.player.get<Save>(address, "save")
  saves[address] = stored ?? { coins: 0 } // Solo usa los valores predeterminados cuando no existe ningún guardado
  return saves[address]
}
```

Llámalo dentro de un `try/catch` en tu controlador de incorporación. Si lanza un error, avísale al cliente para que pueda volver a intentarlo e ignora las acciones de ese jugador hasta que se cargue su guardado.

### Progreso mientras no hay nadie en la Scene

No mantengas un temporizador en marcha para cosas que crecen con el tiempo, como cultivos, energía o la reposición de una tienda. El Multiplayer Server se detiene un par de minutos después de que se vaya el último jugador (consulta [Esperar a que el servidor se inicie](#wait-for-the-server-to-start-up)), así que el temporizador también se detiene. En su lugar, guarda la hora en que se actualizó el progreso por última vez. Cuando vuelva un jugador, calcula el progreso a partir del tiempo transcurrido y actualiza la hora guardada.

Usa el `Date.now()` del servidor para esto; nunca uses una hora enviada por un cliente: un jugador puede adelantar su reloj para saltarse la espera.

### Evitar la pérdida de datos con escrituras simultáneas

Storage no permite actualizar una clave solo si nadie la ha cambiado desde que la leíste (no hay «comparar e intercambiar»). Por eso, si lees una clave, cambias el valor y lo vuelves a escribir, puedes perder datos:

* Dos instancias del servidor pueden escribir al mismo tiempo. Esto ocurre cuando una versión antigua y una nueva de tu Scene se superponen durante una nueva implementación.
* Una lectura puede devolver un valor anterior al último que se escribió. Storage ha devuelto un valor antiguo de una clave durante una hora o más, incluso con `Storage.get(key, { fresh: true })`, y también después de reiniciar los servidores. La opción `fresh` solo omite la propia caché del SDK.
* Una lista obtenida con `Storage.getValues()` también puede estar desactualizada: podría omitir una clave escrita recientemente o seguir mostrando una que eliminaste.

Para los datos que solo aumentan, como un registro de resultados o los comentarios de los jugadores, usa este patrón en lugar de reescribir una sola clave:

1. Escribe cada instantánea en una **clave nueva** que se ordene por hora y no pueda coincidir con otra; por ejemplo, `results-1-20261027-130512-k3fz`: un prefijo, un número de parte, la hora UTC y algunos caracteres aleatorios.
2. Para leer, enumera todas las claves de la parte con `Storage.getValues({ prefix, offset })`, página por página, hasta obtener `pagination.total` entradas, y combínalas por ID de fila.
3. Escribe las filas combinadas como una clave nueva. Vuelve a leer esa clave y, solo si coincide, elimina las claves que combinaste. Nunca elimines una clave que otro escritor aún pueda modificar basándose en sus propias lecturas.

Así, una condición de carrera deja una clave extra, que se combinará en la siguiente escritura, en lugar de perder una fila. Quien lea los datos, incluso tú cuando los descargues desde la [interfaz de usuario de Storage](#access-stored-data), debe leer todas las claves de la parte y descartar los ID duplicados.

```typescript
import { Storage } from "@dcl/sdk/server"

type Row = { id: string; text: string }
const PREFIX = "results-1-"

// Todas las claves que comienzan con el prefijo, de la más antigua a la más reciente
async function listAll(prefix: string) {
  const entries: { key: string; value: unknown }[] = []
  for (;;) {
    const page = await Storage.getValues({ prefix, offset: entries.length })
    entries.push(...page.data)
    if (page.data.length === 0 || entries.length >= page.pagination.total) break
  }
  return entries.sort((a, b) => (a.key < b.key ? -1 : 1))
}

async function appendRows(newRows: Row[]): Promise<boolean> {
  const versions = await listAll(PREFIX)
  // Combinar por ID de fila; prevalece el primero encontrado
  const rows = new Map<string, Row>()
  for (const { value } of versions) for (const row of value as Row[]) if (!rows.has(row.id)) rows.set(row.id, row)
  for (const row of newRows) if (!rows.has(row.id)) rows.set(row.id, row)
  const merged = [...rows.values()]

  // Una clave nueva cada vez: hora UTC más caracteres aleatorios
  // "2026-10-27T13:05:12.123Z" se convierte en "20261027-130512"
  const stamp = new Date().toISOString().slice(0, 19).replace(/[-:]/g, "").replace("T", "-")
  const key = `${PREFIX}${stamp}-${Math.random().toString(36).slice(2, 6)}`
  if (!(await Storage.set(key, merged))) return false // No se guardó; vuelve a intentarlo más tarde

  // Eliminar las claves combinadas solo cuando se haya confirmado la lectura de la nueva
  const check = await Storage.get<Row[]>(key, { fresh: true })
  if (JSON.stringify(check) !== JSON.stringify(merged)) return true
  for (const version of versions) {
    try {
      await Storage.delete(version.key)
    } catch {
      // Se deja intacta: la siguiente escritura volverá a combinarla
    }
  }
  return true
}
```

Un valor puede ocupar como máximo 512 KB, así que crea una nueva parte (`results-2-`) antes de que una parte se acerque a ese límite. El ejemplo de [Scene Feedback](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/0%2C-1-scene-feedback) usa este patrón para sus archivos CSV y crea una nueva parte al llegar a 400 KB.

### Acceder a los datos almacenados

Puedes ver y editar los datos almacenados en vivo en tu servidor desde la UI de almacenamiento. Para ello, abre este enlace:

[decentraland.org/storage](https://decentraland.org/storage)

Si se trata de un World, también puedes acceder a esta página desde Creator Hub. Abre la página **Manage** haz clic en los tres puntos de la tarjeta del World y selecciona **View Storage**.

Ahí puedes ver una lista de todos los Worlds y terrenos donde puedes publicar escenas.

Abre tu escena y luego la pestaña **Scene** o **Player** .

En la pestaña **Scene** verás una lista de todas las variables almacenadas. Desde aquí puedes editar o eliminar cualquiera de ellas haciendo clic en el icono del lápiz o de la papelera.

![Activate stream](https://1216664193-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-bbb302fbdb29f57fdcff7bf62fc6608838a06d44%2Fscene-data.webp?alt=media)

En la pestaña **Player** verás una lista de todos los jugadores que tienen datos almacenados en tu servidor. Puedes buscarlos por dirección o nombre y luego ver todos los datos asociados. También puedes editar o eliminar estos datos haciendo clic en el icono del lápiz o de la papelera.

### Cambiar la estructura de los datos

Los datos almacenados en producción **no se borran al publicar una nueva versión de la escena**. Esto es ideal para tablas de clasificación, el progreso de los jugadores y los cambios persistentes del entorno que los jugadores esperan que se mantengan después de pequeñas actualizaciones de la escena.

Por otro lado, los datos que hay en el almacenamiento se escribieron con una versión anterior del código. Si el código nuevo espera una estructura distinta, analizar o leer los datos antiguos puede fallar de maneras sutiles. Faltará cualquier campo al que le hayas cambiado el nombre. Un campo que antes era una cadena y ahora es un objeto provocará un error al intentar acceder a una de sus propiedades. Un jugador que no haya iniciado sesión durante meses podría cargar datos anteriores a una estructura que tu código ya no sabe manejar.

{% hint style="warning" %}
**📔 Nota**: Los cambios de esquema no afectan solo a la primera lectura después de una implementación. Los datos almacenados permanecen hasta que se sobrescriben o eliminan, por lo que un valor con un formato antiguo puede aparecer en cualquier momento, a menudo cuando regresa un jugador del que ya te habías olvidado.
{% endhint %}

#### Prácticas recomendadas

* *Lee siempre con cautela*. Considera que todo lo que proviene del almacenamiento es una entrada no confiable, aunque lo hayas escrito tú. El tipo que pasas a `get<T>()` no se comprueba, así que verifica que los campos existan y tengan el tipo correcto antes de leerlos, y ten preparado un valor predeterminado razonable por si no es así:

  ```typescript
  import { Storage } from "@dcl/sdk/server"

  const saved = await Storage.player.get<any>(playerAddress, "progress")
  const progress = {
    level: typeof saved?.level === "number" ? saved.level : 1,
    coins: typeof saved?.coins === "number" ? saved.coins : 0,
  }
  ```
* *Añade campos; no los renombres ni los elimines*. El cambio de esquema más seguro es uno aditivo: introduce un campo nuevo con un valor predeterminado y deja intactos los campos existentes. A los datos antiguos simplemente les faltará el campo nuevo, algo que tu análisis defensivo ya contempla. Renombrar un campo hace que todos los registros antiguos dejen de funcionar.
* *Versiona los objetos almacenados*. Incluye un campo `version` desde el primer día. Al leer los datos, ramifica según la versión y migra las estructuras antiguas a la actual antes de usarlas. Así, el resto del código puede trabajar con una única estructura actual:

  ```typescript
  type ProgressV2 = { version: 2; level: number; coins: number; xp: number }

  function migrate(raw: any): ProgressV2 {
    const version = raw?.version ?? 1
    if (version === 1) {
      // v1 no tenía el campo xp: asígnale un valor predeterminado
      return {
        version: 2,
        level: raw.level ?? 1,
        coins: raw.coins ?? 0,
        xp: 0,
      }
    }
    return raw as ProgressV2
  }
  ```
* *Vuelve a guardar el valor migrado*. Una vez que hayas actualizado un registro en memoria, guárdalo para que la próxima lectura ya lo encuentre en el formato nuevo. Con el tiempo, esto reduce el conjunto de registros con la estructura antigua, sin necesidad de ejecutar un script de migración de una sola vez.
* *Para cambios incompatibles, usa una clave nueva*. Si la nueva estructura es realmente incompatible y no vale la pena migrarla, escribe en una nueva clave de almacenamiento (por ejemplo, `progress_v2`) e ignora la anterior. La clave antigua permanece sin causar problemas en el almacenamiento y evitas cualquier ruta de lectura que tenga que interpretarla. Más adelante, puedes limpiar las claves antiguas mediante la [interfaz de usuario de almacenamiento](https://decentraland.org/storage) o con los `npx sdk-commands storage` comandos.
* *Prueba con datos reales de producción*. Antes de implementar un cambio estructural, obtén algunos registros reales desde la interfaz de usuario de almacenamiento y prueba con ellos el nuevo código de análisis. Los casos límite que causan problemas suelen ser registros cuya existencia desconocías.
* *Deja una vía de escape*. Recuerda que puedes editar o eliminar registros individuales desde la interfaz de usuario de almacenamiento o mediante `npx sdk-commands storage`. Si tras un cambio de esquema un jugador queda en un estado problemático, puedes corregir su registro directamente sin volver a implementar la escena.

## Variables de entorno

Configura tu escena sin codificar valores directamente en el código. Las variables de entorno son útiles para datos confidenciales, así como para indicadores de funciones o parámetros que se pueden cambiar fácilmente sin volver a publicar la escena.

Las variables de entorno son **solo del servidor**. Protégelas con `isServer()`. El servidor puede leer las variables de entorno, pero no cambiar sus valores.

`EnvVar.get()` devuelve un `Promise<string>` y se resuelve en una cadena vacía cuando la variable no está definida, así que proporciona siempre un valor alternativo para los valores que falten:

```typescript
import { EnvVar } from "@dcl/sdk/server"
import { isServer } from "@dcl/sdk/network"

export async function main() {
  if (!isServer()) return

  const maxPlayers = parseInt((await EnvVar.get("MAX_PLAYERS")) || "4")
  const gameDuration = parseInt((await EnvVar.get("GAME_DURATION")) || "300")
  const debugMode = ((await EnvVar.get("DEBUG")) || "false") === "true"
}
```

### Datos sensibles

Las variables de entorno son especialmente útiles para almacenar claves privadas, códigos para reclamar recompensas y otros datos sensibles que sería arriesgado exponer en el código compilado de la escena pública.

Puedes almacenar las claves privadas en el almacenamiento del servidor y hacer que solo el servidor las lea con `isServer()`. De esta forma, los datos sensibles nunca pasan por el equipo del jugador.

### Desarrollo local

Para usar variables de entorno mientras ejecutas el proyecto localmente, crea un archivo `.env` en la raíz del proyecto:

```
MAX_PLAYERS=8
GAME_DURATION=300
DEBUG=true
```

Importante: Añade `.env` a tu `.gitignore`, para que estos valores potencialmente sensibles nunca se suban a los servidores de contenido públicos.

### Cambiar las variables de entorno

La forma más sencilla de cambiar los valores de las variables de entorno es mediante la UI de almacenamiento.

Puedes acceder a los datos almacenados por el almacenamiento de la escena con este enlace:

[decentraland.org/storage](https://decentraland.org/storage)

Si se trata de un World, también puedes acceder a esta página desde Creator Hub. Abre la página **Manage** haz clic en los tres puntos de la tarjeta del World y selecciona **View Storage**.

Ahí puedes ver una lista de todos los Worlds y terrenos donde puedes publicar escenas.

Abre la escena y, a continuación, la pestaña **Entorno** . Deberías ver todas las variables de entorno del proyecto.

![Activate stream](https://1216664193-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-766c8433de10c67980a737242d867ad3c4fb5948%2Fenvironment-variables.webp?alt=media)

Ten en cuenta que no puedes leer los valores de estas variables de entorno (para proteger los datos sensibles), pero sí puedes eliminarlas o sobrescribirlas. Solo tienes que hacer clic en el icono del lápiz o de la papelera.

También puedes gestionar las variables de entorno desde la línea de comandos, usando `npx sdk-commands storage env`:

```bash
# Establecer una variable
npx sdk-commands storage env set MAX_PLAYERS --value 8

# Eliminar una variable
npx sdk-commands storage env delete OLD_VAR

# Eliminar todas las variables de entorno
npx sdk-commands storage env clear --confirm
```

También puedes indicar un entorno específico con la `--target` opción:

```bash
# Implementar en el entorno de pruebas
npx sdk-commands storage env set MY_KEY --value my_value --target https://storage.decentraland.zone

# Implementar en un servidor de desarrollo local
npx sdk-commands storage env set MY_KEY --value my_value --target http://localhost:8000
```

Las variables de entorno implementadas tienen prioridad sobre los valores de `.env` .

## Estructura recomendada del proyecto

Separar el código del servidor, del cliente y el código compartido mantiene la base de código legible a medida que crece:

```
src/
├── index.ts              # Punto de entrada — rama isServer()
├── client/
│   ├── setup.ts          # Manejadores de entrada, emisores de mensajes
│   └── ui.tsx            # UI de React ECS (lee el estado sincronizado)
├── server/
│   ├── server.ts         # Bucle del juego, manejadores de mensajes, mutaciones de estado
│   └── gameState.ts      # Funciones auxiliares para el estado del servidor
└── shared/
    ├── schemas.ts        # Definiciones de Component + validateBeforeChange
    └── messages.ts       # registerMessages() — importado por ambos lados
```

{% hint style="info" %}
**💡 Consejo**: Mantén todas las llamadas a `registerMessages()` y las definiciones de Component personalizadas en `shared/`. Tanto el servidor como el cliente importan desde allí, lo que garantiza que siempre coincidan en los esquemas de mensajes.
{% endhint %}

## Prácticas recomendadas de rendimiento

Cada cambio en un Component envía por la red los datos *completos* del Component. Esto es diferente de lo que hace Colyseus, que solo envía las diferencias. Tenlo en cuenta al diseñar Components personalizados. La solución óptima puede ser almacenar los datos en Components separados según la frecuencia con que cambien.

### ❌ Evita los Components monolíticos

```typescript
import { engine, Schemas } from "@dcl/sdk/ecs"

// MAL — cambiar la puntuación también envía el array de posiciones
const GameState = engine.defineComponent("GameState", {
  playerAScore: Schemas.Int,
  playerBScore: Schemas.Int,
  timer: Schemas.Int,
  playerPositions: Schemas.Array(Schemas.Vector3), // carga útil grande
})
```

### ✅ Es preferible usar Components atómicos

```typescript
import { engine, Schemas } from "@dcl/sdk/ecs"

// BIEN — cada actualización es pequeña e independiente
const PlayerScore = engine.defineComponent("PlayerScore", {
  playerA: Schemas.Int,
  playerB: Schemas.Int,
})

const GameTimer = engine.defineComponent("GameTimer", {
  secondsLeft: Schemas.Int,
})
```

*Regla general*: agrupa los campos que cambian juntos y con una frecuencia similar. Separa los datos que cambian rápidamente (temporizadores, posiciones) de los que cambian lentamente (puntuaciones, configuración).

### Limita la frecuencia de los mensajes

Evita enviar mensajes en cada frame. Agrúpalos o limita su frecuencia cuando sea posible:

```typescript
import { engine } from "@dcl/sdk/ecs"
import { room } from "./shared/messages"

let lastSend = 0
engine.addSystem((dt) => {
  lastSend += dt
  if (lastSend > 0.1) {
    // cada 100 ms
    room.send("position", transform.position)
    lastSend = 0
  }
})
```

Por ejemplo, si el servidor controla una cuenta regresiva, no es necesario enviar actualizaciones a todos los jugadores cada segundo. Lo mejor es que cada cliente calcule por su cuenta el paso del tiempo y que el servidor difunda su estado actual cada 30 segundos aproximadamente para garantizar la coherencia.

## Límites de recursos del servidor

El servidor multijugador ejecuta cada Scene en un entorno aislado (isolate) con límites estrictos de recursos. Superar estos límites puede provocar que se descarten datos sin aviso o que el servidor se cierre para todos los participantes de la Scene, así que diseña tu Scene para mantenerte holgadamente dentro de ellos.

### Memoria

El isolate tiene un **256 MB** límite de memoria. Si se supera, se descarta el isolate y el servidor se apaga para todos los jugadores conectados. Mantén reducido el estado de trabajo y elimina los datos de cada jugador cuando se vaya.

### CPU

Cada turno de ejecución tiene un límite de tiempo de reloj:

* **Ejecución síncrona**: 10 segundos por turno. Un bucle sin límite que supere este tiempo provoca la finalización del isolate.
* **Finalización de turnos asíncronos**: 60 segundos. Si una cadena de `Promise` o un `await` tarda más en resolverse, el isolate se termina.

Distribuye el trabajo pesado en varios ticks usando un acumulador `dt` en `engine.addSystem()`. Nunca ejecutes bucles síncronos sin límite en el servidor.

### Frecuencia de mensajes entrantes

Cada peer conectado puede enviar hasta aproximadamente **300 mensajes por cada 1.000 ms**. Los paquetes de datos que superen el límite se descartan (no se ponen en cola). Nunca envíes mensajes desde el cliente en cada frame. Consulta [Prácticas recomendadas de rendimiento](#performance-best-practices) para ver patrones de limitación de frecuencia.

### Tamaño de los mensajes

* El tamaño de los paquetes entrantes está limitado a **128 KB** por paquete. Los paquetes que superen este tamaño se descartan por completo.
* El tamaño de los mensajes de la escena a comms está limitado a aproximadamente **30 KB**. Para el transporte práctico, mantén los mensajes sincronizados muy por debajo de **13 KB** (consulta la sección [Messages](#messages) ).

### Solicitudes externas

Las llamadas `signedFetch` simultáneas están limitadas a **32** en curso. Las solicitudes adicionales se ponen en cola hasta que se libera un espacio. Cada intento de solicitud tiene un tiempo de espera de **15 segundos** . Las respuestas de las solicitudes están limitadas a **10 MB**. Las conexiones WebSocket están limitadas a **32** sockets simultáneos, con un tamaño máximo de mensaje de **1 MB** por mensaje.

### Llamadas al host en curso

El límite de 40 llamadas descrito en [Almacenamiento de datos](#data-storage) se aplica a todas las llamadas al host en todo el isolate, incluidas las de Storage, `signedFetch`y otras API del runtime. Las llamadas que excedan el límite se rechazan de inmediato y no se ponen en cola.

## Errores comunes

### Olvidar la validación en el estado exclusivo del servidor

Sin `validateBeforeChange`, los clientes pueden escribir en cualquier componente:

```typescript
import { engine, Schemas } from "@dcl/sdk/ecs"
import { isServer } from "@dcl/sdk/network"
import { AUTH_SERVER_PEER_ID } from "@dcl/sdk/network/message-bus-sync"

// ❌ MAL: los clientes pueden hacer trampa
const Score = engine.defineComponent("Score", { value: Schemas.Int })

// ✅ BIEN: exclusivo del servidor
if (isServer()) {
  Score.validateBeforeChange((v) => v.senderAddress === AUTH_SERVER_PEER_ID)
}
```

### Confiar en los valores proporcionados por el cliente

Nunca permitas que un cliente determine sus propios valores para datos importantes como la salud, la puntuación o la posición:

```typescript
import { room } from "./shared/messages"

// ❌ MAL
room.onMessage("setHealth", (data) => {
  player.health = data.health // ¡el cliente controla el valor!
})

// ✅ BIEN: el servidor calcula el resultado
room.onMessage("takeDamage", (data) => {
  const damage = calculateDamage(data.source)
  player.health = Math.max(0, player.health - damage)
})
```

### Confiar en los importes y las direcciones de los mensajes

Un mensaje de un cliente es una solicitud, no un hecho. Comprueba cada campo antes de usarlo:

* **Importes**: `Schemas.Int` decodifica el valor como un entero de 32 bits, pero este aún puede ser cero o negativo. Rechaza los importes iguales o inferiores a cero; de lo contrario, un jugador podría «enviar» `-500` monedas y recibirlas en su lugar. Comprueba también que el remitente tenga suficientes monedas.
* **Direcciones**: una dirección de Wallet enviada por el cliente debe ser `0x` seguido de 40 caracteres hexadecimales. Rechaza cualquier otro valor antes de que llegue a tus mapas o a Storage.

```typescript
import { room } from "./shared/messages"

const ADDRESS = /^0x[0-9a-f]{40}$/
const balances: Record<string, number> = {}

room.onMessage("giveCoins", (data, context) => {
  if (!context) return
  const from = context.from.toLowerCase()
  const to = String(data.to).toLowerCase()
  if (!ADDRESS.test(to) || to === from) return
  if (!Number.isInteger(data.amount) || data.amount <= 0) return // Rechaza negativos y cero
  if ((balances[from] ?? 0) < data.amount) return // No hay suficientes monedas
  balances[from] -= data.amount
  balances[to] = (balances[to] ?? 0) + data.amount
})
```

### Enviar mensajes antes de que se sincronice el estado

Los clientes deben esperar a que se sincronice el estado antes de interactuar:

```typescript
import { engine } from "@dcl/sdk/ecs"
import { isStateSyncronized } from "@dcl/sdk/network"

engine.addSystem(() => {
  if (!isStateSyncronized()) return
  // ya es seguro enviar mensajes
})
```

### Espera a que el servidor se inicie

El servidor solo está activo mientras haya al menos un jugador en la escena. Cuando se va el último jugador, el servidor permanece activo aproximadamente dos minutos y luego se apaga. La siguiente visita inicia una instancia nueva desde cero, lo que tarda aproximadamente **15 segundos en producción**. La vista previa local inicia el servidor al instante, por lo que los problemas de arranque en frío casi siempre solo aparecen después de publicar.

El código de tu escena debe estar preparado para esperar a que el servidor esté disponible. Los mensajes enviados antes de que el servidor termine de iniciarse se pierden sin aviso. Mientras esperas, muestra al jugador un mensaje como «el servidor se está iniciando» y añade lógica de reintento a las solicitudes iniciales al servidor.

{% hint style="info" %}
**Consejo:** Una forma fiable de detectar que el servidor está listo es usar un heartbeat: haz que el servidor escriba `Date.now()` a un campo de componente sincronizado cada 2 segundos, y hacer que el cliente registre cuándo vio por última vez un cambio en el valor. Si no llega ningún cambio en 6 segundos, considera que el servidor está desconectado. Esto es más robusto que `isStateSyncronized()`, que solo confirma que el transporte está conectado, no que el servidor esté en ejecución.
{% endhint %}

## Ejemplo completo

Un contador multijugador mínimo: haz clic en un botón y el servidor incrementa una puntuación sincronizada. El servidor guarda el contador en `Storage` para que el valor se conserve al reiniciar el servidor. Recuerda que el servidor se apaga cuando no hay jugadores en la escena, así que, sin almacenamiento, el contador volvería a cero cada vez que la escena se quedara sin jugadores.

```typescript
import { engine, Schemas } from "@dcl/sdk/ecs"
import { registerMessages, isServer, syncEntity } from "@dcl/sdk/network"
import { AUTH_SERVER_PEER_ID } from "@dcl/sdk/network/message-bus-sync"
import { pointerEventsSystem } from "@dcl/sdk/ecs"
import { Storage } from "@dcl/sdk/server"

// 1. Define los mensajes (compartidos)
const Messages = {
  increment: Schemas.Map({}),
  stateUpdate: Schemas.Map({
    count: Schemas.Int,
    lastPlayer: Schemas.String,
  }),
}

// 2. Define un componente exclusivo del servidor (compartido)
const Counter = engine.defineComponent("Counter", {
  value: Schemas.Int,
  lastPlayer: Schemas.String,
})

// 3. Crea la sala
const room = registerMessages(Messages)

export async function main() {
  if (isServer()) {
    // === SERVIDOR ===

    // Only the server can modify this component
    Counter.validateBeforeChange(
      (v) => v.senderAddress === AUTH_SERVER_PEER_ID
    )

    // Restaura el contador desde el almacenamiento por si se reinició el servidor
    let initialCount = 0
    let initialPlayer = "none"
    let loaded = false
    try {
      initialCount = (await Storage.get<number>("counter")) ?? 0
      initialPlayer = (await Storage.get<string>("lastPlayer")) ?? "none"
      loaded = true
    } catch (error) {
      console.log("[Server] Could not load the counter:", error)
    }

    const counterEntity = engine.addEntity()
    syncEntity(counterEntity, [Counter.componentId], 1)
    Counter.create(counterEntity, {
      value: initialCount,
      lastPlayer: initialPlayer,
    })

    room.onMessage("increment", async (_data, context) => {
      if (!context) return
      if (!loaded) return // Never save over a counter that didn't load
      const from = context.from.toLowerCase()
      const counter = Counter.getMutable(counterEntity)
      counter.value += 1
      counter.lastPlayer = from

      // Guarda en el almacenamiento para que el valor se conserve al reiniciar el servidor
      const saved =
        (await Storage.set("counter", counter.value)) &&
        (await Storage.set("lastPlayer", from))
      if (!saved) console.log("[Server] Counter not saved, the next click saves it again")

      room.send("stateUpdate", {
        count: counter.value,
        lastPlayer: from,
      })
    })
  } else {
    // === CLIENT ===
    const button = engine.addEntity()
    // ... add Transform, MeshRenderer, etc.

    pointerEventsSystem.onPointerDown(button, () => {
      room.send("increment", {})
    })

    room.onMessage("stateUpdate", (data) => {
      console.log(`Count: ${data.count} (last click by ${data.lastPlayer})`)
    })
  }
}
```

## Pruebas en local

La vista previa estándar se encarga de todo. Al usar la rama auth-server del SDK, el servidor local se inicia automáticamente en segundo plano junto con la vista previa del cliente.

Para probar interacciones multijugador en local, abre la vista previa en dos ventanas separadas; cada ventana se considera un jugador distinto. Conecta cada ventana con una dirección diferente. Ambos clientes se conectarán a la misma instancia del servidor local.

En Creator Hub, activa **Multi-Instance Preview** en el submenú **Desktop Client** de **Play Options**, y luego haz clic por segunda vez en el botón **Play** para abrir una segunda ventana de Decentraland Explorer. Debes conectarte en ambas ventanas con direcciones distintas. Las mismas sesiones permanecerán abiertas cuando se vuelva a cargar la escena.

Como alternativa, puedes abrir una segunda ventana del Explorer de Decentraland escribiendo lo siguiente en la URL del navegador:

> `decentraland://realm=http://127.0.0.1:8000&local-scene=true&debug=true&multi-instance=true`

### Consejos para depurar

* *Añade un prefijo a tus registros* con `[SERVER]` o `[CLIENT]` para distinguirlos en la terminal:

  ```typescript
  import { isServer } from "@dcl/sdk/network"

  if (isServer()) {
    console.log("[SERVER] Starting...")
  } else {
    console.log("[CLIENT] Starting...")
  }
  ```
* *Verifica la sincronización de Component* en el cliente registrando la cantidad de Entities:

  ```typescript
  import { engine } from "@dcl/sdk/ecs"

  engine.addSystem(() => {
    const entities = Array.from(engine.getEntitiesWith(MyComponent))
    console.log("[CLIENT] Synced entities:", entities.length)
  })
  ```

## Depurar en producción

Usa [Scene Insights](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/depuracion/scene-insights.md) para buscar registros publicados del servidor, consultarlos en tiempo real y obtener métricas de CPU, memoria y otras. Los registros y las métricas se conservan durante **7 días**, incluso después de reinicios y nuevas implementaciones.

Actualiza a la versión más reciente del `auth-server` SDK y, a continuación, ejecuta estos comandos desde el proyecto de tu escena:

```bash
npx sdk-commands scene-insights login
npx sdk-commands scene-insights tail
```

Inicia sesión con una Wallet autorizada en el navegador. La sesión de solo lectura se reutiliza para los comandos posteriores durante un máximo de 12 horas. Pulsa **Ctrl+C** para dejar de consultar los registros.

La guía de [Scene Insights](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/depuracion/scene-insights.md) abarca las búsquedas históricas, la selección de escenas, los permisos de acceso, las métricas, la depuración asistida por IA y los límites de recopilación.

### Ver los datos de almacenamiento

Puedes acceder a los datos almacenados por el almacenamiento de la escena con este enlace:

[decentraland.org/storage](https://decentraland.org/storage)

Si se trata de un World, también puedes acceder a esta página desde Creator Hub. Abre la página **Manage** haz clic en los tres puntos de la tarjeta del World y selecciona **View Storage**.

Ahí puedes ver una lista de todos los Worlds y terrenos donde puedes publicar escenas.

Abre los datos del World o del jugador para ver la información almacenada de cada uno.

Por ejemplo, si un jugador tiene un problema al jugar en tu escena, puedes buscarlo por su dirección y ver qué datos tiene almacenados para comprender su situación. Quizá se topó con un caso límite que hizo que acabara con datos contradictorios. Incluso puedes borrar o editar los datos de ese jugador desde esta página para restablecer un estado estable.

## Control de versiones

Cada versión publicada de tu escena obtiene un ID hash único, y cada hash está asociado a su propia instancia del servidor. Esto significa que el código del cliente y el del servidor siempre se actualizan juntos; no hay ningún intervalo en el que un cliente que ejecuta una lógica antigua se comunique con un servidor que ejecuta una lógica nueva (ni viceversa).

Al publicar una actualización:

* *Los jugadores que ya están en la escena* siguen viendo la versión antigua de la escena hasta que salen y vuelven a entrar. Sus clientes permanecen conectados a la instancia del servidor que corresponde al hash antiguo.
* *Los nuevos jugadores que llegan* después de la actualización cargan la nueva versión de la escena y se conectan a la nueva instancia del servidor.

Esto garantiza que el estado del cliente y del servidor nunca se desincronice debido a un cambio de esquema o al cambio de nombre de un Component. Una actualización nunca puede interrumpir la sesión de un jugador que ya está en tu Scene.

La contrapartida es que, durante un breve período justo después de un Deploy, los jugadores pueden quedar repartidos entre dos instancias de Server diferentes. Es posible que un jugador que ya estaba allí y otro que acaba de llegar no se vean ni puedan interactuar a través de la Scene, aunque estén en la misma Scene, hasta que los jugadores de la instancia anterior se vayan y vuelvan a entrar.

{% hint style="info" %}
**💡 Consejo**: Los datos almacenados mediante el servicio [Storage](#data-storage) (como tablas de clasificación, el progreso de los jugadores o los cambios persistentes en el entorno) *no* se eliminan entre versiones. Storage se conserva en la ubicación y se comparte entre todas las instancias de Server que apuntan a la misma Scene, por lo que las nuevas versiones continúan justo donde terminó la anterior.
{% endhint %}

## Migrar desde Colyseus

Si tienes una Scene existente creada con Colyseus, la tabla siguiente relaciona los patrones comunes de Colyseus con sus equivalentes en SDK7:

| Colyseus                             | Multiplayer Server de SDK7                            |
| ------------------------------------ | ----------------------------------------------------- |
| `room.send(type, data)`              | `room.send(type, data)` — la misma API                |
| `room.onMessage(type, cb)`           | `room.onMessage(type, cb)` — la misma API             |
| `room.state.players` (schema)        | `syncEntity` + Components personalizados              |
| Serialización JSON                   | Serialización binaria (automática mediante `Schemas`) |
| Aplicación de Server independiente   | Misma base de código — `isServer()` ramificación      |
| Alojamiento personalizado del Server | Integrado: Preview ejecuta el Server automáticamente  |

Diferencias clave que debes tener en cuenta:

* *Serialización*: Colyseus envía diferencias de JSON; SDK envía el Component completo con cada cambio. Mantén los Components pequeños (consulta [Prácticas recomendadas de rendimiento](#performance-best-practices)).
* *Modelo de estado*: Colyseus utiliza un árbol de estado mutable con detección automática de diferencias. SDK utiliza Components de ECS sincronizados mediante `syncEntity` y protegidos con `validateBeforeChange`.
* *Alojamiento*: No se necesita una implementación independiente del Server. El Multiplayer Server se implementa automáticamente junto con la Scene.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/networking/authoritative-servers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
