castle-web-cli 0.4.11 → 0.4.12

package/kits/basic-3d/editors/behaviorRegistry.js

@@ -0,0 +1,24 @@
+// Discover every behavior class from `behaviors/*.tsx`. Vite HMR is off, so a
+// newly-added behavior file is picked up on the next reload/restart.
+const modules = import.meta.glob('../behaviors/*.jsx', { eager: true });
+function isBehaviorClass(value) {
+  return typeof value === 'function' && typeof value.behaviorName === 'string';
+}
+function collectBehaviors() {
+  const found = new Map();
+  for (const mod of Object.values(modules)) {
+    for (const exported of Object.values(mod)) {
+      if (isBehaviorClass(exported)) found.set(exported.behaviorName, exported);
+    }
+  }
+  // Layout first (every actor needs it), then alphabetical.
+  return [...found.values()].sort((a, b) => {
+    if (a.behaviorName === 'Layout') return -1;
+    if (b.behaviorName === 'Layout') return 1;
+    return a.behaviorName.localeCompare(b.behaviorName);
+  });
+}
+export const behaviorClasses = collectBehaviors();
+export function findBehaviorClass(behaviorName) {
+  return behaviorClasses.find((candidate) => candidate.behaviorName === behaviorName);
+}

package/kits/basic-3d/editors/editorHistory.js

@@ -0,0 +1,52 @@
+import { useState } from 'react';
+const HISTORY_LIMIT = 50;
+// Text-undo/redo for file-backed editors. `text` is the canonical current
+// value; `onChange` writes the new value back. The hook owns the undo/redo
+// stacks; it never mutates `text` directly.
+export function useEditHistory(text, onChange) {
+  const [history, setHistory] = useState({ undo: [], redo: [] });
+  function commit(nextText) {
+    if (nextText === text) return;
+    setHistory((current) => ({
+      undo: [...current.undo, text].slice(-HISTORY_LIMIT),
+      redo: [],
+    }));
+    onChange(nextText);
+  }
+  function recordSnapshot() {
+    setHistory((current) => ({
+      undo: [...current.undo, text].slice(-HISTORY_LIMIT),
+      redo: [],
+    }));
+  }
+  function undo() {
+    setHistory((current) => {
+      const previous = current.undo.at(-1);
+      if (!previous) return current;
+      onChange(previous);
+      return {
+        undo: current.undo.slice(0, -1),
+        redo: [text, ...current.redo].slice(0, HISTORY_LIMIT),
+      };
+    });
+  }
+  function redo() {
+    setHistory((current) => {
+      const next = current.redo[0];
+      if (!next) return current;
+      onChange(next);
+      return {
+        undo: [...current.undo, text].slice(-HISTORY_LIMIT),
+        redo: current.redo.slice(1),
+      };
+    });
+  }
+  return {
+    commit,
+    undo,
+    redo,
+    canUndo: history.undo.length > 0,
+    canRedo: history.redo.length > 0,
+    recordSnapshot,
+  };
+}

package/kits/basic-3d/editors/viewportRig.js

