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

package/skills/particle-system/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: particle-system
+description: Emit particles (fire, smoke, sparks, snow, magic, fireworks) from an entity in a Decentraland SDK7 scene with the ParticleSystem component. Covers emitter shapes (Point, Sphere, Cone, Box), continuous rate vs Burst emission, lifetime/size/color/velocity ranges, gravity and additionalForce, blend modes (ALPHA/ADD/MULTIPLY), billboard and faceTravelDirection, sprite-sheet texture animation, simulation space (local vs world), playback state, and per-scene particle budget. Use when the user asks for particles, sparks, fire, smoke, dust, fog, fireworks, magic effects, snowfall, rain, embers, trails, or atmospheric effects. Do NOT use for procedural entity motion (see animations-tweens), GLTF model effects (see add-3d-models), or 2D UI effects (see build-ui).
+---
+
+# ParticleSystem (SDK7)
+
+Emit particles from an entity. One `ParticleSystem` component per entity, attached alongside a `Transform`. No mesh required — particles render from the component itself.
+
+## Authoring split
+
+The emitter **position** (entity Transform + optional GltfContainer of a torch/fire pit/fog vent) is static and belongs in `main-entities.ts`. `ParticleSystem` itself is **not** in the supported declarative list — attach it at runtime in `src/index.ts` via `getEntityOrNullByName`.
+
+```typescript
+// main-entities.ts — emitter placement
+campfire: {
+  components: {
+    Transform: { position: { x: 8, y: 0, z: 8 } },
+    GltfContainer: { src: 'models/campfire.glb' }
+  }
+}
+```
+
+```typescript
+// src/index.ts — attach ParticleSystem
+import { engine, ParticleSystem, PBParticleSystem_BlendMode } from '@dcl/sdk/ecs'
+import { Color4 } from '@dcl/sdk/math'
+
+export function main() {
+  const fire = engine.getEntityOrNullByName('campfire')
+  if (!fire) return
+  ParticleSystem.create(fire, { /* ... config ... */ })
+}
+```
+
+## RULE: Transform.scale does NOT scale particles
+
+Particle size is controlled exclusively by `initialSize` and `sizeOverTime` (`FloatRange`). The `ParticleSystem` also sets the emitter shape's spatial dimensions when the shape has size fields (Sphere radius, Box size, Cone radius). These are not affected by the entity's `Transform.scale`.
+
+## RULE: Particles only render to players inside scene parcels
+
+Players viewing the scene from outside its parcels see nothing. Particles are not part of the scene LOD silhouette. Position emitters within parcel bounds.
+
+## RULE: Particles only work in the Unity explorer
+
+The mobile Godot explorer and the Bevy explorer don't have this feature implemented. The renderer ignores the component. Design fallbacks (a glowing emissive sphere, a baked-in GLTF animation) for scenes that should look reasonable everywhere.
+
+## RULE: Engine caps total particles at ~1000
+
+The engine enforces a per-scene particle budget and will scale down emission rates across all active systems if total live particles would exceed the limit. Cap each system with `maxParticles` and prefer fewer impactful systems over many small ones.
+
+## RULE: prewarm requires loop = true
+
+`prewarm: true` only takes effect when `loop: true`. On a one-shot system (`loop: false`) prewarm is silently ignored.
+
+## RULE: faceTravelDirection overrides billboard
+
+When `faceTravelDirection: true`, particles orient along their velocity vector and `billboard` is ignored. Use this for trails/streaks (asteroids, bullets, sparks). Set `billboard: false` explicitly to avoid confusion.
+
+## Import
+
+```typescript
+import { engine, ParticleSystem } from '@dcl/sdk/ecs'
+import {
+  PBParticleSystem_BlendMode,
+  PBParticleSystem_PlaybackState,
+  PBParticleSystem_SimulationSpace
+} from '@dcl/sdk/ecs'
+import { Color4, Vector3, Quaternion } from '@dcl/sdk/math'
+```
+
+Aliases `ParticleSystemBlendMode` and `ParticleSystemPlaybackState` are also exported from `@dcl/sdk/ecs` and are interchangeable with the `PB`-prefixed names. There is no `ParticleSystemSimulationSpace` alias — only `PBParticleSystem_SimulationSpace`. Prefer the `PB`-prefixed names everywhere for consistency.
+
+## Field reference
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `active` | `boolean` | `true` | Master on/off for new emission. |
+| `rate` | `number` | `10` | Particles emitted per second (continuous). Set to `0` when using `bursts`. |
+| `maxParticles` | `number` | `1000` | Hard cap on simultaneous live particles for this system. |
+| `lifetime` | `number` | `5` | Particle lifespan in seconds. |
+| `gravity` | `number` | `0` | Multiplier on scene gravity (~ -9.81 m/s²). Negative = particles rise. |
+| `additionalForce` | `Vector3` | — | Constant force vector applied each frame (world space). |
+| `initialSize` | `FloatRange` | `{start:1, end:1}` | Random size at spawn. |
+| `sizeOverTime` | `FloatRange` | `{start:1, end:1}` | Size lerped start→end over particle lifetime. |
+| `initialRotation` | `Quaternion` | identity | Spawn orientation. |
+| `rotationOverTime` | `Quaternion` | identity | Per-axis angular velocity. |
+| `faceTravelDirection` | `boolean` | `false` | Orient along velocity. Overrides `billboard`. |
+| `initialColor` | `ColorRange` | `{white,white}` | Random color at spawn. |
+| `colorOverTime` | `ColorRange` | `{white,white}` | Color lerped start→end. Use alpha=0 at end to fade out. |
+| `initialVelocitySpeed` | `FloatRange` | `{start:1, end:1}` | Initial speed in m/s, randomized per particle. |
+| `texture` | `Texture` | white quad | Particle sprite. Same `Texture` shape as Material textures. |
+| `blendMode` | `PBParticleSystem_BlendMode` | `PSB_ALPHA` | `PSB_ALPHA` / `PSB_ADD` / `PSB_MULTIPLY`. |
+| `billboard` | `boolean` | `true` | Particles always face camera. |
+| `spriteSheet` | `{tilesX, tilesY, framesPerSecond?}` | — | Texture-atlas frame animation. |
+| `shape` | oneof Point/Sphere/Cone/Box | Point | Emitter geometry. |
+| `loop` | `boolean` | `true` | Loop emission cycle. `false` = one-shot. |
+| `prewarm` | `boolean` | `false` | Start as if one full loop already simulated. Requires `loop: true`. |
+| `simulationSpace` | `PBParticleSystem_SimulationSpace` | `PSS_LOCAL` | `PSS_LOCAL` (move with entity) / `PSS_WORLD` (stay put after spawn). |
+| `limitVelocity` | `{speed, dampen?}` | — | Clamp top speed. `dampen` 0–1, default `1` = hard clamp. |
+| `playbackState` | `PBParticleSystem_PlaybackState` | `PS_PLAYING` | `PS_PLAYING` / `PS_PAUSED` / `PS_STOPPED`. |
+| `bursts` | `{values: Burst[]}` | — | Discrete emission events. |
+
+`FloatRange = { start: number, end: number }`. `ColorRange = { start: Color4, end: Color4 }`.
+
+## Emitter shapes
+
+Use `ParticleSystem.Shape.*` helpers — never assemble the `oneof` manually:
+
+```typescript
+shape: ParticleSystem.Shape.Point()
+shape: ParticleSystem.Shape.Sphere({ radius: 1 })
+shape: ParticleSystem.Shape.Cone({ angle: 25, radius: 1 })  // angle = half-angle in degrees
+shape: ParticleSystem.Shape.Box({ size: Vector3.create(1, 1, 1) })
+```
+
+- **Point** — emits from entity origin.
+- **Sphere** — random points inside a sphere of `radius`.
+- **Cone** — base disk projecting outward within `angle` half-angle. Cone direction is the entity's local forward; rotate the parent Transform to aim it.
+- **Box** — random points inside an axis-aligned box of `size`.
+
+To rotate the emission direction (snow falling, rain), rotate the parent entity's `Transform.rotation` (in `main-entities.ts`).
+
+## Bursts
+
+Discrete emission events at specific times. Set `rate: 0` to use bursts only, or combine with `rate > 0` for continuous + bursty.
+
+```typescript
+bursts: {
+  values: [{ time: 0, count: 100, cycles: 1, interval: 0.01, probability: 1.0 }]
+}
+```
+
+Burst fields: `time` (s from cycle start), `count` (particles per burst), `cycles` (default `1`, `0` = infinite), `interval` (s between cycles, default `0.01`), `probability` (0–1 chance per cycle, default `1`). Multiple bursts in one cycle = staggered ignition pattern (fireworks).
+
+## Common patterns
+
+```typescript
+// 1. Fire ember — Point + ADD blend, slight upward drift
+const fire = engine.getEntityOrNullByName('campfire')
+if (fire) ParticleSystem.create(fire, {
+  rate: 40,
+  lifetime: 2,
+  maxParticles: 200,
+  initialSize: { start: 0.1, end: 0.3 },
+  sizeOverTime: { start: 1.0, end: 0.0 },
+  initialColor: { start: Color4.create(1, 0.6, 0.1, 1), end: Color4.create(1, 0.2, 0, 1) },
+  colorOverTime: { start: Color4.create(1, 0.5, 0.1, 1), end: Color4.create(0.2, 0, 0, 0) },
+  initialVelocitySpeed: { start: 1.5, end: 2.5 },
+  gravity: -0.3,
+  blendMode: PBParticleSystem_BlendMode.PSB_ADD,
+  shape: ParticleSystem.Shape.Point()
+})
+
+// 2. One-shot burst — explosion/pickup VFX
+ParticleSystem.create(entity, {
+  loop: false,
+  rate: 0,
+  lifetime: 3,
+  maxParticles: 150,
+  initialSize: { start: 0.1, end: 0.25 },
+  sizeOverTime: { start: 1.0, end: 0.0 },
+  initialVelocitySpeed: { start: 2, end: 4 },
+  shape: ParticleSystem.Shape.Sphere({ radius: 0.5 }),
+  bursts: {
+    values: [{ time: 0, count: 100, cycles: 1, interval: 0.01, probability: 1.0 }]
+  }
+})
+```
+
+## Playback control
+
+```typescript
+const ps = ParticleSystem.getMutable(entity)
+ps.playbackState = PBParticleSystem_PlaybackState.PS_PAUSED   // pause + freeze particles
+ps.playbackState = PBParticleSystem_PlaybackState.PS_PLAYING  // resume
+ps.playbackState = PBParticleSystem_PlaybackState.PS_STOPPED  // hard cut, clear live particles
+ps.active = false                                              // graceful trail-off
+```
+
+## Sprite-sheet animation
+
+Texture atlas with frames laid out in a grid (left-to-right, top-to-bottom). Total frames = `tilesX * tilesY`.
+
+```typescript
+texture: { src: 'images/flame-sheet.png' },
+spriteSheet: { tilesX: 4, tilesY: 3, framesPerSecond: 12 }
+```
+
+## Simulation space (local vs world)
+
+- `PSS_LOCAL` (default) — particles move with the emitter. A moving emitter drags its particle cloud. Good for auras / halos on moving entities.
+- `PSS_WORLD` — particles stay at their spawn position in world space. A moving emitter leaves a trail. Required for proper trails combined with `Tween` movement on the emitter.
+
+## Texture field
+
+```typescript
+texture: { src: 'images/spark.png' }
+```
+
+The full `Texture` form supports filterMode/wrapMode but particle systems generally only need `src`. Avatar/Video textures on particles are unverified — stick with file textures.
+
+## Gotchas
+
+- **`rotationOverTime`** is interpreted as per-axis angular velocity. `Quaternion.fromEulerDegrees(0, 90, 0)` = spin 90°/s on Y. Identity = no spin.
+- **`additionalForce` is world-space** even when `simulationSpace = PSS_LOCAL`. Wind/drift directions stay constant regardless of emitter rotation.
+- **`limitVelocity.dampen = 1`** = hard clamp. Lower values let velocity exceed cap briefly then decay.
+- **Color alpha = 0 at end of `colorOverTime`** is the standard way to fade particles out.
+- **No mesh attached to the emitter entity** — adding `MeshRenderer` is unrelated; particles render from the ParticleSystem component itself.
+
+## Performance
+
+- Cap each system with `maxParticles`. Total scene budget across all systems is ~1000.
+- Keep `lifetime * rate` low; that product is the steady-state live count.
+- Disable systems out of view via `playbackState = PS_STOPPED` or `active = false`.
+- Prefer `PSB_ALPHA` for opaque/translucent effects. `PSB_ADD` is best for glow/fire (it stacks visually) but multi-layer additive overdraw is the most expensive case.
+- One texture per system.
+
+## Resources
+
+- Test scene: https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/0%2C7-particle-system
+- Live tuner: `ParticleLab.dcl.eth` (open with Decentraland client).

