@dcl-regenesislabs/opendcl 0.2.1-26165320302.commit-e6effe4 → 0.2.1-26238928766.commit-28648d7

package/skills/add-3d-models/SKILL.md

@@ -5,27 +5,30 @@ description: Add 3D models (.glb/.gltf) to a Decentraland scene using GltfContai
 
 # Adding 3D Models to Decentraland Scenes
 
-## Loading a 3D Model
+## Where models go: `main-entities.ts`
 
-Use `GltfContainer` to load `.glb` or `.gltf` files:
+A 3D model placed at author time is a static visible entity. **Declare it in `main-entities.ts`**, not via `engine.addEntity()` in `src/index.ts`. The build compiles `main-entities.ts` into `main.crdt`, the engine preloads it before `main()` runs, and the editor can drag/rotate the model interactively.
 
 ```typescript
-import { engine, Transform, GltfContainer, ColliderLayer } from '@dcl/sdk/ecs'
-import { Vector3, Quaternion } from '@dcl/sdk/math'
-
-const model = engine.addEntity()
-Transform.create(model, {
-  position: Vector3.create(8, 0, 8),
-  rotation: Quaternion.fromEulerDegrees(0, 0, 0),
-  scale: Vector3.create(1, 1, 1)
-})
-GltfContainer.create(model, {
-  src: 'models/myModel.glb',
-  visibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER
-})
+// main-entities.ts
+import type { Scene } from '@dcl/sdk/scene-types'
+
+export const scene = {
+  my_model: {
+    components: {
+      Transform: { position: { x: 8, y: 0, z: 8 } },
+      GltfContainer: {
+        src: 'models/myModel.glb',
+        visibleMeshesCollisionMask: 3 // CL_PHYSICS | CL_POINTER
+      }
+    }
+  }
+} satisfies Scene
 ```
 
-> **Always set `visibleMeshesCollisionMask`** when loading models. Catalog models don't include separate collider meshes — using the visible mesh as the collider ensures the model is solid and clickable.
+> **Always set `visibleMeshesCollisionMask`** on `GltfContainer`. Catalog models don't include separate collider meshes — using the visible mesh as the collider ensures the model is solid and clickable. Use the integer value (`ColliderLayer.CL_PHYSICS = 1`, `CL_POINTER = 2`, both = `3`) inside `main-entities.ts` since enums aren't allowed in the literal.
+
+**When to use `engine.addEntity()` in `src/index.ts` instead**: only when the model is spawned dynamically (procedurally placed in a loop, dropped on an event, gated by NFT ownership, etc.). For static props, always use `main-entities.ts`.
 
 ## File Organization
 
@@ -46,52 +49,80 @@ project/
 ## Colliders
 
 ### Using Model's Built-in Colliders
-Models exported with collision meshes work automatically. Set the collision mask:
+
 ```typescript
-GltfContainer.create(model, {
-  src: 'models/building.glb',
-  visibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER,
-  invisibleMeshesCollisionMask: ColliderLayer.CL_PHYSICS
-})
+// main-entities.ts — declared inline with GltfContainer
+building: {
+  components: {
+    Transform: { position: { x: 8, y: 0, z: 8 } },
+    GltfContainer: {
+      src: 'models/building.glb',
+      visibleMeshesCollisionMask: 3,    // CL_PHYSICS | CL_POINTER
+      invisibleMeshesCollisionMask: 1   // CL_PHYSICS
+    }
+  }
+}
 ```
 
 ### Adding Simple Colliders
-For basic shapes, add `MeshCollider`:
+
+For basic shapes (no GLTF), add `MeshCollider`:
+
 ```typescript
-import { MeshCollider } from '@dcl/sdk/ecs'
-MeshCollider.setBox(model) // Box collider
-MeshCollider.setSphere(model) // Sphere collider
+// main-entities.ts
+invisible_wall: {
+  components: {
+    Transform: { position: { x: 0, y: 1, z: 8 }, scale: { x: 0.1, y: 2, z: 16 } },
+    MeshCollider: { mesh: { $case: 'box', box: { uvs: [] } } }
+  }
+}
 ```
 
