@dcl-regenesislabs/opendcl 0.1.4 → 0.1.5-23161709858.commit-828c176

package/skills/animations-tweens/SKILL.md

@@ -1,10 +1,24 @@
 ---
 name: animations-tweens
-description: Animate objects in Decentraland scenes using Animator (GLTF animations), Tween (move/rotate/scale over time), and TweenSequence (chain animations). Use when user wants to animate, move, rotate, spin, slide, or create motion effects.
+description: Animate objects in Decentraland scenes. Play GLTF model animations with Animator, create procedural motion with Tween (move/rotate/scale), and chain sequences with TweenSequence. Use when the user wants to animate, move, rotate, spin, slide, bob, or create motion effects. Do NOT use for audio/video playback (see audio-video).
 ---
 
 # Animations and Tweens in Decentraland
 
+## When to Use Which Animation Approach
+
+| Need | Approach | When |
+|------|----------|------|
+| Play animation baked into a .glb model | `Animator` | Character walks, door opens, flag waves — any animation created in Blender/Maya |
+| Move/rotate/scale an entity smoothly | `Tween` | Sliding doors, floating platforms, growing objects — procedural A-to-B motion |
+| Chain multiple animations in sequence | `TweenSequence` | Patrol paths, multi-step doors, complex choreography |
+| Continuous per-frame control | `engine.addSystem()` | Physics-like motion, following a target, custom easing |
+
+**Decision flow:**
+1. Does the .glb model already have the animation? → `Animator`
+2. Is it a simple move/rotate/scale between two values? → `Tween`
+3. Do you need frame-by-frame control or custom math? → System with `dt`
+
 ## GLTF Animations (Animator)
 
 Play animations embedded in .glb models:
@@ -67,7 +81,7 @@ Tween.create(box, {
     end: Vector3.create(14, 1, 8)
   }),
   duration: 2000,  // milliseconds
-  easingFunction: EasingFunction.EF_EASEINOUTSINE
+  easingFunction: EasingFunction.EF_EASESINE
 })
 ```
 
@@ -100,7 +114,7 @@ Tween.create(box, {
 Chain multiple tweens to play one after another:
 
 ```typescript
-import { TweenSequence } from '@dcl/sdk/ecs'
+import { TweenSequence, TweenLoop } from '@dcl/sdk/ecs'
 
 // First tween
 Tween.create(box, {
@@ -109,7 +123,7 @@ Tween.create(box, {
     end: Vector3.create(14, 1, 8)
   }),
   duration: 2000,
-  easingFunction: EasingFunction.EF_EASEINOUTSINE
+  easingFunction: EasingFunction.EF_EASESINE
 })
 
 // Chain sequence
@@ -122,7 +136,7 @@ TweenSequence.create(box, {
         end: Vector3.create(2, 1, 8)
       }),
       duration: 2000,
-      easingFunction: EasingFunction.EF_EASEINOUTSINE
+      easingFunction: EasingFunction.EF_EASESINE
     }
   ],
   loop: TweenLoop.TL_RESTART // Loop the entire sequence
