3395b643

• A file picked or dropped from disk arrives as its real absolute path — no copy, no base64 round-trip, no size cap. Read it in place; do not ask the user to re-paste its contents or to move it into the project. A pasted (clipboard) image has no path, so the app writes it to a temp file and hands you that path instead.
• Any file type is accepted. The app classifies it only for the chip icon:

  image

  (png, jpg, jpeg, gif, webp, bmp, svg, avif),

  model

  (glb, gltf),

  audio

  (mp3, wav, ogg, m4a, flac),

  file

  for everything else.
• This is the natural way to hand over a reference image or a GLB. A dropped

  .glb

  is a model the user wants in the scene: it is still outside the project, so copy it under

  assets/Models/

  before referencing it from

  GltfContainer

  (see add-3d-models for the bounding-box and collider audit). A reference image is usually art direction for a UI or material, not a file to import.
• A prompt may arrive with attachments and no text at all — the attachment is the request. Ask what to do with it rather than guessing.

assets/scene/main.composite

main.crdt

scene.json

• The editor owns those files. It regenerates

  main.composite

  wholesale from its in-memory engine on every autosave (~100 ms after any editor transaction) and never re-reads the file from disk. A hand edit to an open scene is silently lost; there is no error.
• The tools do the bookkeeping the file workflow makes you do by hand:

  inspector::Nodes

  registration,

  core-schema::Name

  ,

  inspector::TransformConfig

  ,

  entity-names.ts

  , entity-id allocation,

  jsonSchema

  on non-core components.
