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

package/README.md

@@ -28,11 +28,11 @@ The result: **more creators building more scenes, faster.**
 - **Branded header** — on startup, displays a block-character "Decentraland" ASCII art banner with version and working directory. Falls back to a compact text header on narrow terminals
 - **Multi-provider LLM support** — works with Claude, OpenAI, Google, Ollama (free/local), OpenRouter, and more
 - **Scene-aware** — automatically detects your project's `scene.json`, SDK version, and entry points
-- **19 built-in skills** — scaffolding, 3D models, interactivity, UI, animations, multiplayer, authoritative server, audio/video, deployment (Genesis City & Worlds), optimization, camera control, lighting, player/avatar, NFT/blockchain, advanced rendering, advanced input, scene runtime, visual feedback
+- **20 built-in skills** — scaffolding, 3D models, interactivity, UI, animations, multiplayer, authoritative server, audio/video, deployment (Genesis City & Worlds), optimization, camera control, lighting, player/avatar, NFT/blockchain, advanced rendering, advanced input, scene runtime, visual feedback, game design
 - **Integrated commands** — `/init` to scaffold, `/preview` to launch the dev server, `/tasks` to manage running processes, `/review` to audit code
 - **TypeScript validation** — catches type errors immediately after writing code
 - **Free asset catalogs** — 2,700+ Creator Hub 3D models, 900+ CC0-licensed models, and 50 audio files the agent proactively suggests when building scenes
-- **Permission gate** — prompts for confirmation before destructive bash commands, writes to sensitive files, or any file access outside the working directory
+- **Permission gate** — prompts for confirmation before destructive bash commands, writes to sensitive files, or writes/edits outside the working directory
 - **Compact tool output** — write shows path + size instead of file content, read shows a 5-line preview instead of 10
 - **Session persistence** — pick up where you left off across sessions
 
@@ -128,6 +128,7 @@ OpenDCL loads domain-specific skills on demand based on what you're asking:
 | `advanced-input` | Cursor state, movement restriction, WASD patterns |
 | `scene-runtime` | Async tasks, fetch, timers, realm info, restricted actions, testing |
 | `visual-feedback` | Use the screenshot tool to see your scene, verify changes, iterate visually |
+| `game-design` | Plan game architecture, scene limits, state management, MVP planning |
 
 ## How It Works
 
@@ -160,7 +161,7 @@ opendcl/
 │   ├── dcl-tasks.ts          # /tasks command (process manager)
 │   ├── process-registry.ts   # Shared background process registry
 │   └── permissions/           # Permission gate for dangerous operations
-├── skills/                   # 19 SKILL.md files (domain expertise)
+├── skills/                   # 20 SKILL.md files (domain expertise)
 ├── prompts/                  # System prompt + command templates
 ├── context/                  # SDK7 reference docs + asset catalog
 └── tests/                    # Vitest test suites

package/context/sdk7-cheat-sheet.md

@@ -18,8 +18,8 @@ import ReactEcs, { ReactEcsRenderer, UiEntity, Label, Button, Input, Dropdown }
 import { movePlayerTo, teleportTo, triggerEmote, changeRealm,
   openExternalUrl, openNftDialog, triggerSceneEmote,
   copyToClipboard } from '~system/RestrictedActions'
-import { getSceneInformation, getRealm, readFile } from '~system/Runtime'
-import { getWorldTime, getExplorerInformation } from '~system/EnvironmentApi'
+import { getSceneInformation, getRealm, readFile, getWorldTime,
+  getExplorerInformation } from '~system/Runtime'
 import { signedFetch, getHeaders } from '~system/SignedFetch'
 import { getPlayer } from '@dcl/sdk/src/players'
 ```
@@ -136,7 +136,7 @@ ColliderLayer.CL_CUSTOM1 … CL_CUSTOM8  // user-defined layers
   "featureToggles": { "voiceChat": "enabled" },
   "worldConfiguration": {
     "name": "my-world.dcl.eth",
-    "skyboxConfig": { "fixedHour": 14.0 }
+    "skyboxConfig": { "fixedTime": 36000 }
   }
 }
 ```