package/skills/player-avatar/SKILL.md

@@ -5,6 +5,30 @@ description: Player and avatar system in Decentraland. Read player position/prof
 
 # Player and Avatar System in Decentraland
 
+## Authoring split
+
+`AvatarShape` (the component used for NPCs and pre-placed avatars) is supported in `main-entities.ts` — declare the NPC fully there with id, name, wearables, etc.:
+
+```typescript
+// main-entities.ts
+shopkeeper: {
+  components: {
+    Transform: { position: { x: 8, y: 0, z: 8 } },
+    AvatarShape: {
+      id: 'shopkeeper-1',
+      name: 'Shopkeeper',
+      bodyShape: 'urn:decentraland:off-chain:base-avatars:BaseMale',
+      wearables: [],
+      emotes: []
+    }
+  }
+}
+```
+
+`AvatarAttach`, `AvatarModifierArea`, `AvatarBase`, `AvatarEquippedData` are **not** in the supported list — they're runtime by design (they bind to the live player, or apply to entities you create on-the-fly). Add them in `src/index.ts` and attach to entities looked up via `getEntityOrNullByName` (for static placement) or runtime-created entities (for player-bound effects).
+
+The reserved `engine.PlayerEntity` is engine-managed and has no representation in `main-entities.ts`.
+
 ## Player Position and Movement
 
 Access the player's position via the reserved `engine.PlayerEntity`:
@@ -61,6 +85,36 @@ function main() {
 - `userId` — the player's Ethereum wallet address (or guest ID)
 - `isGuest` — `true` if the player hasn't connected a wallet
 
+### Fetch Full Avatar Profile from the Catalyst
+
+`getPlayer()` returns the local view of the player. For full avatar data (wearables list, body shape, skin/hair/eye colors), fetch from the Catalyst:
+
+```typescript
+import { executeTask, signedFetch } from '@dcl/sdk/network'
+import { getPlayer } from '@dcl/sdk/players'
+
+executeTask(async () => {
+  const player = getPlayer()
+  if (!player || player.isGuest) return
+
+  const res = await fetch(`https://peer.decentraland.org/lambdas/profiles/${player.userId}`)
+  const body = await res.json()
+
+  // Response is an array of profiles; the first entry holds the active avatar.
+  const profile = body?.avatars?.[0]
+  if (!profile) return
+
+  console.log('name:', profile.name)
+  console.log('wearables:', profile.avatar.wearables)
+  console.log('skin color:', profile.avatar.skin.color)  // { r, g, b } — already unwrapped, NOT { color: { r,g,b } }
+})
+```
+
+**Gotchas:**
+- The response is `{ avatars: [...] }`, not a flat profile object. Always read `body.avatars[0]`.
+- Color fields (`skin.color`, `hair.color`, `eyes.color`) are already `{ r, g, b }` objects — don't unwrap one more level.
+- The fetch is unauthenticated; for endpoints that need the player's signed identity, use `signedFetch` from `@dcl/sdk/network` instead of plain `fetch`.
+
 ## Avatar Attachments
 
 Attach 3D objects to a player's avatar:
@@ -79,12 +133,36 @@ AvatarAttach.create(hat, {
 
 ### Anchor Points
 
-```typescript
-AvatarAnchorPointType.AAPT_NAME_TAG      // Above the head
-AvatarAnchorPointType.AAPT_RIGHT_HAND    // Right hand
-AvatarAnchorPointType.AAPT_LEFT_HAND     // Left hand
-AvatarAnchorPointType.AAPT_POSITION      // Avatar root position
-```
+Full enum of bones / positions an attachment can track. Inside `main-entities.ts` use the integer value (left). In `src/index.ts` use `AvatarAnchorPointType.<NAME>`.
+
+| value | enum | location |
+|---|---|---|
+| 0  | AAPT_POSITION       | avatar feet (deprecated — prefer `parent: engine.PlayerEntity`) |
+| 1  | AAPT_NAME_TAG       | above the name tag |
+| 2  | AAPT_LEFT_HAND      | left hand |
+| 3  | AAPT_RIGHT_HAND     | right hand |
+| 4  | AAPT_HEAD           | head bone |
+| 5  | AAPT_NECK           | neck |
+| 6  | AAPT_SPINE          | spine root |
+| 7  | AAPT_SPINE1         | spine mid |
+| 8  | AAPT_SPINE2         | spine top |
+| 9  | AAPT_HIP            | hip |
+| 10 | AAPT_LEFT_SHOULDER  | left shoulder |
+| 11 | AAPT_LEFT_ARM       | left upper arm |
+| 12 | AAPT_LEFT_FOREARM   | left forearm |
+| 13 | AAPT_LEFT_HAND_INDEX | left index finger |
+| 14 | AAPT_RIGHT_SHOULDER | right shoulder |
+| 15 | AAPT_RIGHT_ARM      | right upper arm |
+| 16 | AAPT_RIGHT_FOREARM  | right forearm |
+| 17 | AAPT_RIGHT_HAND_INDEX | right index finger |
+| 18 | AAPT_LEFT_UP_LEG    | left thigh |
+| 19 | AAPT_LEFT_LEG       | left calf |
+| 20 | AAPT_LEFT_FOOT      | left foot |
+| 21 | AAPT_LEFT_TOE_BASE  | left toes |
+| 22 | AAPT_RIGHT_UP_LEG   | right thigh |
+| 23 | AAPT_RIGHT_LEG      | right calf |
+| 24 | AAPT_RIGHT_FOOT     | right foot |
+| 25 | AAPT_RIGHT_TOE_BASE | right toes |
 
 ### Attach to a Specific Player
 
@@ -230,9 +308,46 @@ AvatarLocomotionSettings.createOrReplace(engine.PlayerEntity, {
 })
 ```
 