+Other shapes: `{ $case: 'sphere', sphere: {} }`, `{ $case: 'plane', plane: { uvs: [] } }`, `{ $case: 'cylinder', cylinder: {} }`.
+
+## ⚠️ Important: Never Pass `undefined` in Transform Fields
+
+The SDK serializer crashes if any Transform field (`position`, `rotation`, `scale`) is present but `undefined`. **Omit the key entirely** instead — both in `main-entities.ts` literals and in any runtime helpers. In `main-entities.ts` this is natural (you just don't write the field).
+
 ## Common Model Operations
 
 ### Scaling
-```typescript
-Transform.create(model, {
-  position: Vector3.create(8, 0, 8),
-  scale: Vector3.create(2, 2, 2) // 2x size
-})
-```
 
-### Rotation
 ```typescript
-Transform.create(model, {
-  position: Vector3.create(8, 0, 8),
-  rotation: Quaternion.fromEulerDegrees(0, 90, 0) // Rotate 90° on Y axis
-})
+// main-entities.ts
+big_statue: {
+  components: {
+    Transform: { position: { x: 8, y: 0, z: 8 }, scale: { x: 2, y: 2, z: 2 } },
+    GltfContainer: { src: 'models/statue.glb' }
+  }
+}
 ```
 
-### Parenting (Attach to Another Entity)
-```typescript
-const parent = engine.addEntity()
-Transform.create(parent, { position: Vector3.create(8, 0, 8) })
+### Rotation (Euler angles converted to a quaternion at author time)
+
+Quaternions are `{ x, y, z, w }`. For `Quaternion.fromEulerDegrees(0, 90, 0)` the equivalent literal is `{ x: 0, y: 0.7071, z: 0, w: 0.7071 }`. If you need exact-degree rotations and don't want to compute by hand, set `rotation` to identity in `main-entities.ts` and rotate at runtime in `src/index.ts` using `Transform.getMutable(entity).rotation = Quaternion.fromEulerDegrees(0, 90, 0)`.
+
+### Parenting
+
+Reference the parent by **name** (a string key from the same `scene` object). The build resolves names to entity IDs in a second pass.
 
-const child = engine.addEntity()
-Transform.create(child, {
-  position: Vector3.create(0, 2, 0), // 2m above parent
-  parent: parent
-})
-GltfContainer.create(child, { src: 'models/hat.glb' })
+```typescript
+// main-entities.ts
+character: {
+  components: {
+    Transform: { position: { x: 8, y: 0, z: 8 } },
+    GltfContainer: { src: 'models/character.glb' }
+  }
+},
+hat: {
+  components: {
+    Transform: {
+      position: { x: 0, y: 2, z: 0 },  // 2m above parent's origin
+      parent: 'character'
+    },
+    GltfContainer: { src: 'models/hat.glb' }
+  }
+}
 ```
 
 ## Free 3D Models — OpenDCL Catalog (5,700+ models)
@@ -146,19 +177,34 @@ curl -o models/zombie-purple.glb "https://models.dclregenesislabs.xyz/blobs/bafy
 ```
 
 ```typescript
-// Use in code with animations
-import { engine, Transform, GltfContainer, Animator } from '@dcl/sdk/ecs'
-import { Vector3 } from '@dcl/sdk/math'
+// main-entities.ts — declare the entity with all its initial state
+import type { Scene } from '@dcl/sdk/scene-types'
+
+export const scene = {
+  zombie: {
+    components: {
+      Transform: { position: { x: 8, y: 0, z: 8 } },
+      GltfContainer: { src: 'models/zombie-purple.glb' },
+      Animator: {
+        states: [
+          { clip: 'ZombieWalk', playing: true, loop: true },
+          { clip: 'ZombieAttack', playing: false, loop: false }
+        ]
+      }
+    }
+  }
+} satisfies Scene
+```
+
+To switch animations at runtime (e.g., trigger attack on click), use `src/index.ts`:
 
-const zombie = engine.addEntity()
-Transform.create(zombie, { position: Vector3.create(8, 0, 8) })
-GltfContainer.create(zombie, { src: 'models/zombie-purple.glb' })
-Animator.create(zombie, {
-  states: [
-    { clip: 'ZombieWalk', playing: true, loop: true },
-    { clip: 'ZombieAttack', playing: false, loop: false }
-  ]
-})
+```typescript
+import { engine, Animator } from '@dcl/sdk/ecs'
+
+export function main() {
+  const zombie = engine.getEntityOrNullByName('zombie')
+  if (zombie) Animator.playSingleAnimation(zombie, 'ZombieAttack')
+}
 ```
 
 > **Important**: `GltfContainer` only works with **local files**. Never use external URLs for the model `src` field. Always download models into `models/` first.
@@ -166,19 +212,23 @@ Animator.create(zombie, {
 
 ### Checking Model Load State
 
-Use `GltfContainerLoadingState` to check if a model has finished loading:
+Load-state polling is runtime behavior — put it in `src/index.ts` and reference the entity by name:
 
 ```typescript
-import { GltfContainer, GltfContainerLoadingState, LoadingState } from '@dcl/sdk/ecs'
-
-engine.addSystem(() => {
-  const state = GltfContainerLoadingState.getOrNull(modelEntity)
-  if (state && state.currentState === LoadingState.FINISHED) {
-    console.log('Model loaded successfully')
-  } else if (state && state.currentState === LoadingState.FINISHED_WITH_ERROR) {
-    console.log('Model failed to load')
-  }
-})
+import { engine, GltfContainerLoadingState, LoadingState } from '@dcl/sdk/ecs'
+
+export function main() {
+  engine.addSystem(() => {
+    const model = engine.getEntityOrNullByName('zombie')
+    if (!model) return
+    const state = GltfContainerLoadingState.getOrNull(model)
+    if (state?.currentState === LoadingState.FINISHED) {
+      console.log('Model loaded successfully')
+    } else if (state?.currentState === LoadingState.FINISHED_WITH_ERROR) {
+      console.log('Model failed to load')
+    }
+  })
+}
 ```
 
 ## Troubleshooting

package/skills/add-interactivity/SKILL.md

@@ -5,6 +5,37 @@ description: Add click handlers, hover effects, pointer events, trigger areas, r
 
 # Adding Interactivity to Decentraland Scenes
 
+## Authoring split
+
+The clickable entity (cube, button, model) is static — declare it in `main-entities.ts` with its Transform / Mesh / Material. The clickability itself is **always** added at runtime in `src/index.ts` via `pointerEventsSystem.onPointerDown(...)` (or the related helpers). The helper writes the `PointerEvents` component AND registers the callback in a single call — do NOT also declare `PointerEvents` in `main-entities.ts`; the helper would just overwrite it and the duplication invites drift.
+
+```typescript
+// main-entities.ts — entity only, no PointerEvents
+clickable_cube: {
+  components: {
+    Transform: { position: { x: 8, y: 1, z: 8 } },
+    MeshRenderer: { mesh: { $case: 'box', box: { uvs: [] } } }
+  }
+}
+```
+
+```typescript
+// src/index.ts — register clickability via the helper system
+import { engine, pointerEventsSystem, InputAction } from '@dcl/sdk/ecs'
+
+export function main() {
+  const cube = engine.getEntityOrNullByName('clickable_cube')
+  if (cube) {
+    pointerEventsSystem.onPointerDown(
+      { entity: cube, opts: { button: InputAction.IA_POINTER, hoverText: 'Open' } },
+      () => { /* what happens on click */ }
+    )
+  }
+}
+```
+
+`TriggerArea` and `Raycast` are also runtime — they live in `src/index.ts`. Code examples below that create entities inline with `engine.addEntity()` are for runtime/technical entities (raycast probes, trigger volumes generated from data); for static clickable props, declare the prop in `main-entities.ts` and attach handlers in `src/index.ts` as above.
+
 ## Decision Tree
 
 | Need | Approach | API |
@@ -89,10 +120,10 @@ pointerEventsSystem.removeOnPointerUp(cube)
 ```
 
 ### Important: Colliders Required
-Pointer events only work on entities with a **collider**. Add one if your entity doesn't have a mesh:
+Pointer events only work on entities with a **collider on the `CL_POINTER` layer**. Add one if your entity doesn't have a mesh:
 ```typescript
 import { MeshCollider } from '@dcl/sdk/ecs'
-MeshCollider.setBox(entity) // Invisible box collider
+MeshCollider.setBox(entity) // Invisible box collider — defaults include CL_POINTER
 ```
 
 For GLTF models, set the collision mask:
@@ -105,6 +136,47 @@ GltfContainer.create(entity, {
 
 ---
 
+## Proximity Events (Pointer-Free Triggers)
+
+Like `pointerEventsSystem.onPointerDown`, but fires based on **player distance** to the entity instead of a click. Useful for "press E when near" interactions and signposts that highlight on approach. No collider required — the system polls the player position vs the entity transform.
+
+```typescript
+import { engine, pointerEventsSystem, InputAction } from '@dcl/sdk/ecs'
+
+const door = engine.getEntityOrNullByName('shop_door')
+if (door) {
+  pointerEventsSystem.onProximityDown(
+    {
+      entity: door,
+      opts: {
+        button: InputAction.IA_PRIMARY,
+        hoverText: 'Open shop',
+        maxPlayerDistance: 3   // metres
+      }
+    },
+    () => { /* run when the player presses the button within range */ }
+  )
+
+  pointerEventsSystem.onProximityEnter(
+    { entity: door, opts: { maxPlayerDistance: 5 } },
+    () => { /* fired once when the player enters the radius */ }
+  )
+
+  pointerEventsSystem.onProximityLeave(
+    { entity: door, opts: { maxPlayerDistance: 5 } },
+    () => { /* fired once when the player leaves the radius */ }
+  )
+}
+```
+
+- `maxPlayerDistance` is required and is measured from the **avatar root**, not the camera.
+- `priority` (number) — if multiple proximity events overlap, the higher value wins.
+- Remove with `pointerEventsSystem.removeOnProximityDown(entity)` etc.
+
+Prefer **proximity events** over `pointerEventsSystem.onPointerDown` when the entity has no visible collider or when the player shouldn't need to aim at it (signs, doors that just open when approached, etc.).
+
+---
+
 ## Trigger Areas (Proximity Detection)
 
 Detect when the player enters, exits, or stays inside an area:

package/skills/advanced-input/SKILL.md

@@ -83,6 +83,8 @@ engine.addSystem(myInputSystem)
 
 ### Global Input Checks
 
+Fires regardless of whether the player's cursor was over an entity.
+
 ```typescript
 function globalInputSystem() {
   // Was the key just pressed this frame?
@@ -99,6 +101,31 @@ function globalInputSystem() {
 engine.addSystem(globalInputSystem)
 ```
 
+### Tag-Based Input Batching
+
+If you have many similar entities that all respond to the same input (e.g., every barrel responds to E to break), tag them via the `Tag` component and iterate the tag query each frame:
+
+```typescript
+import { engine, Tag, inputSystem, InputAction, PointerEventType } from '@dcl/sdk/ecs'
+
+// At setup: tag the entities (or declare Tag in main-entities.ts).
+for (const barrel of [b1, b2, b3]) {
+  Tag.createOrReplace(barrel, { value: 'breakable' })
+}
+
+engine.addSystem(() => {
+  for (const [entity] of engine.getEntitiesByTag('breakable')) {
+    const cmd = inputSystem.getInputCommand(InputAction.IA_PRIMARY, PointerEventType.PET_DOWN, entity)
+    if (cmd) {
+      // entity was the IA_PRIMARY target this frame
+      engine.removeEntity(entity)
+    }
+  }
+})
+```
+
+Cleaner than registering N individual `pointerEventsSystem.onPointerDown` handlers when the behavior is uniform.
+
 ## All InputAction Values
 
 | InputAction | Key/Button |
@@ -138,11 +165,15 @@ InputModifier.create(engine.PlayerEntity, {
   mode: InputModifier.Mode.Standard({ disableAll: true })
 })
 
-// Restrict specific movement
+// Restrict specific movement (every flag is optional and defaults to false)
 InputModifier.createOrReplace(engine.PlayerEntity, {
   mode: InputModifier.Mode.Standard({
+    disableWalk: false,
+    disableJog: false,
     disableRun: true,
     disableJump: true,
+    disableDoubleJump: true,
+    disableGliding: true,
     disableEmote: true
   })
 })
@@ -151,6 +182,8 @@ InputModifier.createOrReplace(engine.PlayerEntity, {
 InputModifier.deleteFrom(engine.PlayerEntity)
 ```
 
+While restricted: gravity still applies, the camera still rotates, and pointer / proximity events still fire. All restrictions auto-lift when the player leaves the scene.
+
 **Important:** InputModifier only works in the DCL 2.0 desktop client. It has no effect in the web browser explorer.
 
 ### Cutscene Pattern

package/skills/advanced-rendering/SKILL.md

@@ -5,6 +5,22 @@ description: Advanced rendering in Decentraland scenes. Billboard (face camera),
 
 # Advanced Rendering in Decentraland
 
+## Authoring split
+
+`Billboard`, `TextShape`, `Material`, `MeshRenderer`, `GltfContainer`, `VisibilityComponent`, and `GltfNodeModifiers` are **all supported in `main-entities.ts`** — declare the visual entity (sign, label, billboard, glowing prop, model with per-node overrides) fully there with its visual components. Examples below that show `engine.addEntity()` followed by `Transform.create` + `MeshRenderer` / `Billboard` / `TextShape` are pre-`main-entities.ts` patterns — translate them by moving the entity declaration into `main-entities.ts` and keeping only runtime modifications (e.g., `VisibilityComponent.getMutable(entity).visible = false`) in `src/index.ts`.
+
+```typescript
+// Example: floating label
+// main-entities.ts
+shop_label: {
+  components: {
+    Transform: { position: { x: 8, y: 3, z: 8 } },
+    TextShape: { text: 'OPEN', fontSize: 4, textColor: { r: 1, g: 1, b: 1, a: 1 } },
+    Billboard: { billboardMode: 7 }  // BM_ALL
+  }
+}
+```
+
 ## When to Use Which Rendering Feature
 
 | Need | Component | When |
@@ -230,21 +246,78 @@ engine.addSystem(lodSystem)
 
 ### Per-Node Modifiers (GltfNodeModifiers)
 
-Override material or shadow casting on specific nodes within a GLTF model:
+Override material or shadow casting on specific nodes within a GLTF model. Supported in `main-entities.ts`:
+
+```typescript
+// main-entities.ts
+armored_knight: {
+  components: {
+    Transform: { position: { x: 8, y: 0, z: 8 } },
+    GltfContainer: { src: 'models/knight.glb' },
+    GltfNodeModifiers: {
+      modifiers: [
+        {
+          path: 'RootNode/Armor',     // GLTF hierarchy path
+          castShadows: false           // disable shadows for this node
+        }
+      ]
+    }
+  }
+}
+```
+
+**Whole-model override**: pass `path: ''` (empty string) to apply the modifier to every node in the model. Useful for re-skinning an entire model with a single material swap:
 
 ```typescript
-import { GltfNodeModifiers } from '@dcl/sdk/ecs'
+red_team_unit: {
+  components: {
+    Transform: { position: { x: 4, y: 0, z: 8 } },
+    GltfContainer: { src: 'models/unit.glb' },
+    GltfNodeModifiers: {
+      modifiers: [
+        {
+          path: '',
+          material: {
+            material: {
+              $case: 'pbr',
+              pbr: { albedoColor: { r: 1, g: 0, b: 0, a: 1 } }
+            }
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+### Texture Tweens (Animate Material Textures)
+
+Animate a material's texture offset/tiling over time — useful for water, lava, conveyor belts, scrolling backgrounds. Tween component is supported in `main-entities.ts`:
 
-GltfNodeModifiers.create(entity, {
-  modifiers: [
-    {
-      path: 'RootNode/Armor',     // GLTF hierarchy path
-      castShadows: false           // Disable shadow casting for this node
+```typescript
+// main-entities.ts — continuous texture scroll
+conveyor: {
+  components: {
+    Transform: { position: { x: 8, y: 1, z: 8 } },
+    MeshRenderer: { mesh: { $case: 'plane', plane: { uvs: [] } } },
+    Material: { material: { $case: 'pbr', pbr: { texture: { tex: { $case: 'texture', texture: { src: 'images/belt.png' } } } } } },
+    Tween: {
+      duration: 2000,
+      easingFunction: 0,  // EF_LINEAR
+      mode: {
+        $case: 'textureMoveContinuous',
+        textureMoveContinuous: { direction: { x: 1, y: 0 }, speed: 0.5 }
+        // movementType defaults to 0 = TMT_OFFSET; use 1 = TMT_TILING to scale instead
+      }
     }
-  ]
-})
+  }
+}
 ```
 
+For a finite from-to texture move, use `{ $case: 'textureMove', textureMove: { start: { x: 0, y: 0 }, end: { x: 1, y: 0 }, movementType: 0 } }` with a `duration`.
+
+Runtime helpers (in `src/index.ts`): `Tween.setTextureMove(entity, from, to, durationMs)` and `Tween.setTextureMoveContinuous(entity, direction, speed)`.
+
 ### Avatar Texture
 
 Generate a texture from a player's avatar: