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

package/skills/camera-control/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: camera-control
+description: Control camera behavior in Decentraland scenes. Switch between first-person and third-person with CameraMode, force camera in regions with CameraModeArea, create cinematic scripted cameras with VirtualCamera, and read camera position/rotation via MainCamera. Use when user wants camera control, cinematic views, cutscenes, or camera mode switching.
+---
+
+# Camera Control in Decentraland
+
+## Reading Camera State
+
+Access the camera's current position and rotation via the reserved `engine.CameraEntity`:
+
+```typescript
+import { engine, Transform, CameraMode, CameraType } from '@dcl/sdk/ecs'
+
+function trackCamera() {
+  if (!Transform.has(engine.CameraEntity)) return
+
+  const cameraTransform = Transform.get(engine.CameraEntity)
+  console.log('Camera position:', cameraTransform.position)
+  console.log('Camera rotation:', cameraTransform.rotation)
+}
+
+engine.addSystem(trackCamera)
+```
+
+## Camera Mode Detection
+
+Check whether the player is in first-person or third-person:
+
+```typescript
+function checkCameraMode() {
+  if (!CameraMode.has(engine.CameraEntity)) return
+
+  const cameraMode = CameraMode.get(engine.CameraEntity)
+  if (cameraMode.mode === CameraType.CT_FIRST_PERSON) {
+    console.log('First person camera')
+  } else if (cameraMode.mode === CameraType.CT_THIRD_PERSON) {
+    console.log('Third person camera')
+  }
+}
+
+engine.addSystem(checkCameraMode)
+```
+
+### Camera Mode Values
+
+```typescript
+CameraType.CT_FIRST_PERSON  // First-person view
+CameraType.CT_THIRD_PERSON  // Third-person view (default)
+```
+
+## CameraModeArea (Force Camera in a Region)
+
+Force a specific camera mode when the player enters an area:
+
+```typescript
+import { engine, Transform, CameraModeArea, CameraType } from '@dcl/sdk/ecs'
+import { Vector3 } from '@dcl/sdk/math'
+
+const fpArea = engine.addEntity()
+Transform.create(fpArea, { position: Vector3.create(8, 1.5, 8) })
+
+CameraModeArea.create(fpArea, {
+  area: Vector3.create(6, 4, 6),         // 6x4x6 meter box
+  mode: CameraType.CT_FIRST_PERSON       // Force first-person inside
+})
+```
+
+When the player leaves the area, the camera reverts to their preferred mode.
+
+## VirtualCamera (Cinematic Cameras)
+
+Create scripted camera positions for cutscenes or special views:
+
+```typescript
+import { engine, Transform, VirtualCamera, CameraTransition } from '@dcl/sdk/ecs'
+import { Vector3, Quaternion } from '@dcl/sdk/math'
+
+const cinematicCam = engine.addEntity()
+Transform.create(cinematicCam, {
+  position: Vector3.create(8, 5, 2),
+  rotation: Quaternion.fromEulerDegrees(-20, 0, 0)
+})
+
+VirtualCamera.create(cinematicCam, {
+  defaultTransition: {
+    transitionMode: CameraTransition.CT_SPEED,
+    speed: 1.0
+  }
+})
+```
+
+### Transition Modes
+
+- `CameraTransition.CT_SPEED` — smooth transition at a fixed speed
+- Higher `speed` values = faster camera movement to the virtual camera position
+
+### Look-At Target
+
+Make the virtual camera track an entity:
+
+```typescript
+const target = engine.addEntity()
+Transform.create(target, { position: Vector3.create(8, 1, 8) })
+
+VirtualCamera.create(cinematicCam, {
+  lookAtEntity: target,
+  defaultTransition: {
+    transitionMode: CameraTransition.CT_SPEED,
+    speed: 2.0
+  }
+})
+```
+
+## Tracking Camera Position
+
+Poll camera position each frame for camera-triggered events:
+
+```typescript
+import { engine, Transform, CameraMode, CameraType } from '@dcl/sdk/ecs'
+import { Vector3 } from '@dcl/sdk/math'
+
+let lastNotifiedZone = ''
+
+function cameraZoneSystem() {
+  if (!Transform.has(engine.CameraEntity)) return
+
+  const camPos = Transform.get(engine.CameraEntity).position
+  let currentZone = ''
+
+  if (camPos.y > 10) {
+    currentZone = 'sky'
+  } else if (camPos.x < 4) {
+    currentZone = 'west'
+  } else {
+    currentZone = 'center'
+  }
+
+  if (currentZone !== lastNotifiedZone) {
+    lastNotifiedZone = currentZone
+    console.log('Camera entered zone:', currentZone)
+  }
+}
+
+engine.addSystem(cameraZoneSystem)
+```
+
+## Common Patterns
+
+### Camera-Triggered Events
+
+Use the camera position to trigger actions when the player looks at a specific area:
+
+```typescript
+function cameraLookTrigger() {
+  const camTransform = Transform.get(engine.CameraEntity)
+  const targetPos = Vector3.create(8, 2, 8)
+  const distance = Vector3.distance(camTransform.position, targetPos)
+
+  if (distance < 5) {
+    // Player is close — check if camera is pointing at target
+    // Use raycasting for precise look detection (see add-interactivity skill)
+  }
+}
+
+engine.addSystem(cameraLookTrigger)
+```
+
+### Following an NPC
+
+Move camera to track an NPC by updating a VirtualCamera's Transform:
+
+```typescript
+function followNpcCamera(dt: number) {
+  const npcPos = Transform.get(npcEntity).position
+  const camTransform = Transform.getMutable(cinematicCam)
+
+  // Position camera behind and above the NPC
+  camTransform.position = Vector3.create(
+    npcPos.x - 2,
+    npcPos.y + 3,
+    npcPos.z - 2
+  )
+}
+
+engine.addSystem(followNpcCamera)
+```
+
+## 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
+
+For component field details, see `context/components-reference.md`.

