incanto 0.29.0 → 0.31.0

package/bin/incanto-editor.mjs

@@ -9,7 +9,7 @@
  *
  * API (the page can only address *.scene.json files under the launch directory):
  *   GET  /api/meta            → { version, mode, root, input?, output? }
- *   GET  /api/scenes          → [{ rel, abs }]            (project mode)
+ *   GET  /api/scenes          → [{ rel, abs, size, modified, scene?|notScene? }]
  *   POST /api/scenes          → { path } creates a minimal scene (project mode)
  *   GET  /api/scene[?file=]   → scene JSON  (single mode ignores ?file=)
  *   PUT  /api/scene[?file=]   → validates the scene shape, writes the file
@@ -27,7 +27,7 @@
  * request host. Bodies are capped at 8MB. Addressable paths are root-bounded
  * and must end in .scene.json.
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { createServer } from 'node:http';
 import { basename, dirname, extname, join, normalize, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -213,9 +213,20 @@ function discoverScenes() {
     for (const e of entries) {
       if (e.isDirectory()) {
         if (!SKIP_DIRS.has(e.name) && !e.name.startsWith('.')) walk(join(dir, e.name), depth + 1);
-      } else if (e.name.endsWith('.scene.json')) {
+      } else if (e.name.endsWith('.json')) {
         const abs = join(dir, e.name);
-        found.push({ rel: relative(ROOT, abs), abs });
+        // size + mtime are what the browser prints beside each row; a folder
+        // whose files are all "just now" is the one you were working in
+        let size = 0;
+        let modified = 0;
+        try {
+          const stat = statSync(abs);
+          size = stat.size;
+          modified = stat.mtimeMs;
+        } catch {
+          // listed without facts beats not listed at all
+        }
+        found.push({ rel: relative(ROOT, abs), abs, size, modified, ...inspectJson(abs, size) });
       }
     }
   };
@@ -223,9 +234,65 @@ function discoverScenes() {
   return found.sort((a, b) => a.rel.localeCompare(b.rel));
 }
 
-/** Root-bounded, *.scene.json-only — the page can never address anything else. */
+/**
+ * Is this JSON a scene? The file says so itself — `type: "scene"`, the same key
+ * the loader demands — so a row can be marked instead of guessed from its name.
+ */
+function sceneFacts(json) {
+  if (json === null || typeof json !== 'object' || Array.isArray(json)) {
+    return { ok: false, why: 'the file is JSON, but not a JSON object' };
+  }
+  if (json.type !== 'scene') {
+    return {
+      ok: false,
+      why:
+        json.type === undefined
+          ? '"type" must be "scene", and this file has no "type"'
+          : `"type" must be "scene", not ${JSON.stringify(json.type)}`,
+    };
+  }
+  if (json.format !== 1)
+    return { ok: false, why: `"format" must be 1, not ${JSON.stringify(json.format)}` };
+  if (typeof json.root !== 'object' || json.root === null) {
+    return { ok: false, why: '"root" must be a node object' };
+  }
+  const count = (n) =>
+    Array.isArray(n?.children) ? n.children.reduce((t, c) => t + count(c), 1) : 1;
+  return {
+    ok: true,
+    name: typeof json.name === 'string' ? json.name : '',
+    // only when the file SAYS so — `dimension` is optional and has no default
+    ...(json.dimension === '2d' || json.dimension === '3d' ? { dimension: json.dimension } : {}),
+    nodes: count(json.root),
+  };
+}
+
+function inspectJson(abs, size) {
+  if (size > 16_000_000) return { notScene: 'too large to check without opening it' };
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(abs, 'utf-8'));
+  } catch (error) {
+    return { notScene: `not valid JSON: ${String(error.message ?? error)}` };
+  }
+  const facts = sceneFacts(parsed);
+  return facts.ok
+    ? {
+        scene: {
+          name: facts.name,
+          ...(facts.dimension ? { dimension: facts.dimension } : {}),
+          nodes: facts.nodes,
+        },
+      }
+    : { notScene: facts.why };
+}
+
+/**
+ * Root-bounded, .json-only — the browser offers every JSON and the LOAD decides,
+ * but this must never become a way to read .env or somebody's key file.
+ */
 function resolveSceneFile(rel) {
-  if (typeof rel !== 'string' || !rel.endsWith('.scene.json')) return null;
+  if (typeof rel !== 'string' || !rel.endsWith('.json')) return null;
   const abs = normalize(resolve(ROOT, rel));
   if (abs !== ROOT && !abs.startsWith(ROOT + sep)) return null;
   return abs;
@@ -276,18 +343,6 @@ function originAllowed(req) {
   }
 }
 