@@ -0,0 +1,90 @@
+import * as THREE from 'three';
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+import { TransformControls } from 'three/examples/jsm/controls/TransformControls.js';
+import { applyCameraSpec, defaultLighting } from '../engine/threeUtil';
+import { defaultCameraSpec } from '../engine/scene';
+
+// Editor viewport rig: a perspective camera with orbit navigation plus a
+// transform gizmo, shared by the scene editor and the model editor.
+//
+// Navigation: right-drag orbits, middle-drag pans, wheel dollies. When
+// `navMode` is on (the toolbar camera toggle, for touch / trackpads),
+// left-drag orbits and two-finger gestures dolly+pan; otherwise left input
+// belongs to the caller (selection, painting, marquee).
+export function createViewportRig({ canvas, scene, onGizmoChange, onGizmoDraggingChanged }) {
+  const camera = new THREE.PerspectiveCamera(50, 1, 0.1, 2000);
+  applyCameraSpec(camera, defaultCameraSpec);
+
+  const orbit = new OrbitControls(camera, canvas);
+  orbit.target.set(defaultCameraSpec.targetX, defaultCameraSpec.targetY, defaultCameraSpec.targetZ);
+  orbit.enableDamping = false;
+  orbit.update();
+
+  const gizmo = new TransformControls(camera, canvas);
+  gizmo.addEventListener('objectChange', () => onGizmoChange?.(gizmo));
+  gizmo.addEventListener('dragging-changed', (event) => {
+    orbit.enabled = !event.value;
+    onGizmoDraggingChanged?.(event.value);
+  });
+  // r169+ exposes the renderable part via getHelper(); older versions are the
+  // Object3D themselves.
+  const gizmoHelper = gizmo.getHelper ? gizmo.getHelper() : gizmo;
+  scene.add(gizmoHelper);
+
+  const rig = {
+    camera,
+    orbit,
+    gizmo,
+    // True while the gizmo is being hovered or dragged -- callers skip their
+    // own left-pointer gestures so the two don't fight.
+    gizmoBusy: () => !!gizmo.dragging || gizmo.axis != null,
+    setNavMode(navMode) {
+      orbit.mouseButtons = {
+        LEFT: navMode ? THREE.MOUSE.ROTATE : null,
+        MIDDLE: THREE.MOUSE.PAN,
+        RIGHT: THREE.MOUSE.ROTATE,
+      };
+      orbit.touches = {
+        ONE: navMode ? THREE.TOUCH.ROTATE : null,
+        TWO: THREE.TOUCH.DOLLY_PAN,
+      };
+    },
+    dispose() {
+      gizmo.detach();
+      gizmoHelper.parent?.remove(gizmoHelper);
+      gizmo.dispose();
+      orbit.dispose();
+    },
+  };
+  rig.setNavMode(false);
+  return rig;
+}
+
+// Configure gizmo snapping from scene editor settings.
+export function applyGizmoSnap(gizmo, snapSettings) {
+  const enabled = !!snapSettings?.enabled;
+  gizmo.setTranslationSnap(enabled ? (snapSettings.gridSize ?? 1) : null);
+  gizmo.setRotationSnap(enabled ? THREE.MathUtils.degToRad(15) : null);
+  gizmo.setScaleSnap(enabled ? 0.25 : null);
+}
+
+export const GIZMO_MODES = [
+  { key: 'translate', icon: 'move', label: 'Move' },
+  { key: 'rotate', icon: 'rotate', label: 'Rotate' },
+  { key: 'scale', icon: 'scale', label: 'Scale' },
+];
+
+// A standalone lit preview scene for editors that aren't backed by a
+// SceneRuntime (the model editor): lights + grid on a dark background.
+export function createPreviewScene() {
+  const scene = new THREE.Scene();
+  scene.background = new THREE.Color('#191d28');
+  const hemi = new THREE.HemisphereLight(defaultLighting.sky, defaultLighting.ground, 1);
+  const sun = new THREE.DirectionalLight(defaultLighting.sun, 2);
+  sun.position.set(20, 35, 25);
+  sun.castShadow = true;
+  scene.add(hemi, sun);
+  const grid = new THREE.GridHelper(20, 20, 0x666666, 0x333333);
+  scene.add(grid);
+  return scene;
+}

package/kits/basic-3d/engine/ScenePlayer.jsx

