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

package/prompts/system.md

@@ -0,0 +1,126 @@
+---
+name: system
+description: OpenDCL system identity and Decentraland SDK7 knowledge base
+---
+
+You are **OpenDCL**, an AI coding assistant specialized in Decentraland SDK7 scene development.
+
+## Your Identity
+- You help creators build interactive 3D scenes for Decentraland using SDK7.
+- You are beginner-friendly: always explain what you're doing and why.
+- You are precise about SDK7 APIs and never invent components or functions that don't exist.
+- When unsure, read the context files in the `context/` directory for accurate SDK7 reference.
+
+## Decentraland SDK7 Fundamentals
+
+### Architecture
+- **Entity-Component System (ECS)**: Scenes are built with entities (IDs), components (data), and systems (logic).
+- **Runtime**: Sandboxed QuickJS — **no** Node.js APIs (`fs`, `http`, `path`, `process` are unavailable).
+- **Imports**: Use `@dcl/sdk/ecs`, `@dcl/sdk/math`, `@dcl/sdk/react-ecs` — never `~system/` or internal paths.
+- **Entry point**: `export function main() {}` in `src/index.ts` — the engine calls this on scene load.
+
+### Scene Constraints
+- Each **parcel** = 16m × 16m × 20m height.
+- Scenes have **entity limits**, **triangle budgets**, and **texture memory limits** based on parcel count.
+- 1 parcel: ~512 entities, ~10,000 triangles. Scales with parcel count.
+- All coordinates are in meters. Y is up. Scene origin (0,0,0) is the southwest corner of the base parcel at ground level.
+
+### Key Patterns
+
+**Creating an entity with components:**
+```typescript
+import { engine, Transform, MeshRenderer, Material } from '@dcl/sdk/ecs'
+import { Vector3, Color4 } from '@dcl/sdk/math'
+
+const cube = engine.addEntity()
+Transform.create(cube, { position: Vector3.create(8, 1, 8) })
+MeshRenderer.setBox(cube)
+Material.setPbrMaterial(cube, { albedoColor: Color4.Red() })
+```
+
+**Adding interactivity:**
+```typescript
+import { pointerEventsSystem, InputAction } from '@dcl/sdk/ecs'
+
+pointerEventsSystem.onPointerDown({ entity: cube, opts: { button: InputAction.IA_POINTER, hoverText: 'Click me' } }, () => {
+  // Handle click
+})
+```
+
+**Systems (per-frame logic):**
+```typescript
+engine.addSystem((dt: number) => {
+  // Runs every frame, dt = delta time in seconds
+})
+```
+
+**UI with React-ECS:**
+```tsx
+import ReactEcs, { UiEntity, Label, Button } from '@dcl/sdk/react-ecs'
+
+function MyUI() {
+  return (
+    <UiEntity uiTransform={{ width: 200, height: 50, positionType: 'absolute' }}>
+      <Label value="Hello" fontSize={18} />
+    </UiEntity>
+  )
+}
+
+export function setupUi() {
+  ReactEcs.setUiRenderer(MyUI)
+}
+```
+
+### Project Structure
+```
+scene-project/
+├── scene.json          # Scene metadata (parcels, title, main entry)
+├── package.json        # Dependencies (@dcl/sdk)
+├── tsconfig.json       # TypeScript config
+└── src/
+    ├── index.ts        # Main entry point (export function main)
+    └── ui.tsx          # UI components (optional)
+```
+
+### scene.json Required Fields
+```json
+{
+  "ecs7": true,
+  "runtimeVersion": "7",
+  "display": { "title": "My Scene" },
+  "scene": { "parcels": ["0,0"], "base": "0,0" },
+  "main": "bin/index.js"
+}
+```
+
+## How to Help Users
+
+### Empty Folder (No scene.json)
+1. Ask the user what they want to build.
+2. **Use the `init` tool first** — this uses the official SDK scaffolding to create scene.json, package.json, tsconfig.json, and src/index.ts with the correct, up-to-date configuration. Never create these files manually.
+3. After init completes, customize `scene.json` (title, description, parcels) and `src/index.ts` (scene code) based on what the user wants.
+4. Run `npm install`, then use the `preview` tool to start the preview server.
+
+### Existing Scene
+1. Read scene.json and src/index.ts to understand the project.
+2. Offer contextual help — adding features, fixing bugs, optimizing.
+3. Always preserve existing code when making edits.
+
+### Best Practices
+- Always position objects within the scene boundaries (based on parcels).
+- Use `Vector3.create()` and `Quaternion.fromEulerDegrees()` for transforms.
+- For 3D models, use `GltfContainer.create(entity, { src: 'models/myModel.glb' })`.
+- Place `.glb` files in a `models/` directory, textures in `images/`.
+- After writing TypeScript, use the `preview` tool to start the preview server.
+- If the user asks about 3D models, reference the open-source-3D-assets catalog in `context/open-source-3d-assets.md`.
+
+## Tools & Commands
+
+You have these Decentraland-specific tools — **use them directly** when the user's request matches:
+- `init` — Scaffold a new scene (**always use this first** in an empty folder)
+- `preview` — Start the Bevy-web preview server
+- `deploy` — Deploy to Genesis City or a World (auto-detects from scene.json)
+- `tasks` — List or stop running background processes
+
+The user can also type these as `/init`, `/preview`, `/deploy`, `/tasks` slash commands directly.
+Additional user-only commands: `/review`, `/explain`, `/setup`, `/setup-ollama`

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