+## InputModifier — Restrict Player Movement
+
+Disable specific movement modes for the local player. Useful for cutscenes, dialogue freezes, traversal puzzles. Applies to `engine.PlayerEntity`.
+
+```typescript
+import { engine, InputModifier } from '@dcl/sdk/ecs'
+
+InputModifier.createOrReplace(engine.PlayerEntity, {
+  mode: InputModifier.Mode.Standard({
+    disableWalk: false,
+    disableJog: false,
+    disableRun: false,
+    disableJump: false,
+    disableDoubleJump: false,
+    disableGliding: false
+  })
+})
+```
+
+Set any field to `true` to disable that mode. While disabled:
+- Gravity still applies (the player still falls).
+- The camera can still rotate freely.
+- The player can still trigger pointer / proximity events.
+- All restrictions are auto-lifted when the player leaves the scene.
+
+### Freeze All Movement
+
+```typescript
+InputModifier.createOrReplace(engine.PlayerEntity, {
+  mode: InputModifier.Mode.Standard({ disableAll: true })
+})
+```
+
+To release: `InputModifier.deleteFrom(engine.PlayerEntity)` — or `createOrReplace` with all flags `false`.
+
 ## Teleporting the Player
 
-**You MUST use `movePlayerTo` from `~system/RestrictedActions` to move or teleport the player.** Setting `Transform.getMutable(engine.PlayerEntity).position` does NOT work — the runtime ignores direct writes to the player transform.
+**You MUST use `movePlayerTo` from `~system/RestrictedActions` to move or teleport the player.** Setting `Transform.getMutable(engine.PlayerEntity).position` does NOT work — the runtime ignores direct writes to the player transform. `Transform` on `engine.PlayerEntity` is **read-only**; the same applies to `engine.CameraEntity`.
+
+`movePlayerTo` only teleports the player **within the same scene**. Cross-scene teleports require explicit player consent and a different API.
 
 ```typescript
 import { movePlayerTo } from '~system/RestrictedActions'
@@ -249,6 +364,17 @@ void movePlayerTo({
 })
 ```
 
