@relu-interactives/spatial-ecs 0.2.17 → 0.2.20

package/dist/systems/index.cjs

@@ -1418,6 +1418,17 @@ var _InstancedMeshComponent = class _InstancedMeshComponent extends Component {
 __name(_InstancedMeshComponent, "InstancedMeshComponent");
 var InstancedMeshComponent = _InstancedMeshComponent;
 
+// core/components/InstanceSlotComponent.ts
+var _InstanceSlotComponent = class _InstanceSlotComponent extends Component {
+  constructor(groupEntityId, slotIndex) {
+    super();
+    this.groupEntityId = groupEntityId;
+    this.slotIndex = slotIndex;
+  }
+};
+__name(_InstanceSlotComponent, "InstanceSlotComponent");
+var InstanceSlotComponent = _InstanceSlotComponent;
+
 // core/components/Physics.ts
 var DEFAULT_RIGIDBODY_STATE = {
   enabled: true,
@@ -1605,6 +1616,34 @@ var _PhysicsComponent = class _PhysicsComponent extends Component {
 };
 __name(_PhysicsComponent, "PhysicsComponent");
 var PhysicsComponent = _PhysicsComponent;
+
+// core/components/Image.ts
+var _ImageComponent = class _ImageComponent extends Component {
+  constructor(path, width = 1, height = 1) {
+    super();
+    this.path = path;
+    this.width = width;
+    this.height = height;
+    this.texture = null;
+    this.object = null;
+  }
+};
+__name(_ImageComponent, "ImageComponent");
+var ImageComponent = _ImageComponent;
+
+// core/components/ImageTarget.ts
+var _ImageTarget = class _ImageTarget extends Component {
+  constructor(options, texture, object) {
+    super();
+    this.targets = options?.targets ?? [];
+    this.compiledTargetUrl = options?.compiledTargetUrl;
+    this.compiledTargetDir = options?.compiledTargetDir;
+    this.texture = texture ?? null;
+    this.object = object ?? null;
+  }
+};
+__name(_ImageTarget, "ImageTarget");
+var ImageTarget = _ImageTarget;
 function toHexColor(value) {
   return `#${value.getHexString()}`;
 }
@@ -1733,8 +1772,23 @@ var _MaterialComponent = class _MaterialComponent extends Component {
     this.materials = [];
     this.material = null;
     this.values = [];
+    this.assetRefs = [];
     this.setMaterials(materialOrMaterials);
   }
+  /** Link/unlink a slot to a material asset URL (editor bookkeeping only). */
+  setAssetRef(index, url) {
+    if (index < 0) {
+      return;
+    }
+    while (this.assetRefs.length <= index) {
+      this.assetRefs.push(null);
+    }
+    this.assetRefs[index] = url;
+  }
+  /** The material-asset URL a slot is linked to, or null when local. */
+  getAssetRef(index) {
+    return this.assetRefs[index] ?? null;
+  }
   setMaterials(materialOrMaterials = []) {
     this.materials = Array.isArray(materialOrMaterials) ? materialOrMaterials.filter(Boolean) : materialOrMaterials ? [materialOrMaterials] : [];
     this.material = this.materials[0] ?? null;
@@ -1789,6 +1843,37 @@ var _ModelComponent = class _ModelComponent extends Component {
 __name(_ModelComponent, "ModelComponent");
 var ModelComponent = _ModelComponent;
 
+// core/components/Name.ts
+var _Name = class _Name extends Component {
+  constructor(value) {
+    super();
+    this.value = value;
+  }
+};
+__name(_Name, "Name");
+var Name = _Name;
+
+// core/components/PrefabInstance.ts
+var _PrefabInstance = class _PrefabInstance extends Component {
+  constructor(url, overrides = []) {
+    super();
+    this.url = url;
+    this.overrides = overrides;
+  }
+};
+__name(_PrefabInstance, "PrefabInstance");
+var PrefabInstance = _PrefabInstance;
+
+// core/components/PrefabNode.ts
+var _PrefabNode = class _PrefabNode extends Component {
+  constructor(nodeId) {
+    super();
+    this.nodeId = nodeId;
+  }
+};
+__name(_PrefabNode, "PrefabNode");
+var PrefabNode = _PrefabNode;
+
 // core/components/ScriptComponent.ts
 var _ScriptComponent = class _ScriptComponent extends Component {
   constructor(entries = []) {
@@ -1820,6 +1905,30 @@ var _ScriptComponent = class _ScriptComponent extends Component {
 __name(_ScriptComponent, "ScriptComponent");
 var ScriptComponent = _ScriptComponent;
 
+// core/components/Selectable.ts
+var _Selectable = class _Selectable extends Component {
+  constructor(enabled = true) {
+    super();
+    this.enabled = enabled;
+  }
+};
+__name(_Selectable, "Selectable");
+var Selectable = _Selectable;
+
+// core/components/Sprite.ts
+var _SpriteComponent = class _SpriteComponent extends Component {
+  constructor(path, width = 1, height = 1) {
+    super();
+    this.path = path;
+    this.width = width;
+    this.height = height;
+    this.texture = null;
+    this.object = null;
+  }
+};
+__name(_SpriteComponent, "SpriteComponent");
+var SpriteComponent = _SpriteComponent;
+
 // core/components/Video.ts
 var DEFAULT_VIDEO_OPTIONS = {
   autoplay: false,
@@ -4518,6 +4627,1235 @@ var _RenderSystem = class _RenderSystem {
 };
 __name(_RenderSystem, "RenderSystem");
 var RenderSystem = _RenderSystem;
+
+// core/prefab/collectEntitySubtree.ts
+function collectEntitySubtree(world, rootIds) {
+  const childrenByParent = /* @__PURE__ */ new Map();
+  for (const entityId of world.query(ParentId)) {
+    const parentId = world.getComponent(entityId, ParentId)?.value;
+    if (parentId === null || parentId === void 0) {
+      continue;
+    }
+    const siblings = childrenByParent.get(parentId);
+    if (siblings) {
+      siblings.push(entityId);
+    } else {
+      childrenByParent.set(parentId, [entityId]);
+    }
+  }
+  const ordered = [];
+  const seen = /* @__PURE__ */ new Set();
+  const queue = [...rootIds];
+  while (queue.length > 0) {
+    const entityId = queue.shift();
+    if (seen.has(entityId)) {
+      continue;
+    }
+    seen.add(entityId);
+    ordered.push(entityId);
+    const children = childrenByParent.get(entityId);
+    if (children) {
+      queue.push(...children.sort((a, b) => a - b));
+    }
+  }
+  return ordered;
+}
+__name(collectEntitySubtree, "collectEntitySubtree");
+
+// core/hydration/readers.ts
+function asRecord3(value) {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  return value;
+}
+__name(asRecord3, "asRecord");
+function readString(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  const record = asRecord3(value);
+  if (!record) {
+    return null;
+  }
+  return typeof record.value === "string" ? record.value : null;
+}
+__name(readString, "readString");
+function readTransform(value) {
+  const record = asRecord3(value);
+  if (!record) {
+    return void 0;
+  }
+  const position = asRecord3(record.position);
+  const rotation = asRecord3(record.rotation);
+  const scale = asRecord3(record.scale);
+  return {
+    position: position ? {
+      x: typeof position.x === "number" ? position.x : void 0,
+      y: typeof position.y === "number" ? position.y : void 0,
+      z: typeof position.z === "number" ? position.z : void 0
+    } : void 0,
+    rotation: rotation ? {
+      x: typeof rotation.x === "number" ? rotation.x : void 0,
+      y: typeof rotation.y === "number" ? rotation.y : void 0,
+      z: typeof rotation.z === "number" ? rotation.z : void 0
+    } : void 0,
+    scale: scale ? {
+      x: typeof scale.x === "number" ? scale.x : void 0,
+      y: typeof scale.y === "number" ? scale.y : void 0,
+      z: typeof scale.z === "number" ? scale.z : void 0
+    } : void 0
+  };
+}
+__name(readTransform, "readTransform");
+function readByComponent(components, componentName) {
+  const component = components.find((entry) => entry.component === componentName);
+  const map = /* @__PURE__ */ new Map();
+  if (!component) {
+    return map;
+  }
+  for (const entry of component.entries) {
+    map.set(entry.entityId, entry.value);
+  }
+  return map;
+}
+__name(readByComponent, "readByComponent");
+function readBoolean(value) {
+  return typeof value === "boolean" ? value : void 0;
+}
+__name(readBoolean, "readBoolean");
+function readNumber(value) {
+  return typeof value === "number" ? value : void 0;
+}
+__name(readNumber, "readNumber");
+
+// core/hydration/componentValues.ts
+function buildComponentValueMaps(snapshot) {
+  return {
+    object3DRefValues: readByComponent(snapshot.components, "Object3DRef"),
+    nameValues: readByComponent(snapshot.components, "Name"),
+    transformValues: readByComponent(snapshot.components, "TransformComponent"),
+    modelValues: readByComponent(snapshot.components, "ModelComponent"),
+    imageValues: readByComponent(snapshot.components, "ImageComponent"),
+    spriteValues: readByComponent(snapshot.components, "SpriteComponent"),
+    videoValues: readByComponent(snapshot.components, "VideoComponent"),
+    cameraValues: readByComponent(snapshot.components, "CameraComponent"),
+    environmentValues: readByComponent(snapshot.components, "Environment"),
+    postprocessingValues: readByComponent(snapshot.components, "Postprocessing"),
+    audioValues: readByComponent(snapshot.components, "AudioComponent"),
+    imageTargetValues: readByComponent(snapshot.components, "ImageTarget"),
+    lightValues: readByComponent(snapshot.components, "LightComponent"),
+    materialValues: readByComponent(snapshot.components, "MaterialComponent"),
+    meshGeometryValues: readByComponent(snapshot.components, "MeshGeometryComponent"),
+    selectableValues: readByComponent(snapshot.components, "Selectable"),
+    physicsValues: readByComponent(snapshot.components, "PhysicsComponent"),
+    animationValues: readByComponent(snapshot.components, "AnimationComponent"),
+    imageTargetAnchorValues: readByComponent(snapshot.components, "ImageTargetAnchor"),
+    scriptValues: readByComponent(snapshot.components, "ScriptComponent"),
+    instancedMeshValues: readByComponent(snapshot.components, "InstancedMeshComponent"),
+    instanceSlotValues: readByComponent(snapshot.components, "InstanceSlotComponent"),
+    prefabNodeValues: readByComponent(snapshot.components, "PrefabNode"),
+    prefabInstanceValues: readByComponent(snapshot.components, "PrefabInstance")
+  };
+}
+__name(buildComponentValueMaps, "buildComponentValueMaps");
+
+// core/hydration/parentLinks.ts
+function applyParentLinks(snapshot, idMap, objectManagementSystem, world) {
+  const parentValues = readByComponent(snapshot.components, "ParentId");
+  for (const [sourceEntityId, parentValue] of parentValues.entries()) {
+    const targetEntityId = idMap.get(sourceEntityId);
+    if (targetEntityId === void 0) {
+      continue;
+    }
+    const parentRecord = asRecord3(parentValue);
+    const sourceParentId = parentRecord && typeof parentRecord.value === "number" ? parentRecord.value : null;
+    if (sourceParentId === null) {
+      objectManagementSystem.setParent(world, targetEntityId, null, {
+        preserveWorldTransform: false
+      });
+      continue;
+    }
+    const mappedParentId = idMap.get(sourceParentId);
+    objectManagementSystem.setParent(world, targetEntityId, mappedParentId ?? null, {
+      preserveWorldTransform: false
+    });
+  }
+}
+__name(applyParentLinks, "applyParentLinks");
+
+// core/hydration/postCreateComponents.ts
+function remapEntityRefsInScriptData(data, idMap) {
+  const result = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      const v = value;
+      if (v.type === "entity" && typeof v.value === "number") {
+        result[key] = { ...v, value: idMap.get(v.value) ?? v.value };
+      } else if (v.type === "component" && v.value !== null && typeof v.value === "object" && !Array.isArray(v.value) && typeof v.value.entityId === "number") {
+        const ref = v.value;
+        result[key] = {
+          ...v,
+          value: { ...ref, entityId: idMap.get(ref.entityId) ?? ref.entityId }
+        };
+      } else {
+        result[key] = value;
+      }
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+__name(remapEntityRefsInScriptData, "remapEntityRefsInScriptData");
+function restorePostCreateComponents(world, objectManagementSystem, targetEntityId, sourceEntityId, entityType, values, idMap) {
+  const objectRef = world.getComponent(targetEntityId, Object3DRef)?.object ?? null;
+  const sourceAudio = asRecord3(values.audioValues.get(sourceEntityId));
+  if (sourceAudio && entityType !== "audio") {
+    const sourceOptions = asRecord3(sourceAudio.options) ?? {};
+    objectManagementSystem.createComponentNow(
+      "audio",
+      world,
+      targetEntityId,
+      typeof sourceAudio.path === "string" ? sourceAudio.path : "",
+      sourceOptions,
+      {
+        object: objectRef,
+        listener: objectManagementSystem.getOrCreateAudioListener(),
+        isEditor: objectManagementSystem.isEditorMode()
+      }
+    );
+  }
+  const sourceImageTarget = asRecord3(values.imageTargetValues.get(sourceEntityId));
+  if (sourceImageTarget && entityType !== "imageTarget") {
+    objectManagementSystem.createComponentNow(
+      "imageTarget",
+      world,
+      targetEntityId,
+      {
+        targets: Array.isArray(sourceImageTarget.targets) ? sourceImageTarget.targets : [],
+        compiledTargetUrl: typeof sourceImageTarget.compiledTargetUrl === "string" ? sourceImageTarget.compiledTargetUrl : void 0,
+        compiledTargetDir: typeof sourceImageTarget.compiledTargetDir === "string" ? sourceImageTarget.compiledTargetDir : void 0
+      }
+    );
+  }
+  const sourceImageTargetAnchor = asRecord3(values.imageTargetAnchorValues.get(sourceEntityId));
+  if (sourceImageTargetAnchor) {
+    const mappedTargetId = typeof sourceImageTargetAnchor.targetId === "number" && Number.isFinite(sourceImageTargetAnchor.targetId) ? sourceImageTargetAnchor.targetId : null;
+    objectManagementSystem.createComponentNow("imageTargetAnchor", world, targetEntityId, {
+      targetId: mappedTargetId,
+      targetUrl: typeof sourceImageTargetAnchor.targetUrl === "string" ? sourceImageTargetAnchor.targetUrl : void 0
+    });
+  }
+  const sourceScript = asRecord3(values.scriptValues.get(sourceEntityId));
+  if (sourceScript) {
+    const entries = Array.isArray(sourceScript.entries) ? sourceScript.entries.map((entry) => asRecord3(entry)).filter((entry) => Boolean(entry)).map((entry) => {
+      const runtimeState = entry.runtimeState === "idle" || entry.runtimeState === "loading" || entry.runtimeState === "ready" || entry.runtimeState === "error" ? entry.runtimeState : void 0;
+      return {
+        entityId: targetEntityId,
+        className: typeof entry.className === "string" ? entry.className : "",
+        scriptUrl: typeof entry.scriptUrl === "string" ? entry.scriptUrl : "",
+        enabled: typeof entry.enabled === "boolean" ? entry.enabled : true,
+        data: entry.data && typeof entry.data === "object" && !Array.isArray(entry.data) ? remapEntityRefsInScriptData(entry.data, idMap) : {},
+        runtimeState,
+        runtimeMessage: typeof entry.runtimeMessage === "string" ? entry.runtimeMessage : void 0
+      };
+    }).filter((entry) => entry.className || entry.scriptUrl) : [];
+    if (!entries.length) {
+      return;
+    }
+    world.addComponent(
+      targetEntityId,
+      new ScriptComponent(entries)
+    );
+  }
+  {
+    const imComponent = world.getComponent(targetEntityId, InstancedMeshComponent);
+    if (imComponent && imComponent.instanceEntityIds.length > 0) {
+      imComponent.instanceEntityIds = imComponent.instanceEntityIds.map(
+        (oldId) => idMap.get(oldId) ?? oldId
+      );
+    }
+  }
+  {
+    const slotComponent = world.getComponent(targetEntityId, InstanceSlotComponent);
+    if (slotComponent && slotComponent.groupEntityId !== -1) {
+      slotComponent.groupEntityId = idMap.get(slotComponent.groupEntityId) ?? slotComponent.groupEntityId;
+    }
+  }
+}
+__name(restorePostCreateComponents, "restorePostCreateComponents");
+
+// core/hydration/animation.ts
+function readAnimationClipName(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  const record = asRecord3(value);
+  if (!record) {
+    return null;
+  }
+  if (typeof record.name === "string") {
+    return record.name;
+  }
+  return null;
+}
+__name(readAnimationClipName, "readAnimationClipName");
+function readAnimationStates(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const states = [];
+  for (const entry of value) {
+    const state = asRecord3(entry);
+    if (!state) {
+      continue;
+    }
+    const name = typeof state.name === "string" ? state.name : null;
+    const clip = readAnimationClipName(state.clip);
+    if (!name || !clip) {
+      continue;
+    }
+    states.push({
+      name,
+      clip,
+      clipId: typeof state.clipId === "string" ? state.clipId : void 0,
+      loop: typeof state.loop === "boolean" ? state.loop : false
+    });
+  }
+  return states;
+}
+__name(readAnimationStates, "readAnimationStates");
+function readAnimationClipSources(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const sources = [];
+  for (const entry of value) {
+    if (typeof entry !== "string") {
+      continue;
+    }
+    const trimmed = entry.trim();
+    if (!trimmed || seen.has(trimmed)) {
+      continue;
+    }
+    seen.add(trimmed);
+    sources.push(trimmed);
+  }
+  return sources;
+}
+__name(readAnimationClipSources, "readAnimationClipSources");
+function toAnimationOptions(sourceAnimation) {
+  const paused = readBoolean(sourceAnimation.paused);
+  const reverse = readBoolean(sourceAnimation.reverse);
+  const timeScale = readNumber(sourceAnimation.timeScale);
+  const crossFadeDuration = readNumber(sourceAnimation.crossFadeDuration);
+  const states = readAnimationStates(sourceAnimation.states);
+  const externalClipSources = readAnimationClipSources(
+    sourceAnimation.externalClipSources
+  );
+  const activeStateName = typeof sourceAnimation.activeStateName === "string" ? sourceAnimation.activeStateName : typeof sourceAnimation.activeState === "string" ? sourceAnimation.activeState : typeof sourceAnimation.active?.name === "string" ? sourceAnimation.active.name ?? null : null;
+  return {
+    paused,
+    reverse,
+    timeScale,
+    crossFadeDuration,
+    states,
+    externalClipSources,
+    activeState: activeStateName
+  };
+}
+__name(toAnimationOptions, "toAnimationOptions");
+function restoreAnimationComponent(world, objectManagementSystem, targetEntityId, sourceAnimation) {
+  const options = toAnimationOptions(sourceAnimation);
+  let animation = world.getComponent(targetEntityId, AnimationComponent);
+  if (!animation) {
+    objectManagementSystem.createComponentNow(
+      "animation",
+      world,
+      targetEntityId,
+      options
+    );
+    animation = world.getComponent(targetEntityId, AnimationComponent);
+  }
+  if (!animation) {
+    return;
+  }
+  const availableClips = Array.isArray(sourceAnimation.availableClips) ? sourceAnimation.availableClips.filter(
+    (clip) => typeof clip === "string" && clip.length > 0
+  ) : [];
+  if (availableClips.length > 0) {
+    animation.availableClips = [...availableClips];
+  }
+  if (Array.isArray(options.externalClipSources)) {
+    animation.setExternalClipSources(options.externalClipSources);
+  }
+  const states = options.states ?? [];
+  const hasClips = Array.isArray(animation.clips) && animation.clips.length > 0;
+  if (!hasClips) {
+    animation.__pendingHydratedOptions = options;
+    if (typeof options.reverse === "boolean") {
+      animation.reverse = options.reverse;
+    }
+    if (typeof options.timeScale === "number") {
+      animation.timeScale = options.timeScale;
+    }
+    if (typeof options.crossFadeDuration === "number") {
+      animation.crossFadeDuration = options.crossFadeDuration;
+    }
+    if (typeof options.paused === "boolean") {
+      animation.paused = options.paused;
+    }
+    return;
+  }
+  if (states.length > 0) {
+    animation.setStates(states);
+  }
+  if (typeof options.reverse === "boolean") {
+    animation.reverse = options.reverse;
+  }
+  if (typeof options.timeScale === "number") {
+    animation.timeScale = options.timeScale;
+  }
+  if (typeof options.crossFadeDuration === "number") {
+    animation.crossFadeDuration = options.crossFadeDuration;
+  }
+  if (typeof options.activeState === "string" && options.activeState.length > 0) {
+    animation.setActiveState(options.activeState, !options.paused);
+  }
+  if (typeof options.paused === "boolean") {
+    if (options.paused) {
+      animation.pauseState();
+    } else if (typeof options.activeState === "string" && options.activeState.length > 0) {
+      animation.playState(options.activeState);
+    }
+  }
+}
+__name(restoreAnimationComponent, "restoreAnimationComponent");
+
+// core/hydration/restoreComponentState.ts
+function readEnvironmentState(value) {
+  const record = asRecord3(value);
+  if (!record) {
+    return null;
+  }
+  const nestedValues = asRecord3(record.values);
+  if (nestedValues) {
+    return nestedValues;
+  }
+  return record;
+}
+__name(readEnvironmentState, "readEnvironmentState");
+function readPostprocessingState(value) {
+  const record = asRecord3(value);
+  if (!record) {
+    return null;
+  }
+  const nestedValues = asRecord3(record.values);
+  if (nestedValues) {
+    return nestedValues;
+  }
+  return record;
+}
+__name(readPostprocessingState, "readPostprocessingState");
+function restoreComponentState(world, objectManagementSystem, targetEntityId, sourceEntityId, entityType, values) {
+  const sourceName = readString(values.nameValues.get(sourceEntityId));
+  if (sourceName !== null) {
+    const nameComponent = world.getComponent(targetEntityId, Name);
+    if (nameComponent) {
+      nameComponent.value = sourceName;
+    }
+  }
+  const sourceObject3DRef = asRecord3(values.object3DRefValues.get(sourceEntityId));
+  if (sourceObject3DRef) {
+    const object3DRefComponent = world.getComponent(targetEntityId, Object3DRef);
+    const visibility = readBoolean(sourceObject3DRef.visibility);
+    if (object3DRefComponent && typeof visibility === "boolean") {
+      object3DRefComponent.visibility = visibility;
+    }
+  }
+  const sourceTransform = readTransform(values.transformValues.get(sourceEntityId));
+  if (sourceTransform) {
+    const transformComponent = world.getComponent(targetEntityId, TransformComponent);
+    if (transformComponent) {
+      if (typeof sourceTransform.position?.x === "number") {
+        transformComponent.position.x = sourceTransform.position.x;
+      }
+      if (typeof sourceTransform.position?.y === "number") {
+        transformComponent.position.y = sourceTransform.position.y;
+      }
+      if (typeof sourceTransform.position?.z === "number") {
+        transformComponent.position.z = sourceTransform.position.z;
+      }
+      if (typeof sourceTransform.rotation?.x === "number") {
+        transformComponent.rotation.x = sourceTransform.rotation.x;
+      }
+      if (typeof sourceTransform.rotation?.y === "number") {
+        transformComponent.rotation.y = sourceTransform.rotation.y;
+      }
+      if (typeof sourceTransform.rotation?.z === "number") {
+        transformComponent.rotation.z = sourceTransform.rotation.z;
+      }
+      if (typeof sourceTransform.scale?.x === "number") {
+        transformComponent.scale.x = sourceTransform.scale.x;
+      }
+      if (typeof sourceTransform.scale?.y === "number") {
+        transformComponent.scale.y = sourceTransform.scale.y;
+      }
+      if (typeof sourceTransform.scale?.z === "number") {
+        transformComponent.scale.z = sourceTransform.scale.z;
+      }
+    }
+  }
+  const sourceModel = asRecord3(values.modelValues.get(sourceEntityId));
+  if (sourceModel) {
+    const modelComponent = world.getComponent(targetEntityId, ModelComponent);
+    if (modelComponent && typeof sourceModel.path === "string") {
+      modelComponent.path = sourceModel.path;
+    }
+  }
+  const sourceImage = asRecord3(values.imageValues.get(sourceEntityId));
+  if (sourceImage) {
+    const imageComponent = world.getComponent(targetEntityId, ImageComponent);
+    if (imageComponent) {
+      if (typeof sourceImage.path === "string") {
+        imageComponent.path = sourceImage.path;
+      }
+      const width = readNumber(sourceImage.width);
+      if (typeof width === "number") {
+        imageComponent.width = width;
+      }
+      const height = readNumber(sourceImage.height);
+      if (typeof height === "number") {
+        imageComponent.height = height;
+      }
+    }
+  }
+  const sourceSprite = asRecord3(values.spriteValues.get(sourceEntityId));
+  if (sourceSprite) {
+    const spriteComponent = world.getComponent(targetEntityId, SpriteComponent);
+    if (spriteComponent) {
+      if (typeof sourceSprite.path === "string") {
+        spriteComponent.path = sourceSprite.path;
+      }
+      const width = readNumber(sourceSprite.width);
+      if (typeof width === "number") {
+        spriteComponent.width = width;
+      }
+      const height = readNumber(sourceSprite.height);
+      if (typeof height === "number") {
+        spriteComponent.height = height;
+      }
+    }
+  }
+  const sourceVideo = asRecord3(values.videoValues.get(sourceEntityId));
+  if (sourceVideo) {
+    const videoComponent = world.getComponent(targetEntityId, VideoComponent);
+    if (videoComponent) {
+      if (typeof sourceVideo.path === "string") {
+        videoComponent.path = sourceVideo.path;
+      }
+      const videoOptions = asRecord3(sourceVideo.options);
+      if (videoOptions) {
+        videoComponent.options = {
+          ...videoComponent.options,
+          ...videoOptions
+        };
+      }
+    }
+  }
+  const sourceAudio = asRecord3(values.audioValues.get(sourceEntityId));
+  if (sourceAudio && entityType === "audio") {
+    const audioComponent = world.getComponent(targetEntityId, AudioComponent);
+    if (audioComponent) {
+      if (typeof sourceAudio.path === "string") {
+        audioComponent.path = sourceAudio.path;
+      }
+      const audioOptions = asRecord3(sourceAudio.options);
+      if (audioOptions) {
+        audioComponent.options = {
+          ...audioComponent.options,
+          ...audioOptions
+        };
+      }
+    }
+  }
+  const sourceCamera = asRecord3(values.cameraValues.get(sourceEntityId));
+  if (sourceCamera) {
+    const cameraComponent = world.getComponent(targetEntityId, CameraComponent);
+    if (cameraComponent) {
+      if (sourceCamera.projection === "orthographic" || sourceCamera.projection === "perspective") {
+        cameraComponent.projection = sourceCamera.projection;
+      }
+      if (sourceCamera.type === "3d" || sourceCamera.type === "ar") {
+        cameraComponent.type = sourceCamera.type;
+      }
+      if (typeof sourceCamera.isDefault === "boolean") {
+        cameraComponent.isDefault = sourceCamera.isDefault;
+      }
+      const fov = readNumber(sourceCamera.fov);
+      if (typeof fov === "number") {
+        cameraComponent.fov = fov;
+      }
+      const near = readNumber(sourceCamera.near);
+      if (typeof near === "number") {
+        cameraComponent.near = near;
+      }
+      const far = readNumber(sourceCamera.far);
+      if (typeof far === "number") {
+        cameraComponent.far = far;
+      }
+      const left = readNumber(sourceCamera.left);
+      if (typeof left === "number") {
+        cameraComponent.left = left;
+      }
+      const right = readNumber(sourceCamera.right);
+      if (typeof right === "number") {
+        cameraComponent.right = right;
+      }
+      const top = readNumber(sourceCamera.top);
+      if (typeof top === "number") {
+        cameraComponent.top = top;
+      }
+      const bottom = readNumber(sourceCamera.bottom);
+      if (typeof bottom === "number") {
+        cameraComponent.bottom = bottom;
+      }
+      const zoom = readNumber(sourceCamera.zoom);
+      if (typeof zoom === "number") {
+        cameraComponent.zoom = zoom;
+      }
+    }
+  }
+  const sourceEnvironment = readEnvironmentState(
+    values.environmentValues.get(sourceEntityId)
+  );
+  if (sourceEnvironment) {
+    let environmentComponent = world.getComponent(targetEntityId, Environment);
+    if (!environmentComponent) {
+      objectManagementSystem.createComponentNow(
+        "environment",
+        world,
+        targetEntityId,
+        sourceEnvironment
+      );
+      environmentComponent = world.getComponent(targetEntityId, Environment);
+    }
+    if (environmentComponent) {
+      environmentComponent.values = new Environment({
+        ...environmentComponent.values,
+        ...sourceEnvironment
+      }).values;
+    }
+  }
+  const sourcePostprocessing = readPostprocessingState(
+    values.postprocessingValues.get(sourceEntityId)
+  );
+  if (sourcePostprocessing) {
+    let postprocessingComponent = world.getComponent(targetEntityId, Postprocessing);
+    if (!postprocessingComponent) {
+      objectManagementSystem.createComponentNow(
+        "postprocessing",
+        world,
+        targetEntityId,
+        sourcePostprocessing
+      );
+      postprocessingComponent = world.getComponent(targetEntityId, Postprocessing);
+    }
+    if (postprocessingComponent) {
+      postprocessingComponent.values = new Postprocessing({
+        ...postprocessingComponent.values,
+        ...sourcePostprocessing
+      }).values;
+    }
+  }
+  const sourceImageTarget = asRecord3(values.imageTargetValues.get(sourceEntityId));
+  if (sourceImageTarget && entityType === "imageTarget") {
+    const imageTargetComponent = world.getComponent(targetEntityId, ImageTarget);
+    if (imageTargetComponent) {
+      imageTargetComponent.targets = Array.isArray(sourceImageTarget.targets) ? sourceImageTarget.targets : [];
+      imageTargetComponent.compiledTargetUrl = typeof sourceImageTarget.compiledTargetUrl === "string" ? sourceImageTarget.compiledTargetUrl : void 0;
+      imageTargetComponent.compiledTargetDir = typeof sourceImageTarget.compiledTargetDir === "string" ? sourceImageTarget.compiledTargetDir : void 0;
+    }
+  }
+  const sourceLight = asRecord3(values.lightValues.get(sourceEntityId));
+  if (sourceLight) {
+    const lightComponent = world.getComponent(targetEntityId, LightComponent);
+    const sourceValues = asRecord3(sourceLight.values);
+    if (lightComponent && sourceValues) {
+      lightComponent.values = {
+        ...lightComponent.values,
+        ...sourceValues
+      };
+    }
+  }
+  const sourceMaterial = asRecord3(values.materialValues.get(sourceEntityId));
+  if (sourceMaterial) {
+    const materialComponent = world.getComponent(targetEntityId, MaterialComponent);
+    const sourceValues = sourceMaterial.values;
+    if (materialComponent && Array.isArray(sourceValues)) {
+      materialComponent.values = sourceValues;
+    }
+    const sourceAssetRefs = sourceMaterial.assetRefs;
+    if (materialComponent && Array.isArray(sourceAssetRefs)) {
+      materialComponent.assetRefs = sourceAssetRefs;
+    }
+  }
+  const sourceMeshGeometry = asRecord3(values.meshGeometryValues.get(sourceEntityId));
+  if (sourceMeshGeometry) {
+    const meshGeometryComponent = world.getComponent(
+      targetEntityId,
+      MeshGeometryComponent
+    );
+    if (meshGeometryComponent) {
+      const parameters = asRecord3(sourceMeshGeometry.parameters);
+      if (parameters) {
+        meshGeometryComponent.parameters = parameters;
+      }
+      if (typeof sourceMeshGeometry.modelName === "string") {
+        meshGeometryComponent.modelName = sourceMeshGeometry.modelName;
+      }
+      if (typeof sourceMeshGeometry.castShadow === "boolean") {
+        meshGeometryComponent.castShadow = sourceMeshGeometry.castShadow;
+      }
+      if (typeof sourceMeshGeometry.receiveShadow === "boolean") {
+        meshGeometryComponent.receiveShadow = sourceMeshGeometry.receiveShadow;
+      }
+    }
+  }
+  const sourceSelectable = asRecord3(values.selectableValues.get(sourceEntityId));
+  if (sourceSelectable) {
+    const enabled = readBoolean(sourceSelectable.enabled);
+    let selectable = world.getComponent(targetEntityId, Selectable);
+    if (!selectable) {
+      objectManagementSystem.createComponentNow(
+        "selectable",
+        world,
+        targetEntityId,
+        enabled ?? true
+      );
+      selectable = world.getComponent(targetEntityId, Selectable);
+    }
+    if (selectable && typeof enabled === "boolean") {
+      selectable.enabled = enabled;
+    }
+  }
+  const sourcePhysics = asRecord3(values.physicsValues.get(sourceEntityId));
+  if (sourcePhysics) {
+    const physicsValues = asRecord3(sourcePhysics.values) ?? sourcePhysics;
+    let physics = world.getComponent(targetEntityId, PhysicsComponent);
+    if (!physics) {
+      objectManagementSystem.createComponentNow(
+        "physics",
+        world,
+        targetEntityId,
+        physicsValues
+      );
+      physics = world.getComponent(targetEntityId, PhysicsComponent);
+    }
+    if (physics) {
+      physics.setValues({
+        rigidbody: asRecord3(physicsValues.rigidbody) ?? {},
+        collider: asRecord3(physicsValues.collider) ?? {}
+      });
+    }
+  }
+  const sourceAnimation = asRecord3(values.animationValues.get(sourceEntityId));
+  if (sourceAnimation) {
+    restoreAnimationComponent(
+      world,
+      objectManagementSystem,
+      targetEntityId,
+      sourceAnimation
+    );
+  }
+  const sourceInstancedMesh = asRecord3(values.instancedMeshValues.get(sourceEntityId));
+  if (sourceInstancedMesh) {
+    const imComponent = world.getComponent(targetEntityId, InstancedMeshComponent);
+    if (imComponent) {
+      if (typeof sourceInstancedMesh.meshKind === "string") {
+        imComponent.meshKind = sourceInstancedMesh.meshKind;
+      }
+      if (typeof sourceInstancedMesh.modelPath === "string") {
+        imComponent.modelPath = sourceInstancedMesh.modelPath;
+      }
+      const parameters = asRecord3(sourceInstancedMesh.meshParameters);
+      if (parameters) {
+        imComponent.meshParameters = parameters;
+      }
+      if (typeof sourceInstancedMesh.castShadow === "boolean") {
+        imComponent.castShadow = sourceInstancedMesh.castShadow;
+      }
+      if (typeof sourceInstancedMesh.receiveShadow === "boolean") {
+        imComponent.receiveShadow = sourceInstancedMesh.receiveShadow;
+      }
+      if (Array.isArray(sourceInstancedMesh.instanceEntityIds)) {
+        imComponent.instanceEntityIds = sourceInstancedMesh.instanceEntityIds;
+      }
+      imComponent.instancedMesh = null;
+    }
+  }
+  const sourceInstanceSlot = asRecord3(values.instanceSlotValues.get(sourceEntityId));
+  if (sourceInstanceSlot) {
+    const slotComponent = world.getComponent(targetEntityId, InstanceSlotComponent);
+    if (slotComponent) {
+      if (typeof sourceInstanceSlot.slotIndex === "number") {
+        slotComponent.slotIndex = sourceInstanceSlot.slotIndex;
+      }
+    }
+  }
+  const sourcePrefabNode = asRecord3(values.prefabNodeValues.get(sourceEntityId));
+  if (sourcePrefabNode && typeof sourcePrefabNode.nodeId === "string") {
+    if (!world.getComponent(targetEntityId, PrefabNode)) {
+      world.addComponent(targetEntityId, new PrefabNode(sourcePrefabNode.nodeId));
+    }
+  }
+  const sourcePrefabInstance = asRecord3(
+    values.prefabInstanceValues.get(sourceEntityId)
+  );
+  if (sourcePrefabInstance && typeof sourcePrefabInstance.url === "string") {
+    if (!world.getComponent(targetEntityId, PrefabInstance)) {
+      const overrides = Array.isArray(sourcePrefabInstance.overrides) ? sourcePrefabInstance.overrides.filter(
+        (entry) => typeof entry === "string"
+      ) : [];
+      world.addComponent(
+        targetEntityId,
+        new PrefabInstance(sourcePrefabInstance.url, overrides)
+      );
+    }
+  }
+}
+__name(restoreComponentState, "restoreComponentState");
+
+// core/hydration/types.ts
+var HYDRATABLE_ENTITY_KINDS = /* @__PURE__ */ new Set([
+  "cube",
+  "sphere",
+  "plane",
+  "capsule",
+  "cylinder",
+  "empty",
+  "model",
+  "image",
+  "imageTarget",
+  "sprite",
+  "audio",
+  "camera",
+  "video",
+  "ambientLight",
+  "directionalLight",
+  "pointLight",
+  "spotLight",
+  "areaLight",
+  "instancedMesh",
+  "instanceSlot"
+]);
+
+// core/hydration/hydrateWorld.ts
+function buildEntityCreationPayload(sourceEntityId, kind, componentValues) {
+  const payload = {
+    name: readString(componentValues.nameValues.get(sourceEntityId)) ?? void 0,
+    transform: readTransform(componentValues.transformValues.get(sourceEntityId))
+  };
+  if (kind === "model") {
+    const model = asRecord3(componentValues.modelValues.get(sourceEntityId));
+    if (typeof model?.path === "string") {
+      payload.path = model.path;
+    }
+  }
+  if (kind === "image") {
+    const image = asRecord3(componentValues.imageValues.get(sourceEntityId));
+    if (typeof image?.path === "string") {
+      payload.path = image.path;
+    }
+  }
+  if (kind === "sprite") {
+    const sprite = asRecord3(componentValues.spriteValues.get(sourceEntityId));
+    if (typeof sprite?.path === "string") {
+      payload.path = sprite.path;
+    }
+  }
+  if (kind === "video") {
+    const video = asRecord3(componentValues.videoValues.get(sourceEntityId));
+    if (typeof video?.path === "string") {
+      payload.path = video.path;
+    }
+    const videoOptions = asRecord3(video?.options);
+    if (videoOptions) {
+      payload.options = videoOptions;
+    }
+  }
+  if (kind === "audio") {
+    const audio = asRecord3(componentValues.audioValues.get(sourceEntityId));
+    if (typeof audio?.path === "string") {
+      payload.path = audio.path;
+    }
+    const audioOptions = asRecord3(audio?.options);
+    if (audioOptions) {
+      payload.options = audioOptions;
+    }
+  }
+  if (kind === "camera") {
+    const camera = asRecord3(componentValues.cameraValues.get(sourceEntityId));
+    if (camera) {
+      const projection = camera.projection === "orthographic" || camera.projection === "perspective" ? camera.projection : void 0;
+      const type = camera.type === "3d" || camera.type === "ar" ? camera.type : void 0;
+      payload.options = {
+        isDefault: typeof camera.isDefault === "boolean" ? camera.isDefault : void 0,
+        projection,
+        type,
+        fov: typeof camera.fov === "number" ? camera.fov : void 0,
+        near: typeof camera.near === "number" ? camera.near : void 0,
+        far: typeof camera.far === "number" ? camera.far : void 0,
+        left: typeof camera.left === "number" ? camera.left : void 0,
+        right: typeof camera.right === "number" ? camera.right : void 0,
+        top: typeof camera.top === "number" ? camera.top : void 0,
+        bottom: typeof camera.bottom === "number" ? camera.bottom : void 0,
+        zoom: typeof camera.zoom === "number" ? camera.zoom : void 0
+      };
+    }
+  }
+  if (kind === "imageTarget") {
+    const imageTarget = asRecord3(componentValues.imageTargetValues.get(sourceEntityId));
+    if (imageTarget) {
+      payload.options = {
+        targets: Array.isArray(imageTarget.targets) ? imageTarget.targets : [],
+        compiledTargetUrl: typeof imageTarget.compiledTargetUrl === "string" ? imageTarget.compiledTargetUrl : void 0,
+        compiledTargetDir: typeof imageTarget.compiledTargetDir === "string" ? imageTarget.compiledTargetDir : void 0
+      };
+    }
+  }
+  if (kind === "instancedMesh") {
+    const im = asRecord3(componentValues.instancedMeshValues.get(sourceEntityId));
+    if (im) {
+      payload.options = {
+        meshKind: typeof im.meshKind === "string" ? im.meshKind : "cube",
+        modelPath: typeof im.modelPath === "string" ? im.modelPath : void 0,
+        meshParameters: asRecord3(im.meshParameters) ?? void 0,
+        castShadow: typeof im.castShadow === "boolean" ? im.castShadow : false,
+        receiveShadow: typeof im.receiveShadow === "boolean" ? im.receiveShadow : false,
+        // New format: signal the factory to skip child entity creation.
+        // Old format (instances[]): pass through for migration — factory will
+        // create slot entities from the legacy InstanceTransform array.
+        ...Array.isArray(im.instanceEntityIds) ? { instanceEntityIds: im.instanceEntityIds } : Array.isArray(im.instances) ? { instances: im.instances } : {}
+      };
+    }
+  }
+  if (kind === "instanceSlot") {
+    const slot = asRecord3(componentValues.instanceSlotValues.get(sourceEntityId));
+    if (slot) {
+      payload.options = {
+        groupEntityId: typeof slot.groupEntityId === "number" ? slot.groupEntityId : -1,
+        slotIndex: typeof slot.slotIndex === "number" ? slot.slotIndex : 0
+      };
+    }
+  }
+  return payload;
+}
+__name(buildEntityCreationPayload, "buildEntityCreationPayload");
+function resolvePrimaryCameraSourceEntityId(snapshot, componentValues, entityTypeValues) {
+  let firstCameraSourceEntityId = null;
+  for (const sourceEntityId of snapshot.entities) {
+    const entityType = readString(entityTypeValues.get(sourceEntityId));
+    if (entityType !== "camera") {
+      continue;
+    }
+    if (firstCameraSourceEntityId === null) {
+      firstCameraSourceEntityId = sourceEntityId;
+    }
+    const cameraValue = asRecord3(componentValues.cameraValues.get(sourceEntityId));
+    if (cameraValue?.isDefault === true) {
+      return sourceEntityId;
+    }
+  }
+  return firstCameraSourceEntityId;
+}
+__name(resolvePrimaryCameraSourceEntityId, "resolvePrimaryCameraSourceEntityId");
+function applyLocalTransformsAfterHierarchyRestore(world, scopeEntityIds) {
+  const transformEntities = scopeEntityIds ? Array.from(scopeEntityIds) : world.query(TransformComponent, Object3DRef);
+  for (const entityId of transformEntities) {
+    const transform = world.getComponent(entityId, TransformComponent);
+    const object = world.getComponent(entityId, Object3DRef)?.object;
+    if (!transform || !object) {
+      continue;
+    }
+    applyTransform(object, transform);
+    object.updateMatrixWorld(true);
+  }
+}
+__name(applyLocalTransformsAfterHierarchyRestore, "applyLocalTransformsAfterHierarchyRestore");
+function hydrateWorldFromSnapshotDetailed(snapshot, world, objectManagementSystem, options) {
+  if (!snapshot || !snapshot.entities.length) {
+    return {
+      restoredCount: 0,
+      selectedEntityId: null,
+      idMap: /* @__PURE__ */ new Map()
+    };
+  }
+  const assignPrimaryCamera = options?.assignPrimaryCamera !== false;
+  const entityTypeValues = readByComponent(snapshot.components, "EntityType");
+  const componentValues = buildComponentValueMaps(snapshot);
+  const primaryCameraSourceEntityId = assignPrimaryCamera ? resolvePrimaryCameraSourceEntityId(
+    snapshot,
+    componentValues,
+    entityTypeValues
+  ) : null;
+  const idMap = /* @__PURE__ */ new Map();
+  for (const sourceEntityId of snapshot.entities) {
+    const entityTypeValue = entityTypeValues.get(sourceEntityId);
+    const entityType = readString(entityTypeValue);
+    if (!entityType || !HYDRATABLE_ENTITY_KINDS.has(entityType)) {
+      continue;
+    }
+    const kind = entityType;
+    const payload = buildEntityCreationPayload(sourceEntityId, kind, componentValues);
+    if (kind === "camera" && sourceEntityId === primaryCameraSourceEntityId) {
+      payload.useWorldCamera = true;
+      const options2 = asRecord3(payload.options);
+      payload.options = {
+        ...options2 ?? {},
+        isDefault: true
+      };
+    }
+    const createdEntityId = objectManagementSystem.createNow(kind, world, payload);
+    idMap.set(sourceEntityId, createdEntityId);
+  }
+  for (const sourceEntityId of snapshot.entities) {
+    const targetEntityId = idMap.get(sourceEntityId);
+    if (targetEntityId === void 0) {
+      continue;
+    }
+    const entityType = readString(entityTypeValues.get(sourceEntityId));
+    restoreComponentState(
+      world,
+      objectManagementSystem,
+      targetEntityId,
+      sourceEntityId,
+      entityType,
+      componentValues
+    );
+    restorePostCreateComponents(
+      world,
+      objectManagementSystem,
+      targetEntityId,
+      sourceEntityId,
+      entityType,
+      componentValues,
+      idMap
+    );
+  }
+  applyParentLinks(snapshot, idMap, objectManagementSystem, world);
+  objectManagementSystem.reconcileSceneFromWorld(world);
+  applyLocalTransformsAfterHierarchyRestore(
+    world,
+    options?.applyTransformsScope === "created" ? idMap.values() : void 0
+  );
+  const selectedEntityId = typeof snapshot.selectedEntityId === "number" ? idMap.get(snapshot.selectedEntityId) ?? null : null;
+  return {
+    restoredCount: idMap.size,
+    selectedEntityId,
+    idMap
+  };
+}
+__name(hydrateWorldFromSnapshotDetailed, "hydrateWorldFromSnapshotDetailed");
+
+// core/prefab/overrides.ts
+var asRecord4 = /* @__PURE__ */ __name((value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : null, "asRecord");
+function findSnapshotRootEntityIds(snapshot) {
+  const parentBlock = snapshot.components.find(
+    (block) => block.component === "ParentId"
+  );
+  const parentByEntity = /* @__PURE__ */ new Map();
+  for (const entry of parentBlock?.entries ?? []) {
+    parentByEntity.set(entry.entityId, asRecord4(entry.value)?.value ?? null);
+  }
+  return snapshot.entities.filter(
+    (entityId) => typeof parentByEntity.get(entityId) !== "number"
+  );
+}
+__name(findSnapshotRootEntityIds, "findSnapshotRootEntityIds");
+
+// core/prefab/instantiateSubtree.ts
+var INSTANTIATE_EXCLUDED_COMPONENTS = /* @__PURE__ */ new Set([
+  "Environment",
+  "Postprocessing",
+  "SelectionTransformState",
+  "PrefabInstance"
+]);
+function instantiateSubtree(world, objectManagementSystem, snapshot) {
+  const safeSnapshot = {
+    entities: snapshot.entities,
+    components: snapshot.components.filter(
+      (block) => !INSTANTIATE_EXCLUDED_COMPONENTS.has(block.component)
+    )
+  };
+  const result = hydrateWorldFromSnapshotDetailed(
+    safeSnapshot,
+    world,
+    objectManagementSystem,
+    { assignPrimaryCamera: false, applyTransformsScope: "created" }
+  );
+  const rootSourceId = findSnapshotRootEntityIds(safeSnapshot).find(
+    (sourceId) => result.idMap.has(sourceId)
+  );
+  return {
+    rootId: rootSourceId !== void 0 ? result.idMap.get(rootSourceId) ?? null : null,
+    idMap: result.idMap
+  };
+}
+__name(instantiateSubtree, "instantiateSubtree");
+
+// core/prefab/types.ts
+var isRecord = /* @__PURE__ */ __name((value) => value !== null && typeof value === "object" && !Array.isArray(value), "isRecord");
+function parsePrefabAsset(json) {
+  if (!isRecord(json)) {
+    return null;
+  }
+  if (typeof json.version !== "number" || json.version < 1) {
+    return null;
+  }
+  const snapshot = json.snapshot;
+  if (!isRecord(snapshot)) {
+    return null;
+  }
+  const entities = snapshot.entities;
+  const components = snapshot.components;
+  if (!Array.isArray(entities) || !Array.isArray(components)) {
+    return null;
+  }
+  if (!entities.every((id) => typeof id === "number")) {
+    return null;
+  }
+  if (!components.every(
+    (block) => isRecord(block) && typeof block.component === "string" && Array.isArray(block.entries)
+  )) {
+    return null;
+  }
+  return {
+    version: json.version,
+    type: json.type === "scene" ? "scene" : "prefab",
+    name: typeof json.name === "string" ? json.name : void 0,
+    snapshot
+  };
+}
+__name(parsePrefabAsset, "parsePrefabAsset");
+var resolveUrl = /* @__PURE__ */ __name((url) => url, "resolveUrl");
+function transformStringsDeep(value, fn) {
+  if (typeof value === "string") {
+    return fn(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => transformStringsDeep(item, fn));
+  }
+  if (value !== null && typeof value === "object") {
+    const result = {};
+    for (const [key, item] of Object.entries(value)) {
+      result[key] = transformStringsDeep(item, fn);
+    }
+    return result;
+  }
+  return value;
+}
+__name(transformStringsDeep, "transformStringsDeep");
+var prefabCache = /* @__PURE__ */ new Map();
+function loadPrefab(url) {
+  const cached = prefabCache.get(url);
+  if (cached) {
+    return cached;
+  }
+  const pending = (async () => {
+    const response = await fetch(resolveUrl(url));
+    if (!response.ok) {
+      throw new Error(`Failed to fetch prefab "${url}" (${response.status})`);
+    }
+    const json = await response.json();
+    const parsed = parsePrefabAsset(json);
+    if (!parsed) {
+      throw new Error(`Invalid prefab file at "${url}"`);
+    }
+    return {
+      ...parsed,
+      snapshot: transformStringsDeep(
+        parsed.snapshot,
+        resolveUrl
+      )
+    };
+  })();
+  prefabCache.set(url, pending);
+  pending.catch(() => {
+    if (prefabCache.get(url) === pending) {
+      prefabCache.delete(url);
+    }
+  });
+  return pending;
+}
+__name(loadPrefab, "loadPrefab");
+function resolveSource(source) {
+  if (typeof source === "string") {
+    return { url: source, asset: loadPrefab(source) };
+  }
+  if ("path" in source && typeof source.path === "string") {
+    return { url: source.path, asset: loadPrefab(source.path) };
+  }
+  const asset = source;
+  return { url: asset.name ?? "", asset };
+}
+__name(resolveSource, "resolveSource");
+async function spawnPrefab(world, source, options) {
+  const { url, asset } = resolveSource(source);
+  const prefab = await asset;
+  const objectManagementSystem = world.getObjectManagementSystem();
+  const { rootId } = instantiateSubtree(
+    world,
+    objectManagementSystem,
+    prefab.snapshot
+  );
+  if (rootId === null) {
+    throw new Error(
+      `Prefab "${url || prefab.name || "unknown"}" contained no spawnable entities`
+    );
+  }
+  if (!world.getComponent(rootId, PrefabInstance)) {
+    world.addComponent(rootId, new PrefabInstance(url, []));
+  }
+  if (options?.parentId !== void 0 && options.parentId !== null) {
+    objectManagementSystem.setParent(world, rootId, options.parentId, {
+      preserveWorldTransform: false
+    });
+  }
+  const transform = world.getComponent(rootId, TransformComponent);
+  if (transform && (options?.position || options?.rotation || options?.scale)) {
+    const write = /* @__PURE__ */ __name((target, src) => {
+      if (!src) return;
+      if (typeof src.x === "number") target.x = src.x;
+      if (typeof src.y === "number") target.y = src.y;
+      if (typeof src.z === "number") target.z = src.z;
+    }, "write");
+    write(transform.position, options.position);
+    write(transform.rotation, options.rotation);
+    write(transform.scale, options.scale);
+    const object = world.getComponent(rootId, Object3DRef)?.object;
+    if (object) {
+      applyTransform(object, transform);
+      object.updateMatrixWorld(true);
+    }
+  }
+  return rootId;
+}
+__name(spawnPrefab, "spawnPrefab");
+function despawnPrefab(world, rootId, dispose = true) {
+  const objectManagementSystem = world.getObjectManagementSystem();
+  const subtree = collectEntitySubtree(world, [rootId]).reverse();
+  let removed = 0;
+  for (const entityId of subtree) {
+    if (objectManagementSystem.deleteEntity(world, entityId, dispose)) {
+      removed += 1;
+    }
+  }
+  return removed;
+}
+__name(despawnPrefab, "despawnPrefab");
 var _Behaviour = class _Behaviour {
   /**
    * Engine-managed constructor. Hosts (`ScriptBehaviourSystem`) instantiate
@@ -4572,6 +5910,35 @@ var _Behaviour = class _Behaviour {
    */
   dispose(world) {
   }
+  /**
+   * Instantiate a prefab asset into the world at runtime.
+   *
+   * `source` is typically an `AssetInput` field from this script's `data`
+   * (drag a `.prefab` from the asset browser onto the field in the editor),
+   * a URL string, or a pre-loaded `PrefabAsset`. Resolves with the new root
+   * entity id.
+   *
+   * ```ts
+   * data = { enemyPrefab: { path: "", type: "prefab" } };
+   * async onUpdate() {
+   *   if (shouldSpawn) {
+   *     const id = await this.spawnPrefab(this.data.enemyPrefab, {
+   *       position: { x: 0, y: 0, z: -5 },
+   *     });
+   *   }
+   * }
+   * ```
+   */
+  spawnPrefab(source, options) {
+    return spawnPrefab(this.world, source, options);
+  }
+  /**
+   * Remove a spawned prefab instance (the root entity and all descendants).
+   * Returns the number of entities removed.
+   */
+  despawn(rootEntityId) {
+    return despawnPrefab(this.world, rootEntityId);
+  }
   /**
    * Returns the entity's world-space position as a new `THREE.Vector3`, or
    * `null` if the entity has no scene presence.