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

package/README.md

@@ -26,7 +26,7 @@ The result: **more creators building more scenes, faster.**
 ## Features
 
 - **Branded header** — on startup, displays a block-character "Decentraland" ASCII art banner with version and working directory. Falls back to a compact text header on narrow terminals
-- **Multi-provider LLM support** — works with Claude, OpenAI, Google, Ollama (free/local), OpenRouter, and more
+- **Multi-provider LLM support** — works with Claude, OpenAI, Google, OpenRouter, and more
 - **Scene-aware** — automatically detects your project's `scene.json`, SDK version, and entry points
 - **20 built-in skills** — scaffolding, 3D models, interactivity, UI, animations, multiplayer, authoritative server, audio/video, deployment (Genesis City & Worlds), optimization, camera control, lighting, player/avatar, NFT/blockchain, advanced rendering, advanced input, scene runtime, visual feedback, game design
 - **Integrated commands** — `/init` to scaffold, `/preview` to launch the dev server, `/tasks` to manage running processes, `/review` to audit code
@@ -99,6 +99,7 @@ This uses the open [skills](https://github.com/vercel-labs/skills) CLI to copy S
 | `/deploy` | Deploy the scene to Genesis City or a World (auto-detects from scene.json) |
 | `/tasks` | Interactively manage running background processes (preview server, etc.) |
 | `/review` | Review scene code for quality, performance, and SDK7 best practices |
+| `/save-editor` | Apply pending visual editor changes to scene source code |
 | `/explain <concept>` | Explain a Decentraland SDK7 concept (e.g., `/explain tweens`) |
 
 The agent also has a `screenshot` tool it can call automatically to see the running preview. On first use it asks for your permission to open a headless browser. The browser stays open for the entire session — no repeated logins.
@@ -129,6 +130,7 @@ OpenDCL loads domain-specific skills on demand based on what you're asking:
 | `scene-runtime` | Async tasks, fetch, timers, realm info, restricted actions, testing |
 | `visual-feedback` | Use the screenshot tool to see your scene, verify changes, iterate visually |
 | `game-design` | Plan game architecture, scene limits, state management, MVP planning |
+| `editor-gizmo` | Use a visual in-scene editor with translate/rotate gizmos |
 
 ## How It Works
 
@@ -150,7 +152,7 @@ opendcl/
 │   └── scene-context.ts      # Scene detection & context formatting
 ├── extensions/
 │   ├── dcl-context.ts        # Auto-detect scene, inject metadata
-│   ├── dcl-init.ts           # /init command
+│   ├── dcl-init.ts           # /init command + editor setup
 │   ├── dcl-preview.ts        # /preview command
 │   ├── dcl-deploy.ts         # /deploy command
 │   ├── dcl-setup.ts          # /setup command (cloud API provider config)
@@ -159,6 +161,7 @@ opendcl/
 │   ├── dcl-validate.ts       # Post-write TypeScript validation
 │   ├── dcl-screenshot.ts      # screenshot tool (headless Chrome, persistent browser)
 │   ├── dcl-tasks.ts          # /tasks command (process manager)
+│   ├── dcl-editor-save.ts    # /save-editor command (apply visual editor changes)
 │   ├── process-registry.ts   # Shared background process registry
 │   └── permissions/           # Permission gate for dangerous operations
 ├── skills/                   # 20 SKILL.md files (domain expertise)
@@ -231,7 +234,6 @@ OpenDCL supports any provider compatible with pi-coding-agent:
 | Anthropic (Claude) | `ANTHROPIC_API_KEY` | Best quality |
 | OpenAI | `OPENAI_API_KEY` | GPT-4o, o1, etc. |
 | Google | `GOOGLE_API_KEY` | Gemini models |
-| Ollama | — | Free, runs locally |
 | OpenRouter | `OPENROUTER_API_KEY` | Access to many models |
 
 Set the environment variable or enter the key on first run. Switch models anytime with `Ctrl+P`.

package/context/sdk7-cheat-sheet.md

@@ -34,6 +34,10 @@ removeEntityWithChildren(engine, entity)
 
 // Components — CRUD
 Transform.create(entity, { position: Vector3.create(8, 1, 8) })
+// ⚠️ NEVER pass undefined values in Transform fields — the SDK serializer crashes
+// reading .x on undefined. If a field is optional, omit the key entirely:
+//   BAD:  Transform.create(e, { position, rotation })  // rotation may be undefined
+//   GOOD: Transform.create(e, rotation ? { position, rotation } : { position })
 const t = Transform.get(entity)           // read-only, throws if missing
 const t = Transform.getMutable(entity)     // mutable reference
 const t = Transform.getOrNull(entity)      // read-only, returns null if missing

package/dist/index.js

@@ -67,10 +67,6 @@ const extensions = headless
         "dcl-asset-path.ts",
         "dcl-screenshot.ts",
     ];