@@ -0,0 +1,115 @@
+---
+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.
+---
+
+# Adding 3D Models to Decentraland Scenes
+
+## Loading a 3D Model
+
+Use `GltfContainer` to load `.glb` or `.gltf` files:
+
+```typescript
+import { engine, Transform, GltfContainer } 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'
+})
+```
+
+## File Organization
+
+Place model files in a `models/` directory at the project root:
+```
+project/
+├── models/
+│   ├── building.glb
+│   ├── tree.glb
+│   └── furniture/
+│       ├── chair.glb
+│       └── table.glb
+├── src/
+│   └── index.ts
+└── scene.json
+```
+
+## 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
+})
+```
+
+### Adding Simple Colliders
+For basic shapes, add `MeshCollider`:
+```typescript
+import { MeshCollider } from '@dcl/sdk/ecs'
+MeshCollider.setBox(model) // Box collider
+MeshCollider.setSphere(model) // Sphere collider
+```
+
+## 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
+})
+```
+
+### Parenting (Attach to Another Entity)
+```typescript
+const parent = engine.addEntity()
+Transform.create(parent, { position: Vector3.create(8, 0, 8) })
+
+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' })
+```
+
+## Free 3D Models
+
+For free CC0-licensed 3D models suitable for Decentraland, read the catalog at:
+`context/open-source-3d-assets.md` (in the opendcl repo root). If unavailable locally, fetch from:
+https://raw.githubusercontent.com/dcl-regenesislabs/opendcl/main/context/open-source-3d-assets.md
+
+This catalog contains 991+ models organized by themed collections (Cyberpunk, Medieval, MomusPark, etc.) with direct download URLs.
+
+When the user asks for 3D models:
+1. Read the open-source-3d-assets.md file
+2. Suggest models that match their description
+3. Show them how to download and add the model to their scene
+
+## Model Best Practices
+
+- Keep models under 50MB per file for good loading times
+- Use `.glb` format (binary GLTF) — smaller than `.gltf`
+- Optimize triangle count: aim for under 1,500 triangles per model for small props
+- Use texture atlases when possible to reduce draw calls
+- Models with embedded animations can be played with the `Animator` component
+- Test model orientation — Decentraland uses Y-up coordinate system
+- Materials in models should use PBR (physically-based rendering) for best results

package/skills/add-interactivity/SKILL.md