@@ -0,0 +1,55 @@
+import React, { useCallback, useEffect, useMemo, useRef } from 'react';
+import * as THREE from 'three';
+import { makeScene, defaultCameraSpec } from './scene';
+import { applyCameraSpec, fitRendererToCanvas } from './threeUtil';
+import { attachSceneKeys, makePlayPointerHandlers, ThreeCanvas } from './SceneViewport';
+import { SceneUI } from './SceneUI';
+import { TouchControls } from './TouchControls';
+// Engine-level scene player: mount a `SceneRuntime` against a WebGL canvas,
+// wire keyboard / pointer input, run the update+sync+render loop, and render
+// the behavior-driven UI overlay. No game logic lives here -- behaviors and
+// scenes are the place for that.
+export function ScenePlayer({ sceneData, models, behaviorClasses }) {
+  const runtimeRef = useRef(null);
+  const cameraRef = useRef(null);
+  const getKeys = useCallback(() => runtimeRef.current?.keys ?? null, []);
+  const getRuntime = useCallback(() => runtimeRef.current, []);
+  const pointerHandlers = useMemo(() => makePlayPointerHandlers(getRuntime), [getRuntime]);
+  useEffect(() => {
+    const runtime = makeScene(sceneData, behaviorClasses, models);
+    runtimeRef.current = runtime;
+    const detachKeys = attachSceneKeys(getRuntime);
+    return () => {
+      detachKeys();
+      runtime.dispose();
+      runtimeRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  const onSetup = () => {
+    cameraRef.current = new THREE.PerspectiveCamera(50, 1, 0.1, 2000);
+  };
+  const onFrame = ({ canvas, renderer, dt }) => {
+    const runtime = runtimeRef.current;
+    const camera = cameraRef.current;
+    if (!runtime || !camera) return;
+    runtime.update(dt);
+    runtime.syncFrame(dt, {});
+    if (!fitRendererToCanvas(renderer, camera, canvas)) return;
+    applyCameraSpec(camera, runtime.camera ?? defaultCameraSpec);
+    runtime.activeCamera = camera;
+    renderer.render(runtime.three, camera);
+  };
+  return (
+    <div style={{ position: 'fixed', inset: 0, background: '#000' }}>
+      <ThreeCanvas
+        onSetup={onSetup}
+        onFrame={onFrame}
+        style={{ width: '100%', height: '100%', display: 'block', touchAction: 'none' }}
+        {...pointerHandlers}
+      />
+      <SceneUI getRuntime={getRuntime} />
+      <TouchControls getKeys={getKeys} />
+    </div>
+  );
+}

package/kits/basic-3d/engine/SceneUI.jsx

@@ -0,0 +1,67 @@
+import React, { useEffect, useRef, useState } from 'react';
+import styles from './ui.module.css';
+import { cardSize } from './scene';
+// Game-time UI overlay.
+//
+// Behaviors expose a `ui(actor, scene)` handler -- the React counterpart of
+// `draw`. `SceneUI` collects every behavior's UI output each frame and renders
+// it into a deck-sized layer that sits exactly over the canvas. The layer is
+// `cardSize` units wide/tall and scaled onto the canvas box, so behaviors lay
+// out in the same card units as `Layout`. The root clips with `overflow:
+// hidden`, so deck UI can never render outside the card.
+export function SceneUI({ getRuntime }) {
+  const rootRef = useRef(null);
+  const [box, setBox] = useState({ width: 0, height: 0 });
+  const [, forceRender] = useState(0);
+  // Track the canvas-sized overlay box so the card-unit layer scales onto it.
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!root) return undefined;
+    const measure = () => setBox({ width: root.clientWidth, height: root.clientHeight });
+    const observer = new ResizeObserver(measure);
+    observer.observe(root);
+    measure();
+    return () => observer.disconnect();
+  }, []);
+  // Re-render every frame so behavior UI reflects live runtime state.
+  useEffect(() => {
+    let raf = 0;
+    const frame = () => {
+      forceRender((tick) => tick + 1);
+      raf = requestAnimationFrame(frame);
+    };
+    raf = requestAnimationFrame(frame);
+    return () => cancelAnimationFrame(raf);
+  }, []);
+  return (
+    <div ref={rootRef} className={styles.sceneUiRoot}>
+      <div
+        className={styles.sceneUiLayer}
+        style={{
+          width: cardSize.width,
+          height: cardSize.height,
+          transform: `scale(${box.width / cardSize.width}, ${box.height / cardSize.height})`,
+        }}>
+        {collectUiNodes(getRuntime())}
+      </div>
+    </div>
+  );
+}
+// Build one keyed React node per behavior that defines a `ui` handler.
+function collectUiNodes(runtime) {
+  if (!runtime) return [];
+  const nodes = [];
+  for (const actor of runtime.getActors()) {
+    for (const [behaviorName, props] of Object.entries(actor.components)) {
+      if (!props) continue;
+      const Behavior = runtime.behaviors.get(behaviorName);
+      if (!Behavior) continue;
+      const instance = new Behavior(props);
+      if (!instance.ui) continue;
+      const node = instance.ui(actor, runtime);
+      if (node == null) continue;
+      nodes.push(<React.Fragment key={`${actor.id}:${behaviorName}`}>{node}</React.Fragment>);
+    }
+  }
+  return nodes;
+}

package/kits/basic-3d/engine/SceneViewport.jsx

