@dcl-regenesislabs/opendcl 0.1.0-22234509684.commit-63dfd19

package/skills/advanced-rendering/SKILL.md

@@ -0,0 +1,235 @@
+---
+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.
+---
+
+# Advanced Rendering in Decentraland
+
+## Billboard (Face the Camera)
+
+Make entities always rotate to face the player's camera:
+
+```typescript
+import { engine, Transform, Billboard, BillboardMode, MeshRenderer } from '@dcl/sdk/ecs'
+import { Vector3 } from '@dcl/sdk/math'
+
+const sign = engine.addEntity()
+Transform.create(sign, { position: Vector3.create(8, 2, 8) })
+MeshRenderer.setPlane(sign)
+
+// Rotate only on Y axis (most common — stays upright)
+Billboard.create(sign, {
+  billboardMode: BillboardMode.BM_Y
+})
+```
+
+### Billboard Modes
+
+```typescript
+BillboardMode.BM_Y      // Rotate on Y axis only (stays upright) — most common
+BillboardMode.BM_ALL    // Rotate on all axes (fully faces camera)
+BillboardMode.BM_X      // Rotate on X axis only
+BillboardMode.BM_Z      // Rotate on Z axis only
+BillboardMode.BM_NONE   // No billboard rotation
+```
+
+- Prefer `BM_Y` over `BM_ALL` for most use cases — it looks more natural and is cheaper to render.
+- `BM_ALL` is useful for particles or effects that should always directly face the camera.
+
+## TextShape (3D Text)
+
+Render text directly in 3D space:
+
+```typescript
+import { engine, Transform, TextShape, TextAlignMode } from '@dcl/sdk/ecs'
+import { Vector3, Color4 } from '@dcl/sdk/math'
+
+const label = engine.addEntity()
+Transform.create(label, { position: Vector3.create(8, 3, 8) })
+
+TextShape.create(label, {
+  text: 'Hello World!',
+  fontSize: 24,
+  fontWeight: 'bold',
+  color: Color4.White(),
+  outlineColor: Color4.Black(),
+  outlineWidth: 0.1,
+  textAlign: TextAlignMode.TAM_MIDDLE_CENTER
+})
+```
+
+### Text Alignment Options
+
+```typescript
+TextAlignMode.TAM_TOP_LEFT
+TextAlignMode.TAM_TOP_CENTER
+TextAlignMode.TAM_TOP_RIGHT
+TextAlignMode.TAM_MIDDLE_LEFT
+TextAlignMode.TAM_MIDDLE_CENTER
+TextAlignMode.TAM_MIDDLE_RIGHT
+TextAlignMode.TAM_BOTTOM_LEFT
+TextAlignMode.TAM_BOTTOM_CENTER
+TextAlignMode.TAM_BOTTOM_RIGHT
+```
+
+### Floating Label (Billboard + TextShape)
+
+Combine Billboard and TextShape to create labels that always face the player:
+
+```typescript
+const floatingLabel = engine.addEntity()
+Transform.create(floatingLabel, { position: Vector3.create(8, 4, 8) })
+
+TextShape.create(floatingLabel, {
+  text: 'NPC Name',
+  fontSize: 16,
+  color: Color4.White(),
+  outlineColor: Color4.Black(),
+  outlineWidth: 0.08,
+  textAlign: TextAlignMode.TAM_BOTTOM_CENTER
+})
+
+Billboard.create(floatingLabel, {
+  billboardMode: BillboardMode.BM_Y
+})
+```
+
+## Advanced PBR Materials
+
+### Metallic and Roughness
+
+```typescript
+import { engine, Transform, MeshRenderer, Material, MaterialTransparencyMode } from '@dcl/sdk/ecs'
+import { Color4, Color3 } from '@dcl/sdk/math'
+
+// Shiny metal
+Material.setPbrMaterial(entity, {
+  albedoColor: Color4.create(0.8, 0.8, 0.9, 1),
+  metallic: 1.0,
+  roughness: 0.1
+})
+
+// Rough stone
+Material.setPbrMaterial(entity, {
+  albedoColor: Color4.create(0.5, 0.5, 0.5, 1),
+  metallic: 0.0,
+  roughness: 0.9
+})
+```
+
+### Transparency
+
+```typescript
+// Alpha blend — smooth transparency
+Material.setPbrMaterial(entity, {
+  albedoColor: Color4.create(1, 0, 0, 0.5), // 50% transparent red
+  transparencyMode: MaterialTransparencyMode.MTM_ALPHA_BLEND
+})
+
+// Alpha test — cutout (binary visible/invisible based on threshold)
+Material.setPbrMaterial(entity, {
+  texture: Material.Texture.Common({ src: 'assets/cutout.png' }),
+  transparencyMode: MaterialTransparencyMode.MTM_ALPHA_TEST,
+  alphaTest: 0.5
+})
+```
+
+### Emissive (Glow Effects)
+
+```typescript
+// Glowing material
+Material.setPbrMaterial(entity, {
+  albedoColor: Color4.create(0, 0, 0, 1),
+  emissiveColor: Color4.create(0, 1, 0, 1),  // Green glow
+  emissiveIntensity: 2.0
+})
+
+// Emissive with texture
+Material.setPbrMaterial(entity, {
+  texture: Material.Texture.Common({ src: 'assets/diffuse.png' }),
+  emissiveTexture: Material.Texture.Common({ src: 'assets/emissive.png' }),
+  emissiveIntensity: 1.0,
+  emissiveColor: Color3.White()
+})
+```
+
+### Texture Maps
+
+```typescript
+Material.setPbrMaterial(entity, {
+  texture: Material.Texture.Common({ src: 'assets/diffuse.png' }),
+  bumpTexture: Material.Texture.Common({ src: 'assets/normal.png' }),
+  emissiveTexture: Material.Texture.Common({ src: 'assets/emissive.png' })
+})
+```
+
+## GltfNodeModifiers
+
+Override visibility or materials on specific nodes within a GLTF model:
+
+```typescript
+import { engine, Transform, GltfContainer, GltfNodeModifiers, Material } from '@dcl/sdk/ecs'
+import { Vector3, Color4 } from '@dcl/sdk/math'
+
+const model = engine.addEntity()
+GltfContainer.create(model, { src: 'models/myModel.glb' })
+Transform.create(model, { position: Vector3.create(4, 0, 4) })
+
+// Override material of the entire model (empty path = whole model)
+GltfNodeModifiers.create(model, {
+  modifiers: [
+    {
+      path: '',  // empty string = all nodes
+      materialOverride: Material.setPbrMaterial(model, {
+        albedoColor: Color4.Red()
+      })
+    }
+  ]
+})
+```
+
+Use node paths to target specific parts of a model for visibility or material changes.
+
+## VisibilityComponent
+
+Show or hide entities without removing them:
+
+```typescript
+import { engine, VisibilityComponent } from '@dcl/sdk/ecs'
+
+// Hide an entity
+VisibilityComponent.create(entity, { visible: false })
+
+// Toggle visibility
+const visibility = VisibilityComponent.getMutable(entity)
+visibility.visible = !visibility.visible
+
+// Useful for LOD (Level of Detail)
+function lodSystem() {
+  const playerPos = Transform.get(engine.PlayerEntity).position
+
+  for (const [entity, transform] of engine.getEntitiesWith(Transform, MeshRenderer)) {
+    const distance = Vector3.distance(playerPos, transform.position)
+
+    if (distance > 30) {
+      VisibilityComponent.createOrReplace(entity, { visible: false })
+    } else {
+      VisibilityComponent.createOrReplace(entity, { visible: true })
+    }
+  }
+}
+
+engine.addSystem(lodSystem)
+```
+
+## Best Practices
+
+- Use `BillboardMode.BM_Y` instead of `BM_ALL` — looks more natural and renders faster
+- Keep `fontSize` readable (16-32 for in-world text)
+- Add `outlineColor` and `outlineWidth` to TextShape for legibility against any background
+- Use `emissiveColor` with a dark `albedoColor` for maximum glow visibility
+- `MTM_ALPHA_TEST` is cheaper than `MTM_ALPHA_BLEND` — use cutout when smooth transparency isn't needed
+- Combine Billboard + TextShape for floating name labels above NPCs or objects
+- Use VisibilityComponent for LOD systems instead of removing/re-adding entities
+
+For more component details, see `context/components-reference.md`.