package/extensions/permissions/index.ts

@@ -7,7 +7,7 @@
  */
 
 import type { ExtensionFactory } from "@mariozechner/pi-coding-agent";
-import { classifyBashCommand, classifyFilePath, isOutsideCwd, OUTSIDE_CWD_REASON } from "./utils.js";
+import { classifyBashCommand, classifyFilePath, OUTSIDE_CWD_REASON } from "./utils.js";
 import { resolve } from "node:path";
 
 type BlockResult = { block: true; reason: string };
@@ -91,17 +91,6 @@ const extension: ExtensionFactory = (pi) => {
       return promptOrBlock(ctx, reason, `Path: ${filePath}`, () => sessionAllow.add(reason));
     }
 
-    if (toolName === "read" || toolName === "grep" || toolName === "find" || toolName === "ls") {
-      const filePath = (event.input as { path?: string }).path ?? "";
-      if (!filePath) return;
-
-      const resolved = resolve(ctx.cwd, filePath);
-      const reason = isOutsideCwd(filePath, ctx.cwd);
-      if (!reason) return;
-      if (isPathAllowed(resolved)) return;
-
-      return promptOrBlock(ctx, reason, `Path: ${filePath}`, () => allowedPaths.add(resolved));
-    }
   });
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dcl-regenesislabs/opendcl",
-  "version": "0.1.4",
+  "version": "0.1.5-23161709858.commit-828c176",
   "description": "AI coding assistant for Decentraland SDK7 scene development",
   "type": "module",
   "bin": {
@@ -67,5 +67,5 @@
     "prompts/",
     "context/"
   ],
-  "commit": "4a4167760132e6b2be9adbf0486f4b061222db69"
+  "commit": "828c176b27aa3da4e6eeebd001e2434c1df161fe"
 }

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

@@ -1,6 +1,6 @@
 ---
 name: add-3d-models
-description: Add 3D models (.glb/.gltf) to a Decentraland scene using GltfContainer. Covers loading models, positioning, scaling, colliders, and browsing the open-source 3D assets catalog for free CC0 models. Use when user wants to add models, import GLB files, or find free 3D assets.
+description: Add 3D models (.glb/.gltf) to a Decentraland scene using GltfContainer. Covers loading, positioning, scaling, colliders, parenting, and browsing 2,700+ free assets from the Creator Hub catalog and 991 CC0 models. Use when the user wants to add models, import GLB files, find free 3D assets, or set up model colliders. Do NOT use for materials/textures (see advanced-rendering) or model animations (see animations-tweens).
 ---
 
 # Adding 3D Models to Decentraland Scenes