-// Conditionally load dcl-setup-ollama (hidden by default, enable with ENABLE_OLLAMA_SETUP=true)
-if (!headless && process.env.ENABLE_OLLAMA_SETUP === "true") {
-    extensions.push("dcl-setup-ollama.ts");
-}
 for (const ext of extensions) {
     args.push("-e", join(extDir, ext));
 }
@@ -90,14 +86,6 @@ if (!isDev()) {
 }
 // InteractiveMode patches — only needed for terminal UI, skip in headless mode
 if (!headless) {
-    // Suppress pi's generic "No models available" warning — our dcl-setup-ollama
-    // extension shows a more helpful message that mentions /setup-ollama.
-    const _showWarning = InteractiveMode.prototype.showWarning;
-    InteractiveMode.prototype.showWarning = function (msg) {
-        if (msg.startsWith("No models available"))
-            return;
-        _showWarning.call(this, msg);
-    };
     // Suppress pi's "What's New" changelog notification on startup — it shows pi's
     // own version/changes, which confuses OpenDCL users.
     InteractiveMode.prototype.getChangelogForDisplay = function () {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/extensions/dcl-init.ts

@@ -3,24 +3,40 @@
  *
  * Registers the `init` tool (LLM-callable) and `/init` command that scaffolds
  * a new Decentraland scene project using `npx @dcl/sdk-commands init`.
+ * After scaffolding, triggers the editor-gizmo skill to set up the visual editor.
+ * On session start, prompts the user to enable the editor if a scene exists but lacks it.
  */
 
 import type { ExtensionFactory } from "@mariozechner/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import { join } from "node:path";
 import { readFile, writeFile } from "node:fs/promises";
-import { fileExists } from "./scene-utils.js";
+import { fileExists, findSceneRoot } from "./scene-utils.js";
+
+function triggerEditorSkill(pi: { sendMessage(msg: unknown, opts?: unknown): void }) {
+  pi.sendMessage(
+    {
+      customType: "editor-setup",
+      content: "Scene initialized (dependencies not yet installed). Now set up the visual editor by following the editor-gizmo skill.",
+      display: true,
+    },
+    { triggerTurn: true }
+  );
+}
 
 async function initScene(
   cwd: string,
-  pi: { exec(cmd: string, args: string[], opts?: unknown): Promise<{ code: number; stdout: string; stderr: string }> }
+  pi: {
+    exec(cmd: string, args: string[], opts?: unknown): Promise<{ code: number; stdout: string; stderr: string }>;
+    sendMessage(msg: unknown, opts?: unknown): void;
+  }
 ): Promise<{ message: string; isError?: boolean }> {
   if (await fileExists(join(cwd, "scene.json"))) {
     return { message: "A scene.json already exists in this directory. Aborting to prevent overwriting.", isError: true };
   }
 
   try {
-    const result = await pi.exec("npx", ["@dcl/sdk-commands", "init", "--yes"], {
+    const result = await pi.exec("npx", ["@dcl/sdk-commands", "init", "--yes", "--skip-install"], {
       cwd,
       timeout: 180000,
     });
@@ -36,7 +52,23 @@ async function initScene(
       } catch {
         // Non-fatal: scene was still initialized successfully
       }
-      return { message: "Scene initialized and dependencies installed! Use the preview tool to start." };
+
+      // Append OpenDCL build artifacts to .gitignore so they don't get committed.
+      // main.crdt is generated from main-entities.ts at bundle time.
+      try {
+        const ignorePath = join(cwd, ".gitignore");
+        let existing = "";
+        try { existing = await readFile(ignorePath, "utf-8"); } catch {}
+        if (!existing.split(/\r?\n/).includes("main.crdt")) {
+          const sep = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+          await writeFile(ignorePath, existing + sep + "main.crdt\n");
+        }
+      } catch {
+        // Non-fatal: scene still works without .gitignore updates
+      }
+
+      triggerEditorSkill(pi);
+      return { message: "Scene initialized! Setting up visual editor..." };
     } else {
       return { message: `Init failed (exit code ${result.code}): ${result.stderr || result.stdout}`, isError: true };
     }
@@ -50,7 +82,7 @@ const extension: ExtensionFactory = (pi) => {
     name: "init",
     label: "Init Scene",
     description:
-      "Initialize a new Decentraland SDK7 scene. Scaffolds scene.json, package.json, tsconfig.json, and src/index.ts. Use when user wants to create or start a new scene.",
+      "Initialize a new Decentraland SDK7 scene with visual editor. Scaffolds scene.json, package.json, tsconfig.json, src/index.ts, and the __editor/ directory. Use when user wants to create or start a new scene.",
     parameters: Type.Object({}),
     async execute(_id, _params, _signal, _onUpdate, ctx) {
       const result = await initScene(ctx.cwd, pi);
@@ -60,7 +92,7 @@ const extension: ExtensionFactory = (pi) => {
   });
 
   pi.registerCommand("init", {
-    description: "Initialize a new Decentraland scene project in the current directory",
+    description: "Initialize a new Decentraland scene project with visual editor",
     handler: async (_args, ctx) => {
       ctx.ui.notify("Initializing new Decentraland scene...", "info");
       const result = await initScene(ctx.cwd, pi);
@@ -68,6 +100,26 @@ const extension: ExtensionFactory = (pi) => {
       if (!result.isError) await ctx.reload();
     },
   });
+
+  // Prompt on session start if scene exists but editor is not installed
+  let editorPromptShown = false;
+  pi.on("before_agent_start", async (_event, ctx) => {
+    if (editorPromptShown) return;
+    editorPromptShown = true;
+
+    const sceneRoot = await findSceneRoot(ctx.cwd);
+    if (!sceneRoot) return;
+
+    if (await fileExists(join(sceneRoot, "src", "__editor", "state.ts"))) return;
+
+    const enable = await ctx.ui.confirm(
+      "Visual Editor",
+      "Enable the visual editor for this scene?"
+    );
+    if (!enable) return;
+
+    triggerEditorSkill(pi);
+  });
 };
 
 export default extension;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dcl-regenesislabs/opendcl",
-  "version": "0.2.1",
+  "version": "0.2.2-26850672477.commit-99ffd91",
   "description": "AI coding assistant for Decentraland SDK7 scene development",
   "type": "module",
   "bin": {
@@ -63,7 +63,7 @@
     }
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
   "files": [
     "dist/",
@@ -72,5 +72,5 @@
     "prompts/",
     "context/"
   ],
-  "commit": "96d9b973a1059d26e9b7b972add8b62f4ea08dd3"
+  "commit": "99ffd91e623721dc4921ceae1e45d342f4211044"
 }

package/prompts/system.md

@@ -25,26 +25,58 @@ You are **OpenDCL**, an AI coding assistant specialized in Decentraland SDK7 sce
 - 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
+### Authoring Model: Data in `main-entities.ts`, Behavior in `src/`
 
-**Creating an entity with components:**
-```typescript
-import { engine, Transform, MeshRenderer, Material } from '@dcl/sdk/ecs'
-import { Vector3, Color4 } from '@dcl/sdk/math'
+OpenDCL scenes split the source of truth in two:
+
+- **`main-entities.ts`** at the scene root — typed declarative entities keyed by Name, with their data components (Transform, GltfContainer, MeshRenderer, Material, AudioSource, etc.). Compiled to `main.crdt` at build time and preloaded by the engine before `main()` runs.
+- **`src/index.ts`** — behavior only. References entities by Name and attaches systems, pointer events, tweens.
 
-const cube = engine.addEntity()
-Transform.create(cube, { position: Vector3.create(8, 1, 8) })
-MeshRenderer.setBox(cube)
-Material.setPbrMaterial(cube, { albedoColor: Color4.Red() })
+**Adding a declared entity (in `main-entities.ts`):**
+```typescript
+import type { Scene } from '@dcl/sdk/scene-types'
+
+export const scene = {
+  blue_cube: {
+    components: {
+      Transform: { position: { x: 8, y: 1, z: 8 }, rotation: { x: 0, y: 0, z: 0, w: 1 }, scale: { x: 1, y: 1, z: 1 } },
+      MeshRenderer: { mesh: { $case: 'box', box: { uvs: [] } } },
+      Material: { material: { $case: 'pbr', pbr: { albedoColor: { r: 1, g: 0, b: 0, a: 1 } } } },
+    },
+  },
+} satisfies Scene
 ```
 
-**Adding interactivity:**
+**Referencing it in code:**
 ```typescript
-import { pointerEventsSystem, InputAction } from '@dcl/sdk/ecs'
+import { engine, pointerEventsSystem, InputAction } from '@dcl/sdk/ecs'
+import type { scene } from '../main-entities'
 
-pointerEventsSystem.onPointerDown({ entity: cube, opts: { button: InputAction.IA_POINTER, hoverText: 'Click me' } }, () => {
-  // Handle click
-})
+type EntityName = keyof typeof scene
+
+export function main() {
+  const cube = engine.getEntityOrNullByName<EntityName>('blue_cube')
+  if (cube === null) return
+
+  pointerEventsSystem.onPointerDown(
+    { entity: cube, opts: { button: InputAction.IA_POINTER, hoverText: 'Click me' } },
+    () => { /* handle click */ },
+  )
+}
+```
+
+**Rules:**
+- Every declarative entity goes in `main-entities.ts` with a unique Name. The `satisfies Scene` clause keeps literal keys typed for safe references.
+- Parents are referenced by Name (`parent: 'barrel_1'`); the build resolves them.
+- Pure-data components (Transform, GltfContainer, MeshRenderer, MeshCollider, Material, AudioSource, VideoPlayer, TextShape, Animator config, NftShape, Billboard, VisibilityComponent) all live in `main-entities.ts`.
+- Behavior, callbacks, systems, conditional logic stay in `src/`.
+- The `scene` literal must contain only JSON-compatible values — no function calls, no spreads, no comments inside the object.
+
+**Dynamic entities** spawned at runtime (effects, projectiles, runtime markers) still use `engine.addEntity()` and **don't get Names** — they're invisible to the editor and not persisted:
+```typescript
+const explosion = engine.addEntity()
+Transform.create(explosion, { position: Vector3.create(...) })
+GltfContainer.create(explosion, { src: 'models/Explosion.glb' })
 ```
 
 **Systems (per-frame logic):**
@@ -73,10 +105,11 @@ export function setupUi() {
 ```
 scene-project/
 ├── scene.json          # Scene metadata (parcels, title, main entry)
+├── main-entities.ts    # Declarative entities (data) — preloaded into the engine before main() runs
 ├── package.json        # Dependencies (@dcl/sdk)
-├── tsconfig.json       # TypeScript config
+├── tsconfig.json       # TypeScript config (must include main-entities.ts)
 └── src/
-    ├── index.ts        # Main entry point (export function main)
+    ├── index.ts        # Main entry point — references entities by Name, attaches behavior
     └── ui.tsx          # UI components (optional)
 ```
 
@@ -94,19 +127,25 @@ scene-project/
 ## 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, and installs dependencies. Never create these files manually.
-3. After init completes, customize `scene.json` (title, description, parcels) and add the first element to `src/index.ts`. Then offer next steps — don't build the entire scene at once.
+**Do NOT ask the user what they want to build.** Instead, immediately run the `init` tool to scaffold the project — no questions, no menu of options, just init. 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, and installs dependencies. Never create these files manually. After init completes, ask the user what they'd like to do next. Offer small, concrete steps — don't propose building an entire scene at once.
 
 ### Existing Scene
-1. Read scene.json and src/index.ts to understand the project.
+1. Read scene.json, main-entities.ts (if it exists), 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.
+4. When adding a new declarative entity (cube, model, lamp, etc.), edit `main-entities.ts` and reference the new Name from `src/index.ts` if it needs behavior. Don't reach for `engine.addEntity()` in code as a default.
 
 ### Best Practices
+
+**Always declare static / editable entities in `main-entities.ts`** — never via `engine.addEntity()` in `src/index.ts` for things the user might want to move, rotate, or see in the visual editor. Entities declared in `main-entities.ts` are preloaded by the engine before `main()` runs, are visible in the editor's hierarchy panel, and are draggable. Entities created at runtime via `engine.addEntity()` are invisible to the editor and lost when the user reloads.
+
+Use `engine.addEntity()` only for genuinely dynamic things (effects spawned at runtime, projectiles, throwaway markers). Those entities should NOT have a `Name` component — Naming is the marker for "this entity belongs in main-entities.ts."
+
+When the user asks to add a barrel, a tree, a prop, a model — that goes in `main-entities.ts` first, and code references it via `engine.getEntityOrNullByName<EntityName>(name)`. Don't fall back to the old `addEntity + Transform.create + GltfContainer.create` pattern in code unless the user explicitly asks for runtime spawning.
+
 - 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' })`.
+- For positions/rotations inside `main-entities.ts`, use plain object literals (`{ x: 8, y: 1, z: 8 }`), not `Vector3.create()` — the `scene` literal must stay JSON-compatible. In `src/index.ts` (behavior code), `Vector3.create()` and `Quaternion.fromEulerDegrees()` are fine.
+- For 3D models, declare `GltfContainer: { src: 'models/myModel.glb' }` inside the entity's `components` block in `main-entities.ts`.
 - `GltfContainer` only works with **local files** — never use external URLs for the `src` field. Always download models into the scene's `models/` directory first.
 - Place `.glb` files in a `models/` directory, textures in `images/`.
 - Don't start the preview server automatically after writing code. The user will type `/preview` when ready.
@@ -115,39 +154,30 @@ scene-project/
   - Search with `grep -i "keyword" skills/add-3d-models/references/model-catalog.md`, fetch the preview thumbnail to confirm, then download with curl.
   - Download matching models with `curl -o models/filename.glb "URL"` before referencing them in code.
 
-### Visual Iteration Workflow
-
-When the preview server is running, **proactively use the `screenshot` tool after making scene changes**. Don't wait for the user to check — verify your own work:
-
-1. Write code or modify the scene.
-2. Use `screenshot` (with a `wait` of ~2000ms for hot-reload) to see the result.
-3. Describe what you see honestly — what's working, what's missing, what looks wrong.
-4. If something is off, fix it and screenshot again.
+### Visual Feedback
 
-This way the user gets a working scene without having to open a browser and report issues back to you.
+When the preview server is running, use the `screenshot` tool **after completing code changes** to verify the result. Do NOT use screenshots to explore or navigate the scene.
 
-The screenshot tool supports actions before capture — move around (moveForward, moveLeft, etc.), look around (lookLeft, lookUp), click objects, press keys. Use these to explore from different angles or test interactivity.
+1. Make all code changes first.
+2. Take **one** screenshot (with `wait: 2000` for hot-reload) to verify.
+3. Describe what you see honestly — what works, what's wrong.
+4. If something is off, fix the code and take **one more** screenshot to confirm.
 
-The browser stays open between calls — only the first screenshot takes ~15s (launch + enter scene). Subsequent ones are instant.
+Keep it to **1-2 screenshots per task**. Each screenshot consumes significant tokens. Do not wander around taking multiple screenshots to "explore" — that wastes the user's budget.
 
-If the user asks you to iterate autonomously (e.g., "keep going until it looks right"):
-1. Make code changes.
-2. Wait for hot reload (~2s), then take a screenshot.
-3. Analyze whether the result matches the goal.
-4. If not, make targeted fixes and screenshot again.
-5. Repeat (up to 5 iterations) until done.
+The screenshot tool supports actions before capture (move, look, click, key press), but use these sparingly and only when needed to verify a specific thing (e.g., moving to see an object you just placed behind the spawn point).
 
 ## 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
-- `screenshot` — Capture a screenshot of the running preview. Supports movement and interaction actions before capture.
+- `screenshot` — Capture a screenshot of the running preview to verify code changes. Limit to 1-2 per task.
 - `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`
+Additional user-only commands: `/review`, `/explain`, `/setup`
 
 ## Pacing