@dcl-regenesislabs/opendcl 0.2.1 → 0.2.2-26850672477.commit-99ffd91

package/skills/editor-gizmo/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: editor-gizmo
+description: Enable the visual editor in a Decentraland scene with translate/rotate gizmos. Adds click-to-select, drag-to-move arrows, drag-to-rotate rings, plane handles, wireframe selection box, and UI overlay. Auto-discovers all entities declared in main-entities.ts. Use when user wants to enable the editor, add gizmos, edit the scene interactively, or tweak object positions and rotations in preview.
+---
+
+# Visual Editor Gizmo
+
+Add an in-scene visual editor that lets users click objects to select them, then drag arrow/disc handles to move or rotate them. The editor only edits entities declared in `main-entities.ts` — runtime-spawned entities are hidden from the hierarchy.
+
+## How It Works
+
+- **Preview only**: the editor only activates in `/preview`. Deployed scenes never show editor UI.
+- **Editor toggle**: a pencil button in the bottom-right corner toggles the editor on/off (starts OFF).
+- **Auto-discovery**: finds all entities with `Transform` + `MeshRenderer` or `GltfContainer`. Hierarchy filters to entities whose `Name` is declared in `main-entities.ts`.
+- **Click to select**: shows a wireframe bounding box and spawns the gizmo.
+- **Translate mode**: 3 colored arrows (R/G/B = X/Y/Z) — drag to move along a world axis. 3 plane handles (XZ/XY/YZ) for 2-axis constrained movement.
+- **Rotate mode**: 3 colored ring outlines — drag to rotate around a world axis.
+- **World-aligned gizmos**: arrows and rings always point along world X/Y/Z, regardless of entity or parent rotation. Drag deltas are converted to local space for child entities.
+- **E key**: toggle between Move and Rotate.
+- **F key** or **click ground**: deselect.
+- **Undo/redo**: key 4 = undo, Shift+4 = redo.
+- **Auto-save**: changes POST to `${realm.baseUrl}/editor/changes` on every drag end. The preview server merges them into `main-entities.ts` and synchronously regenerates `main.crdt`.
+
+## Setup Steps
+
+### Step 0: Check if editor is already installed (and up-to-date)
+
+If `src/__editor/state.ts` exists, read the first line and look for `EDITOR_VERSION`. Compare it with the version in `{baseDir}/src/__editor/state.ts`. If the versions match, skip Step 1 — the files are current. If they differ (or `src/__editor/` doesn't exist), proceed with Step 1 to install or update.
+
+### Step 1: Copy editor files into the scene
+
+```bash
+mkdir -p src/__editor && cp -rf {baseDir}/src/__editor/* src/__editor/
+```
+
+This creates a self-contained editor directory:
+```
+src/__editor/
+├── index.ts       — Entry point + enableEditor() export
+├── state.ts       — Shared state and types
+├── persistence.ts — HTTP POST/GET to {baseUrl}/editor/changes
+├── selection.ts   — Select/deselect + highlight
+├── discovery.ts   — Auto-discover scene entities
+├── gizmo.ts       — Translate/rotate gizmo handles
+├── drag.ts        — Drag system (ray-plane intersection)
+├── camera.ts      — Editor camera (orbit, WASD pan)
+├── input.ts       — Key bindings (E, F, 1-4)
+├── history.ts     — Undo/redo stack
+├── math-utils.ts  — Vector/quaternion helpers
+└── ui.tsx         — Toolbar + hierarchy + properties panel
+```
+
+### Step 2: Add `enableEditor()` to the scene's main function
+
+In `src/index.ts`:
+
+```typescript
+import { enableEditor } from './__editor'
+
+export function main() {
+  // ... your scene code ...
+  enableEditor()
+}
+```
+
+`enableEditor()` is a no-op outside preview mode, so it's safe to leave in deployed scenes.
+
+### Step 3: Make sure the scene has a `main-entities.ts`
+
+If the scene doesn't have one yet, create `main-entities.ts` at the scene root with at least one entity (see "Authoring Model" below). Without it, the editor's hierarchy panel falls back to permissive mode and shows every named entity, including runtime ones.
+
+### Step 4: Update tsconfig.json to include `main-entities.ts`
+
+The default scene `tsconfig.json` only checks `src/**/*`. Widen the include so the typed `Scene` shape is validated:
+
+```json
+{
+  "extends": "@dcl/sdk/types/tsconfig.ecs7.json",
+  "include": ["src/**/*.ts", "src/**/*.tsx", "main-entities.ts"]
+}
+```
+
+### Step 5: Verify
+
+Run `/preview`. You should see a pencil button bottom-right. Click it to toggle the editor. Click any entity declared in `main-entities.ts` to select it; drag arrows or rings to move or rotate.
+
+## Scene Authoring Model
+
+The editor only edits **declared** entities — those that exist in `main-entities.ts`. Dynamic entities created at runtime via `engine.addEntity()` are hidden from the hierarchy and not draggable.
+
+### `main-entities.ts` (canonical entity declarations)
+
+`main-entities.ts` lives at the scene root, exports a typed `scene` constant, and is bundled into `main.crdt` at build time. The `satisfies Scene` clause keeps the literal keys typed (so code can reference entity names safely) while still validating the shape against the schema.
+
+```typescript
+import type { Scene } from '@dcl/sdk/scene-types'
+
+export const scene = {
+  "barrel_1": {
+    "components": {
+      "Transform": {
+        "position": { "x": 5, "y": 0, "z": 8 },
+        "rotation": { "x": 0, "y": 0, "z": 0, "w": 1 },
+        "scale": { "x": 1, "y": 1, "z": 1 }
+      },
+      "GltfContainer": { "src": "models/Barrel.glb" }
+    }
+  },
+  "lamp_1": {
+    "components": {
+      "Transform": {
+        "position": { "x": 0, "y": 1.5, "z": 0 },
+        "rotation": { "x": 0, "y": 0, "z": 0, "w": 1 },
+        "scale": { "x": 1, "y": 1, "z": 1 },
+        "parent": "barrel_1"
+      },
+      "GltfContainer": { "src": "models/Lamp.glb" }
+    }
+  }
+} satisfies Scene
+```
+
+**Rules:**
+- **Names are unique** within `scene` — they're the stable ID the editor and code use to reference an entity.
+- **Parents are referenced by Name**, not entity ID (e.g. `"parent": "barrel_1"`). The build resolves names to IDs.
+- **`Transform.position` is required.** `rotation` defaults to identity, `scale` defaults to `(1,1,1)`, but you must provide all three keys when authoring.
+- **Literal-only constraint:** values inside `scene` must be plain JSON-compatible literals — no function calls (`Vector3.create(...)`), no spread, no computed expressions, no comments inside the literal. The build parses the AST and the editor save handler rewrites the whole literal as JSON, so anything outside this discipline gets stripped or breaks.
+
+### Behavior in `src/index.ts`
+
+Code references entities by Name and attaches behavior. Use a type-only import of `scene` so the bundle stays small, and derive `EntityName` for typo-safe lookups:
+
+```typescript
+import { engine, pointerEventsSystem, InputAction } from '@dcl/sdk/ecs'
+import { enableEditor } from './__editor'
+import type { scene } from '../main-entities'
+
+type EntityName = keyof typeof scene
+
+export function main() {
+  const barrel = engine.getEntityOrNullByName<EntityName>('barrel_1')
+  if (barrel === null) return
+
+  pointerEventsSystem.onPointerDown(
+    { entity: barrel, opts: { button: InputAction.IA_POINTER, hoverText: 'Open' } },
+    () => console.log('clicked barrel')
+  )
+
+  enableEditor()
+}
+```
+
+- `engine.getEntityOrNullByName<EntityName>(name)` looks up an entity by its `Name` component, populated by the `main.crdt` preload (built from `main-entities.ts` at bundle time).
+- The `<EntityName>` type parameter makes typos a compile error: passing `'barrl_1'` (typo) fails type-checking.
+- Renaming an entity in `main-entities.ts` immediately surfaces every stale reference in code as a compile error.
+- Use `getEntityOrNullByName` rather than `getEntityByName` — the SDK's typed `getEntityByName` requires awkward generics and silently returns `undefined` cast as `Entity`, so null-handling is cleaner.
+
+### Dynamic entities
+
+Anything that needs to spawn at runtime (effects, projectiles, dynamic UI markers) still uses `engine.addEntity()` directly:
+
+```typescript
+const explosion = engine.addEntity()
+Transform.create(explosion, { position: Vector3.create(8, 1, 8) })
+GltfContainer.create(explosion, { src: 'models/Explosion.glb' })
+// Don't give dynamic entities a Name — they don't go in main-entities.ts.
+```
+
+**Rule**: only declarative, editable entities go in `main-entities.ts`. Dynamic runtime entities use `engine.addEntity` and don't get `Name` components.
+
+## Persistence
+
+When the user drags an entity in preview:
+
+1. The scene applies the new Transform client-side (instant).
+2. The editor POSTs `${realm.baseUrl}/editor/changes` with the entity's new Transform, keyed by Name.
+3. The preview server merges the change into `main-entities.ts` on disk by parsing the AST, mutating the scene object, and splicing the new JSON back into the source — preserving everything outside the `scene` literal (imports, `satisfies` clause, comments above the export).
+4. The same handler synchronously regenerates `main.crdt` so the next reload preloads the updated state.
+5. Both `main-entities.ts` and `main.crdt` are excluded from the file watcher, so editor saves do not trigger a scene reload.
+
+There is no manual "save" step — every drag persists.
+
+If the AI / a human edits `main-entities.ts` directly (without going through the editor), a dedicated watcher on `main-entities.ts` regenerates `main.crdt` out-of-band as well, with an mtime check that skips redundant work when the editor's POST handler already produced a fresh CRDT.
+
+## Removing the Editor
+
+To remove:
+1. Delete `src/__editor/`
+2. Remove the `import { enableEditor } from './__editor'` line and the `enableEditor()` call
+
+`main-entities.ts` is unaffected — it remains the source of truth for declared entities, regardless of whether the editor is installed.
+
+## Adding New Entities
+
+When the user asks to add a new entity (e.g., "add a barrel"):
+
+1. **Add the entry to `main-entities.ts`** with a unique Name and the components needed to render it (`Transform`, `GltfContainer` or `MeshRenderer` + `Material`, etc.). The TS compiler will validate the shape against `Scene`.
+2. **Reference it in code** if you need to attach behavior:
+   ```typescript
+   const barrel = engine.getEntityOrNullByName<EntityName>('barrel_1')
+   ```
+3. Run `/preview` — the entity will appear in the scene at the position declared in `main-entities.ts`, and will be draggable in the editor.
+
+## Components supported in `main-entities.ts`
+
+All ECS data components that the client renders/uses:
+
+- `Transform` (required for every entity)
+- `GltfContainer`, `MeshRenderer`, `MeshCollider`, `Material`
+- `VisibilityComponent`, `Billboard`
+- `AudioSource`, `VideoPlayer`, `TextShape`, `NftShape`
+- `Animator` (state-machine config; runtime control via code)
+
+Behavior — pointer event callbacks, systems, tweens, conditional logic — stays in `src/`.
+
+## Common Pitfalls
+
+- **Component shapes mirror the SDK protobuf.** `MeshRenderer` is `{ mesh: { $case: 'box', box: { uvs: [] } } }`, not `MeshRenderer.setBox()`. The TS compiler validates against the protobuf-derived types and will flag mismatches.
+- **Don't use `Vector3.create(...)` inside `main-entities.ts`.** Use plain `{ x, y, z }` objects. The literal-only constraint means function calls and identifier references will break the build/save pipeline.
+- **`box` mesh requires `uvs: []`.** Same for `plane`. Sphere and cylinder default to `{}`. The TS type forces this — pay attention to red squiggles.
+- **Renaming an entity** breaks every code reference until you update them. That's the type system working as intended; let TS guide you to the broken references.
+- **Comments inside the `scene` literal get wiped on the first editor save.** Keep comments outside the literal (above the import, before the `export const scene =` line).

package/skills/editor-gizmo/src/__editor/camera.ts

@@ -0,0 +1,277 @@
+/**
+ * Editor orbit camera + drag lock camera.
+ *
+ * Orbit model: target + yaw + pitch + distance.
+ * Lock camera: freezes view during gizmo drag (non-editor-cam mode only).
+ */
+
+import {
+  engine,
+  Entity,
+  Transform,
+  VirtualCamera,
+  MainCamera,
+  InputModifier,
+  inputSystem,
+  InputAction,
+  PrimaryPointerInfo,
+} from '@dcl/sdk/ecs'
+import { Vector3, Quaternion } from '@dcl/sdk/math'
+import { getSceneInformation } from '~system/Runtime'
+import { state, editorEntities, selectableInfoMap, gizmoClickConsumed } from './state'
+import { copyVec3, copyQuat } from './math-utils'
+
+// ── Scene bounds (computed once) ────────────────────────
+let sceneCenter = Vector3.create(8, 0, 8)
+let sceneBoundsMin = Vector3.create(0, 0, 0)
+let sceneBoundsMax = Vector3.create(16, 20, 16)
+
+async function getSceneInformationAsync() {
+  try {
+    const info = await getSceneInformation({})
+    const metadata = JSON.parse(info.metadataJson)
+    const parcels: string[] = metadata?.scene?.parcels ?? ['0,0']
+    let minX = Infinity, minZ = Infinity, maxX = -Infinity, maxZ = -Infinity
+    for (const p of parcels) {
+      const [px, pz] = p.split(',').map(Number)
+      if (px < minX) minX = px
+      if (pz < minZ) minZ = pz
+      if (px > maxX) maxX = px
+      if (pz > maxZ) maxZ = pz
+    }
+    const base = parcels[0].split(',').map(Number)
+    const offX = -base[0] * 16
+    const offZ = -base[1] * 16
+    sceneBoundsMin = Vector3.create((minX * 16) + offX, 0, (minZ * 16) + offZ)
+    sceneBoundsMax = Vector3.create(((maxX + 1) * 16) + offX, 20, ((maxZ + 1) * 16) + offZ)
+    sceneCenter = Vector3.create(
+      (sceneBoundsMin.x + sceneBoundsMax.x) / 2,
+      0,
+      (sceneBoundsMin.z + sceneBoundsMax.z) / 2,
+    )
+  } catch (e) {
+    console.log('[editor] failed to read scene bounds, using defaults', e)
+  }
+}
+void getSceneInformationAsync()
+
+// ============================================================
+// Editor Camera
+// ============================================================
+
+let editorCamEntity: Entity | undefined
+
+const editorCam = {
+  target: Vector3.create(16, 2, 16),
+  yaw: -45,
+  pitch: 35,
+  distance: 25,
+}
+
+// Tuning
+const PAN_SPEED = 12
+const VERTICAL_SPEED = 8
+const ORBIT_SENSITIVITY = 0.15
+const ZOOM_SPEED = 15
+const MIN_DISTANCE = 3
+const MAX_DISTANCE = 80
+const MIN_PITCH = 5
+const MAX_PITCH = 89
+const FOCUS_DISTANCE = 8
+
+export function createEditorCamera() {
+  editorCamEntity = engine.addEntity()
+  Transform.create(editorCamEntity, {
+    position: Vector3.Zero(),
+    rotation: Quaternion.Identity(),
+  })
+  VirtualCamera.create(editorCamEntity, {
+    defaultTransition: { transitionMode: VirtualCamera.Transition.Time(0) },
+  })
+  editorEntities.add(editorCamEntity)
+}
+
+function updateEditorCamera() {
+  if (editorCamEntity === undefined) return
+
+  const pitchRad = editorCam.pitch * (Math.PI / 180)
+  const yawRad = editorCam.yaw * (Math.PI / 180)
+
+  const cosP = Math.cos(pitchRad)
+  const offset = Vector3.create(
+    -Math.sin(yawRad) * cosP * editorCam.distance,
+    Math.sin(pitchRad) * editorCam.distance,
+    -Math.cos(yawRad) * cosP * editorCam.distance,
+  )
+
+  const camPos = Vector3.add(editorCam.target, offset)
+  const forward = Vector3.normalize(Vector3.subtract(editorCam.target, camPos))
+  const camRot = Quaternion.lookRotation(forward)
+
+  const t = Transform.getMutable(editorCamEntity)
+  copyVec3(t.position, camPos)
+  copyQuat(t.rotation, camRot)
+}
+
+export function activateEditorCamera() {
+  if (state.editorCamActive || state.isDragging) return
+  state.editorCamActive = true
+
+  // Center on scene
+  editorCam.target = Vector3.create(sceneCenter.x, 0, sceneCenter.z)
+
+  updateEditorCamera()
+  MainCamera.getMutable(engine.CameraEntity).virtualCameraEntity = editorCamEntity
+
+  InputModifier.createOrReplace(engine.PlayerEntity, {
+    mode: InputModifier.Mode.Standard({ disableAll: true }),
+  })
+
+  console.log('[editor] editor camera ON — WASD pan, Space/Shift up/down, 2/3 zoom, drag to orbit, F focus')
+}
+
+export function deactivateEditorCamera() {
+  if (!state.editorCamActive) return
+  state.editorCamActive = false
+
+  MainCamera.getMutable(engine.CameraEntity).virtualCameraEntity = undefined
+
+  if (InputModifier.has(engine.PlayerEntity)) {
+    InputModifier.deleteFrom(engine.PlayerEntity)
+  }
+
+  console.log('[editor] editor camera OFF')
+}
+
+export function toggleEditorCamera() {
+  if (state.editorCamActive) deactivateEditorCamera()
+  else activateEditorCamera()
+}
+
+export function focusSelectedEntity() {
+  if (state.selectedEntity === undefined || !Transform.has(state.selectedEntity)) return
+  const info = selectableInfoMap.get(state.selectedEntity)
+  const entityPos = Transform.get(state.selectedEntity).position
+  const offset = info?.centerOffset ?? Vector3.Zero()
+
+  editorCam.target = Vector3.create(
+    entityPos.x + offset.x,
+    entityPos.y + offset.y,
+    entityPos.z + offset.z,
+  )
+  editorCam.distance = FOCUS_DISTANCE
+
+  updateEditorCamera()
+  console.log(`[editor] focused on ${info?.name ?? 'entity'}`)
+}
+
+function getCamRight(): Vector3 {
+  const yawRad = editorCam.yaw * (Math.PI / 180)
+  return Vector3.create(Math.cos(yawRad), 0, -Math.sin(yawRad))
+}
+
+function getCamForward(): Vector3 {
+  const yawRad = editorCam.yaw * (Math.PI / 180)
+  return Vector3.create(Math.sin(yawRad), 0, Math.cos(yawRad))
+}
+
+export function editorCameraSystem(dt: number) {
+  if (!state.editorActive || !state.editorCamActive) return
+
+  let changed = false
+  const right = getCamRight()
+  const forward = getCamForward()
+
+  if (inputSystem.isPressed(InputAction.IA_FORWARD)) {
+    editorCam.target = Vector3.add(editorCam.target, Vector3.scale(forward, PAN_SPEED * dt))
+    changed = true
+  }
+  if (inputSystem.isPressed(InputAction.IA_BACKWARD)) {
+    editorCam.target = Vector3.add(editorCam.target, Vector3.scale(forward, -PAN_SPEED * dt))
+    changed = true
+  }
+  if (inputSystem.isPressed(InputAction.IA_RIGHT)) {
+    editorCam.target = Vector3.add(editorCam.target, Vector3.scale(right, PAN_SPEED * dt))
+    changed = true
+  }
+  if (inputSystem.isPressed(InputAction.IA_LEFT)) {
+    editorCam.target = Vector3.add(editorCam.target, Vector3.scale(right, -PAN_SPEED * dt))
+    changed = true
+  }
+  if (inputSystem.isPressed(InputAction.IA_JUMP)) {
+    editorCam.target.y += VERTICAL_SPEED * dt
+    changed = true
+  }
+  if (inputSystem.isPressed(InputAction.IA_WALK)) {
+    editorCam.target.y -= VERTICAL_SPEED * dt
+    changed = true
+  }
+  if (inputSystem.isPressed(InputAction.IA_ACTION_4)) {
+    editorCam.distance = Math.max(MIN_DISTANCE, editorCam.distance - ZOOM_SPEED * dt)
+    changed = true
+  }
+  if (inputSystem.isPressed(InputAction.IA_ACTION_5)) {
+    editorCam.distance = Math.min(MAX_DISTANCE, editorCam.distance + ZOOM_SPEED * dt)
+    changed = true
+  }
+
+  if (inputSystem.isPressed(InputAction.IA_POINTER) && !state.isDragging && !gizmoClickConsumed) {
+    const pointer = PrimaryPointerInfo.getOrNull(engine.RootEntity)
+    if (pointer && pointer.screenDelta) {
+      const dx = pointer.screenDelta.x ?? 0
+      const dy = pointer.screenDelta.y ?? 0
+      if (Math.abs(dx) > 0.001 || Math.abs(dy) > 0.001) {
+        editorCam.yaw += dx * ORBIT_SENSITIVITY
+        editorCam.pitch = Math.max(MIN_PITCH, Math.min(MAX_PITCH, editorCam.pitch + dy * ORBIT_SENSITIVITY))
+        changed = true
+      }
+    }
+  }
+
+  if (changed) updateEditorCamera()
+}
+
+// ============================================================
+// Drag Lock Camera
+// ============================================================
+
+let lockCamEntity: Entity | undefined
+
+export function createLockCamera() {
+  lockCamEntity = engine.addEntity()
+  Transform.create(lockCamEntity, {
+    position: Vector3.Zero(),
+    rotation: Quaternion.Identity(),
+  })
+  VirtualCamera.create(lockCamEntity, {
+    defaultTransition: { transitionMode: VirtualCamera.Transition.Time(0) },
+  })
+  editorEntities.add(lockCamEntity)
+}
+
+export function lockCamera() {
+  if (state.editorCamActive || lockCamEntity === undefined) return
+  if (!Transform.has(engine.CameraEntity)) return
+  const camT = Transform.get(engine.CameraEntity)
+  const lockT = Transform.getMutable(lockCamEntity)
+  copyVec3(lockT.position, camT.position)
+  copyQuat(lockT.rotation, camT.rotation)
+  MainCamera.getMutable(engine.CameraEntity).virtualCameraEntity = lockCamEntity
+}
+
+export function unlockCamera() {
+  if (state.editorCamActive || lockCamEntity === undefined) return
+  MainCamera.getMutable(engine.CameraEntity).virtualCameraEntity = undefined
+}
+
+// ============================================================
+// Active Camera Helper
+// ============================================================
+
+/** Returns the active camera transform -- editor cam when active, otherwise player camera. */
+export function getActiveCameraTransform() {
+  if (state.editorCamActive && editorCamEntity !== undefined && Transform.has(editorCamEntity)) {
+    return Transform.get(editorCamEntity)
+  }
+  return Transform.get(engine.CameraEntity)
+}