@@ -145,6 +145,21 @@ engine.addSystem(() => {
 })
 ```
 
+## Troubleshooting
+
+| Problem | Cause | Solution |
+|---------|-------|----------|
+| Model not visible | Wrong file path | Verify the file exists at the exact path relative to project root (e.g., `models/myModel.glb`) |
+| Model not visible | Position outside scene boundaries | Check Transform position is within 0-16 per parcel. Center of 1-parcel scene is (8, 0, 8) |
+| Model not visible | Scale is 0 or very small | Check `Transform.scale` — default is (1,1,1). Try larger values if model was exported very small |
+| Model not visible | Behind the camera | Move the avatar or rotate to look in the model's direction |
+| Model loads but looks wrong | Y-up vs Z-up mismatch | Decentraland uses Y-up. Re-export from Blender with "Y Up" checked |
+| "FINISHED_WITH_ERROR" load state | Corrupted or unsupported .glb | Re-export the model. Use `.glb` (binary GLTF) format. Ensure no unsupported extensions |
+| Clicking model does nothing | Missing collider | Add `visibleMeshesCollisionMask: ColliderLayer.CL_POINTER` to `GltfContainer` or add `MeshCollider` |
+
+> **Need to optimize models for scene limits?** See the **optimize-scene** skill for triangle budgets and LOD patterns.
+> **Need animations from your model?** See the **animations-tweens** skill for playing GLTF animation clips with Animator.
+
 ## Model Best Practices
 
 - Keep models under 50MB per file for good loading times

package/skills/add-interactivity/SKILL.md

@@ -1,10 +1,22 @@
 ---
 name: add-interactivity
-description: Add click handlers, hover effects, pointer events, triggers, and raycasting to Decentraland scene entities. Use when user wants to make objects clickable, add interactions, detect player proximity, or handle user input.
+description: Add click handlers, hover effects, pointer events, trigger areas, raycasting, and global input to Decentraland scene entities. Use when the user wants to make objects clickable, add hover effects, detect player proximity, handle E/F key actions, or cast rays. Do NOT use for advanced input patterns like movement restriction, cursor lock, or WASD control (see advanced-input). Do NOT use for screen-space UI buttons (see build-ui).
 ---
 
 # Adding Interactivity to Decentraland Scenes
 
+## Decision Tree
+
+| Need | Approach | API |
+|------|----------|-----|
+| Click/hover on a specific entity | Pointer events | `pointerEventsSystem.onPointerDown()` |
+| Detect player entering an area | Trigger area | `TriggerArea` + `triggerAreaEventsSystem` |
+| Poll key state every frame | Global input | `inputSystem.isTriggered()` / `isPressed()` |
+| Detect objects in a direction | Raycasting | `raycastSystem` or `Raycast` component |
+| Read cursor position / lock state | Cursor state | `PointerLock`, `PrimaryPointerInfo` |
+
+---
+
 ## Pointer Events (Click / Hover)
 
 ### Using the Helper System (Recommended)
@@ -32,15 +44,29 @@ pointerEventsSystem.onPointerDown(
 )
 ```
 
-### Available Input Actions
+### All Input Actions
+```typescript
+InputAction.IA_POINTER    // Left mouse button
+InputAction.IA_PRIMARY    // E key
+InputAction.IA_SECONDARY  // F key
+InputAction.IA_ACTION_3   // 1 key
+InputAction.IA_ACTION_4   // 2 key
+InputAction.IA_ACTION_5   // 3 key
+InputAction.IA_ACTION_6   // 4 key
+InputAction.IA_JUMP       // Space key
+InputAction.IA_FORWARD    // W key
+InputAction.IA_BACKWARD   // S key
+InputAction.IA_LEFT       // A key
+InputAction.IA_RIGHT      // D key
+InputAction.IA_WALK       // Shift key
+```
+
+### All Event Types
 ```typescript
-InputAction.IA_POINTER   // Left click / primary
-InputAction.IA_PRIMARY   // E key
-InputAction.IA_SECONDARY // F key
-InputAction.IA_ACTION_3  // Key 1
-InputAction.IA_ACTION_4  // Key 2
-InputAction.IA_ACTION_5  // Key 3
-InputAction.IA_ACTION_6  // Key 4
+PointerEventType.PET_DOWN         // Button pressed
+PointerEventType.PET_UP           // Button released
+PointerEventType.PET_HOVER_ENTER  // Cursor enters entity
+PointerEventType.PET_HOVER_LEAVE  // Cursor leaves entity
 ```
 
 ### Pointer Up (Release)
@@ -77,6 +103,8 @@ GltfContainer.create(entity, {
 })
 ```
 
+---
+
 ## Trigger Areas (Proximity Detection)
 
 Detect when the player enters, exits, or stays inside an area:
@@ -121,9 +149,66 @@ Transform.create(mover, { position: Vector3.create(8, 0, 8) })
 MeshCollider.setBox(mover, ColliderLayer.CL_CUSTOM1)
 ```
 
+---
+
 ## Raycasting
 