package/skills/create-scene/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: create-scene
+description: Scaffold a new Decentraland SDK7 scene project from scratch. Creates scene.json, package.json, tsconfig.json, and src/index.ts with a basic scene setup. Use when user wants to start a new scene, initialize a project, or set up from an empty folder.
+---
+
+# Create a New Decentraland SDK7 Scene
+
+When the user wants to create a new scene, follow these steps:
+
+## 1. Ask What They Want to Build
+
+If the user hasn't described their scene, ask them:
+- What kind of scene? (gallery, game, social space, interactive art, etc.)
+- How many parcels? (default: 1 parcel = 16x16m)
+- Any specific features? (3D models, interactivity, UI, multiplayer)
+
+## 2. Scaffold the Project with `/init`
+
+**Always run `/init` first.** This uses the official `@dcl/sdk-commands init` to create scene.json, package.json, tsconfig.json, and src/index.ts with the correct, up-to-date configuration.
+
+Never manually create scene.json, package.json, or tsconfig.json — the SDK templates may change between versions and hand-written copies will diverge.
+
+## 3. Customize the Generated Files
+
+After `/init` completes, customize the generated files based on what the user wants:
+
+### scene.json
+Update the `display` fields and parcels:
+- `display.title` — set to the scene name
+- `display.description` — set to a short description
+- `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:
+
+```typescript
+import { engine, Transform, MeshRenderer, Material } from '@dcl/sdk/ecs'
+import { Vector3, Color4 } from '@dcl/sdk/math'
+
+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)
+  })
+}
+```
+
+## 4. Post-Creation Steps
+
+After creating the files, tell the user:
+1. Run `npm install` to install dependencies
+2. Use the `preview` tool to start the preview server (or run `npx @dcl/sdk-commands start --bevy-web` manually)
+3. The scene will open in a browser at http://localhost:8000
+
+## Important Notes
+
+- Always place objects within the scene boundaries (0 to 16*parcelsX for X, 0 to 16*parcelsZ for Z)
+- Center of a single-parcel scene is (8, 0, 8) at ground level
+- 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` in tsconfig are required for React-ECS UI support