package/skills/animations-tweens/SKILL.md

@@ -0,0 +1,173 @@
+---
+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.
+---
+
+# Animations and Tweens in Decentraland
+
+## GLTF Animations (Animator)
+
+Play animations embedded in .glb models:
+
+```typescript
+import { engine, Transform, GltfContainer, Animator } from '@dcl/sdk/ecs'
+import { Vector3 } from '@dcl/sdk/math'
+
+const character = engine.addEntity()
+Transform.create(character, { position: Vector3.create(8, 0, 8) })
+GltfContainer.create(character, { src: 'models/character.glb' })
+
+// Set up animation states
+Animator.create(character, {
+  states: [
+    { clip: 'idle', playing: true, loop: true, speed: 1 },
+    { clip: 'walk', playing: false, loop: true, speed: 1 },
+    { clip: 'attack', playing: false, loop: false, speed: 1.5 }
+  ]
+})
+
+// Play a specific animation
+Animator.playSingleAnimation(character, 'walk')
+
+// Stop all animations
+Animator.stopAllAnimations(character)
+```
+
+### Switching Animations
+```typescript
+function playAnimation(entity: Entity, clipName: string) {
+  const animator = Animator.getMutable(entity)
+  // Stop all
+  for (const state of animator.states) {
+    state.playing = false
+  }
+  // Play the desired one
+  const state = animator.states.find(s => s.clip === clipName)
+  if (state) {
+    state.playing = true
+  }
+}
+```
+
+## Tweens (Code-Based Animation)
+
+Animate entity properties smoothly over time:
+
+### Move
+```typescript
+import { engine, Transform, Tween, EasingFunction } from '@dcl/sdk/ecs'
+import { Vector3 } from '@dcl/sdk/math'
+
+const box = engine.addEntity()
+Transform.create(box, { position: Vector3.create(2, 1, 8) })
+
+Tween.create(box, {
+  mode: Tween.Mode.Move({
+    start: Vector3.create(2, 1, 8),
+    end: Vector3.create(14, 1, 8)
+  }),
+  duration: 2000,  // milliseconds
+  easingFunction: EasingFunction.EF_EASEINOUTSINE
+})
+```
+
+### Rotate
+```typescript
+Tween.create(box, {
+  mode: Tween.Mode.Rotate({
+    start: Quaternion.fromEulerDegrees(0, 0, 0),
+    end: Quaternion.fromEulerDegrees(0, 360, 0)
+  }),
+  duration: 3000,
+  easingFunction: EasingFunction.EF_LINEAR
+})
+```
+
+### Scale
+```typescript
+Tween.create(box, {
+  mode: Tween.Mode.Scale({
+    start: Vector3.create(1, 1, 1),
+    end: Vector3.create(2, 2, 2)
+  }),
+  duration: 1000,
+  easingFunction: EasingFunction.EF_EASEOUTBOUNCE
+})
+```
+
+## Tween Sequences (Chained Animations)
+
+Chain multiple tweens to play one after another:
+
+```typescript
+import { TweenSequence } from '@dcl/sdk/ecs'
+
+// First tween
+Tween.create(box, {
+  mode: Tween.Mode.Move({
+    start: Vector3.create(2, 1, 8),
+    end: Vector3.create(14, 1, 8)
+  }),
+  duration: 2000,
+  easingFunction: EasingFunction.EF_EASEINOUTSINE
+})
+
+// Chain sequence
+TweenSequence.create(box, {
+  sequence: [
+    // Second: move back
+    {
+      mode: Tween.Mode.Move({
+        start: Vector3.create(14, 1, 8),
+        end: Vector3.create(2, 1, 8)
+      }),
+      duration: 2000,
+      easingFunction: EasingFunction.EF_EASEINOUTSINE
+    }
+  ],
+  loop: TweenLoop.TL_RESTART // Loop the entire sequence
+})
+```
+
+## Easing Functions
+
+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
+
+## Custom Animation Systems
+
+For complex animations, create a system:
+
+```typescript
+// Continuous rotation system
+function spinSystem(dt: number) {
+  for (const [entity] of engine.getEntitiesWith(Transform, Spinner)) {
+    const transform = Transform.getMutable(entity)
+    const spinner = Spinner.get(entity)
+    // Rotate around Y axis
+    const currentRotation = Quaternion.toEulerAngles(transform.rotation)
+    transform.rotation = Quaternion.fromEulerDegrees(
+      currentRotation.x,
+      currentRotation.y + spinner.speed * dt,
+      currentRotation.z
+    )
+  }
+}
+
+engine.addSystem(spinSystem)
+```
+
+## Best Practices
+
+- Use Tweens for simple A-to-B animations (doors, platforms, UI elements)
+- Use Animator for character/model animations baked into GLTF files
+- Use Systems for continuous or physics-based animations
+- Tween durations are in **milliseconds** (1000 = 1 second)
+- Combine move + rotate tweens by applying them to parent/child entities
+- For looping: use `TweenSequence` with `loop: TweenLoop.TL_RESTART`

