@dcl-regenesislabs/opendcl 0.2.1 → 0.2.2-26850672477.commit-99ffd91

package/skills/audio-video/SKILL.md

@@ -5,6 +5,11 @@ description: Add sound effects, music, audio streaming, and video players to Dec
 
 # Audio and Video in Decentraland
 
+## Authoring split
+
+- **`AudioSource`** (local audio files), **`AudioStream`** (streaming URLs), and **`VideoPlayer`** are all supported in `main-entities.ts` — declare the speaker / radio / screen entity fully there with the streaming/playback config.
+- Volume / play / pause toggles at runtime happen in `src/index.ts` via `getMutable`.
+
 ## When to Use Which Media Component
 
 | Need | Component | Key Difference |
@@ -20,22 +25,26 @@ description: Add sound effects, music, audio streaming, and video players to Dec
 
 ## Audio Source (Sound Effects & Music)
 
-Play audio clips from files:
+Declare the speaker in `main-entities.ts`:
 
 ```typescript
-import { engine, Transform, AudioSource } from '@dcl/sdk/ecs'
-import { Vector3 } from '@dcl/sdk/math'
-
-const speaker = engine.addEntity()
-Transform.create(speaker, { position: Vector3.create(8, 1, 8) })
-
-AudioSource.create(speaker, {
-  audioClipUrl: 'sounds/music.mp3',
-  playing: true,
-  loop: true,
-  volume: 0.5,   // 0 to 1
-  pitch: 1.0     // Playback speed (0.5 = half speed, 2.0 = double)
-})
+// main-entities.ts
+import type { Scene } from '@dcl/sdk/scene-types'
+
+export const scene = {
+  speaker: {
+    components: {
+      Transform: { position: { x: 8, y: 1, z: 8 } },
+      AudioSource: {
+        audioClipUrl: 'sounds/music.mp3',
+        playing: true,
+        loop: true,
+        volume: 0.5,   // 0 to 1
+        pitch: 1.0     // Playback speed (0.5 = half speed, 2.0 = double)
+      }
+    }
+  }
+} satisfies Scene
 ```
 
 ### Supported Formats