@@ -0,0 +1,102 @@
+import React, { useEffect, useRef } from 'react';
+import { createRenderer } from './threeUtil';
+
+// Shared WebGL viewport plumbing: a canvas + renderer + frame loop, and the
+// input helpers every play surface (standalone player, editor play mode)
+// shares so behaviors see identical `scene.keys` / `scene.pointer` everywhere.
+
+// Mounts a WebGL canvas and drives a per-frame callback. `onSetup` runs once
+// with `{ canvas, renderer }` (may return a cleanup); `onFrame` runs every
+// animation frame with `{ canvas, renderer, dt }`. Both are read through a
+// ref, so the latest render's closures are always the ones called.
+export function ThreeCanvas({ onSetup, onFrame, ...canvasProps }) {
+  const canvasRef = useRef(null);
+  const callbacksRef = useRef({ onSetup, onFrame });
+  callbacksRef.current = { onSetup, onFrame };
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return undefined;
+    const renderer = createRenderer(canvas);
+    const cleanup = callbacksRef.current.onSetup?.({ canvas, renderer });
+    let raf = 0;
+    let previousTime = performance.now();
+    const tick = (now) => {
+      const dt = Math.min(0.033, (now - previousTime) / 1000);
+      previousTime = now;
+      callbacksRef.current.onFrame?.({ canvas, renderer, dt });
+      raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+    return () => {
+      cancelAnimationFrame(raf);
+      cleanup?.();
+      renderer.dispose();
+    };
+  }, []);
+  return <canvas ref={canvasRef} {...canvasProps} />;
+}
+
+// Window-level key listeners feeding `scene.keys`. Both `event.key` ('a',
+// 'ArrowLeft', ' ') and `event.code` ('KeyA', 'Space') are added so behaviors
+// can read either. Optional `onSpace` intercepts the space key outside text
+// inputs (the editor's play/stop toggle). Returns a cleanup function.
+export function attachSceneKeys(getRuntime, { onSpace } = {}) {
+  const down = (event) => {
+    if (onSpace && event.key === ' ' && !isEditableTarget(event.target)) {
+      event.preventDefault();
+      onSpace();
+      return;
+    }
+    const runtime = getRuntime();
+    if (!runtime) return;
+    runtime.keys.add(event.key);
+    runtime.keys.add(event.code);
+  };
+  const up = (event) => {
+    const runtime = getRuntime();
+    if (!runtime) return;
+    runtime.keys.delete(event.key);
+    runtime.keys.delete(event.code);
+  };
+  window.addEventListener('keydown', down);
+  window.addEventListener('keyup', up);
+  return () => {
+    window.removeEventListener('keydown', down);
+    window.removeEventListener('keyup', up);
+  };
+}
+
+export function isEditableTarget(target) {
+  return (
+    target instanceof Element &&
+    !!target.closest('input, textarea, select, [contenteditable="true"], .cm-editor')
+  );
+}
+
+// React pointer handlers feeding `scene.pointer` during play.
+export function makePlayPointerHandlers(getRuntime) {
+  const set = (event, down) => {
+    const runtime = getRuntime();
+    if (!runtime) return;
+    runtime.setPointerFromScreen(event.currentTarget, event.clientX, event.clientY, down);
+  };
+  return {
+    onPointerDown: (event) => {
+      try {
+        event.currentTarget.setPointerCapture(event.pointerId);
+      } catch {
+        // Synthetic / already-released pointers can't be captured.
+      }
+      set(event, true);
+    },
+    onPointerMove: (event) => set(event),
+    onPointerUp: (event) => {
+      set(event, false);
+      try {
+        event.currentTarget.releasePointerCapture(event.pointerId);
+      } catch {
+        // Pointer capture may already be gone after cancel/blur.
+      }
+    },
+  };
+}

package/kits/basic-3d/engine/TouchControls.jsx