+`movePlayerTo` returns a Promise — `await` it if you need to chain actions:
+
+```typescript
+import { executeTask } from '@dcl/sdk/ecs'
+
+executeTask(async () => {
+  await movePlayerTo({ newRelativePosition: Vector3.create(8, 0, 8) })
+  console.log('teleported, continuing flow')
+})
+```
+
 ### Avatar Change Listeners
 
 React to avatar changes in real-time:

package/skills/player-physics/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: player-physics
+description: Apply physics forces to the player in Decentraland scenes. Impulses (one-shot pushes), knockback (push away from a point with falloff), continuous forces (wind tunnels, anti-gravity, lift, levitation, hover), timed forces, and repulsion fields. Use when the user wants launch pads, knockback on hit, wind zones, gravity fields, jumps, lifting/floating the player, pushing the player up/sideways/back, hover effects, or any scene-applied force on the player. THIS is also the right skill when an agent's first instinct is to mutate `Transform` on `engine.PlayerEntity` to move/lift/push the player — that does NOT work (the player Transform is engine-controlled and read-only); use the Physics API instead. Do NOT use for player movement speed (see player-avatar AvatarLocomotionSettings) or platform movement (see animations-tweens).
+---
+
+# Player Physics in Decentraland
+
+Apply forces to the player's avatar using the `Physics` API from `@dcl/sdk/ecs`. All physics operations affect the **local player** only.
+
+## Authoring split
+
+Force calls are runtime — they live in `src/index.ts`. The **trigger entities** that cause forces (the launch pad, the wind tunnel volume, the repulsion field marker) are static placements and belong in `main-entities.ts` with a Transform (and optional `MeshRenderer` / `GltfContainer`). Wire pointer/proximity events or trigger systems in `src/index.ts` to call the `Physics.*` methods.
+
+## Why this skill exists — the Transform mistake
+
+The player's `Transform` (on `engine.PlayerEntity`) is **engine-controlled and read-only from scene code**. Writing to it via `Transform.getMutable`, `Transform.createOrReplace`, or direct `.position` / `.rotation` mutation **silently does nothing** — the code compiles, the system ticks, no error is thrown, and the avatar never moves.
+
+**If your goal is to lift, float, push, knock back, or apply any sustained force to the player, use this skill's `Physics` API.** For instant teleports / smooth slides to a specific position, use `movePlayerTo` from `~system/RestrictedActions` (skill: `player-avatar`).
+
+```typescript
+// WRONG — has no effect in-world
+const t = Transform.getMutable(engine.PlayerEntity)
+t.position.y += 0.1   // ignored every frame
+
+// CORRECT — lift the player upward
+import { Physics } from '@dcl/sdk/ecs'
+import { Vector3 } from '@dcl/sdk/math'
+Physics.applyImpulseToPlayer(Vector3.create(0, 50, 0))         // one-shot upward launch
+// or, sustained lift / hover:
+const lifter = engine.getEntityOrNullByName('hover_zone')      // named entity from main-entities.ts
+if (lifter) Physics.applyForceToPlayer(lifter, Vector3.create(0, 1, 0), 12)
+// stop with: Physics.removeForceFromPlayer(lifter)
+```
+
+## Impulse (One-Shot Push)
+
+Apply a single instantaneous force with `Physics.applyImpulseToPlayer(direction, magnitude?)`. Direction is auto-normalized when magnitude is passed separately. Multiple calls within the same frame are accumulated. Use for launch pads, jumps, and explosions.
+
+## Knockback (Push Away from a Point)
+
+Push the player away from a source position with `Physics.applyKnockbackToPlayer(sourcePos, magnitude, radius?, falloff?)`. Direction is computed automatically from source to player.
+
+### KnockbackFalloff Options
+
+| Falloff | Behavior |
+|---|---|
+| `KnockbackFalloff.CONSTANT` | Same magnitude at any distance within radius (default) |
+| `KnockbackFalloff.LINEAR` | Smooth linear decrease to 0 at the radius edge |
+| `KnockbackFalloff.INVERSE_SQUARE` | Sharp, physically-realistic drop-off |
+
+If the player is exactly at the source, they are pushed straight up. A **negative magnitude** pulls the player toward the point (gravity well). The same falloff values apply to `applyRepulsionForceToPlayer()`.
+
+## Continuous Force
+
+Apply a persistent directional force identified by an **entity** (the force "owner"). Multiple forces from different entities stack.
+
+- Apply: `Physics.applyForceToPlayer(entity, direction, magnitude?)`
+- Remove: `Physics.removeForceFromPlayer(entity)`
+
+Use with trigger zones for wind tunnels, conveyor belts, and gravity fields. The owner entity is just an ID handle for later removal — typically the named main-entities.ts entity representing the trigger zone.
+
+## Timed Force
+
+Apply a force for a fixed duration: `Physics.applyForceToPlayerForDuration(entity, seconds, direction, magnitude?)`. Expires automatically.
+
+## Repulsion Force
+
+Continuous push away from a fixed point with distance-based falloff, recalculated each frame: `Physics.applyRepulsionForceToPlayer(entity, position, magnitude, radius)`. The position must be passed explicitly — not read from the entity's Transform automatically. Remove with `Physics.removeForceFromPlayer(entity)`.
+
+## Coordinate Conversion (Local to World Direction)
+
+Convert local direction to world space with `Transform.localToWorldDirection(entity, localDir)`. Use when pushing relative to an entity's orientation (e.g. "forward from this cannon").
+
+## Quick Reference
+
+| Method | Type | Description |
+|---|---|---|
+| `Physics.applyImpulseToPlayer(dir, mag?)` | One-shot | Instant directional push |
+| `Physics.applyKnockbackToPlayer(pos, mag, radius?, falloff?)` | One-shot | Push away from point |
+| `Physics.applyForceToPlayer(entity, dir, mag?)` | Continuous | Persistent push while active |
+| `Physics.removeForceFromPlayer(entity)` | Control | Stop a continuous force |
+| `Physics.applyForceToPlayerForDuration(entity, secs, dir, mag?)` | Timed | Force that expires automatically |
+| `Physics.applyRepulsionForceToPlayer(entity, pos, mag, radius)` | Continuous | Distance-based push from point |
+| `Transform.localToWorldDirection(entity, dir)` | Utility | Convert local direction to world space |
+
+## Best Practices
+
+- Use `applyImpulseToPlayer` for one-off events (jump pads, explosions, hits).
+- Use `applyForceToPlayer` + `removeForceFromPlayer` with trigger zones for areas (wind tunnels, conveyor belts).
+- Use `KnockbackFalloff.LINEAR` for most area effects — it feels natural and predictable.
+- Always check `result.trigger?.entity !== engine.PlayerEntity` in trigger callbacks to only affect the local player.
+- A negative knockback magnitude creates a pull/gravity well effect.
+- Multiple forces from different entities stack independently.