-function isSceneShaped(json) {
-  return (
-    json !== null &&
-    typeof json === 'object' &&
-    json.format === 1 &&
-    json.type === 'scene' &&
-    typeof json.name === 'string' &&
-    json.root !== null &&
-    typeof json.root === 'object'
-  );
-}
-
 function readBody(req, res, onJson) {
   const chunks = [];
   let received = 0;
@@ -346,18 +401,23 @@ const server = createServer((req, res) => {
         return send(res, 403, JSON.stringify({ error: 'cross-origin write rejected' }));
       }
       readBody(req, res, (body) => {
-        const abs = resolveSceneFile(body?.path);
+        // a path with no extension means the usual thing, so `levels/arena` works
+        const wanted =
+          typeof body?.path === 'string' && body.path && !body.path.endsWith('.json')
+            ? `${body.path}.scene.json`
+            : body?.path;
+        const abs = resolveSceneFile(wanted);
         if (!abs) {
           return send(
             res,
             400,
-            JSON.stringify({ error: 'path must be a *.scene.json inside the project' }),
+            JSON.stringify({ error: 'path must be a .json file inside the project' }),
           );
         }
         if (existsSync(abs)) {
-          return send(res, 409, JSON.stringify({ error: `already exists: ${body.path}` }));
+          return send(res, 409, JSON.stringify({ error: `already exists: ${wanted}` }));
         }
-        const name = basename(abs).replace(/\.scene\.json$/, '') || 'Scene';
+        const name = basename(abs).replace(/\.scene\.json$|\.json$/, '') || 'Scene';
         const scene = {
           format: 1,
           type: 'scene',
@@ -388,26 +448,39 @@ const server = createServer((req, res) => {
       );
     }
     if (req.method === 'GET') {
+      let text;
+      let parsed;
       try {
-        const text = readFileSync(target.input, 'utf-8');
-        JSON.parse(text); // must at least be JSON before the page gets it
-        return send(res, 200, text);
+        text = readFileSync(target.input, 'utf-8');
+        parsed = JSON.parse(text); // must at least be JSON before the page gets it
       } catch (error) {
         return send(res, 422, JSON.stringify({ error: String(error.message ?? error) }));
       }
+      // A JSON that is not a scene is refused WITH THE REASON and its contents
+      // never leave: "offer everything, explain the no" must not also mean
+      // "this server will read you any JSON in the project".
+      const facts = sceneFacts(parsed);
+      if (!facts.ok) {
+        return send(
+          res,
+          422,
+          JSON.stringify({ error: `not an incanto scene — ${facts.why}.`, notScene: true }),
+        );
+      }
+      return send(res, 200, text);
     }
     if (req.method === 'PUT') {
       if (!originAllowed(req)) {
         return send(res, 403, JSON.stringify({ error: 'cross-origin write rejected' }));
       }
       readBody(req, res, (json, raw) => {
-        if (!isSceneShaped(json)) {
+        const shape = sceneFacts(json);
+        if (!shape.ok) {
           return send(
             res,
             422,
             JSON.stringify({
-              error:
-                'not an incanto scene — required: format: 1, type: "scene", name: string, root: object. The file was NOT written.',
+              error: `not an incanto scene — ${shape.why}. The file was NOT written.`,
             }),
           );
         }

package/dist/2d.d.ts

@@ -1,7 +1,7 @@
+import { C as RendererStats, S as GameStats, X as Node, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-D_jMpFh8.js";
+import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-BJb-CWfA.js";
 import { i as SceneJson, s as JsonObject } from "./schema-CcoWb32N.js";
-import { $ as Node, C as RendererStats, S as GameStats, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-BAc0erXF.js";
-import { t as EditorSwitchOptions } from "./editor-switch-B0wB_DSr.js";
-import { t as LoadSceneOptions } from "./loader-B242FF6N.js";
+import { t as LoadSceneOptions } from "./loader-BYBrqTxP.js";
 import { t as ParticleSim } from "./particle-sim-CwJ5rI_P.js";
 import { Group, Mesh, Object3D, Scene, Texture } from "three";
 import * as RapierNs from "@dimforge/rapier2d-compat";
@@ -24,9 +24,15 @@ interface SheetInfo {
 * `"$key"`. The texture loader is injectable so tests run headless.
 */
 declare class AssetStore2D {
+  private readonly engine;
   private readonly entries;
   private readonly loader;
-  constructor(loader?: (url: string, callbacks?: TextureLoadCallbacks) => Texture);
+  /**
+  * `engine` is optional so a bare store still constructs in tests. Given one,
+  * a texture that fails to load lands in `engine.log` — where the overlay and
+  * `runScript()` can see it — instead of only in the browser console.
+  */
+  constructor(loader?: (url: string, callbacks?: TextureLoadCallbacks) => Texture, engine?: DiagnosticSink | null);
   /** Load (or extend with) a scene's `assets` declarations. Hard-validates each entry. */
   load(assets: Record<string, JsonObject>): void;
   /** Load status of a declared asset KEY (no '$'), or undefined if unknown. */
@@ -146,6 +152,12 @@ type Rapier = typeof RapierNs;
 interface Physics2DOptions {
   /** px/s², y-down. Default: scene `physics.gravity`, else [0, 980]. */
   gravity?: [number, number];
+  /**
+  * Build the colliders and keep them on the tree, but never advance the world
+  * (default: `true`, i.e. simulate). See {@link Physics3DOptions.simulate} —
+  * the scene editor uses it to draw the REAL colliders without running them.
+  */
+  simulate?: boolean;
 }
 /**
 * Enable 2D physics for an engine. Dynamically imports Rapier (compat build,
@@ -158,7 +170,7 @@ declare function enablePhysics2D(engine: Engine, opts?: Physics2DOptions): Promi
 */
 declare class Physics2D {
   private readonly R;
-  private readonly engine;
+  readonly engine: Engine;
   /** Render collider outlines in the GAME view (renderers pick this up). */
   debugDraw: boolean;
   /** Narrow those outlines to one node's subtree (see DebugLineSource). */
@@ -177,6 +189,8 @@ declare class Physics2D {
   private lastScene;
   constructor(R: Rapier, engine: Engine, opts?: Physics2DOptions);
   /** @internal Driven by engine.fixedUpdated. */
+  /** Whether the solver runs at all. False = collider outlines only. */
+  private readonly simulate;
   step(dt: number): void;
   /** @internal Called by CharacterBody2D.moveAndSlide (during tree fixedUpdate). */
   moveAndSlide(node: CharacterBody2D): void;
@@ -210,6 +224,13 @@ declare class Physics2D {
   private readonly jointSet;
   private readonly joints;
   private readonly bodySet;
+  /**
+  * Move every body to its node's current transform — outline mode only.
+  *
+  * Computed exactly as `ensureEntry` computes a body's first pose, so an
+  * outline drawn in the editor is the outline the running game draws.
+  */
+  private poseFromTree;
   private syncBodies;
   private ensureEntry;
 }
@@ -742,7 +763,8 @@ declare class Renderer2D {
   private readonly worldCam;
   private readonly uiCam;
   private readonly engine;
-  private readonly assets;
+  /** The texture store. Public so `renderer.assets.status(key)` is reachable. */
+  readonly assets: AssetStore2D;
   private readonly loadedAssetScenes;
   private readonly disconnect;
   private readonly canvas;

package/dist/2d.js

@@ -1,7 +1,7 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-CbuLWorm.js";
-import { _ as RigidBody2D, a as parseCells, c as ColorRect2D, d as AnimatedSprite2D, f as Sprite2D, g as PhysicsBody2D, h as CharacterBody2D, i as mergeSolidRects, l as CharacterController2D, m as Area2D, n as UILayer, o as Particles2D, p as Joint2D, r as TileMap2D, s as Label, t as registerNodes2D, u as Camera2D, v as StaticBody2D, y as Node2D } from "./register-DWcWq4QG.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-CCVTrKOd.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-z5XaB1p5.js";
+import { _ as RigidBody2D, a as parseCells, c as ColorRect2D, d as AnimatedSprite2D, f as Sprite2D, g as PhysicsBody2D, h as CharacterBody2D, i as mergeSolidRects, l as CharacterController2D, m as Area2D, n as UILayer, o as Particles2D, p as Joint2D, r as TileMap2D, s as Label, t as registerNodes2D, u as Camera2D, v as StaticBody2D, y as Node2D } from "./register-tkR_8tWg.js";
+import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-D9wquBvK.js";
 //#region src/2d/library-sprite.ts
 /**
 * Turn a library sprite-animation JSON into a scene-ready spritesheet asset

package/dist/3d.d.ts

@@ -1,9 +1,9 @@
+import { C as RendererStats, S as GameStats, X as Node, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-D_jMpFh8.js";
+import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-BJb-CWfA.js";
 import { i as SceneJson, s as JsonObject } from "./schema-CcoWb32N.js";
-import { $ as Node, C as RendererStats, S as GameStats, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-BAc0erXF.js";
-import { t as EditorSwitchOptions } from "./editor-switch-B0wB_DSr.js";
-import { t as LoadSceneOptions } from "./loader-B242FF6N.js";
+import { t as LoadSceneOptions } from "./loader-BYBrqTxP.js";
 import { t as ParticleSim } from "./particle-sim-CwJ5rI_P.js";
-import { n as PathGrid, s as SpatialPose } from "./pathfinding-BwD974Ss.js";
+import { n as PathGrid, s as SpatialPose } from "./pathfinding-BwhqPD3i.js";
 import { AnimationClip, AnimationMixer, BufferGeometry, Color, DirectionalLight, Group, InstancedMesh, Mesh, MeshPhysicalMaterial, Object3D, PerspectiveCamera, Scene, ShaderMaterial, Vector3, WebGLRenderer } from "three";
 import { VRM } from "@pixiv/three-vrm";
 import { Sky } from "three/examples/jsm/objects/Sky.js";
@@ -44,12 +44,28 @@ interface AnimationEntry {
 * @pixiv/three-vrm (VRM 0.x facing fixed via rotateVRM0).
 */
 declare class AssetStore3D {
+  private readonly engine;
   private readonly models;
   private readonly animations;
   private readonly modelKeys;
   private readonly animationKeys;
   private readonly loader;
-  constructor();
+  /**
+  * `engine` is optional only so a bare store still constructs in tests. Give it
+  * one and every load failure lands in `engine.log` — where the debug overlay,
+  * `runScript()` and any agent tool can see it. Without it a 404'd GLB was a
+  * console line and an invisible model.
+  */
+  constructor(engine?: DiagnosticSink | null);
+  /**
+  * Every asset that failed, with the reason — the answer to "why is my model
+  * not there". Empty is the healthy case.
+  */
+  errors(): Array<{
+    ref: string;
+    url: string;
+    error: string;
+  }>;
   /** Map a scene's `assets` header. */
   load(assets: JsonObject): void;
   /** Animation `$key`s declared by the scene (editor dropdowns). */
@@ -185,6 +201,13 @@ declare class Node3D extends Node {
   * back to a local Y by subtracting the parents' offset.
   */
   applyGroundSnap(): void;
+  /**
+  * @internal The backing object IF it has been built — never builds one.
+  *
+  * `_ensureObject3D()` is the wrong call during teardown: it allocates a mesh
+  * for a node that never rendered, purely so the next line can dispose it.
+  */
+  protected get _builtObject3D(): Object3D | null;
   /** @internal The backing three object (lazily created). */
   _ensureObject3D(): Object3D;
   /** @internal Override point for subclasses (mesh, camera, light…). */
@@ -269,6 +292,20 @@ type Rapier = typeof RapierNs;
 interface Physics3DOptions {
   /** m/s², y-up. Default: scene `physics.gravity`, else [0, -9.81, 0]. */
   gravity?: [number, number, number];
+  /**
+  * Build the colliders and keep them on the tree, but never advance the world
+  * (default: `true`, i.e. simulate).
+  *
+  * This exists for the scene editor. "Show colliders" there used to hand-draw
+  * wireframes from the `collider` JSON — which cannot show what the engine
+  * actually creates, because the shape is not always in the JSON (a mesh-fitted
+  * body, a scatter's hulls, a character capsule) and the drawing ignored
+  * rotation and scale. With `simulate: false` the editor gets the SAME lines
+  * play mode gets, from the same Rapier world, without anything falling over
+  * the moment you look at it: bodies are posed FROM the tree each tick and the
+  * solver never runs.
+  */
+  simulate?: boolean;
 }
 /**
 * Enable 3D physics for an engine. Dynamically imports Rapier (compat build)
@@ -279,7 +316,7 @@ declare function enablePhysics3D(engine: Engine, opts?: Physics3DOptions): Promi
 /** Per-engine 3D physics world. Same contract as Physics2D. */
 declare class Physics3D {
   private readonly R;
-  private readonly engine;
+  readonly engine: Engine;
   /** Render collider outlines in the GAME view (renderers pick this up). */
   debugDraw: boolean;
   /** Narrow those outlines to one node's subtree (see DebugLineSource). */
@@ -297,8 +334,20 @@ declare class Physics3D {
   private readonly optsGravity;
   private lastScene;
   constructor(R: Rapier, engine: Engine, opts?: Physics3DOptions);
+  /** Whether the solver runs at all. False = collider outlines only. */
+  private readonly simulate;
   /** @internal Driven by engine.fixedUpdated. */
   step(dt: number): void;
+  /**
+  * Move every body to its node's current transform.
+  *
+  * Only used in outline mode: normally physics owns the pose and writes it
+  * INTO the node, so nothing re-reads the tree. Deliberately computed the same
+  * way `ensureEntry` computes a body's initial pose — world position, node-local
+  * euler — so an outline in the editor is the outline the game will draw, right
+  * down to the places where that pair disagrees with a rotated parent.
+  */
+  private poseFromTree;
   /** @internal Called by CharacterBody3D.moveAndSlide (during tree fixedUpdate). */
   moveAndSlide(node: CharacterBody3D): void;
   /** Rapier debug segments (meters). Null while debugDraw is off. */
@@ -462,6 +511,14 @@ interface CreateGame3DOptions {
 interface GameRenderer {
   dispose(): void;
   stats?(): RendererStats;
+  /** Loaded models/animations — `assets.errors()` answers "why is my model missing". */
+  assets?: {
+    errors(): Array<{
+      ref: string;
+      url: string;
+      error: string;
+    }>;
+  };
 }
 interface Game3D {
   engine: Engine;
@@ -480,6 +537,18 @@ interface Game3D {
   /** Engine + renderer perf counters in one read (fps/nodes/triangles/…). */
   stats(): GameStats;
   /**
+  * Assets that failed to load, with the reason.
+  *
+  * "The model just never appeared" used to be unanswerable from outside: the
+  * store was private on the renderer and the 404 went to the console only.
+  * Check this — and `stats().errors` — before assuming a scene is fine.
+  */
+  assetErrors(): Array<{
+    ref: string;
+    url: string;
+    error: string;
+  }>;
+  /**
   * Turn this page into the scene editor, right where the player is standing —
   * what the ☰ debug menu's "edit this scene" calls. Bind it to your own key or
   * button if you want the switch without the overlay.
@@ -2958,7 +3027,12 @@ declare class Renderer3D {
   private readonly engine;
   private readonly disconnect;
   private readonly canvas;
-  private readonly assets;
+  /**
+  * The model/animation store. Public so a game (and an agent's tool) can ask
+  * `renderer.assets.errors()` why a model is not there — it used to be private,
+  * so a 404'd GLB was unanswerable from outside.
+  */
+  readonly assets: AssetStore3D;
   private readonly ownsAssets;
   private readonly loadedAssetScenes;
   /** The scene whose GPU programs have been pre-compiled (warm-up, see render). */

package/dist/3d.js

@@ -1,9 +1,9 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { A as Water3D, F as PhysicsBody3D, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D, V as WATER_MAX_RIPPLES, j as WATER_CUTOUT_MAX } from "./gameplay-L05WgWd1.js";
-import { a as Environment3D, c as sunDirectionFromElevationAzimuth, i as syncTree, l as sunDirectionFromSky, o as horizonColorFromSky, r as Renderer3D, s as parseEnvironment3D, t as createGame3D, u as AssetStore3D } from "./create-game-CNKXGfpr.js";
-import { A as DEFAULT_TERRAIN_TEXTURE_BASE, B as movementState, C as FLOWER_VARIETIES, D as BoneAttachment3D, E as BoneLookAt3D, F as MeshInstance3D, L as QUARTER_PITCH, M as terrainThemeLayers, N as Joint3D, O as Billboard3D, P as InstancedMesh3D, R as cameraRelative, S as resolveFlowerDensity, T as Camera3D, V as rigPose, _ as DirectionalLight3D, a as Trail3D, b as DENSITY_PRESETS, c as findRiverCoverageGaps, d as riverStepFor, f as smoothCourse, g as LoftMesh3D, h as ModelInstance3D, i as Tree3D, j as TERRAIN_THEMES, k as Terrain3D, l as projectToRiver, m as Particles3D, n as VOXEL_PALETTE, o as River3D, p as traceDownhillPath, r as VoxelGrid3D, s as buildRiverRings, t as registerNodes3D, u as riverCarveChannels, v as OmniLight3D, w as CharacterController3D, x as Flowers3D, y as Foliage3D, z as keyboardIntensity } from "./register-C44aSduO.js";
+import { A as Water3D, F as PhysicsBody3D, I as RigidBody3D, L as StaticBody3D, M as WaterCutout3D, N as Area3D, P as CharacterBody3D, R as Node3D, V as WATER_MAX_RIPPLES, j as WATER_CUTOUT_MAX } from "./gameplay-BftxM_It.js";
+import { a as Environment3D, c as sunDirectionFromElevationAzimuth, i as syncTree, l as sunDirectionFromSky, o as horizonColorFromSky, r as Renderer3D, s as parseEnvironment3D, t as createGame3D, u as AssetStore3D } from "./create-game-DqOjMBUS.js";
+import { A as Terrain3D, B as keyboardIntensity, C as resolveFlowerDensity, D as BoneLookAt3D, E as Camera3D, F as InstancedMesh3D, H as rigPose, I as MeshInstance3D, M as TERRAIN_THEMES, N as terrainThemeLayers, O as BoneAttachment3D, P as Joint3D, R as QUARTER_PITCH, S as Flowers3D, T as CharacterController3D, V as movementState, _ as LoftMesh3D, a as Tree3D, b as Foliage3D, c as buildRiverRings, d as riverCarveChannels, f as riverStepFor, g as ModelInstance3D, h as Particles3D, i as VoxelGrid3D, j as DEFAULT_TERRAIN_TEXTURE_BASE, k as Billboard3D, l as findRiverCoverageGaps, m as traceDownhillPath, n as registerNodes3D, o as Trail3D, p as smoothCourse, r as VOXEL_PALETTE, s as River3D, u as projectToRiver, v as DirectionalLight3D, w as FLOWER_VARIETIES, x as DENSITY_PRESETS, y as OmniLight3D, z as cameraRelative } from "./environment-presets--DigHNg4.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-BZZLtwJu.js";
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-CnPygVGo.js";
 //#region src/3d/environment-runtime.ts
 /**
 * Live environment editing — the renderer re-applies `scene.environment`

package/dist/{audit-C6rMyict.js → audit-C4kmDK0o.js}

@@ -25,6 +25,19 @@ const HUD_WIDGETS = new Set([
 	"UiButton",
 	"UiDialogue"
 ]);
+const LIGHT_TYPES = new Set([
+	"DirectionalLight3D",
+	"OmniLight3D",
+	"SpotLight3D"
+]);
+/** Does the scene header light anything by itself (sky, hdri, ambient, preset)? */
+function isLit(environment) {
+	if (!environment) return false;
+	if (environment.preset !== void 0 || environment.sky !== void 0) return true;
+	if (environment.hdri !== void 0) return true;
+	const ambient = environment.ambient;
+	return typeof ambient?.intensity === "number" && ambient.intensity > 0;
+}
 /** Human-readable warnings (empty = clean). Pure JSON walk, no registry. */
 function auditScene(scene) {
 	const warnings = [];
@@ -32,6 +45,7 @@ function auditScene(scene) {
 	if (!root) return warnings;
 	let currentCameras = 0;
 	let cameras = 0;
+	let lights = 0;
 	const walk = (node, path, insideHud, staticRoot) => {
 		const type = node.type ?? "";
 		const props = node.props ?? {};
@@ -39,6 +53,7 @@ function auditScene(scene) {
 			cameras += 1;
 			if (props.current === true) currentCameras += 1;
 		}
+		if (LIGHT_TYPES.has(type)) lights += 1;
 		if (BODY_TYPES.has(type)) {
 			const collider = props.collider;
 			if (!collider || collider.shape === void 0) warnings.push(`${path}: ${type} has no collider — physics will skip it (add "collider": { "shape": ... }).`);
@@ -52,6 +67,7 @@ function auditScene(scene) {
 	walk(root, root.name ?? "root", false, root.props?.static === true ? root.name ?? "root" : null);
 	if (cameras > 0 && currentCameras === 0) warnings.push("no camera has \"current\": true — the screen renders from a default view, probably not what you framed.");
 	if (currentCameras > 1) warnings.push(`${currentCameras} cameras claim "current": true — only the first found wins.`);
+	if (scene.dimension === "3d" && lights === 0 && !isLit(scene.environment)) warnings.push("nothing lights this 3D scene — no light node, no environment sky/hdri, and no ambient intensity. It will render black. Add a DirectionalLight3D, or an \"environment\": { \"sky\": { \"type\": \"atmosphere\" } } / { \"preset\": \"...\" }.");
 	return warnings;
 }
 //#endregion