• Every mutation is undoable by the user (Ctrl+Z / the assistant's Undo AI changes button). A file edit is not.

1. Tools present and answering (

   get_selection

   or

   scene_state

   returns) → use them for every entity/component/settings change. Read the composite from disk only as a read-only cross-check.
2. Tools present but failing (

   No editor window is open.

   , connection refused,

   401

   ) → the Creator Hub is closed, was restarted (URL and token rotate per launch), or no scene is open. Say so and ask the user to open the scene in the Creator Hub (or re-copy the connection snippet). Do not fall back to editing the file silently.
3. Tools absent, but the user has the Creator Hub → tell them the MCP is the safe route and point them at

   reference/connect.md

   . Hand-edit the file only if they decline, and only with the scene closed in the Creator Hub (the composites skill's edit-mode rules then apply in full).
4. No Creator Hub in play (CLI-only project, CI) → the composites skill's file workflow applies.

src/**

assets/Scripts/*.tsx

attach_script

assets/Models/

assets/Images/

create_entity

set_component

search_catalog

• Lights — the catalog has Spotlight and Point Light Smart Items (category

  lights

  ) that bundle a real GLB model, a pre-configured

  LightSource

  component, and built-in Turn On / Turn Off / Toggle actions. Manually creating a

  LightSource

  entity misses the visual model, inspector integration, and action wiring.
• Interactive furniture — doors, chairs, platforms, chests, buttons, levers, etc.
• Media — screens, image displays, NFT frames.
• Triggers — trigger areas, click triggers. The

  utils

  category has exactly one entry named "Trigger Area" (

  e9fa0eab-44de-4efe-af77-a71171a1a73f

  ), a script-based item: an invisible box or sphere the user places and resizes, with a control that seeds the AI-assistant composer with a prompt describing what should happen on enter/leave. The older non-script item of the same name (

  1ab2733f-1782-4521-9eda-6aa8ad684277

  ) and the interim label "Trigger Area (Script)" were both removed in creator-hub

  e43441b5

  — do not search for either.

place_smart_item

set_component

• Downloads the item's GLB files and resolves

  asset-packs::Placeholder

  with the real on-disk path (e.g.

  assets/asset-packs/spotlight/spotlight.glb

  ).
• Sets up

  asset-packs::Script

  ,

  asset-packs::Actions

  , and

  inspector::Config

  components so the item works in the Creator Hub UI with configurable actions and triggers.
• Registers the entity in

  inspector::Nodes

  automatically.

062ed0a2

inspector::Config

.png

.jpg

.jpeg

37460a1e-affc-4f87-b725-118cc11d86fc

Material

src

+0.5 m

.mp3

.ogg

.wav

5c8b4646-6ec0-41a0-8e9b-415a58728a9e

AudioSource.audioClipUrl

.mp4

0201653b-bd38-48af-b9ef-a902a7e8bc9c

VideoPlayer.src

asset-packs::VideoScreen.defaultURL

src

defaultURL

src

.glb

.gltf

place_smart_item

set_component

get_project_info

get_scene_metrics

scene_state

get_selection

• Catalog item →

  search_catalog

  then

  place_smart_item

  . Files land in

  assets/asset-packs/<pkg>/

  automatically.
• Architecture (rooms, corridors, doorways, anything the avatar walks through or into) → size the envelope for the third-person camera before placing; realistic dimensions read cramped in-world. The dimensions are in add-3d-models → "RULE: Scale interiors up for the third-person camera".
• Model the user already has, or one you authored → put the GLB under

  assets/Models/

  (see the add-3d-models skill for Blender authoring and the bounding-box audit), then

  create_entity

  (with a

  name

  ),

  set_component

  Transform

  (

  {position:{x,y,z}, rotation:{x,y,z,w}, scale:{x,y,z}}

  ), and

  set_component

  core::GltfContainer

  (

  {src, visibleMeshesCollisionMask, invisibleMeshesCollisionMask}

  — mask rules and the animation/collider checks from add-3d-models still apply; add

  core::Animator

  when the GLB has clips).
• Lights →

  search_catalog

  with category

  lights

  to find Spotlight and Point Light Smart Items, then

  place_smart_item

  . These include the light model,

  LightSource

  , and toggle actions. Only create a bare

  LightSource

  entity manually when you need an invisible light source or non-standard parameters -- see lighting-environment for the full

  LightSource

  API and the Smart Item rule.
• Behaviour on it → a Smart Item if one fits (

  search_catalog

  first), otherwise write a script under

  assets/Scripts/

  and

  attach_script

  (rules in script-components), or reference the entity by name from

  src/

  code (

  engine.getEntityOrNullByName

  ).

set_component

entity_detail

asset-packs::Script

layout

attach_script

scene_state

get_scene_metrics

editor_screenshot

launch_preview

explorer_*

explorer_*

claude mcp add

creator-hub

stop_preview

remove_entity

set_component

main.composite

assets/scene/main.composite

[UtilityProcess] Running "sdk-commands start --port <n> --no-browser --no-client --data-layer"

main/src/modules/bevy-realm.ts

node_modules/@dcl/sdk-commands

assets/scene/main.composite

ls -l

stat

stat -f '%m %N' "assets/scene/main.composite"   # macOS; coreutils: stat -c '%Y %n'

(Get-Item "assets\scene\main.composite").LastWriteTime   # Windows (PowerShell)

• set_component

  ,

  create_entity

  ,

  place_smart_item

  and friends all still return success.

• scene_state

  /

  entity_detail

  keep returning the pre-crash values — a read-back "confirming" your write is confirming the old snapshot.

• editor_screenshot

  returns a blank image.

• get_scene_metrics

  returned all zeros with an empty

  entitiesOutOfBoundaries

  — but do not use that as the tell — under the Bevy renderer those fields are hardcoded zeros anyway (see Gotchas). The mtime check is the reliable one.

~/Library/Logs/creator-hub/main.log

%APPDATA%\creator-hub\logs\main.log

Exiting "sdk-commands start … --data-layer" … exit code=1

TypeError: Cannot read properties of undefined (reading 'deserialize')

node_modules/@dcl/inspector/dist/tooling-entrypoint.js

Object.deserialize

updateFromCrdt

receiveMessages

update

set_scene_settings

spawnPoints

[min, max]

place_smart_item

stop_preview

main/src/modules/explorer-gateway.ts

treeKill

sdk-commands start --explorer-alpha --hub … --mcp --mcp-port <n>

[UtilityProcess] Killing process "…"

{ok: true}

open decentraland://…

preview_status

running

child.alive()

launch_preview

[Gateway] launching preview … with MCP on :53880

--mcp-port

The preview launched but its MCP server never answered. The Explorer may still be starting, or this build has no MCP support. (TypeError: fetch failed)

preview_status

launch_preview

pgrep -fl '[M]acOS/Explorer'    # the Explorer app itself
pgrep -fl '[d]cl_watchdog'      # its watchdog, from /Applications/Decentraland.app

pgrep -f

pkill -f

bash -c "<command>"

pkill

[d]cl_watchdog

preview_status

launch_preview

pkill -f '[d]cl_watchdog'; pkill -f '[D]ecentraland.app/Contents/MacOS/Explorer'
for i in $(seq 1 30); do pgrep -f '[M]acOS/Explorer' >/dev/null || break; sleep 1; done   # wait up to 30 s

Decentraland.exe

dcl_watchdog.exe

Get-Process Decentraland, dcl_watchdog -ErrorAction SilentlyContinue        # is either alive?
Stop-Process -Name dcl_watchdog -Force -ErrorAction SilentlyContinue        # watchdog first: it reacts to a non-zero Explorer exit
Stop-Process -Name Decentraland -Force -ErrorAction SilentlyContinue
Wait-Process -Name Decentraland -Timeout 30 -ErrorAction SilentlyContinue   # confirm it exited

explorer_reload_scene

@dcl/sdk-commands

no-cache

mtime

launch_preview

explorer_reload_scene

src/

GltfContainer.src

explorer_reload_scene

explorer_get_scene_logs

.dclignore

packages/creator-hub/main/src/modules/skills.ts

• It downloads

  decentraland/sdk-skills

  main into a per-user cache (keyed on the upstream commit SHA plus the app version, swapped atomically, tolerant of being offline).
• It symlinks that cache into the open scene as

  .claude/skills

  and

  .agents/skills

  . Links the app created are added to a

  .gitignore

  . If the user already has a real

  skills

  directory, it links each skill in individually and skips names the user already owns.

• If the Creator Hub currently has the scene open, the app-managed

  .claude/skills

  /

  .agents/skills

  symlinks already exist in the scene folder, so a Claude Code session started in that folder picks them up. Do not duplicate them.
• Otherwise (a different working directory, the scene not open in the Creator Hub, or a client that reads skills from elsewhere), install them the normal way, from the scene folder or the user's skills root:
  bash

  npx skills add decentraland/sdk-skills --all

  Re-run the same command to update;

  npx skills update

  only refreshes skills already present and misses newly added ones. See the repo README for per-skill installs.

create-scene

deploy-scene

deploy-worlds

migrate-sdk6-to-sdk7

• A denylisted skill that has supporting files (

  create-scene

  ,

  migrate-sdk6-to-sdk7

  ) ships without its

  SKILL.md

  — its

  references/

  stay resolvable from other skills' relative paths, but the skill itself can never trigger.
• A denylisted skill whose directory holds nothing but

  SKILL.md

  (

  deploy-scene

  ,

  deploy-worlds

  ) is skipped entirely.

npx skills add

• URL and token rotate on every Creator Hub launch. A config that worked yesterday gives

  ECONNREFUSED

  or

  401

  today; the fix is re-copying the snippet from Settings, not retrying.
• One open project at a time. The server operates on the scene open in the single editor window. Mutation tools answer

  No editor window is open.

  when the user is on the scene list.
• Disk-read tools may say

  No scene is open.

  from an external client even though the scene is visibly open: as of the initial release (creator-hub

  217e2f9f

  , PR #1499) the project directory is bound to

  get_project_info

  /

  scene_state

  /

  entity_detail

  when the embedded assistant runs a turn. Everything routed through the editor (

  get_selection

  ,

  get_scene_metrics

  ,

  get_scene_settings

  , all mutations,

  place_smart_item

  ) works regardless. Workaround: read

  scene.json

  and

  assets/scene/main.composite

  from disk read-only for the roster, then mutate through the tools.
• Read tools trail the engine by one autosave (~100 ms). The mutation tools already wait it out; only matters if the user is dragging things while you read.

• scene_state

  caps at 200 entities. For big scenes filter by name via

  entity_detail

  or read the composite from disk.
• Skill denylist inside the Creator Hub. The app links

  decentraland/sdk-skills

  into the scene as

  .claude/skills

  /

  .agents/skills

  , but drops the

  SKILL.md

  of

  create-scene

  ,

  deploy-scene

  ,

  deploy-worlds

  , and

  migrate-sdk6-to-sdk7

  : scaffolding, publishing, and SDK6 migration are the app's own flows there. Their reference files still resolve for cross-links.
• The Explorer

  --mcp

  preview checkbox is a different server. Enable MCP Server lives in the Play Options popover (the dropdown arrow on the editor header's Play button), in the flyout that opens when you hover the Desktop Client row. It launches the Explorer with its own MCP on port 8123 (the unity-explorer-mcp skill). The Creator Hub MCP described here is the editor's server; when it is connected, use its

  launch_preview

  instead of that checkbox.
• One Ctrl+Z = one of your operations, not one component write. Since creator-hub

  fdc384b5

  a whole synchronous change burst commits as a single undo transaction (the old 200-operation batch cap used to split a big change across several entries, so one Ctrl+Z left orphaned entities behind). A multi-entity op — placing a composite Smart Item, a scripted item with children — is now one entry, and undoing an add removes the entity from the Bevy viewport too. Still describe your changes to the user in the units they will undo them in.
• Scene audio can be muted in the editor, but only under Bevy. The viewport toolbar has a speaker toggle (Mute scene audio / Unmute scene audio) that forwards every

  AudioSource

  /

  AudioStream

  to the renderer at volume 0; the state survives a reload. It is absent under the Babylon renderer, which does not play scene audio at all. So "I can't hear the sound you added" is not evidence the component is wrong — check the renderer and the toggle first, and note that an authored

  volume

  is not what the Bevy viewport is playing while mute is on.

• get_scene_metrics

  reports nothing useful under the Bevy renderer. Verified in

  packages/inspector/src/lib/renderer/bevy/BevyRenderer.ts

  :

  getSceneMetrics()

  returns

  {triangles: 0, bodies: 0, materials: 0, textures: 0}

  and

  getEntitiesOutsideLayout()

  returns

  []

  , both hardcoded ("No renderer to introspect yet — report zeros"). The limits are still real, and

  entities

  is derived from the Nodes tree rather than the renderer, but all-zero content metrics and an empty

  entitiesOutOfBoundaries

  mean "Bevy", not "empty scene" and not "problem" — do not read a budget or an out-of-bounds verdict out of them. Under Babylon they are real:

  computeEntitiesOutsideLayout

  tests each entity's bounding mesh against the layout, so it does catch oversized geometry there. For a trustworthy budget either way,

  launch_preview

  and use

  explorer_get_scene_content_stats

  .

• asset-packs::Placeholder

  src

  needs a resolved file path, not a template variable. The catalog stores paths with

  {assetPath}/model.glb

  as a template; setting that string literally via

  set_component

  produces an invisible or broken gizmo because the engine cannot resolve the variable.

  place_smart_item

  resolves the path automatically (e.g. to

  assets/asset-packs/spotlight/spotlight.glb

  ). If you must set

  Placeholder

  manually, use the real on-disk path to the GLB file.