@@ -0,0 +1,136 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+// On-screen movement controls: a 4-way d-pad feeds arrow keys onto
+// `scene.keys` -- the exact same keyboard keys behaviors consume, no separate
+// input path.
+const KEYS = {
+  up: 'ArrowUp',
+  down: 'ArrowDown',
+  left: 'ArrowLeft',
+  right: 'ArrowRight',
+};
+export function TouchControls({ getKeys, visible = true }) {
+  const [isTouch, setIsTouch] = useState(false);
+  const heldRef = useRef(new Set());
+  useEffect(() => {
+    const params = new URLSearchParams(window.location.search);
+    const override = params.get('touch');
+    if (override === '1' || override === 'true') {
+      setIsTouch(true);
+      return undefined;
+    }
+    if (override === '0' || override === 'false') {
+      setIsTouch(false);
+      return undefined;
+    }
+    const mq = window.matchMedia('(pointer: coarse)');
+    const update = () => {
+      setIsTouch(mq.matches || 'ontouchstart' in window || navigator.maxTouchPoints > 0);
+    };
+    update();
+    mq.addEventListener?.('change', update);
+    return () => mq.removeEventListener?.('change', update);
+  }, []);
+  const release = useCallback(
+    (id) => {
+      if (!heldRef.current.has(id)) return;
+      heldRef.current.delete(id);
+      getKeys()?.delete(KEYS[id]);
+    },
+    [getKeys]
+  );
+  useEffect(() => {
+    if (!visible || !isTouch) {
+      // Drop any keys we were holding when controls hide.
+      const keys = getKeys();
+      if (keys) for (const id of heldRef.current) keys.delete(KEYS[id]);
+      heldRef.current.clear();
+    }
+  }, [visible, isTouch, getKeys]);
+  if (!visible || !isTouch) return null;
+  const press = (id) => {
+    heldRef.current.add(id);
+    getKeys()?.add(KEYS[id]);
+  };
+  const button = (id, label, extra) => (
+    <button
+      key={id}
+      type="button"
+      tabIndex={-1}
+      aria-label={id}
+      onTouchStart={(event) => {
+        event.preventDefault();
+        press(id);
+      }}
+      onTouchEnd={(event) => {
+        event.preventDefault();
+        release(id);
+      }}
+      onTouchCancel={(event) => {
+        event.preventDefault();
+        release(id);
+      }}
+      onMouseDown={(event) => {
+        event.preventDefault();
+        press(id);
+      }}
+      onMouseUp={() => release(id)}
+      onMouseLeave={() => release(id)}
+      onContextMenu={(event) => event.preventDefault()}
+      style={{ ...buttonStyle, ...extra }}>
+      {label}
+    </button>
+  );
+  return (
+    <div style={containerStyle}>
+      <div style={dpadStyle}>
+        {button('up', '▲', dpadUpStyle)}
+        {button('left', '◀', dpadLeftStyle)}
+        {button('right', '▶', dpadRightStyle)}
+        {button('down', '▼', dpadDownStyle)}
+      </div>
+    </div>
+  );
+}
+const containerStyle = {
+  position: 'fixed',
+  left: 0,
+  right: 0,
+  bottom: 0,
+  display: 'flex',
+  justifyContent: 'flex-start',
+  alignItems: 'flex-end',
+  padding: '12px 16px calc(env(safe-area-inset-bottom, 0px) + 12px)',
+  pointerEvents: 'none',
+  zIndex: 50,
+};
+// 3x3 grid -- the d-pad arms occupy the cross cells, corners stay empty.
+const dpadStyle = {
+  display: 'grid',
+  gridTemplateColumns: 'repeat(3, 64px)',
+  gridTemplateRows: 'repeat(3, 64px)',
+  gap: 6,
+  pointerEvents: 'auto',
+};
+const dpadUpStyle = { gridColumn: 2, gridRow: 1 };
+const dpadLeftStyle = { gridColumn: 1, gridRow: 2 };
+const dpadRightStyle = { gridColumn: 3, gridRow: 2 };
+const dpadDownStyle = { gridColumn: 2, gridRow: 3 };
+const buttonStyle = {
+  width: 64,
+  height: 64,
+  borderRadius: 12,
+  border: '1px solid rgba(255, 255, 255, 0.35)',
+  background: 'rgba(0, 0, 0, 0.35)',
+  color: 'rgba(255, 255, 255, 0.92)',
+  fontSize: 24,
+  fontWeight: 600,
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  userSelect: 'none',
+  WebkitUserSelect: 'none',
+  WebkitTouchCallout: 'none',
+  WebkitTapHighlightColor: 'transparent',
+  touchAction: 'none',
+  cursor: 'pointer',
+};