package/skills/deploy-scene/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: deploy-scene
+description: Deploy and publish a Decentraland scene to Genesis City (LAND-based). Use when user wants to deploy, publish, upload, go live, or make their scene accessible on parcels they own.
+---
+
+# Deploying to Genesis City
+
+Deploy to specific parcels you own or have permission to deploy to.
+
+**Use the `/deploy` command** to deploy. It runs `npx @dcl/sdk-commands deploy` and handles the full process:
+1. Build the scene
+2. Upload assets to IPFS
+3. Deploy to the specified parcels
+4. Requires a wallet with LAND or deployment permissions
+
+> **Deploying to a World instead?** See the `deploy-worlds` skill for Worlds deployment (personal spaces using DCL NAMEs or ENS domains).
+
+## Pre-Deployment Checklist
+
+Before deploying, verify:
+
+1. **scene.json is valid**:
+   - `ecs7: true` and `runtimeVersion: "7"`
+   - Correct `parcels` matching your LAND (for Genesis City)
+   - Valid `base` parcel
+   - `main: "bin/index.js"`
+
+2. **Code compiles**:
+   ```bash
+   npx tsc --noEmit
+   ```
+
+3. **Scene previews correctly**:
+   Use the `preview` tool to verify the scene works (or `npx @dcl/sdk-commands start --bevy-web` manually)
+
+4. **Dependencies installed**:
+   ```bash
+   npm install
+   ```
+
+5. **Assets are within limits** (check parcel count):
+   | Parcels | Entities | Triangles | Textures |
+   |---------|----------|-----------|----------|
+   | 1 | 512 | 10,000 | 10 MB |
+   | 2 | 1,024 | 20,000 | 20 MB |
+   | 4 | 2,048 | 40,000 | 40 MB |
+   | 8+ | Scales linearly | | |
+
+## Deployment Process
+
+### Using CLI
+```bash
+# Build first
+npx @dcl/sdk-commands build
+
+# Deploy (will open browser for wallet connection)
+npx @dcl/sdk-commands deploy
+```
+
+### Using Creator Hub
+1. Open Creator Hub
+2. Select your scene
+3. Click "Publish"
+4. Connect wallet
+5. Confirm transaction
+
+## scene.json for Deployment
+
+```json
+{
+  "ecs7": true,
+  "runtimeVersion": "7",
+  "display": {
+    "title": "My Awesome Scene",
+    "description": "A description for the marketplace",
+    "navmapThumbnail": "images/thumbnail.png"
+  },
+  "scene": {
+    "parcels": ["0,0", "0,1"],
+    "base": "0,0"
+  },
+  "main": "bin/index.js",
+  "requiredPermissions": []
+}
+```
+
+## Permissions
+
+Some features require permissions in scene.json:
+```json
+{
+  "requiredPermissions": [
+    "ALLOW_TO_MOVE_PLAYER_INSIDE_SCENE",
+    "ALLOW_TO_TRIGGER_AVATAR_EMOTE",
+    "ALLOW_MEDIA_HOSTNAMES"
+  ]
+}
+```
+
+## Best Practices
+
+- Always preview locally before deploying
+- Use a thumbnail image (`navmapThumbnail`) for the Genesis City map
+- Write a clear description for discovery
+- Test with multiple browser tabs to verify multiplayer behavior
+- Keep scene load time under 15 seconds (optimize assets)