package/skills/audio-video/SKILL.md

@@ -0,0 +1,167 @@
+---
+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.
+---
+
+# Audio and Video in Decentraland
+
+## Audio Source (Sound Effects & Music)
+
+Play audio clips from files:
+
+```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)
+})
+```
+
+### Supported Formats
+- `.mp3` (recommended)
+- `.ogg`
+- `.wav`
+
+### File Organization
+```
+project/
+├── sounds/
+│   ├── click.mp3
+│   ├── background-music.mp3
+│   └── explosion.ogg
+├── src/
+│   └── index.ts
+└── scene.json
+```
+
+### Play/Stop/Toggle
+```typescript
+// Play
+AudioSource.getMutable(speaker).playing = true
+
+// Stop
+AudioSource.getMutable(speaker).playing = false
+
+// 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
+  }
+)
+```
+
+## Audio Streaming
+
+Stream audio from a URL (radio, live streams):
+
+```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
+})
+```
+
+## Video Player
+
+Play video on a surface:
+
+```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
+})
+
+// Set material to show the video texture
+Material.setPbrMaterial(screen, {
+  texture: Material.Texture.Video({ videoPlayerEntity: screen }),
+  roughness: 1,
+  emissiveColor: { r: 1, g: 1, b: 1 },
+  emissiveIntensity: 1,
+  emissiveTexture: Material.Texture.Video({ videoPlayerEntity: screen })
+})
+```
+
+### Video Controls
+```typescript
+// Play
+VideoPlayer.getMutable(screen).playing = true
+
+// Pause
+VideoPlayer.getMutable(screen).playing = false
+
+// Change volume
+VideoPlayer.getMutable(screen).volume = 0.8
+
+// Change source
+VideoPlayer.getMutable(screen).src = 'https://example.com/other.mp4'
+```
+
+## Spatial Audio
+
+Audio in Decentraland is **spatial by default** — it gets louder as the player approaches the audio source entity and quieter as they move away. The position is determined by the entity's `Transform`.
+
+To make audio non-spatial (same volume everywhere), there's no built-in flag — keep the volume low and place the audio at the scene center.
+
+## Important Notes
+
+- Audio files must be in the project's directory (relative paths from project root)
+- Video requires HTTPS URLs — HTTP won't work
+- Players must interact with the scene (click) before audio can play (browser autoplay policy)
+- Keep audio files small — large files increase scene load time
+- Use `.mp3` for music and `.ogg` for sound effects (smaller file sizes)
+- Video playback requires the `ALLOW_MEDIA_HOSTNAMES` permission in scene.json for external URLs
+- For live video streaming, use HLS (.m3u8) URLs when possible