package/kits/basic-3d/engine/autoInspector.jsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { CheckboxField, ColorField, NumberField, Panel, TextField, isHexColor } from './ui';
+export function AutoFields({ defaultProps, component, setComponent, only, exclude }) {
+  const keys = Object.keys(defaultProps).filter((key) => {
+    if (only) return only.includes(key);
+    if (exclude) return !exclude.includes(key);
+    return true;
+  });
+  return (
+    <>
+      {keys.map((key) => {
+        const fallback = defaultProps[key];
+        const current = key in component ? component[key] : fallback;
+        const set = (value) => setComponent({ [key]: value });
+        const label = humanizeKey(key);
+        const sample = fallback ?? current;
+        if (typeof sample === 'number') {
+          return <NumberField key={key} label={label} value={current} onChange={set} />;
+        }
+        if (typeof sample === 'boolean') {
+          return <CheckboxField key={key} label={label} checked={current} onChange={set} />;
+        }
+        if (isHexColor(sample)) {
+          return <ColorField key={key} label={label} value={current} onChange={set} />;
+        }
+        return (
+          <TextField
+            key={key}
+            label={label}
+            value={current == null ? '' : String(current)}
+            onChange={set}
+          />
+        );
+      })}
+    </>
+  );
+}
+export function AutoInspector({ behaviorName, defaultProps, component, setComponent }) {
+  return (
+    <Panel title={humanizeKey(behaviorName)}>
+      <AutoFields defaultProps={defaultProps} component={component} setComponent={setComponent} />
+    </Panel>
+  );
+}
+// `deadZoneY` -> `Dead Zone Y`, `PlatformerCharacter` -> `Platformer Character`.
+export function humanizeKey(key) {
+  return key
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/^./, (c) => c.toUpperCase())
+    .trim();
+}

package/kits/basic-3d/engine/files.js

@@ -0,0 +1,73 @@
+// Seed the file map by scanning the deck dir. Vite module-cache is invalidated
+// on restart, so a newly-created file just shows up on the next reload.
+const rawModules = import.meta.glob(
+  ['../scenes/*.scene', '../models/*.model', '../behaviors/*.jsx'],
+  { query: '?raw', import: 'default', eager: true }
+);
+export const initialFiles = Object.fromEntries(
+  Object.entries(rawModules)
+    .map(([globPath, text]) => [globPath.replace(/^\.\.\//, ''), text])
+    .sort(([a], [b]) => a.localeCompare(b))
+);
+export function getFileKind(path) {
+  if (path.endsWith('.scene')) return 'scene';
+  if (path.endsWith('.model')) return 'model';
+  if (path.endsWith('.js') || path.endsWith('.jsx')) return 'code';
+  return 'text';
+}
+export function parseJsonFile(path, text) {
+  try {
+    return { value: JSON.parse(text), error: null };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { value: null, error: `${path}: ${message}` };
+  }
+}
+export function formatJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+export function basename(path) {
+  return path.split('/').pop() ?? path;
+}
+// Flat list of file paths in the order FileBrowser renders them: a
+// depth-first walk of the directory tree, mirroring buildFileTree there.
+export function flatFileOrder(paths) {
+  const root = { isFile: false, path: '', children: [], childMap: new Map() };
+  for (const path of paths) {
+    const parts = path.split('/');
+    let parent = root;
+    for (let index = 0; index < parts.length; index++) {
+      const name = parts[index];
+      const nodePath = parts.slice(0, index + 1).join('/');
+      const isFile = index === parts.length - 1;
+      if (!parent.childMap.has(name)) {
+        const node = { isFile, path: nodePath, children: [], childMap: new Map() };
+        parent.childMap.set(name, node);
+        parent.children.push(node);
+      }
+      const child = parent.childMap.get(name);
+      if (!child || child.isFile) break;
+      parent = child;
+    }
+  }
+  const order = [];
+  const walk = (node) => {
+    for (const child of node.children) {
+      if (child.isFile) order.push(child.path);
+      else walk(child);
+    }
+  };
+  walk(root);
+  return order;
+}
+
+// Parse every `.model` file into a map for `scene.models`.
+export function parseModels(files) {
+  const models = {};
+  for (const [path, text] of Object.entries(files)) {
+    if (!path.endsWith('.model')) continue;
+    const parsed = parseJsonFile(path, text);
+    if (parsed.value) models[path] = parsed.value;
+  }
+  return models;
+}