package/skills/deploy-worlds/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: deploy-worlds
+description: Deploy and publish a Decentraland scene to a World (personal 3D space). Use when user wants to deploy to a World, publish to a World, set up worldConfiguration, use a DCL NAME or ENS domain for deployment, or opt out of Places listing.
+---
+
+# Deploying to Decentraland Worlds
+
+Worlds are personal 3D spaces not tied to LAND. They have no parcel limitations and are automatically listed on the Places page.
+
+## Requirements
+
+To publish to a World, the user must own either:
+- A **Decentraland NAME** (e.g., `my-name.dcl.eth`)
+- An **ENS domain** (e.g., `my-name.eth`)
+
+The wallet signing the deployment must own the NAME, or have been granted permission via Access Control Lists (ACL).
+
+## 1. Configure scene.json
+
+Add a `worldConfiguration` section to `scene.json`:
+
+```json
+{
+  "worldConfiguration": {
+    "name": "my-name.dcl.eth"
+  }
+}
+```
+
+The `name` field must match a Decentraland NAME or ENS domain owned by the deploying wallet.
+
+### Opt out of Places listing
+
+All Worlds are automatically listed on the [Places page](https://places.decentraland.org). To opt out:
+
+```json
+{
+  "worldConfiguration": {
+    "name": "my-name.dcl.eth",
+    "placesConfig": {
+      "optOut": true
+    }
+  }
+}
+```
+
+## 2. Deploy
+
+**Use the `/deploy` command** — it auto-detects the `worldConfiguration` in scene.json and deploys to the Worlds content server automatically.
+
+Alternatively, deploy manually via CLI:
+
+```bash
+npx @dcl/sdk-commands deploy --target-content https://worlds-content-server.decentraland.org
+```
+
+This will prompt the user to sign the deployment with their wallet. Validations run automatically to allow or reject the scene.
+
+### Via Creator Hub
+
+1. Open the scene project in Creator Hub
+2. Click the **Publish** button (top-right corner)
+3. Select **PUBLISH TO WORLD**
+4. Choose which NAME or ENS domain to publish to
+
+## 3. Access the World
+
+Once deployed, the World is accessible at:
+
+```
+decentraland://?realm=NAME.dcl.eth
+```
+
+Replace `NAME` with the Decentraland NAME or ENS domain used for deployment.
+
+From inside Decentraland, use the chatbox command:
+```
+/goto NAME.dcl.eth
+```
+
+## Full scene.json Example
+
+```json
+{
+  "ecs7": true,
+  "runtimeVersion": "7",
+  "display": {
+    "title": "My World",
+    "description": "A personal 3D space"
+  },
+  "scene": {
+    "parcels": ["0,0"],
+    "base": "0,0"
+  },
+  "main": "bin/index.js",
+  "worldConfiguration": {
+    "name": "my-name.dcl.eth"
+  }
+}
+```
+
+## Key Differences from Genesis City
+
+- **No parcel limitations** — Worlds are not constrained by LAND ownership
+- **NAME/ENS required** — must own a Decentraland NAME or ENS domain instead of LAND
+- **Different deploy target** — uses `--target-content https://worlds-content-server.decentraland.org`
+- **Auto-listed on Places** — unless opted out via `placesConfig.optOut`

package/skills/lighting-environment/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: lighting-environment
+description: Add dynamic lighting and control environment settings in Decentraland scenes. Create point, spot, and directional lights with LightSource, configure shadows, control day/night cycle with SkyboxTime, detect realm info, and use emissive materials for glow effects. Use when user wants lights, shadows, skybox, day-night cycle, or glowing materials.
+---
+
+# Lighting and Environment in Decentraland
+
+## Point Lights
+
+Emit light in all directions from a position:
+
+```typescript
+import { engine, Transform, LightSource } from '@dcl/sdk/ecs'
+import { Vector3, Color3 } from '@dcl/sdk/math'
+
+const light = engine.addEntity()
+Transform.create(light, { position: Vector3.create(8, 3, 8) })
+
+LightSource.create(light, {
+  type: LightSource.Type.Point({}),
+  color: Color3.White(),
+  intensity: 300  // candela
+})
+```
+
+### Colored Point Light
+
+```typescript
+LightSource.create(light, {
+  type: LightSource.Type.Point({}),
+  color: Color3.create(1, 0.5, 0),  // Warm orange
+  intensity: 200,
+  range: 15  // Maximum distance in meters
+})
+```
+
+## Spot Lights
+
+Emit a cone of light in a direction:
+
+```typescript
+const spotlight = engine.addEntity()
+Transform.create(spotlight, {
+  position: Vector3.create(8, 4, 8),
+  rotation: Quaternion.fromEulerDegrees(-90, 0, 0)  // Point downward
+})
+
+LightSource.create(spotlight, {
+  type: LightSource.Type.Spot({ innerAngle: 25, outerAngle: 45 }),
+  color: Color3.White(),
+  intensity: 800
+})
+```
+
+- `innerAngle` — full-brightness cone angle (degrees)
+- `outerAngle` — outer fade angle (degrees)
+- The light direction follows the entity's forward vector (set via Transform rotation)
+
+## Shadows
+
+Enable shadows on point or spot lights:
+
+```typescript
+LightSource.create(spotlight, {
+  type: LightSource.Type.Spot({ innerAngle: 25, outerAngle: 45 }),
+  shadow: true,
+  intensity: 800
+})
+```
+
+### Shadow Mask Textures (Gobos)
+
+Project a pattern through the light:
+
+```typescript
+const maskedLight = LightSource.getMutable(spotlight)
+maskedLight.shadowMaskTexture = Material.Texture.Common({
+  src: 'assets/scene/images/lightmask1.png'
+})
+```
+
+## Toggling Lights
+
+```typescript
+// Toggle on/off
+const lightData = LightSource.getMutable(light)
+lightData.active = !lightData.active
+```
+
+## Light Limits
+
+- Maximum **one active light per parcel** (16m x 16m)
+- The renderer auto-culls lights based on quality settings and proximity
+- Up to ~3 shadowed lights visible at once
+- Intensity is in candela — visible distance grows roughly with `sqrt(intensity)`
+
+## SkyboxTime (Day/Night Cycle)
+
+### Fixed Time in scene.json
+
+Set a permanent time of day without code:
+
+```json
+{
+  "skyboxConfig": {
+    "fixedTime": 36000
+  }
+}
+```
+
+Time values: 0 = midnight, 36000 = noon, 54000 = dusk, 72000 = midnight again.
+
+### Read Current World Time
+
+```typescript
+import { getWorldTime } from '~system/Runtime'
+
+executeTask(async () => {
+  const time = await getWorldTime({})
+  console.log('Seconds since midnight:', time.seconds)
+})
+```
+
+### Change Time Dynamically
+
+```typescript
+import { SkyboxTime, TransitionMode } from '~system/Runtime'
+
+// Set time of day (must target root entity)
+SkyboxTime.create(engine.RootEntity, { fixed_time: 36000 })  // Noon
+
+// Change with transition direction
+SkyboxTime.createOrReplace(engine.RootEntity, {
+  fixed_time: 54000,  // Dusk
+  direction: TransitionMode.TM_BACKWARD
+})
+```
+
+### Day/Night Cycle System
+
+```typescript
+let currentTime = 36000
+const CYCLE_SPEED = 100  // Time units per second
+
+function dayNightCycle(dt: number) {
+  currentTime = (currentTime + CYCLE_SPEED * dt) % 72000
+  SkyboxTime.createOrReplace(engine.RootEntity, {
+    fixed_time: currentTime
+  })
+}
+
+engine.addSystem(dayNightCycle)
+```
+
+## Realm Info
+
+Detect which realm (server) the player is connected to:
+
+```typescript
+import { getRealm } from '~system/Runtime'
+
+executeTask(async () => {
+  const realm = await getRealm({})
+  console.log('Realm:', realm.realmInfo?.realmName)
+  console.log('Network:', realm.realmInfo?.networkId)
+  console.log('Base URL:', realm.realmInfo?.baseUrl)
+})
+```
+
+## Emissive Materials (Glow Effects)
+
+For a visual glow without casting light on surroundings:
+
+```typescript
+import { engine, Material } from '@dcl/sdk/ecs'
+import { Color4, Color3 } from '@dcl/sdk/math'
+
+// Self-illuminated material
+Material.setPbrMaterial(entity, {
+  albedoColor: Color4.create(0, 0, 0, 1),
+  emissiveColor: Color4.create(0, 1, 0, 1),  // Green glow
+  emissiveIntensity: 2.0
+})
+```
+
+### Combining Emissive + LightSource
+
+For an object that both glows visually and casts light:
+
+```typescript
+// Visual glow on the mesh
+Material.setPbrMaterial(bulb, {
+  emissiveColor: Color4.create(1, 0.9, 0.7, 1),
+  emissiveIntensity: 1.5
+})
+
+// Actual light emission
+LightSource.create(bulb, {
+  type: LightSource.Type.Point({}),
+  color: Color3.create(1, 0.9, 0.7),
+  intensity: 200,
+  range: 10
+})
+```
+
+## Best Practices
+
+- Stay within the **one light per parcel** budget — plan light placement around scene parcels
+- Use emissive materials for decorative glow that doesn't need to illuminate surroundings
+- Combine emissive materials with LightSource for realistic light fixtures (lamp = emissive mesh + point light)
+- Use spot lights with shadows for dramatic effects (stage lighting, flashlights)
+- Keep shadow count low (max ~3 visible) — disable `shadow` on lights that don't need it
+- Set `range` on lights to limit their influence and save performance
+- Use `SkyboxTime` for atmosphere — nighttime scenes with point lights create dramatic environments
+
+For component field details, see `context/components-reference.md`.