@@ -43,6 +52,26 @@ AudioSource.create(speaker, {
 - `.ogg`
 - `.wav`
 
+### Spatial vs Non-Spatial Audio
+
+`AudioSource` defaults to spatial (volume falls off with distance). For background music / radio / non-positional sound effects, set `global: true`:
+
+```typescript
+// main-entities.ts
+bg_music: {
+  components: {
+    Transform: { position: { x: 0, y: 0, z: 0 } },  // ignored when global
+    AudioSource: {
+      audioClipUrl: 'sounds/bg.mp3',
+      playing: true,
+      loop: true,
+      volume: 0.5,
+      global: true   // heard everywhere in the scene at constant volume
+    }
+  }
+}
+```
+
 ### File Organization
 ```
 project/
@@ -55,97 +84,127 @@ project/
 └── scene.json
 ```
 
-### Play/Stop/Toggle
+### Play/Stop/Toggle (runtime, in `src/index.ts`)
 ```typescript
-// Play
-AudioSource.getMutable(speaker).playing = true
+import { engine, AudioSource } from '@dcl/sdk/ecs'
+
+export function main() {
+  const speaker = engine.getEntityOrNullByName('speaker')
+  if (!speaker) return
 
-// Stop
-AudioSource.getMutable(speaker).playing = false
+  AudioSource.getMutable(speaker).playing = true   // play
+  AudioSource.getMutable(speaker).playing = false  // stop
 
-// Toggle
-const audio = AudioSource.getMutable(speaker)
-audio.playing = !audio.playing
+  // toggle
+  const audio = AudioSource.getMutable(speaker)
+  audio.playing = !audio.playing
+}
 ```
 
 ### Play on Click
-```typescript
-import { pointerEventsSystem, InputAction } from '@dcl/sdk/ecs'
-
-const button = engine.addEntity()
-// ... set up transform and mesh ...
-
-const audioEntity = engine.addEntity()
-Transform.create(audioEntity, { position: Vector3.create(8, 1, 8) })
-AudioSource.create(audioEntity, {
-  audioClipUrl: 'sounds/click.mp3',
-  playing: false,
-  loop: false,
-  volume: 0.8
-})
 
-pointerEventsSystem.onPointerDown(
-  { entity: button, opts: { button: InputAction.IA_POINTER, hoverText: 'Play sound' } },
-  () => {
-    // Reset and play
-    const audio = AudioSource.getMutable(audioEntity)
-    audio.playing = false
-    audio.playing = true
+Static entities (the button mesh and the click-sfx speaker) go in `main-entities.ts`. `PointerEvents` and the click handler are runtime — they live in `src/index.ts`.
+
+```typescript
+// main-entities.ts
+sfx_button: {
+  components: {
+    Transform: { position: { x: 8, y: 1, z: 8 } },
+    MeshRenderer: { mesh: { $case: 'box', box: { uvs: [] } } }
+  }
+},
+click_sfx: {
+  components: {
+    Transform: { position: { x: 8, y: 1, z: 8 } },
+    AudioSource: {
+      audioClipUrl: 'sounds/click.mp3',
+      playing: false,
+      loop: false,
+      volume: 0.8
+    }
   }
-)
+}
+```
+
+```typescript
+// src/index.ts
+import { engine, AudioSource, pointerEventsSystem, InputAction } from '@dcl/sdk/ecs'
+
+export function main() {
+  const button = engine.getEntityOrNullByName('sfx_button')
+  const sfx = engine.getEntityOrNullByName('click_sfx')
+  if (!button || !sfx) return
+
+  pointerEventsSystem.onPointerDown(
+    { entity: button, opts: { button: InputAction.IA_POINTER, hoverText: 'Play sound' } },
+    () => {
+      // Reset and play
+      const audio = AudioSource.getMutable(sfx)
+      audio.playing = false
+      audio.playing = true
+    }
+  )
+}
 ```
 
 ## Audio Streaming
 
-Stream audio from a URL (radio, live streams):
+`AudioStream` is supported in `main-entities.ts` — declare the radio entity with its streaming config in one place:
 
 ```typescript
-import { engine, Transform, AudioStream } from '@dcl/sdk/ecs'
-import { Vector3 } from '@dcl/sdk/math'
-
-const radio = engine.addEntity()
-Transform.create(radio, { position: Vector3.create(8, 1, 8) })
-
-AudioStream.create(radio, {
-  url: 'https://example.com/stream.mp3',
-  playing: true,
-  volume: 0.3
-})
+// main-entities.ts
+radio: {
+  components: {
+    Transform: { position: { x: 8, y: 1, z: 8 } },
+    GltfContainer: { src: 'models/radio.glb' },
+    AudioStream: {
+      url: 'https://example.com/stream.mp3',
+      playing: true,
+      volume: 0.3
+    }
+  }
+}
 ```
 
+Toggling play / volume at runtime is the same `getMutable` pattern as `AudioSource`.
+
 ## Video Player
 
-Play video on a surface:
+`VideoPlayer`, `MeshRenderer`, and the screen Transform all go in `main-entities.ts`. The video **texture binding** in `Material` needs a runtime Entity ID, not a name — the build only resolves `Transform.parent` by name. So `Material` is set at runtime in `src/index.ts`:
 
 ```typescript
-import { engine, Transform, VideoPlayer, Material, MeshRenderer } from '@dcl/sdk/ecs'
-import { Vector3 } from '@dcl/sdk/math'
-
-// Create a screen
-const screen = engine.addEntity()
-Transform.create(screen, {
-  position: Vector3.create(8, 3, 15.9),
-  scale: Vector3.create(8, 4.5, 1)  // 16:9 ratio
-})
-MeshRenderer.setPlane(screen)
-
-// Add video player
-VideoPlayer.create(screen, {
-  src: 'https://example.com/video.mp4',
-  playing: true,
-  loop: true,
-  volume: 0.5,
-  playbackRate: 1.0,
-  position: 0  // Start time in seconds
-})
+// main-entities.ts
+video_screen: {
+  components: {
+    Transform: {
+      position: { x: 8, y: 3, z: 15.9 },
+      scale: { x: 8, y: 4.5, z: 1 }    // 16:9 ratio
+    },
+    MeshRenderer: { mesh: { $case: 'plane', plane: { uvs: [] } } },
+    VideoPlayer: {
+      src: 'https://example.com/video.mp4',
+      playing: true,
+      loop: true,
+      volume: 0.5,
+      playbackRate: 1.0,
+      position: 0   // start time in seconds
+    }
+  }
+}
+```
 
-// Create video texture
-const videoTexture = Material.Texture.Video({ videoPlayerEntity: screen })
+```typescript
+// src/index.ts
+import { engine, Material } from '@dcl/sdk/ecs'
 
-// Basic material (recommended — better performance)
-Material.setBasicMaterial(screen, {
-  texture: videoTexture
-})
+export function main() {
+  const screen = engine.getEntityOrNullByName('video_screen')
+  if (!screen) return
+
+  const videoTexture = Material.Texture.Video({ videoPlayerEntity: screen })
+  // Basic material — better performance than PBR for video surfaces
+  Material.setBasicMaterial(screen, { texture: videoTexture })
+}
 ```
 
 ### Video Controls
@@ -182,6 +241,48 @@ Material.setPbrMaterial(screen, {
 })
 ```
 
+### Video on a GLTF Surface (Curved Screens, TVs, Monitors)
+
+When the "screen" is part of a model (a TV in a living room scene, a curved arena display), keep the GLTF and override its screen material with the video texture via `GltfNodeModifiers` at runtime:
+
+```typescript
+// main-entities.ts — declare the TV model
+tv: {
+  components: {
+    Transform: { position: { x: 8, y: 1.5, z: 8 } },
+    GltfContainer: { src: 'models/tv.glb' },
+    VideoPlayer: { src: 'https://example.com/show.mp4', playing: true, loop: true }
+  }
+}
+```
+
+```typescript
+// src/index.ts — bind the video texture to the screen sub-mesh by path
+import { engine, Material, GltfNodeModifiers } from '@dcl/sdk/ecs'
+
+export function main() {
+  const tv = engine.getEntityOrNullByName('tv')
+  if (!tv) return
+
+  const videoTexture = Material.Texture.Video({ videoPlayerEntity: tv })
+  GltfNodeModifiers.createOrReplace(tv, {
+    modifiers: [
+      {
+        path: 'TV/Screen',  // GLTF node path to the screen sub-mesh
+        material: {
+          material: {
+            $case: 'unlit',
+            unlit: { texture: videoTexture }
+          }
+        }
+      }
+    ]
+  })
+}
+```
+
+Use `path: ''` (empty) to apply the video material to every node of the model — useful when the whole model is the screen (e.g., a flat billboard mesh exported from Blender).
+
 ### Video Events
 
 Monitor video playback state:

package/skills/build-ui/SKILL.md

@@ -38,7 +38,11 @@ const MyUI = () => (
 )
 
 export function setupUi() {
-  ReactEcsRenderer.setUiRenderer(MyUI)
+  // ALWAYS pass virtualWidth + virtualHeight — the renderer scales the layout
+  // to fit the player's window using these as the reference. Without them,
+  // sizes are interpreted in raw pixels and won't behave consistently across
+  // resolutions and aspect ratios.
+  ReactEcsRenderer.setUiRenderer(MyUI, { virtualWidth: 1920, virtualHeight: 1080 })
 }
 ```
 
@@ -304,6 +308,25 @@ The `Dropdown` component supports additional props:
 />
 ```
 
+### Multiple UI Modules (`addUiRenderer` / `removeUiRenderer`)
+
+If you have several independent UI modules — e.g., a HUD, a dialog system, a debug overlay — combine them under a single root *or* use `addUiRenderer` to mount each module against an **owner entity**. When the owner entity is deleted, the UI renderer is removed automatically.
+
+```tsx
+import { engine, ReactEcsRenderer } from '@dcl/sdk/react-ecs'
+
+const hudOwner = engine.addEntity()
+ReactEcsRenderer.addUiRenderer(hudOwner, () => <HudOverlay />)
+
+// later, when the HUD should disappear:
+engine.removeEntity(hudOwner)  // also removes the UI renderer
+
+// or explicitly:
+ReactEcsRenderer.removeUiRenderer(hudOwner)
+```
+
+Each `addUiRenderer` mount renders independently. Useful for dynamic UIs that should appear/disappear based on game state without manually conditioning every sub-tree of one giant root component.
+
 ## Troubleshooting
 
 | Problem | Cause | Solution |
@@ -312,7 +335,7 @@ The `Dropdown` component supports additional props:
 | UI elements overlapping | Missing `flexDirection` or wrong layout | Set `flexDirection: 'column'` on the parent container |
 | Button clicks not registering | Missing `onMouseDown` handler | Add `onMouseDown={() => { ... }}` to the Button or UiEntity |
 | JSX errors at compile time | File extension is `.ts` instead of `.tsx` | Rename the file to `.tsx` |
-| Multiple UIs fighting | More than one `setUiRenderer` call | Only call `setUiRenderer` once — combine all UI into a single root component |
+| Multiple UIs fighting | More than one `setUiRenderer` call | Use ONE `setUiRenderer` for the main UI; for independent modules use `addUiRenderer(ownerEntity, ...)` instead |
 | Text not visible | Text color matches background | Set contrasting `color` on Label or `uiText` |
 
 > **World interactions instead of screen UI?** See the **add-interactivity** skill for click handlers and pointer events on 3D objects.

package/skills/camera-control/SKILL.md

@@ -5,6 +5,59 @@ description: Control camera behavior in Decentraland scenes. CameraMode detectio
 
 # Camera Control in Decentraland
 
+## Authoring split
+
+`CameraModeArea` and `VirtualCamera` are supported in `main-entities.ts` — both static-by-nature components belong there. `MainCamera` is NOT supported because it lives on the reserved `engine.CameraEntity`; activate a virtual camera at runtime in `src/index.ts`.
+
+`VirtualCamera.lookAtEntity` accepts an entity **name** in `main-entities.ts` (resolved to an Entity ID at build time, same as `Transform.parent`).
+
+```typescript
+// main-entities.ts
+cinematic_cam: {
+  components: {
+    Transform: {
+      position: { x: 12, y: 4, z: 8 },
+      rotation: { x: 0, y: 0.7071, z: 0, w: 0.7071 }
+    },
+    VirtualCamera: {
+      defaultTransition: { transitionMode: { $case: 'time', time: 2 } },
+      lookAtEntity: 'shopkeeper'  // name of another entity in this file
+    }
+  }
+},
+first_person_zone: {
+  components: {
+    Transform: { position: { x: 8, y: 1, z: 8 } },
+    CameraModeArea: {
+      area: { x: 16, y: 2, z: 16 },
+      mode: 0  // CameraType.CT_FIRST_PERSON
+    }
+  }
+}
+```
+
+Activate the cinematic camera at runtime:
+
+```typescript
+// src/index.ts
+import { engine, MainCamera } from '@dcl/sdk/ecs'
+
+export function main() {
+  const cam = engine.getEntityOrNullByName('cinematic_cam')
+  if (cam) MainCamera.createOrReplace(engine.CameraEntity, { virtualCameraEntity: cam })
+}
+```
+
+The reserved `engine.CameraEntity` and `engine.PlayerEntity` are engine-managed and have no representation in `main-entities.ts`.
+
+### CameraType values for `CameraModeArea.mode`
+
+| value | enum | meaning |
+|---|---|---|
+| 0 | CT_FIRST_PERSON | Force first-person inside the zone |
+| 1 | CT_THIRD_PERSON | Force third-person inside the zone |
+| 2 | CT_CINEMATIC    | Force cinematic camera inside the zone |
+
 ## Reading Camera State
 
 Access the camera's current position and rotation via the reserved `engine.CameraEntity`:
@@ -199,12 +252,30 @@ engine.addSystem(followNpcCamera)
 
 > **Freezing player during cutscenes?** Combine VirtualCamera with `InputModifier` from the **advanced-input** skill to prevent player movement during cinematic sequences.
 
+## Camera vs Colliders (preventing camera-through-wall)
+
+In third-person mode the player's camera can slide through walls if the wall's collider mask doesn't include `CL_POINTER`. The camera uses the **pointer** collider mask for occlusion checks — not `CL_PHYSICS`. Set both masks on walls and architecture that the camera should bounce off:
+
+```typescript
+// main-entities.ts
+wall: {
+  components: {
+    Transform: { position: { x: 8, y: 1.5, z: 16 } },
+    GltfContainer: {
+      src: 'models/wall.glb',
+      visibleMeshesCollisionMask: 3   // CL_PHYSICS | CL_POINTER
+    }
+  }
+}
+```
+
+For GLBs that ship with invisible collider meshes (Creator Hub asset packs), set `invisibleMeshesCollisionMask: 3` instead. Default of `CL_PHYSICS` only would let the camera pass through.
+
 ## Best Practices
 
-- Only one VirtualCamera should be active at a time
-- Use `CameraModeArea` to force first-person in tight indoor spaces
-- Keep transition speeds between 0.5 and 3.0 for comfortable camera movement
-- Always provide a way for the player to exit forced camera modes (e.g., leave the area)
-- Read camera state via `engine.CameraEntity` — never try to write to it directly
-- For look-at detection, combine camera position with raycasting (see `add-interactivity` skill)
-- Camera control is read-only outside of VirtualCamera and CameraModeArea — you cannot directly move the player's camera
+- Only one VirtualCamera should be active at a time.
+- Use `CameraModeArea` to force first-person in tight indoor spaces.
+- Keep transition speeds between 0.5 and 3.0 for comfortable camera movement.
+- Read camera state via `engine.CameraEntity` — never try to write to it directly.
+- For look-at detection, combine camera position with raycasting (see `add-interactivity` skill).
+- Camera control is read-only outside of VirtualCamera and CameraModeArea — you cannot directly move the player's camera.

package/skills/create-scene/SKILL.md

@@ -52,26 +52,68 @@ Update the `display` fields and parcels:
 - `scene.parcels` — for multi-parcel scenes, list all parcels (e.g., `["0,0", "0,1", "1,0", "1,1"]` for 2x2)
 - `scene.base` — set to the southwest corner parcel
 
-### src/index.ts
-Replace the generated code with the user's scene. Example:
+### `main-entities.ts` + `src/index.ts`
+
+OpenDCL scenes use a **two-file authoring model**:
+
+- `main-entities.ts` (scene root) — typed declarative entities + their data components, keyed by Name. Compiled to `main.crdt` at build time and preloaded by the engine before `main()` runs.
+- `src/index.ts` — behavior only. References entities by `Name` via `engine.getEntityOrNullByName<EntityName>(name)` and attaches systems, pointer events, tweens, etc.
+
+**Example `main-entities.ts`:**
 
 ```typescript
-import { engine, Transform, MeshRenderer, Material } from '@dcl/sdk/ecs'
-import { Vector3, Color4 } from '@dcl/sdk/math'
+import type { Scene } from '@dcl/sdk/scene-types'
+
+export const scene = {
+  blue_cube: {
+    components: {
+      Transform: { position: { x: 8, y: 1, z: 8 }, rotation: { x: 0, y: 0, z: 0, w: 1 }, scale: { x: 1, y: 1, z: 1 } },
+      MeshRenderer: { mesh: { $case: 'box', box: { uvs: [] } } },
+      Material: {
+        material: { $case: 'pbr', pbr: { albedoColor: { r: 0.2, g: 0.5, b: 1, a: 1 } } },
+      },
+    },
+  },
+} satisfies Scene
+```
+
+The `satisfies Scene` clause keeps the literal keys typed (so `keyof typeof scene` gives the typed entity-name union), while still validating the shape against the `Scene` schema.
+
+**Example `src/index.ts`:**
+
+```typescript
+import { engine, pointerEventsSystem, InputAction } from '@dcl/sdk/ecs'
+import type { scene } from '../main-entities'
+
+type EntityName = keyof typeof scene
 
 export function main() {
-  // Create a cube at the center of the scene
-  const cube = engine.addEntity()
-  Transform.create(cube, {
-    position: Vector3.create(8, 1, 8)
-  })
-  MeshRenderer.setBox(cube)
-  Material.setPbrMaterial(cube, {
-    albedoColor: Color4.create(0.2, 0.5, 1, 1)
-  })
+  const cube = engine.getEntityOrNullByName<EntityName>('blue_cube')
+  if (cube === null) return
+
+  pointerEventsSystem.onPointerDown(
+    { entity: cube, opts: { button: InputAction.IA_POINTER, hoverText: 'Click me' } },
+    () => console.log('clicked'),
+  )
+}
+```
+
+`tsconfig.json` should include `main-entities.ts` so it gets type-checked:
+```json
+{
+  "extends": "@dcl/sdk/types/tsconfig.ecs7.json",
+  "include": ["src/**/*.ts", "src/**/*.tsx", "main-entities.ts"]
 }
 ```
 
+**Rules:**
+
+- Every editable / declared entity must have a unique Name in `main-entities.ts`.
+- Dynamic entities created at runtime (effects, projectiles, dynamic UI markers) use `engine.addEntity()` directly. **Don't give dynamic entities a Name** — they don't go in `main-entities.ts`.
+- Anything that's pure data (Transform, GltfContainer, MeshRenderer, MeshCollider, Material, AudioSource, VideoPlayer, TextShape, Animator config, NftShape, Billboard, VisibilityComponent) goes in `main-entities.ts`.
+- Anything that's behavior (pointer callbacks, systems, tween triggers, conditional logic) goes in `src/`.
+- The `scene` literal must be JSON-compatible — no function calls, no spreads, no comments inside the object.
+
 ### scene.json Reference
 
 All valid `scene.json` fields:
@@ -147,3 +189,4 @@ After customizing the files:
 - Y axis is up, minimum Y=0 (ground)
 - The `main` field in scene.json MUST be `"bin/index.js"` — this is the compiled output path
 - The `jsx` and `jsxImportSource` tsconfig settings are already included by `/init` — do not modify them
+- **Never pass `undefined` values in Transform fields** (position, rotation, scale) — the SDK serializer crashes. If a field is optional, omit the key entirely instead of including it with an `undefined` value.

package/skills/deploy-scene/SKILL.md

@@ -77,6 +77,18 @@ npx @dcl/sdk-commands deploy
 }
 ```
 
+### Scene Tipping (`creator`)
+
+Let visitors send MANA tips to the scene creator. Add a `creator` field with the recipient's wallet address:
+
+```json
+{
+  "creator": "0x1234567890123456789012345678901234567890"
+}
+```
+
+When set, a piggy-bank icon appears in the top-left for visitors. Clicking it opens a MANA tip modal. If the address is linked to a Decentraland NAME, the name is shown in the modal. Creators receive an in-app notification for each tip. Also configurable via Creator Hub → scene Settings → Details → Creator wallet address.
+
 ### Spawn Points
 
 Configure where players appear when entering the scene:

package/skills/deploy-worlds/SKILL.md

@@ -44,6 +44,41 @@ All Worlds are automatically listed on the [Places page](https://places.decentra
 }
 ```
 