@@ -133,12 +147,16 @@ TweenSequence.create(box, {
 
 Available easing functions from `EasingFunction`:
 - `EF_LINEAR` — Constant speed
-- `EF_EASEINQUAD` / `EF_EASEOUTQUAD` / `EF_EASEINOUTQUAD` — Quadratic
-- `EF_EASEINSINE` / `EF_EASEOUTSINE` / `EF_EASEINOUTSINE` — Sinusoidal (smooth)
-- `EF_EASEINEXPO` / `EF_EASEOUTEXPO` / `EF_EASEINOUTEXPO` — Exponential
-- `EF_EASEINELASTIC` / `EF_EASEOUTELASTIC` / `EF_EASEINOUTELASTIC` — Elastic bounce
-- `EF_EASEOUTBOUNCE` / `EF_EASEINBOUNCE` / `EF_EASEINOUTBOUNCE` — Bounce effect
-- `EF_EASEINBACK` / `EF_EASEOUTBACK` / `EF_EASEINOUTBACK` — Overshoot
+- `EF_EASEINQUAD` / `EF_EASEOUTQUAD` / `EF_EASEQUAD` — Quadratic
+- `EF_EASEINSINE` / `EF_EASEOUTSINE` / `EF_EASESINE` — Sinusoidal (smooth)
+- `EF_EASEINEXPO` / `EF_EASEOUTEXPO` / `EF_EASEEXPO` — Exponential
+- `EF_EASEINELASTIC` / `EF_EASEOUTELASTIC` / `EF_EASEELASTIC` — Elastic bounce
+- `EF_EASEOUTBOUNCE` / `EF_EASEINBOUNCE` / `EF_EASEBOUNCE` — Bounce effect
+- `EF_EASEINBACK` / `EF_EASEOUTBACK` / `EF_EASEBACK` — Overshoot
+- `EF_EASEINCUBIC` / `EF_EASEOUTCUBIC` / `EF_EASECUBIC` — Cubic
+- `EF_EASEINQUART` / `EF_EASEOUTQUART` / `EF_EASEQUART` — Quartic
+- `EF_EASEINQUINT` / `EF_EASEOUTQUINT` / `EF_EASEQUINT` — Quintic
+- `EF_EASEINCIRC` / `EF_EASEOUTCIRC` / `EF_EASECIRC` — Circular
 
 ## Custom Animation Systems
 
@@ -165,28 +183,28 @@ engine.addSystem(spinSystem)
 
 ### Tween Helper Methods
 
-Use shorthand helpers instead of creating Tween components manually:
+Use shorthand helpers that create or replace the Tween component directly on the entity:
 
 ```typescript
 import { Tween, EasingFunction } from '@dcl/sdk/ecs'
 
-// Move
-Tween.createOrReplace(entity, Tween.setMove(
+// Move — signature: Tween.setMove(entity, start, end, duration, easingFunction?)
+Tween.setMove(entity,
   Vector3.create(0, 1, 0), Vector3.create(0, 3, 0),
-  { duration: 1500, easingFunction: EasingFunction.EF_EASEINBOUNCE }
-))
+  1500, EasingFunction.EF_EASEINBOUNCE
+)
 
-// Rotate
-Tween.createOrReplace(entity, Tween.setRotate(
+// Rotate — signature: Tween.setRotate(entity, start, end, duration, easingFunction?)
+Tween.setRotate(entity,
   Quaternion.fromEulerDegrees(0, 0, 0), Quaternion.fromEulerDegrees(0, 180, 0),
-  { duration: 2000, easingFunction: EasingFunction.EF_EASEOUTQUAD }
-))
+  2000, EasingFunction.EF_EASEOUTQUAD
+)
 
-// Scale
-Tween.createOrReplace(entity, Tween.setScale(
+// Scale — signature: Tween.setScale(entity, start, end, duration, easingFunction?)
+Tween.setScale(entity,
   Vector3.One(), Vector3.create(2, 2, 2),
-  { duration: 1000, easingFunction: EasingFunction.EF_LINEAR }
-))
+  1000, EasingFunction.EF_LINEAR
+)
 ```
 
 ### Yoyo Loop Mode
@@ -229,6 +247,18 @@ anim.states[0].weight = 0.5  // blend walk at 50%
 anim.states[1].weight = 0.5  // blend idle at 50%
 ```
 
+## Troubleshooting
+
+| Problem | Cause | Solution |
+|---------|-------|----------|
+| GLTF animation not playing | Wrong clip name in `Animator.states` | Open the .glb in a viewer (e.g., Blender) to find exact clip names — they are case-sensitive |
+| Animator component has no effect | Entity missing `GltfContainer` | `Animator` only works on entities that have a loaded GLTF model |
+| Tween doesn't move | Start and end positions are the same | Verify `start` and `end` values differ in `Tween.Mode.Move()` |
+| Tween plays once then stops | No `TweenSequence` with loop | Add `TweenSequence.create(entity, { sequence: [], loop: TweenLoop.TL_YOYO })` for back-and-forth |
+| Animation jitters or stutters | Creating new Tween every frame | Only create Tween once, not inside a system — use `tweenSystem.tweenCompleted()` to chain |
+
+> **Need 3D models to animate?** See the **add-3d-models** skill for loading GLTF models that contain animation clips.
+
 ## Best Practices
 
 - Use Tweens for simple A-to-B animations (doors, platforms, UI elements)

package/skills/audio-video/SKILL.md

@@ -1,10 +1,23 @@
 ---
 name: audio-video
-description: Add audio sources, sound effects, music, audio streaming, and video players to Decentraland scenes. Use when user wants sound, music, audio, video screens, speakers, or media playback.
+description: Add sound effects, music, audio streaming, and video players to Decentraland scenes. Covers AudioSource (local files), AudioStream (streaming URLs), VideoPlayer (video surfaces), video events, and media permissions. Use when the user wants sound, music, audio, video screens, radio, or media playback. Do NOT use for 3D model animations (see animations-tweens).
 ---
 
 # Audio and Video in Decentraland
 
+## When to Use Which Media Component
+
+| Need | Component | Key Difference |
+|------|-----------|---------------|
+| Sound effect from a file (click, explosion, footstep) | `AudioSource` | Local file, spatial, one-shot or looping |
+| Background music or radio stream | `AudioStream` | External URL, non-spatial, continuous |
+| Video on a surface (screen, billboard) | `VideoPlayer` + `Material.Texture.Video` | Requires a mesh to display on |
+
+**Decision flow:**
+1. Is it a local audio file? → `AudioSource`
+2. Is it a streaming URL (radio, live audio)? → `AudioStream`
+3. Is it video content? → `VideoPlayer` on a plane/mesh
+
 ## Audio Source (Sound Effects & Music)
 
 Play audio clips from files:
@@ -289,6 +302,8 @@ Material.setPbrMaterial(screen2, {
 - **Supported formats**: `.mp4` (H.264), `.webm`, HLS (`.m3u8`) for live streaming
 - **Live streaming**: Use HLS (`.m3u8`) URLs — most reliable across clients
 
+For full component field details, supported formats, and advanced patterns, see `{baseDir}/references/media-reference.md`.
+
 ## Important Notes
 
 - Audio files must be in the project's directory (relative paths from project root)

package/skills/audio-video/references/media-reference.md

@@ -0,0 +1,184 @@
+# Media Components Reference
+
+## AudioSource — Full Fields
+
+```typescript
+import { AudioSource } from '@dcl/sdk/ecs'
+
+AudioSource.create(entity, {
+  audioClipUrl: 'sounds/effect.mp3',  // Path to local audio file (required)
+  playing: false,                      // Start/stop playback
+  loop: false,                         // Loop when finished
+  volume: 1.0,                         // Volume 0.0 to 1.0
+  pitch: 1.0                           // Playback speed (0.5 = half, 2.0 = double)
+})
+```
+
+**Supported formats:** `.mp3` (recommended), `.ogg`, `.wav`
+
+Audio is spatial by default — volume decreases with distance from the entity. Place the entity where the sound should originate.
+
+### Playback Control
+
+```typescript
+const audio = AudioSource.getMutable(entity)
+audio.playing = true   // Play
+audio.playing = false  // Stop
+audio.volume = 0.5     // Adjust volume
+audio.pitch = 1.5      // Speed up
+```
+
+### Reset and Replay
+
+To replay a sound effect from the beginning:
+```typescript
+const audio = AudioSource.getMutable(entity)
+audio.playing = false
+audio.playing = true  // Restarts from beginning
+```
+
+## AudioStream — Full Fields
+
+```typescript
+import { AudioStream } from '@dcl/sdk/ecs'
+
+AudioStream.create(entity, {
+  url: 'https://stream.example.com/radio.mp3',  // Streaming URL (required)
+  playing: true,                                   // Start/stop stream
+  volume: 0.5                                      // Volume 0.0 to 1.0
+})
+```
+
+**Supported stream formats:** HTTP/HTTPS audio streams (`.mp3`, `.ogg`, `.aac`)
+
+AudioStream is NOT spatial — it plays at the same volume regardless of player distance. Best for background music or radio.
+
+## VideoPlayer — Full Fields
+
+```typescript
+import { VideoPlayer } from '@dcl/sdk/ecs'
+
+VideoPlayer.create(entity, {
+  src: 'videos/clip.mp4',    // Local file or external URL (required)
+  playing: true,              // Start/stop playback
+  loop: false,                // Loop when finished
+  volume: 1.0,                // Volume 0.0 to 1.0
+  playbackRate: 1.0,          // Playback speed
+  position: 0                 // Start time in seconds
+})
+```
+
+**Supported formats:**
+- `.mp4` (H.264) — most compatible
+- `.webm` — good quality, smaller files
+- `.ogg` — open format
+- `.m3u8` (HLS) — live streaming, most reliable for streams
+
+### Video Texture Setup
+
+VideoPlayer alone doesn't display video. You must create a video texture and apply it to a mesh:
+
+```typescript
+// 1. Create mesh surface
+MeshRenderer.setPlane(entity)
+
+// 2. Create video texture referencing the VideoPlayer entity
+const videoTexture = Material.Texture.Video({ videoPlayerEntity: entity })
+
+// 3. Apply as basic material (best performance)
+Material.setBasicMaterial(entity, { texture: videoTexture })
+
+// OR as PBR material with emissive (self-lit screen)
+Material.setPbrMaterial(entity, {
+  texture: videoTexture,
+  roughness: 1.0,
+  specularIntensity: 0,
+  metallic: 0,
+  emissiveTexture: videoTexture,
+  emissiveIntensity: 0.6,
+  emissiveColor: Color3.White()
+})
+```
+
+### Live Streaming
+
+```typescript
+// HLS stream
+VideoPlayer.create(entity, {
+  src: 'https://example.com/stream.m3u8',
+  playing: true
+})
+
+// LiveKit video stream
+VideoPlayer.create(entity, {
+  src: 'livekit-video://current-stream',
+  playing: true
+})
+```
+
+### Video Events
+
+```typescript
+import { videoEventsSystem, VideoState } from '@dcl/sdk/ecs'
+
+videoEventsSystem.registerVideoEventsEntity(entity, (event) => {
+  console.log('State:', event.state)          // VideoState enum
+  console.log('Time:', event.currentOffset)   // Current playback time
+  console.log('Length:', event.videoLength)    // Total duration
+})
+
+// Poll current state
+const state = videoEventsSystem.getVideoState(entity)
+```
+
+**VideoState values:** `VS_READY`, `VS_PLAYING`, `VS_PAUSED`, `VS_ERROR`, `VS_BUFFERING`, `VS_SEEKING`, `VS_NONE`
+
+### Multiple Screens, One Video
+
+```typescript
+// One VideoPlayer, shared across screens
+VideoPlayer.create(screen1, { src: 'videos/shared.mp4', playing: true })
+const tex = Material.Texture.Video({ videoPlayerEntity: screen1 })
+Material.setBasicMaterial(screen1, { texture: tex })
+Material.setBasicMaterial(screen2, { texture: tex })
+```
+
+### Video Limits
+
+| Quality Setting | Max Simultaneous Videos |
+|----------------|------------------------|
+| Low | 1 |
+| Medium | 5 |
+| High | 10 |
+
+### Media Permissions in scene.json
+
+External audio/video URLs require permissions:
+
+```json
+{
+  "requiredPermissions": ["ALLOW_MEDIA_HOSTNAMES"],
+  "allowedMediaHostnames": ["stream.example.com", "cdn.example.com"]
+}
+```
+
+## AudioAnalysis (Advanced)
+
+Real-time frequency and amplitude data from audio sources:
+
+```typescript
+import { AudioAnalysis, AudioAnalysisView } from '@dcl/sdk/ecs'
+
+// Enable analysis on an audio source entity
+AudioAnalysis.create(audioEntity, {})
+
+// Read analysis data in a system
+engine.addSystem(() => {
+  const view = AudioAnalysisView.getOrNull(audioEntity)
+  if (view) {
+    // Use frequency/amplitude data for visualizers, beat detection, etc.
+  }
+})
+```
+
+Used for music visualizers, reactive environments, and beat-synced animations.

package/skills/authoritative-server/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: authoritative-server
-description: Build multiplayer scenes with a headless authoritative server that controls game state, validates changes, and prevents cheating. Install @dcl/sdk@auth-server and run with hammurabi-server. Use isServer() to branch logic, registerMessages() for client-server communication, validateBeforeChange() for server-only components, Storage for persistence, and EnvVar for configuration. Use when user wants authoritative server, anti-cheat, server-side validation, persistent storage, environment variables, or server messages.
+description: Build multiplayer Decentraland scenes with a headless authoritative server. Covers isServer() branching, registerMessages() for client-server communication, validateBeforeChange() for server-only state, Storage (world and player persistence), EnvVar (environment variables), and project structure. Use when the user wants authoritative multiplayer, anti-cheat, server-side validation, persistent storage, or server messages. Do NOT use for basic CRDT multiplayer without a server (see multiplayer-sync).
 ---
 
 # Authoritative Server Pattern
@@ -181,10 +181,10 @@ room.onMessage('gameEvent', (data) => {
 Before sending messages from the client, wait until state is synchronized:
 
 ```typescript
-import { isStateSynchronized } from '@dcl/sdk/network'
+import { isStateSyncronized } from '@dcl/sdk/network'
 
 engine.addSystem(() => {
-  if (!isStateSynchronized()) return
+  if (!isStateSyncronized()) return
 
   // Safe to send messages now
   room.send('playerJoin', { displayName: 'Player' })
@@ -323,10 +323,12 @@ Put synced components and messages in `shared/` so both server and client import
 ## Important Notes
 
 - **Use `Schemas.Int64` for timestamps**: `Schemas.Number` corrupts large numbers (13+ digits). Always use `Schemas.Int64` for values like `Date.now()`.
-- **State sync readiness**: Clients must wait for `isStateSynchronized()` (from `@dcl/sdk/network`) to return `true` before sending messages.
+- **State sync readiness**: Clients must wait for `isStateSyncronized()` (from `@dcl/sdk/network`) to return `true` before sending messages. Note the intentional SDK typo: "Syncronized" not "Synchronized".
 - **Custom vs built-in validation**: Custom components use global `validateBeforeChange((value) => ...)`. Built-in components (Transform, GltfContainer) use per-entity `validateBeforeChange(entity, (value) => ...)`.
 - **Single codebase**: Both server and client run the same `index.ts` entry point. Use `isServer()` to branch.
 - **No Node.js APIs**: The DCL runtime uses sandboxed QuickJS — no `fs`, `http`, etc. `setTimeout`/`setInterval` are supported. Use SDK-provided APIs (Storage, EnvVar, engine systems) for server-side operations.
 - **SDK branch (MANDATORY)**: The auth-server pattern requires `npm install @dcl/sdk@auth-server`, not the standard `@dcl/sdk`. Without it, `isServer()`, `registerMessages()`, `Storage`, and `EnvVar` are unavailable.
 - **scene.json required fields**: `authoritativeMultiplayer: true` must be set, and `logsPermissions: ["0xWalletAddress"]` must list wallet addresses that should see server logs.
 - For basic CRDT multiplayer without a server, see the `multiplayer-sync` skill.
+
+For complete server setup examples, authentication flow, state reconciliation, Storage patterns, and EnvVar usage, see `{baseDir}/references/server-patterns.md`.

package/skills/authoritative-server/references/server-patterns.md

@@ -0,0 +1,251 @@
+# Authoritative Server Patterns Reference
+
+## Complete Server Setup
+
+### Project Structure
+
+```
+src/
+├── index.ts              # Entry point — isServer() branching
+├── client/
+│   ├── setup.ts          # Client init, input handlers, message senders
+│   └── ui.tsx            # React ECS UI (reads synced state, sends messages)
+├── server/
+│   ├── server.ts         # Server init, game loop, message handlers
+│   └── gameState.ts      # Server state management
+└── shared/
+    ├── schemas.ts        # Custom component definitions + validateBeforeChange
+    └── messages.ts       # Message definitions via registerMessages()
+```
+
+### Entry Point (index.ts)
+
+```typescript
+import { isServer } from '@dcl/sdk/network'
+
+export async function main() {
+  if (isServer()) {
+    const { initServer } = await import('./server/server')
+    initServer()
+    return
+  }
+
+  const { initClient } = await import('./client/setup')
+  const { setupUi } = await import('./client/ui')
+  initClient()
+  setupUi()
+}
+```
+
+### Shared Schemas (shared/schemas.ts)
+
+```typescript
+import { engine, Schemas, Entity } from '@dcl/sdk/ecs'
+import { AUTH_SERVER_PEER_ID } from '@dcl/sdk/network/message-bus-sync'
+
+// Custom synced component
+export const GameState = engine.defineComponent('game:State', {
+  phase: Schemas.String,
+  score: Schemas.Int,
+  timeRemaining: Schemas.Int
+})
+
+// Global validation — only server can modify
+GameState.validateBeforeChange((value) => {
+  return value.senderAddress === AUTH_SERVER_PEER_ID
+})
+
+// For built-in components, use per-entity validation
+type ComponentWithValidation = {
+  validateBeforeChange: (entity: Entity, cb: (value: { senderAddress: string }) => boolean) => void
+}
+
+export function protectServerEntity(entity: Entity, components: ComponentWithValidation[]) {
+  for (const component of components) {
+    component.validateBeforeChange(entity, (value) => {
+      return value.senderAddress === AUTH_SERVER_PEER_ID
+    })
+  }
+}
+```
+
+### Shared Messages (shared/messages.ts)
+
+```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 }),
+
+  // Server → Client
+  gameStarted: Schemas.Map({ roundNumber: Schemas.Int }),
+  playerScored: Schemas.Map({ playerName: Schemas.String, points: Schemas.Int }),
+  gameEnded: Schemas.Map({ winnerId: Schemas.String })
+}
+
+export const room = registerMessages(Messages)
+```
+
+### Server Logic (server/server.ts)
+
+```typescript
+import { engine, PlayerIdentityData, Transform } from '@dcl/sdk/ecs'
+import { syncEntity } from '@dcl/sdk/network'
+import { room } from '../shared/messages'
+import { GameState, protectServerEntity } from '../shared/schemas'
+
+export function initServer() {
+  // Create server-managed entities
+  const stateEntity = engine.addEntity()
+  GameState.create(stateEntity, { phase: 'lobby', score: 0, timeRemaining: 60 })
+  protectServerEntity(stateEntity, [Transform])
+  syncEntity(stateEntity, [GameState.componentId], 1)
+
+  // Handle client messages
+  room.onMessage('playerReady', (data, context) => {
+    if (!context) return
+    console.log(`[Server] ${data.displayName} ready (${context.from})`)
+  })
+
+  room.onMessage('playerAction', (data, context) => {
+    if (!context) return
+    // Validate action on server
+    const playerPos = getPlayerPosition(context.from)
+    if (isValidAction(data.action, playerPos)) {
+      applyAction(data)
+    }
+  })
+
+  // Game loop
+  engine.addSystem(gameLoopSystem)
+}
+```
+
+## Authentication Flow
+
+The auth server automatically provides player identity via `PlayerIdentityData`:
+
+```typescript
+// Server reads actual player positions
+engine.addSystem(() => {
+  for (const [entity, identity] of engine.getEntitiesWith(PlayerIdentityData)) {
+    const transform = Transform.getOrNull(entity)
+    if (!transform) continue
+
+    // identity.address = wallet address (verified by server)
+    // transform.position = actual player position (not client-reported)
+    console.log(`[Server] ${identity.address} at`, transform.position)
+  }
+})
+```
+
+Never trust client-reported positions. The server sees real positions via `PlayerIdentityData` + `Transform`.
+
+## State Reconciliation
+
+When server state diverges from client state, the server always wins:
+
+```typescript
+// Server-side: apply authoritative state
+function reconcileState() {
+  const state = GameState.getMutable(stateEntity)
+
+  // Server calculates correct state
+  state.timeRemaining = Math.max(0, state.timeRemaining - 1)
+
+  if (state.timeRemaining <= 0 && state.phase === 'active') {
+    state.phase = 'ended'
+    room.send('gameEnded', { winnerId: findWinner() })
+  }
+}
+```
+
+Because `validateBeforeChange` blocks client writes, clients can only read the state and send messages. The server is the single source of truth.
+
+## Storage Patterns
+
+### World Storage (Global Data)
+
+```typescript
+import { Storage } from '@dcl/sdk/server'
+
+// Save leaderboard
+await Storage.world.set('leaderboard', JSON.stringify([
+  { name: 'Alice', score: 100 },
+  { name: 'Bob', score: 85 }
+]))
+
+// Load leaderboard
+const data = await Storage.world.get<string>('leaderboard')
+const leaderboard = data ? JSON.parse(data) : []
+
+// Delete
+await Storage.world.delete('leaderboard')
+```
+
+### Player Storage (Per-Player Data)
+
+```typescript
+import { Storage } from '@dcl/sdk/server'
+
+// Save player progress
+await Storage.player.set(playerAddress, 'progress', JSON.stringify({
+  level: 5,
+  coins: 250,
+  achievements: ['first_kill', 'speedrun']
+}))
+
+// Load player progress
+const saved = await Storage.player.get<string>(playerAddress, 'progress')
+const progress = saved ? JSON.parse(saved) : { level: 1, coins: 0, achievements: [] }
+```
+
+**Note:** Storage only accepts strings. Always `JSON.stringify()` objects and `String()` numbers.
+
+**Local dev storage location:** `node_modules/@dcl/sdk-commands/.runtime-data/server-storage.json`
+
+## Environment Variables
+
+```typescript
+import { EnvVar } from '@dcl/sdk/server'
+
+// Read with defaults
+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'
+```
+
+### Local Development (.env file)
+
+```
+MAX_PLAYERS=8
+GAME_DURATION=300
+DEBUG=true
+```
+
+### Production Deployment
+
+```bash
+npx sdk-commands deploy-env MAX_PLAYERS --value 8
+npx sdk-commands deploy-env GAME_DURATION --value 300
+npx sdk-commands deploy-env OLD_VAR --delete
+```
+
+## scene.json Required Fields
+
+```json
+{
+  "authoritativeMultiplayer": true,
+  "worldConfiguration": {
+    "name": "my-world.dcl.eth"
+  },
+  "logsPermissions": ["0xYourWalletAddress"]
+}
+```
+
+- `authoritativeMultiplayer: true` — enables the headless server runtime
+- `worldConfiguration.name` — identifies the world (required for Storage and deploy)
+- `logsPermissions` — wallet addresses that can see `console.log()` from the server