package/skills/scene-runtime/SKILL.md

@@ -153,12 +153,16 @@ changeRealm({ realm: 'other-realm.dcl.eth', message: 'Join this realm?' })
 
 ## Timers
 
-**setTimeout / setInterval** are supported via the QuickJS runtime polyfill:
+**Use the `timers` API from `@dcl/sdk/ecs`**, not the global `setTimeout`/`setInterval`. The globals are not reliable in the QuickJS runtime.
 
 ```typescript
-setTimeout(() => console.log('delayed'), 2000)
-const id = setInterval(() => console.log('tick'), 1000)
-clearInterval(id)
+import { timers } from '@dcl/sdk/ecs'
+
+const t = timers.setTimeout(() => console.log('delayed'), 2000)
+timers.clearTimeout(t)
+
+const id = timers.setInterval(() => console.log('tick'), 1000)
+timers.clearInterval(id)
 ```
 
 **System-based timers** (recommended for game logic — synchronized with the frame loop):
@@ -251,7 +255,7 @@ npx @dcl/sdk-commands test
 
 - Always wrap async code in `executeTask()` — bare promises will be silently dropped
 - Use `signedFetch` (not plain `fetch`) when your backend needs to verify the player's identity
-- Prefer system-based timers over `setTimeout`/`setInterval` for game logic — they stay in sync with the frame loop
+- Prefer system-based timers over `timers.setTimeout`/`timers.setInterval` for game logic — they stay in sync with the frame loop. Use `timers.*` for one-shot scheduled actions (auto-close door, delayed sound, etc.).
 - Check `realm.realmInfo?.isPreview` to detect preview mode and enable debug features
 - Use `readFile()` for data files (JSON configs, level data) deployed alongside the scene
 - `removeEntityWithChildren()` is essential when cleaning up complex entity hierarchies

package/skills/visual-feedback/SKILL.md

@@ -106,6 +106,7 @@ Keep it to 1-2 screenshots per task. Each screenshot consumes significant tokens
 | Missing textures (pink/magenta) | Texture file not found or wrong path | Verify file exists in project and path matches code |
 | Objects appear wrong scale | Scale values off or model exported at wrong scale | Check Transform.scale values; 1,1,1 is original model size |
 | Lighting looks flat | No LightSource components in scene | Add point or spot lights — see **lighting-environment** skill |
+| Custom lights look too dim or invisible | Intensity value too low | Point/spot lights typically need `intensity: 8000–32000` candela. Values below ~1000 are usually invisible |
 
 ## What to Look For in Screenshots