@@ -0,0 +1,176 @@
+---
+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.
+---
+
+# Adding Interactivity to Decentraland Scenes
+
+## Pointer Events (Click / Hover)
+
+### Using the Helper System (Recommended)
+```typescript
+import { engine, Transform, MeshRenderer, pointerEventsSystem, InputAction } from '@dcl/sdk/ecs'
+import { Vector3 } from '@dcl/sdk/math'
+
+const cube = engine.addEntity()
+Transform.create(cube, { position: Vector3.create(8, 1, 8) })
+MeshRenderer.setBox(cube)
+
+// Add click handler
+pointerEventsSystem.onPointerDown(
+  {
+    entity: cube,
+    opts: {
+      button: InputAction.IA_POINTER,    // Left click
+      hoverText: 'Click me!',
+      maxDistance: 10
+    }
+  },
+  (event) => {
+    console.log('Cube clicked!', event.hit?.position)
+  }
+)
+```
+
+### Available Input Actions
+```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
+```
+
+### Pointer Up (Release)
+```typescript
+pointerEventsSystem.onPointerDown(
+  { entity: cube, opts: { button: InputAction.IA_POINTER, hoverText: 'Hold me' } },
+  () => { console.log('Pressed!') }
+)
+
+pointerEventsSystem.onPointerUp(
+  { entity: cube, opts: { button: InputAction.IA_POINTER } },
+  () => { console.log('Released!') }
+)
+```
+
+### Removing Handlers
+```typescript
+pointerEventsSystem.removeOnPointerDown(cube)
+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:
+```typescript
+import { MeshCollider } from '@dcl/sdk/ecs'
+MeshCollider.setBox(entity) // Invisible box collider
+```
+
+For GLTF models, set the collision mask:
+```typescript
+GltfContainer.create(entity, {
+  src: 'models/button.glb',
+  visibleMeshesCollisionMask: ColliderLayer.CL_POINTER
+})
+```
+
+## Trigger Areas (Proximity Detection)
+
+Detect when the player enters or exits an area:
+
+```typescript
+import { engine, Transform, TriggerArea, TriggerAreaResult } from '@dcl/sdk/ecs'
+import { Vector3 } from '@dcl/sdk/math'
+
+const trigger = engine.addEntity()
+Transform.create(trigger, { position: Vector3.create(8, 0, 8) })
+
+TriggerArea.create(trigger, {
+  area: Vector3.create(4, 4, 4) // 4x4x4 meter box
+})
+
+// System to check trigger
+engine.addSystem(() => {
+  const result = TriggerAreaResult.getOrNull(trigger)
+  if (result && result.isTriggered) {
+    // Player is inside the trigger area
+  }
+})
+```
+
+## Raycasting
+
+Cast rays to detect objects in a direction:
+
+```typescript
+import { engine, Raycast, RaycastResult, RaycastQueryType } from '@dcl/sdk/ecs'
+import { Vector3 } from '@dcl/sdk/math'
+
+const rayEntity = engine.addEntity()
+Raycast.create(rayEntity, {
+  direction: { $case: 'localDirection', localDirection: Vector3.Forward() },
+  maxDistance: 16,
+  queryType: RaycastQueryType.RQT_HIT_FIRST,
+  continuous: false // Set true for continuous raycasting
+})
+
+// Check results
+engine.addSystem(() => {
+  const result = RaycastResult.getOrNull(rayEntity)
+  if (result && result.hits.length > 0) {
+    const hit = result.hits[0]
+    console.log('Hit entity:', hit.entityId, 'at', hit.position)
+  }
+})
+```
+
+## Global Input Handling
+
+Listen for key presses anywhere (not entity-specific):
+
+```typescript
+import { inputSystem, InputAction, PointerEventType } from '@dcl/sdk/ecs'
+
+engine.addSystem(() => {
+  // Check if E key was just pressed this frame
+  if (inputSystem.isTriggered(InputAction.IA_PRIMARY, PointerEventType.PET_DOWN)) {
+    console.log('E key pressed!')
+  }
+
+  // Check if a key is currently held down
+  if (inputSystem.isPressed(InputAction.IA_SECONDARY)) {
+    console.log('F key is held!')
+  }
+})
+```
+
+## Toggle Pattern (Click to Switch States)
+
+Common pattern for toggleable objects:
+
+```typescript
+let doorOpen = false
+
+pointerEventsSystem.onPointerDown(
+  { entity: door, opts: { button: InputAction.IA_POINTER, hoverText: 'Toggle door' } },
+  () => {
+    doorOpen = !doorOpen
+    const mutableTransform = Transform.getMutable(door)
+    mutableTransform.rotation = doorOpen
+      ? Quaternion.fromEulerDegrees(0, 90, 0)
+      : Quaternion.fromEulerDegrees(0, 0, 0)
+  }
+)
+```
+
+## Best Practices
+
+- Always set `maxDistance` on pointer events (8-16m is typical)
+- Always set `hoverText` so users know they can interact
+- Clean up handlers when entities are removed
+- 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

package/skills/advanced-input/SKILL.md

@@ -0,0 +1,238 @@
+---
+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.
+---
+
+# Advanced Input Handling in Decentraland
+
+For basic click/hover events, see the `add-interactivity` skill. This skill covers advanced input patterns.
+
+## Pointer Lock State
+
+Detect whether the cursor is captured (first-person mode) or free:
+
+```typescript
+import { engine, PointerLock } from '@dcl/sdk/ecs'
+
+function checkPointerLock() {
+  const isLocked = PointerLock.get(engine.CameraEntity).isPointerLocked
+
+  if (isLocked) {
+    // Cursor is captured — player is in first-person control
+  } else {
+    // Cursor is free — player can click UI elements
+  }
+}
+
+engine.addSystem(checkPointerLock)
+```
+
+### Pointer Lock Change Detection
+
+```typescript
+PointerLock.onChange(engine.CameraEntity, (pointerLock) => {
+  if (pointerLock?.isPointerLocked) {
+    console.log('Cursor locked')
+  } else {
+    console.log('Cursor unlocked')
+  }
+})
+```
+
+## Cursor Position and World Ray
+
+Get the cursor's screen position and the ray it casts into the 3D world:
+
+```typescript
+import { engine, PrimaryPointerInfo } from '@dcl/sdk/ecs'
+
+function readPointer() {
+  const pointerInfo = PrimaryPointerInfo.get(engine.RootEntity)
+  console.log('Cursor position:', pointerInfo.screenCoordinates)
+  console.log('Cursor delta:', pointerInfo.screenDelta)
+  console.log('World ray direction:', pointerInfo.worldRayDirection)
+}
+
+engine.addSystem(readPointer)
+```
+
+## Input Polling with inputSystem
+
+### Per-Entity Input Commands
+
+Check if a specific input action occurred on a specific entity:
+
+```typescript
+import { engine, inputSystem, InputAction, PointerEventType } from '@dcl/sdk/ecs'
+
+function myInputSystem() {
+  // Check for click on a specific entity
+  const clickData = inputSystem.getInputCommand(
+    InputAction.IA_POINTER,
+    PointerEventType.PET_DOWN,
+    myEntity
+  )
+
+  if (clickData) {
+    console.log('Entity clicked via system:', clickData.hit.entityId)
+  }
+}
+
+engine.addSystem(myInputSystem)
+```
+
+### Global Input Checks
+
+```typescript
+function globalInputSystem() {
+  // Was the key just pressed this frame?
+  if (inputSystem.isTriggered(InputAction.IA_PRIMARY, PointerEventType.PET_DOWN)) {
+    console.log('E key pressed!')
+  }
+
+  // Is the key currently held down?
+  if (inputSystem.isPressed(InputAction.IA_SECONDARY)) {
+    console.log('F key is held!')
+  }
+}
+
+engine.addSystem(globalInputSystem)
+```
+
+## All InputAction Values
+
+| InputAction | Key/Button |
+|-------------|-----------|
+| `IA_POINTER` | Left mouse button |
+| `IA_PRIMARY` | E key |
+| `IA_SECONDARY` | F key |
+| `IA_ACTION_3` | 1 key |
+| `IA_ACTION_4` | 2 key |
+| `IA_ACTION_5` | 3 key |
+| `IA_ACTION_6` | 4 key |
+| `IA_JUMP` | Space key |
+| `IA_FORWARD` | W key |
+| `IA_BACKWARD` | S key |
+| `IA_LEFT` | A key |
+| `IA_RIGHT` | D key |
+| `IA_WALK` | Shift key |
+
+## Event Types
+
+```typescript
+PointerEventType.PET_DOWN         // Button/key pressed
+PointerEventType.PET_UP           // Button/key released
+PointerEventType.PET_HOVER_ENTER  // Cursor enters entity
+PointerEventType.PET_HOVER_LEAVE  // Cursor leaves entity
+```
+
+## InputModifier (Movement Restriction)
+
+Restrict or freeze the player's movement:
+
+```typescript
+import { engine, InputModifier } from '@dcl/sdk/ecs'
+
+// Freeze player completely
+InputModifier.create(engine.PlayerEntity, {
+  mode: InputModifier.Mode.Standard({ disableAll: true })
+})
+
+// Restrict specific movement
+InputModifier.createOrReplace(engine.PlayerEntity, {
+  mode: InputModifier.Mode.Standard({
+    disableRun: true,
+    disableJump: true,
+    disableEmote: true
+  })
+})
+
+// Restore normal movement
+InputModifier.deleteFrom(engine.PlayerEntity)
+```
+
+**Important:** InputModifier only works in the DCL 2.0 desktop client. It has no effect in the web browser explorer.
+
+### Cutscene Pattern
+
+Freeze the player during a cinematic sequence:
+
+```typescript
+function startCutscene() {
+  // Freeze player
+  InputModifier.create(engine.PlayerEntity, {
+    mode: InputModifier.Mode.Standard({ disableAll: true })
+  })
+
+  // ... play cinematic with VirtualCamera ...
+
+  // After cutscene ends, restore movement
+  // InputModifier.deleteFrom(engine.PlayerEntity)
+}
+```
+
+## WASD Movement Pattern
+
+Poll movement keys to control custom entities:
+
+```typescript
+import { engine, inputSystem, InputAction, PointerEventType, Transform } from '@dcl/sdk/ecs'
+import { Vector3 } from '@dcl/sdk/math'
+
+const MOVE_SPEED = 5
+
+function customMovementSystem(dt: number) {
+  const transform = Transform.getMutable(controllableEntity)
+  let moveX = 0
+  let moveZ = 0
+
+  if (inputSystem.isPressed(InputAction.IA_FORWARD)) moveZ += 1
+  if (inputSystem.isPressed(InputAction.IA_BACKWARD)) moveZ -= 1
+  if (inputSystem.isPressed(InputAction.IA_LEFT)) moveX -= 1
+  if (inputSystem.isPressed(InputAction.IA_RIGHT)) moveX += 1
+
+  transform.position.x += moveX * MOVE_SPEED * dt
+  transform.position.z += moveZ * MOVE_SPEED * dt
+}
+
+engine.addSystem(customMovementSystem)
+```
+
+## Combining Input Patterns
+
+### Action Bar with Number Keys
+
+```typescript
+function actionBarSystem() {
+  if (inputSystem.isTriggered(InputAction.IA_ACTION_3, PointerEventType.PET_DOWN)) {
+    console.log('Slot 1 activated')
+    useAbility(1)
+  }
+  if (inputSystem.isTriggered(InputAction.IA_ACTION_4, PointerEventType.PET_DOWN)) {
+    console.log('Slot 2 activated')
+    useAbility(2)
+  }
+  if (inputSystem.isTriggered(InputAction.IA_ACTION_5, PointerEventType.PET_DOWN)) {
+    console.log('Slot 3 activated')
+    useAbility(3)
+  }
+  if (inputSystem.isTriggered(InputAction.IA_ACTION_6, PointerEventType.PET_DOWN)) {
+    console.log('Slot 4 activated')
+    useAbility(4)
+  }
+}
+
+engine.addSystem(actionBarSystem)
+```
+
+## Best Practices
+
+- Use `isTriggered()` for one-shot actions (fire weapon, open door) — it returns true only on the frame the key is first pressed
+- Use `isPressed()` for continuous actions (movement, holding a shield) — it returns true every frame while held
+- `getInputCommand()` gives hit data (position, entity) — use it when you need to know what was clicked
+- Prefer `pointerEventsSystem.onPointerDown()` for simple entity clicks — use `inputSystem` for complex multi-key or polling patterns
+- InputModifier only works in the DCL 2.0 desktop client — test with the desktop client if your scene relies on it
+- WASD keys (`IA_FORWARD`, etc.) also control player movement — polling them reads the movement state but doesn't override it
+
+For basic pointer events and click handlers, see the `add-interactivity` skill.
+For component field details, see `context/components-reference.md`.