-Cast rays to detect objects in a direction:
+### Raycast Direction Types
+
+Four direction modes are available:
+
+```typescript
+// 1. Local direction — relative to entity rotation
+{ $case: 'localDirection', localDirection: Vector3.Forward() }
+
+// 2. Global direction — world-space, ignores entity rotation
+{ $case: 'globalDirection', globalDirection: Vector3.Down() }
+
+// 3. Global target — aim at a world position
+{ $case: 'globalTarget', globalTarget: Vector3.create(10, 0, 10) }
+
+// 4. Target entity — aim at another entity
+{ $case: 'targetEntity', targetEntity: entityId }
+```
+
+### Callback-Based Raycasting (Recommended)
+
+```typescript
+import { raycastSystem, RaycastQueryType, ColliderLayer } from '@dcl/sdk/ecs'
+
+// Local direction raycast
+raycastSystem.registerLocalDirectionRaycast(
+  { entity: myEntity, opts: { queryType: RaycastQueryType.RQT_HIT_FIRST, direction: Vector3.Forward(), maxDistance: 16, collisionMask: ColliderLayer.CL_POINTER } },
+  (result) => {
+    if (result.hits.length > 0) {
+      console.log('Hit:', result.hits[0].entityId)
+    }
+  }
+)
+
+// Global direction raycast
+raycastSystem.registerGlobalDirectionRaycast(
+  { entity: myEntity, opts: { queryType: RaycastQueryType.RQT_HIT_FIRST, direction: Vector3.Down(), maxDistance: 20 } },
+  (result) => { /* handle hits */ }
+)
+
+// Target position raycast
+raycastSystem.registerGlobalTargetRaycast(
+  { entity: myEntity, opts: { globalTarget: Vector3.create(8, 0, 8), maxDistance: 20 } },
+  (result) => { /* handle result */ }
+)
+
+// Target entity raycast
+raycastSystem.registerTargetEntityRaycast(
+  { entity: sourceEntity, opts: { targetEntity: targetEntity, maxDistance: 15 } },
+  (result) => { /* handle result */ }
+)
+
+// Remove raycast from entity
+raycastSystem.removeRaycasterEntity(myEntity)
+```
+
+### Component-Based Raycasting
 
 ```typescript
 import { engine, Raycast, RaycastResult, RaycastQueryType } from '@dcl/sdk/ecs'
@@ -147,6 +232,27 @@ engine.addSystem(() => {
 })
 ```
 
+### Camera Raycast
+
+Cast a ray from the camera to detect what the player is looking at:
+
+```typescript
+raycastSystem.registerGlobalDirectionRaycast(
+  {
+    entity: engine.CameraEntity,
+    opts: {
+      direction: Vector3.rotate(Vector3.Forward(), Transform.get(engine.CameraEntity).rotation),
+      maxDistance: 16
+    }
+  },
+  (result) => {
+    if (result.hits.length > 0) console.log('Looking at:', result.hits[0].entityId)
+  }
+)
+```
+
+---
+
 ## Global Input Handling
 
 Listen for key presses anywhere (not entity-specific):
@@ -164,9 +270,35 @@ engine.addSystem(() => {
   if (inputSystem.isPressed(InputAction.IA_SECONDARY)) {
     console.log('F key is held!')
   }
+
+  // Entity-specific input via system
+  const clickData = inputSystem.getInputCommand(
+    InputAction.IA_POINTER,
+    PointerEventType.PET_DOWN,
+    myEntity
+  )
+  if (clickData) {
+    console.log('Entity clicked via system:', clickData.hit.entityId)
+  }
 })
 ```
 
+## Cursor State
+
+```typescript
+import { PointerLock, PrimaryPointerInfo } from '@dcl/sdk/ecs'
+
+// Check if cursor is locked
+const isLocked = PointerLock.get(engine.CameraEntity).isPointerLocked
+
+// Get cursor position and world ray
+const pointerInfo = PrimaryPointerInfo.get(engine.RootEntity)
+console.log('Cursor position:', pointerInfo.screenCoordinates)
+console.log('World ray direction:', pointerInfo.worldRayDirection)
+```
+
+---
+
 ## Toggle Pattern (Click to Switch States)
 
 Common pattern for toggleable objects:
@@ -186,33 +318,6 @@ pointerEventsSystem.onPointerDown(
 )
 ```
 