+### Skybox + Minimap configuration
+
+`worldConfiguration` accepts extra fields that aren't available for Genesis City scenes:
+
+```json
+{
+  "worldConfiguration": {
+    "name": "my-name.dcl.eth",
+    "skyboxConfig": {
+      "fixedTime": 36000,
+      "textures": ["textures/skybox.png"]
+    },
+    "miniMapConfig": {
+      "visible": true,
+      "dataImage": "images/minimap.png",
+      "estateImage": "images/estate.png"
+    }
+  }
+}
+```
+
+`skyboxConfig.fixedTime`:
+
+| Value | Time of day |
+|---|---|
+| `0` | Midnight |
+| `18000` | 6 AM (sunrise) |
+| `36000` | Noon |
+| `45000` | 6 PM (sunset) |
+| `50400` | Maximum |
+
+Omit `fixedTime` for a dynamic day/night cycle. `textures` is an array of cubemap face textures (top/bottom/front/back/left/right) when you want a fully custom sky.
+
+`miniMapConfig`: set `visible: true` to show the minimap inside the World; `dataImage` is the base tile, `estateImage` overlays estate boundaries.
+
 ## 2. Deploy
 
 **Use the `/deploy` command** — it auto-detects the `worldConfiguration` in scene.json and deploys to the Worlds content server automatically.

package/skills/editor-gizmo/.gitignore

@@ -0,0 +1,11 @@
+# Only track the skill doc and editor module.
+# All test-scene scaffolds (scene.json, package.json, src/index.ts, main.json,
+# models/, .vscode/, etc.) are auto-ignored by the *-then-allowlist below.
+*
+!.gitignore
+!SKILL.md
+!src/
+!src/__editor/
+!src/__editor/**
+node_modules/
+bin/