-### Raycast System Helpers
-
-Use `raycastSystem` for convenient raycasting without manual component management:
-
-```typescript
-import { raycastSystem, RaycastQueryType, ColliderLayer } from '@dcl/sdk/ecs'
-
-// Register a continuous local-direction raycast
-raycastSystem.registerLocalDirectionRaycast(
-  { entity: myEntity, opts: { queryType: RaycastQueryType.RQT_HIT_FIRST, direction: Vector3.Forward(), maxDistance: 16, collisionMask: ColliderLayer.CL_POINTER } },
-  (result) => {
-    if (result.hits.length > 0) {
-      console.log('Hit:', result.hits[0].entityId)
-    }
-  }
-)
-
-// Register a global-direction raycast
-raycastSystem.registerGlobalDirectionRaycast(
-  { entity: myEntity, opts: { queryType: RaycastQueryType.RQT_HIT_FIRST, direction: Vector3.Down(), maxDistance: 20 } },
-  (result) => { /* handle hits */ }
-)
-
-// Remove raycast from entity
-raycastSystem.removeRaycasterEntity(myEntity)
-```
-
 ## Best Practices
 
 - Always set `maxDistance` on pointer events (8-16m is typical)
@@ -221,3 +326,7 @@ raycastSystem.removeRaycasterEntity(myEntity)
 - Use `MeshCollider` for invisible trigger surfaces
 - For complex interactions, use a system with state tracking
 - Test interactions in preview — hover text should be visible and clear
+- Set `continuous: false` on raycasts unless you need per-frame results
+- Design for both desktop and mobile — mobile has no keyboard, rely on pointer and on-screen buttons
+
+For the full input action list and advanced patterns, see `{baseDir}/references/input-reference.md`.

package/skills/add-interactivity/references/input-reference.md

@@ -0,0 +1,148 @@
+# Input System Reference
+
+## All Input Actions
+
+| Action | Key Binding | Constant |
+|--------|-------------|----------|
+| Left mouse button | Mouse click / tap | `InputAction.IA_POINTER` |
+| Primary action | E key | `InputAction.IA_PRIMARY` |
+| Secondary action | F key | `InputAction.IA_SECONDARY` |
+| Action 3 | 1 key | `InputAction.IA_ACTION_3` |
+| Action 4 | 2 key | `InputAction.IA_ACTION_4` |
+| Action 5 | 3 key | `InputAction.IA_ACTION_5` |
+| Action 6 | 4 key | `InputAction.IA_ACTION_6` |
+| Jump | Space key | `InputAction.IA_JUMP` |
+| Forward | W key | `InputAction.IA_FORWARD` |
+| Backward | S key | `InputAction.IA_BACKWARD` |
+| Left | A key | `InputAction.IA_LEFT` |
+| Right | D key | `InputAction.IA_RIGHT` |
+| Walk | Shift key | `InputAction.IA_WALK` |
+
+**Notes:**
+- Mouse wheel is **not available** as an input
+- Always design for both desktop and mobile — mobile has no keyboard, rely on pointer and on-screen buttons
+- Set `maxDistance` on pointer events (8-10 meters typical) to prevent interactions from across the scene
+- Use `hoverText` to communicate what an interaction does before the player commits
+
+## All Pointer Event Types
+
+```typescript
+PointerEventType.PET_DOWN         // Button/key pressed
+PointerEventType.PET_UP           // Button/key released
+PointerEventType.PET_HOVER_ENTER  // Cursor enters entity bounds
+PointerEventType.PET_HOVER_LEAVE  // Cursor leaves entity bounds
+```
+
+## Declarative Pointer Events Component
+
+Instead of the callback system, you can use the `PointerEvents` component directly:
+
+```typescript
+import { PointerEvents, PointerEventType, InputAction } from '@dcl/sdk/ecs'
+
+PointerEvents.create(entity, {
+  pointerEvents: [
+    {
+      eventType: PointerEventType.PET_DOWN,
+      eventInfo: {
+        button: InputAction.IA_POINTER,
+        hoverText: 'Click me',
+        showFeedback: true,
+        maxDistance: 10
+      }
+    }
+  ]
+})
+```
+
+Then read results in a system using `inputSystem.getInputCommand()`.
+
+## Raycast Direction Types
+
+```typescript
+// 1. Local direction — relative to entity rotation
+{ $case: 'localDirection', localDirection: Vector3.Forward() }
+
+// 2. Global direction — world-space direction, ignores entity rotation
+{ $case: 'globalDirection', globalDirection: Vector3.Down() }
+
+// 3. Global target — aim at a specific world position
+{ $case: 'globalTarget', globalTarget: Vector3.create(10, 0, 10) }
+
+// 4. Target entity — aim at another entity dynamically
+{ $case: 'targetEntity', targetEntity: entityId }
+```
+
+### Raycast Options
+
+```typescript
+{
+  direction: Vector3.Forward(),
+  maxDistance: 16,
+  queryType: RaycastQueryType.RQT_HIT_FIRST,  // or RQT_QUERY_ALL
+  originOffset: Vector3.create(0, 0.5, 0),     // offset from entity origin
+  collisionMask: ColliderLayer.CL_PHYSICS | ColliderLayer.CL_CUSTOM1,
+  continuous: false  // true = every frame, false = one-shot
+}
+```
+
+### Camera Raycast
+
+Cast a ray from the camera to detect what the player is looking at:
+
+```typescript
+raycastSystem.registerGlobalDirectionRaycast(
+  {
+    entity: engine.CameraEntity,
+    opts: {
+      direction: Vector3.rotate(Vector3.Forward(), Transform.get(engine.CameraEntity).rotation),
+      maxDistance: 16
+    }
+  },
+  (result) => {
+    if (result.hits.length > 0) console.log('Looking at:', result.hits[0].entityId)
+  }
+)
+```
+
+## Avatar Modifier Areas
+
+Modify how avatars appear or behave in a region:
+
+```typescript
+import { AvatarModifierArea, AvatarModifierType } from '@dcl/sdk/ecs'
+
+AvatarModifierArea.create(entity, {
+  area: { box: Vector3.create(4, 3, 4) },
+  modifiers: [AvatarModifierType.AMT_HIDE_AVATARS],
+  excludeIds: ['0x123...abc']  // Optional
+})
+
+// Available modifiers:
+// AMT_HIDE_AVATARS      — Hide all avatars in the area
+// AMT_DISABLE_PASSPORTS — Disable clicking on avatars to see profiles
+// AMT_DISABLE_JUMPING   — Prevent jumping in the area
+```
+
+## Cursor State
+
+```typescript
+// Check if cursor is locked (pointer lock mode)
+const isLocked = PointerLock.get(engine.CameraEntity).isPointerLocked
+
+// Get cursor position and world ray
+const pointerInfo = PrimaryPointerInfo.get(engine.RootEntity)
+console.log('Cursor screen position:', pointerInfo.screenCoordinates)
+console.log('World ray direction:', pointerInfo.worldRayDirection)
+```
+
+## Trigger Area Callback Fields
+
+The trigger area event callback provides:
+- `triggeredEntity` — the entity that activated the area
+- `eventType` — ENTER, EXIT, or STAY
+- `trigger.entity` — the trigger area entity
+- `trigger.layer` — the collider layer
+- `trigger.position` — position of the triggered entity
+- `trigger.rotation` — rotation of the triggered entity
+- `trigger.scale` — scale of the triggered entity

package/skills/advanced-input/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: advanced-input
-description: Advanced input handling in Decentraland scenes. Use PointerLock to detect cursor capture state, InputModifier to freeze or restrict player movement, PrimaryPointerInfo for cursor position and world ray, inputSystem.getInputCommand for per-entity input polling, and keyboard patterns for WASD movement controls. Use when user wants custom input, cursor control, movement restriction, keyboard handling, FPS controls, or input polling.
+description: Advanced input handling in Decentraland. PointerLock (cursor capture state), InputModifier (freeze/restrict player movement), PrimaryPointerInfo (cursor position and world ray), WASD keyboard patterns, and action bar slots. Use when the user wants movement restriction, cursor control, FPS controls, input polling, or cutscene freezing. Do NOT use for basic click/hover events on entities (see add-interactivity).
 ---
 
 # Advanced Input Handling in Decentraland

package/skills/advanced-rendering/SKILL.md

@@ -1,10 +1,26 @@
 ---
 name: advanced-rendering
-description: Advanced rendering features in Decentraland scenes. Use Billboard to make entities face the camera, TextShape for 3D text, advanced PBR material properties like metallic/roughness/transparency, GltfNodeModifiers for per-node visibility and material overrides in GLTF models, and VisibilityComponent to show/hide entities. Use when user wants billboards, 3D text, text labels, material effects, transparency, glow, or model node control.
+description: Advanced rendering in Decentraland scenes. Billboard (face camera), TextShape (3D world text), PBR materials (metallic, roughness, transparency, emissive glow), GltfNodeModifiers (per-node shadow/material overrides), VisibilityComponent (show/hide entities), and texture modes. Use when the user wants billboards, floating labels, 3D text, material effects, glow, transparency, or model node control. Do NOT use for screen-space UI (see build-ui) or loading 3D models (see add-3d-models).
 ---
 
 # Advanced Rendering in Decentraland
 
+## When to Use Which Rendering Feature
+
+| Need | Component | When |
+|------|-----------|------|
+| Entity faces the camera | `Billboard` | Name tags, signs, sprite-like objects |
+| Text in the 3D world | `TextShape` | Labels, signs, floating text above entities |
+| Custom material appearance | `Material.setPbrMaterial` | Metallic, rough, transparent, emissive surfaces |
+| Show/hide without removing | `VisibilityComponent` | LOD systems, toggling objects, conditional display |
+| Modify GLTF model nodes | `GltfNodeModifiers` | Override materials or shadow casting on specific mesh nodes |
+
+**Decision flow:**
+1. Need text on screen? → Use **build-ui** (React-ECS Label) instead
+2. Need text in 3D space? → `TextShape` (+ `Billboard` to face camera)
+3. Need glowing/transparent materials? → `Material.setPbrMaterial` with emissive/transparency
+4. Need to override material on a model node? → `GltfNodeModifiers` with `modifiers` array
+
 ## Billboard (Face the Camera)
 
 Make entities always rotate to face the player's camera:
@@ -212,20 +228,20 @@ function lodSystem() {
 engine.addSystem(lodSystem)
 ```
 
-### Per-Node Material Overrides (GltfNodeModifiers)
+### Per-Node Modifiers (GltfNodeModifiers)
 
-Override materials on specific nodes within a GLTF model without modifying the model file:
+Override material or shadow casting on specific nodes within a GLTF model:
 
 ```typescript
-import { GltfNode, GltfNodeState } from '@dcl/sdk/ecs'
+import { GltfNodeModifiers } from '@dcl/sdk/ecs'
 
-// Hide a specific node in a model
-GltfNode.create(entity, { path: 'RootNode/Armor', visible: false })
-
-// Override a node's material
-GltfNode.create(entity, {
-  path: 'RootNode/Helmet',
-  materialOverride: Material.Texture.Common({ src: 'images/custom-skin.png' })
+GltfNodeModifiers.create(entity, {
+  modifiers: [
+    {
+      path: 'RootNode/Armor',     // GLTF hierarchy path
+      castShadows: false           // Disable shadow casting for this node
+    }
+  ]
 })
 ```