@aethervtt/shard-protocol 0.0.1

package/dist/server.js

@@ -0,0 +1,1086 @@
+import { assetServer } from "@aethervtt/shard-assets";
+import {
+  allComponents,
+  ChildOf,
+  Children,
+  defineSchema,
+  findComponent,
+  findResource,
+  isPlainObject,
+  Last,
+  PostUpdate,
+  ShardError,
+  t
+} from "@aethervtt/shard-core";
+import {
+  describeInput,
+  injectInput,
+  startRecording,
+  startReplay,
+  stopRecording
+} from "@aethervtt/shard-input";
+import {
+  captureBuffer,
+  captureShadowMap,
+  captureView,
+  DebugOverlays,
+  describeRender,
+  Gizmos,
+  Gpu,
+  isOverlayOn,
+  OffscreenTarget,
+  OVERLAYS,
+  overlayNames,
+  pick,
+  raycast,
+  Shaders,
+  setDebugView,
+  setOverlays,
+  Views,
+  Window
+} from "@aethervtt/shard-render";
+import {
+  AppControlResource,
+  LogResource,
+  Time
+} from "@aethervtt/shard-runtime";
+import {
+  applyToPrefab,
+  currentOverrides,
+  expandComponentAliases,
+  findEntityByPath,
+  instanceEntities,
+  loadPrefab,
+  loadScene,
+  pathOfEntity,
+  reloadScene,
+  SceneIndex,
+  saveScene,
+  spawnPrefab,
+  stringifyScene,
+  validateScene,
+  whenSceneReady,
+  worldSchemaContext
+} from "@aethervtt/shard-scene";
+import { Fonts, measureText } from "@aethervtt/shard-text";
+import {
+  createPlacement,
+  FloatingOrigin,
+  Grid,
+  gridOf,
+  placeInGrid,
+  placementOf,
+  Transform,
+  worldPosition64
+} from "@aethervtt/shard-transform";
+import { encodePng, toBase64 } from "./png.js";
+const CAPTURE_DEBUG_VIEWS = ["clusters", "cascades", "lod", "culling", "none"];
+import { previewAsset } from "./preview.js";
+const ERROR = { parse: -32700, invalid: -32600, notFound: -32601, params: -32602, shard: -32e3 };
+function resolveEntity(world, ref) {
+  if (typeof ref === "number" && world.isAlive(ref)) return ref;
+  if (typeof ref === "string") {
+    const e = findEntityByPath(world, ref);
+    if (e !== void 0) return e;
+  }
+  throw new ShardError("protocol/unknown-entity", `No live entity ${JSON.stringify(ref)}`, {
+    hint: 'Pass an entity id from world.query, or a scene path like "ship/camera".'
+  });
+}
+function requireComponent(name) {
+  const def = findComponent(name);
+  if (!def) {
+    throw new ShardError("protocol/unknown-component", `Unknown component "${name}"`, {
+      hint: "schema.list returns every component name."
+    });
+  }
+  return def;
+}
+function toJson(value) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  return JSON.parse(
+    JSON.stringify(value, (_, v) => {
+      if (ArrayBuffer.isView(v)) return Array.from(v);
+      if (typeof v === "function") return void 0;
+      if (v instanceof Map) return Object.fromEntries(v);
+      if (v instanceof Set) return [...v];
+      if (v && typeof v === "object") {
+        if (seen.has(v)) return "[circular]";
+        seen.add(v);
+      }
+      return v;
+    }) ?? "null"
+  );
+}
+function entityJson(world, entity, only) {
+  const components = {};
+  for (const def of world.componentsOf(entity)) {
+    if (!def.serializable && def !== ChildOf) continue;
+    if (only && !only.includes(def.name)) continue;
+    components[def.name] = def.serialize(world.get(entity, def));
+  }
+  const path = pathOfEntity(world, entity);
+  const out = path === void 0 ? { id: entity, components } : { id: entity, path, components };
+  if (!only && hasGrids(world) && world.has(entity, Transform))
+    out.worldPosition64 = [...worldPosition64(world, entity, new Float64Array(3))];
+  return out;
+}
+function hasGrids(world) {
+  return world.query({ with: [Grid] }).count() > 0;
+}
+function firstOf(world, def) {
+  return world.query({ with: [def] }).entities()[0];
+}
+function describeGrids(world) {
+  const place = createPlacement();
+  const refOf = (e) => pathOfEntity(world, e) ?? e;
+  const grids = world.query({ with: [Grid] }).entities().map((e) => {
+    placementOf(world, e, place, true);
+    const children = world.tryGet(e, Children)?.entities ?? [];
+    return {
+      grid: refOf(e),
+      cellSize: world.get(e, Grid).cellSize,
+      parent: place.grid < 0 ? null : refOf(place.grid),
+      cell: [...place.cell],
+      entities: children.filter((c) => c !== null).length
+    };
+  });
+  const originEntity = firstOf(world, FloatingOrigin);
+  let origin = null;
+  if (originEntity !== void 0) {
+    placementOf(world, originEntity, place, true);
+    origin = {
+      entity: refOf(originEntity),
+      grid: place.grid < 0 ? null : refOf(place.grid),
+      cell: [...place.cell]
+    };
+  }
+  return { grids, origin };
+}
+function prepareComponents(world, input, base) {
+  const ctx = worldSchemaContext(world);
+  const out = [];
+  const errors = [];
+  for (const [name, raw] of Object.entries(input)) {
+    const def = requireComponent(name);
+    if (!isPlainObject(raw)) {
+      errors.push(
+        new ShardError("schema/type-mismatch", `"${name}" must be an object`, {
+          path: `${base}/${name}`
+        })
+      );
+      continue;
+    }
+    const json = expandComponentAliases(name, raw);
+    const problems = def.validate(json, ctx);
+    for (const p of problems) {
+      errors.push(
+        new ShardError(p.code, p.message, {
+          path: `${base}/${name.replace("/", "~1")}${p.path ?? ""}`,
+          hint: p.hint
+        })
+      );
+    }
+    if (problems.length === 0) out.push([def, def.deserialize(json, ctx)]);
+  }
+  if (errors.length > 0) {
+    throw new ShardError(
+      "protocol/invalid-components",
+      `${errors.length} invalid value(s); first: ${errors[0].message}`,
+      {
+        path: errors[0].path,
+        hint: errors[0].hint,
+        details: errors
+      }
+    );
+  }
+  return out;
+}
+async function readJson(ctx, file) {
+  if (!ctx.options.platform)
+    throw new ShardError("protocol/no-files", "This host can't read files; pass JSON instead");
+  return JSON.parse(await ctx.options.platform.fs.readText(file));
+}
+function renderOnly(app) {
+  app.runSchedule(PostUpdate);
+  app.runSchedule(Last);
+}
+async function whenRenderReady(world, render) {
+  const gpu = world.tryResource(Gpu);
+  const shaders = world.tryResource(Shaders);
+  if (!gpu) return;
+  for (let i = 0; i < 20; i++) {
+    await render();
+    await shaders?.whenIdle();
+    await gpu.pipelines.whenIdle();
+    if (gpu.pipelines.skipped === 0 && gpu.pipelines.pending === 0) return;
+  }
+}
+function checkOverlays(list) {
+  const names = list ?? [];
+  const known = overlayNames();
+  for (const name of names) {
+    if (!known.includes(name)) {
+      throw new ShardError("protocol/unknown-overlay", `Unknown overlay "${name}"`, {
+        hint: `Overlays: ${known.join(", ")}.`
+      });
+    }
+  }
+  return names;
+}
+function applyOverlays(world, names, components, path) {
+  const o = world.resource(DebugOverlays);
+  const all = overlayNames();
+  const before = {
+    on: Object.fromEntries(all.map((k) => [k, isOverlayOn(o, k)])),
+    filter: { ...o.filter }
+  };
+  setOverlays(world, Object.fromEntries(all.map((k) => [k, names.includes(k)])), {
+    components,
+    path
+  });
+  return () => setOverlays(world, before.on, before.filter);
+}
+function hitJson(hit) {
+  return {
+    entity: hit.entity,
+    path: hit.path ?? null,
+    position: hit.position,
+    normal: hit.normal,
+    distance: hit.distance
+  };
+}
+function nextFrame(app) {
+  return new Promise((resolve) => {
+    const off = app.onFrame(() => {
+      off();
+      resolve();
+    });
+  });
+}
+function depthImage(map) {
+  let lo = Number.POSITIVE_INFINITY;
+  let hi = 0;
+  for (let i = 0; i < map.data.length; i += 4) {
+    const d = map.data[i];
+    if (d > 0) {
+      if (d < lo) lo = d;
+      if (d > hi) hi = d;
+    }
+  }
+  const data = new Uint8Array(map.width * map.height * 4);
+  const span = hi > lo ? hi - lo : 1;
+  for (let i = 0; i < map.data.length; i += 4) {
+    const d = map.data[i];
+    const v = d > 0 ? Math.round(40 + (d - lo) / span * 215) : 0;
+    data[i] = data[i + 1] = data[i + 2] = v;
+    data[i + 3] = 255;
+  }
+  return { width: map.width, height: map.height, data };
+}
+function placementParams(world, entity, p) {
+  const position = p.position64;
+  const hasGrid = p.grid !== null && p.grid !== void 0;
+  if (!position || position.length === 0) {
+    if (hasGrid) {
+      throw new ShardError("protocol/invalid-position64", '"grid" needs "position64"', {
+        path: "/position64",
+        hint: 'Pass { "position64": [x, y, z], "grid": <grid> } together.'
+      });
+    }
+    return void 0;
+  }
+  if (position.length !== 3 || !position.every((v) => Number.isFinite(v))) {
+    throw new ShardError("protocol/invalid-position64", '"position64" must be [x, y, z]', {
+      path: "/position64",
+      hint: "Three finite numbers in metres, e.g. [3.8e8, 0, 0]."
+    });
+  }
+  const grid = hasGrid ? resolveEntity(world, p.grid) : gridOf(world, entity);
+  if (grid === void 0 || !world.has(grid, Grid)) {
+    throw new ShardError(
+      "protocol/not-a-grid",
+      hasGrid ? `${JSON.stringify(p.grid)} is not a Grid` : "The entity is not in a grid",
+      {
+        path: "/grid",
+        hint: 'Pass "grid": the id or path of an entity with transform/Grid.'
+      }
+    );
+  }
+  return { grid, position };
+}
+const s = (name, fields) => defineSchema(`protocol/${name}`, fields);
+const entityRef = () => t.entity({ required: true, description: 'Entity id, or scene path like "ship/camera".' });
+const none = s("None", {});
+const METHODS = [
+  {
+    name: "app.describe",
+    description: "Plugins, schedules, and systems in run order; renderer and input state when present.",
+    params: none,
+    handler: ({ app, world }) => {
+      const out = { ...app.describe(), entities: world.entityCount };
+      if (world.tryResource(Views)) out.render = describeRender(world);
+      try {
+        out.input = describeInput(world);
+      } catch {
+      }
+      out.scenes = [...world.tryResource(SceneIndex)?.keys() ?? []];
+      if (hasGrids(world)) out.grids = describeGrids(world);
+      return toJson(out);
+    }
+  },
+  {
+    name: "schema.list",
+    description: "Every defined component with its description and JSON Schema.",
+    params: none,
+    handler: () => allComponents().filter((d) => !d.name.startsWith("protocol/")).map((d) => ({
+      name: d.name,
+      description: d.description,
+      serializable: d.serializable,
+      requires: d.requires.map((r) => r.name)
+    }))
+  },
+  {
+    name: "schema.get",
+    description: "One component's JSON Schema (fields, types, ranges, presets, descriptions).",
+    params: s("SchemaGetParams", {
+      name: t.string({ required: true, description: 'Component name, e.g. "render/Camera3d".' })
+    }),
+    handler: (_, p) => requireComponent(p.name).jsonSchema()
+  },
+  {
+    name: "world.stats",
+    description: "Entity and archetype counts, and table memory.",
+    params: none,
+    handler: ({ world }) => world.stats()
+  },
+  {
+    name: "world.query",
+    description: "Entities that have every component in `with` and none in `without`, with their component values.",
+    params: s("QueryParams", {
+      with: t.list(t.string, { description: "Component names the entity must have." }),
+      without: t.list(t.string, { description: "Component names the entity must not have." }),
+      fields: t.list(t.string, { description: "Only include these components (default: all)." }),
+      limit: t.u32({ default: 50, min: 1, description: "Maximum entities returned." })
+    }),
+    handler: ({ world }, p) => {
+      const q = world.query({
+        with: p.with.map(requireComponent),
+        without: p.without.map(requireComponent)
+      });
+      const fields = p.fields.length > 0 ? p.fields : void 0;
+      const ids = q.entities().slice(0, p.limit);
+      return { total: q.count(), entities: ids.map((e) => entityJson(world, e, fields)) };
+    }
+  },
+  {
+    name: "entity.get",
+    description: "All components of one entity as JSON. With grids, also worldPosition64: its exact position relative to the floating origin.",
+    params: s("EntityGetParams", { entity: entityRef() }),
+    handler: ({ world }, p) => entityJson(world, resolveEntity(world, p.entity))
+  },
+  {
+    name: "entity.spawn",
+    description: "Spawns an entity from component JSON (validated; required components are added).",
+    params: s("SpawnParams", {
+      components: t.json({ description: "Component values by name, as in scene files." }),
+      parent: t.entity({ description: "Optional parent entity or path." })
+    }),
+    handler: ({ world }, p) => {
+      const inits = prepareComponents(
+        world,
+        p.components ?? {},
+        "/components"
+      );
+      if (p.parent !== null && p.parent !== void 0)
+        inits.push([ChildOf, { parent: resolveEntity(world, p.parent) }]);
+      const entity = world.spawn(...inits);
+      return entityJson(world, entity);
+    }
+  },
+  {
+    name: "entity.patch",
+    description: "Merges fields into components (adding missing ones). All values are validated before anything changes; null removes a component. position64 + grid places the entity at an exact f64 position in a grid (cell and translation computed for you).",
+    params: s("PatchParams", {
+      entity: entityRef(),
+      components: t.json({ description: "Partial values by component name." }),
+      position64: t.list(t.f64, {
+        description: "Exact position [x, y, z] in metres in `grid`'s frame; sets GridCell, Transform.translation, and the parent."
+      }),
+      grid: t.entity({
+        description: "Grid entity or path for position64 (default: the grid the entity is in)."
+      })
+    }),
+    handler: ({ world }, p) => {
+      const entity = resolveEntity(world, p.entity);
+      const place = placementParams(world, entity, p);
+      const patch = p.components ?? {};
+      const merged = {};
+      const removals = [];
+      for (const [name, value] of Object.entries(patch)) {
+        const def = requireComponent(name);
+        if (value === null) {
+          removals.push(def);
+          continue;
+        }
+        const current = world.has(entity, def) ? def.serialize(world.get(entity, def)) : {};
+        const partial = value;
+        const base = { ...current };
+        if (name === "core/Transform" && "rotationEuler" in partial) delete base.rotation;
+        merged[name] = { ...base, ...partial };
+      }
+      const prepared = prepareComponents(world, merged, "/components");
+      for (const [def, value] of prepared) {
+        if (world.has(entity, def)) world.set(entity, def, value);
+        else world.add(entity, def, value);
+      }
+      for (const def of removals) world.remove(entity, def);
+      if (place) placeInGrid(world, entity, place.grid, place.position);
+      return entityJson(world, entity);
+    }
+  },
+  {
+    name: "entity.despawn",
+    description: "Despawns an entity (and its children unless recursive is false).",
+    params: s("DespawnParams", { entity: entityRef(), recursive: t.bool({ default: true }) }),
+    handler: ({ world }, p) => {
+      const entity = resolveEntity(world, p.entity);
+      if (p.recursive) world.despawn(entity);
+      else world.despawnSingle(entity);
+      return { despawned: entity };
+    }
+  },
+  {
+    name: "resource.get",
+    description: "A resource's current value as JSON.",
+    params: s("ResourceGetParams", { name: t.string({ required: true }) }),
+    handler: ({ world }, p) => {
+      const def = findResource(p.name);
+      if (!def || !world.hasResource(def)) {
+        throw new ShardError(
+          "protocol/unknown-resource",
+          `Resource "${p.name}" is not in the world`
+        );
+      }
+      return toJson(world.resource(def));
+    }
+  },
+  {
+    name: "resource.set",
+    description: "Merges fields into a plain-object resource (e.g. render/AmbientLight).",
+    params: s("ResourceSetParams", { name: t.string({ required: true }), value: t.json() }),
+    handler: ({ world }, p) => {
+      const def = findResource(p.name);
+      const current = def && world.tryResource(def);
+      if (!def || !isPlainObject(current)) {
+        throw new ShardError(
+          "protocol/unsettable-resource",
+          `Resource "${p.name}" can't be set from JSON`,
+          {
+            hint: "Only resources that are plain JSON objects can be set."
+          }
+        );
+      }
+      if (!isPlainObject(p.value))
+        throw new ShardError("schema/type-mismatch", '"value" must be an object', {
+          path: "/value"
+        });
+      Object.assign(current, p.value);
+      return toJson(current);
+    }
+  },
+  {
+    name: "time.pause",
+    description: "Pauses the game (rendering continues showing the last frame).",
+    params: none,
+    handler: ({ world }) => {
+      world.resource(AppControlResource).paused = true;
+      return { paused: true, frame: world.resource(Time).frame };
+    }
+  },
+  {
+    name: "time.resume",
+    description: "Resumes a paused game.",
+    params: none,
+    handler: ({ world }) => {
+      const control = world.resource(AppControlResource);
+      control.paused = false;
+      control.pausedByError = false;
+      return { paused: false, frame: world.resource(Time).frame };
+    }
+  },
+  {
+    name: "time.step",
+    description: "Pauses and runs exactly `frames` frames at the fixed timestep, then returns.",
+    params: s("StepParams", {
+      frames: t.u32({ default: 1, min: 1, max: 1e5, description: "Frames to run." })
+    }),
+    handler: async ({ app, world, options }, p) => {
+      const control = world.resource(AppControlResource);
+      const done = control.step(p.frames);
+      done.catch(() => {
+      });
+      if ((options.frames ?? "manual") === "manual") app.pump();
+      await done;
+      return { frame: world.resource(Time).frame, elapsed: world.resource(Time).elapsed };
+    }
+  },
+  {
+    name: "render.capture",
+    description: "A PNG of a camera view (default: the first camera). Renders the current state without advancing time.",
+    params: s("CaptureParams", {
+      camera: t.entity({ description: "Camera entity or path (default: first camera view)." }),
+      width: t.u32({
+        min: 0,
+        max: 4096,
+        description: "Resize the headless target first (0 = keep)."
+      }),
+      height: t.u32({ min: 0, max: 4096 }),
+      debug: t.string({
+        description: "A debug view instead of the image: 'clusters' (lights per cluster heat map), 'cascades' (cascades tinted by index), 'lod' (meshes tinted by LOD level: green, yellow, orange, red), 'shadow-map:<light>[:<layer>]' (a light's raw shadow map), or 'culling' (freezes what the camera culls with, and keeps it frozen for later captures while the camera moves; 'none' unfreezes)."
+      }),
+      overlays: t.list(t.string, {
+        description: `Debug overlays drawn into this capture only: ${OVERLAYS.join(", ")}, plus any a plugin registers (e.g. colliders). 'labels' writes each entity's scene path next to it; 'bounds' outlines what the renderer thinks is there.`
+      }),
+      filter: t.string({
+        description: 'Limit overlays to entities whose scene path starts with this, e.g. "ship/".'
+      }),
+      components: t.list(t.string, {
+        description: "Limit overlays to entities with all these components."
+      }),
+      buffer: t.string({
+        description: "Raw floats of a render buffer instead of the display image: 'hdr' (luminance in cd/m\xB2, before post-processing and tonemapping), 'post-hdr' (after the HDR effects, pre-exposed), 'depth', 'velocity' (screen motion in uv units, TAA and motion blur), 'ssao' (ambient occlusion), 'bloom' (the glow's first level), 'dof-half' (color and signed CoC in pixels), or another graph texture. Returned as base64 little-endian rgba32float."
+      })
+    }),
+    handler: async ({ app, world, options }, p) => {
+      const window = world.tryResource(Window);
+      if (window instanceof OffscreenTarget && p.width > 0 && p.height > 0) {
+        window.resize(p.width, p.height);
+      }
+      const view = p.camera !== null && p.camera !== void 0 ? `camera:${resolveEntity(world, p.camera)}` : void 0;
+      const renderNow = (options.frames ?? "manual") === "manual" || world.resource(AppControlResource).paused;
+      if (world.resource(Views).list.length === 0) renderOnly(app);
+      const name = view ?? world.resource(Views).list[0]?.name;
+      if (!name)
+        throw new ShardError(
+          "protocol/no-view",
+          "Nothing to capture: no camera renders to a target"
+        );
+      const debug = p.debug || "";
+      const cameraEntity = Number(name.slice("camera:".length));
+      if (debug.startsWith("shadow-map:")) {
+        await whenRenderReady(world, () => renderNow ? renderOnly(app) : nextFrame(app));
+        const [, lightRef, layer] = debug.split(":");
+        const light = resolveEntity(world, /^\d+$/.test(lightRef) ? Number(lightRef) : lightRef);
+        const map = await captureShadowMap(world, light, Number(layer ?? 0), cameraEntity);
+        const image = depthImage(map);
+        return {
+          mimeType: "image/png",
+          width: image.width,
+          height: image.height,
+          data: toBase64(await encodePng(image.data, image.width, image.height))
+        };
+      }
+      if (debug && !CAPTURE_DEBUG_VIEWS.includes(debug)) {
+        throw new ShardError("protocol/unknown-debug-view", `Unknown debug view "${debug}"`, {
+          hint: "Use 'clusters', 'cascades', 'lod', 'culling', 'none', or 'shadow-map:<light>'."
+        });
+      }
+      if (debug) setDebugView(world, cameraEntity, debug);
+      const restore = debug !== "" && debug !== "culling" && debug !== "none";
+      const overlays = checkOverlays(p.overlays);
+      const restoreOverlays = overlays.length > 0 ? applyOverlays(
+        world,
+        overlays,
+        p.components ?? [],
+        p.filter || ""
+      ) : void 0;
+      try {
+        await whenRenderReady(world, () => renderNow ? renderOnly(app) : nextFrame(app));
+        if (p.buffer) {
+          const shot2 = captureBuffer(world, name, p.buffer);
+          if (renderNow) renderOnly(app);
+          else await nextFrame(app);
+          const b = await shot2;
+          return {
+            mimeType: "application/octet-stream",
+            format: "rgba32float",
+            source: b.format,
+            width: b.width,
+            height: b.height,
+            data: toBase64(new Uint8Array(b.data.buffer, b.data.byteOffset, b.data.byteLength))
+          };
+        }
+        const shot = captureView(world, name);
+        if (renderNow) renderOnly(app);
+        const image = await shot;
+        return {
+          mimeType: "image/png",
+          width: image.width,
+          height: image.height,
+          data: toBase64(await encodePng(image.data, image.width, image.height))
+        };
+      } finally {
+        if (restore) setDebugView(world, cameraEntity, "none");
+        restoreOverlays?.();
+      }
+    }
+  },
+  {
+    name: "render.pick",
+    description: "What's under a pixel of a camera view (x, y from the top left, in the capture's pixels): the entity, its scene path, and the world position, normal, and distance of the surface. Meshes and world sprites are pickable. null when nothing is there.",
+    params: s("PickParams", {
+      camera: t.entity({ description: "Camera entity or path (default: the first camera view)." }),
+      x: t.f32({ required: true }),
+      y: t.f32({ required: true })
+    }),
+    handler: async ({ app, world, options }, p) => {
+      const manual = (options.frames ?? "manual") === "manual" || world.resource(AppControlResource).paused;
+      if (world.resource(Views).list.length === 0) renderOnly(app);
+      const camera = p.camera !== null && p.camera !== void 0 ? resolveEntity(world, p.camera) : void 0;
+      let done = false;
+      const result = pick(world, camera, p.x, p.y).finally(() => {
+        done = true;
+      });
+      for (let i = 0; i < 30 && !done; i++) {
+        if (manual) renderOnly(app);
+        else await nextFrame(app);
+        await world.tryResource(Gpu)?.pipelines.whenIdle();
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      }
+      const hit = await result;
+      return hit ? hitJson(hit) : null;
+    }
+  },
+  {
+    name: "world.raycast",
+    description: "Casts a ray against mesh entities on the CPU (bounds, then triangles): hits nearest first, each with entity, scene path, position, normal, and distance. Needs no GPU or frame.",
+    params: s("RaycastParams", {
+      origin: t.vec3({ required: true }),
+      direction: t.vec3({ required: true }),
+      maxDistance: t.f32({ min: 0, description: "Ignore hits past this (0: no limit)." }),
+      all: t.bool({ description: "Every entity along the ray, not just the nearest." })
+    }),
+    handler: ({ world }, p) => {
+      const hits = raycast(world, p.origin, p.direction, {
+        maxDistance: p.maxDistance || void 0,
+        all: p.all
+      });
+      return { hits: hits.map(hitJson) };
+    }
+  },
+  {
+    name: "debug.overlays",
+    description: `Shows debug overlays in every frame until changed (render.capture's "overlays" draws them into one capture instead). Pass the full set to show: ${OVERLAYS.join(", ")}, plus plugin overlays (colliders with physics); [] turns them off. Returns what's on.`,
+    params: s("OverlaysParams", {
+      overlays: t.list(t.string, { description: "Overlays to show; the rest turn off." }),
+      filter: t.string({ description: "Only entities whose scene path starts with this." }),
+      components: t.list(t.string, { description: "Only entities with all these components." })
+    }),
+    handler: ({ world }, p) => {
+      const names = checkOverlays(p.overlays);
+      applyOverlays(
+        world,
+        names,
+        p.components ?? [],
+        p.filter || ""
+      );
+      const o = world.resource(DebugOverlays);
+      return { overlays: overlayNames().filter((k) => isOverlayOn(o, k)), filter: o.filter };
+    }
+  },
+  {
+    name: "debug.gizmos",
+    description: "What gizmos drew last frame, as data: line segments (from, to, color, depthTest, width) and labels (position, text). Overlays count too.",
+    params: s("GizmosParams", {
+      limit: t.u32({ default: 200, max: 1e5, description: "Most line segments to list." })
+    }),
+    handler: ({ world }, p) => toJson(world.resource(Gizmos).describe(p.limit))
+  },
+  {
+    name: "render.describe",
+    description: "Render graph order, views, pipelines compiling, per-view stats, recent GPU errors.",
+    params: none,
+    handler: ({ world }) => toJson(describeRender(world))
+  },
+  {
+    name: "input.inject",
+    description: 'Queues input for the next frame: a key, a mouse button, or an action ("<map>.<action>").',
+    params: s("InjectParams", {
+      key: t.string({ description: 'KeyboardEvent.code, e.g. "KeyW".' }),
+      mouse: t.enum(["", "left", "middle", "right"]),
+      action: t.string({
+        description: 'Action as "<map>.<action>", e.g. "star-explorer/Controls.thrust".'
+      }),
+      pressed: t.bool({ default: true }),
+      value: t.f32({ description: "Analog value for actions (default 1 when pressed)." })
+    }),
+    handler: ({ world }, p) => {
+      if (p.action)
+        injectInput(world, {
+          action: p.action,
+          pressed: p.pressed,
+          value: p.value || void 0
+        });
+      else if (p.key) injectInput(world, { key: p.key, pressed: p.pressed });
+      else if (p.mouse)
+        injectInput(world, { mouse: p.mouse, pressed: p.pressed });
+      else
+        throw new ShardError("protocol/invalid-params", "Give one of key, mouse, or action", {
+          path: ""
+        });
+      return { queued: true };
+    }
+  },
+  {
+    name: "input.record",
+    description: "Starts recording input, or stops and returns the recording.",
+    params: s("RecordParams", { action: t.enum(["start", "stop"]) }),
+    handler: ({ world }, p) => p.action === "stop" ? { recording: stopRecording(world) } : (startRecording(world), { recording: true })
+  },
+  {
+    name: "input.replay",
+    description: "Replays a recording from the next frame, ignoring live input until it ends.",
+    params: s("ReplayParams", { recording: t.string({ required: true }) }),
+    handler: ({ world }, p) => {
+      startReplay(world, p.recording);
+      return { replaying: true };
+    }
+  },
+  {
+    name: "scene.validate",
+    description: "Every error in a scene (by file path or inline JSON), each with a JSON pointer.",
+    params: s("SceneValidateParams", { file: t.string(), json: t.json() }),
+    handler: async (ctx, p) => {
+      const json = p.file ? await readJson(ctx, p.file) : p.json;
+      const errors = validateScene(ctx.world, json);
+      return { valid: errors.length === 0, errors: errors.map((e) => e.toJSON()) };
+    }
+  },
+  {
+    name: "scene.load",
+    description: "Loads a scene (replacing a loaded scene with the same id). Returns entity paths and ids.",
+    params: s("SceneLoadParams", {
+      file: t.string(),
+      json: t.json(),
+      id: t.string({ description: "Defaults to the file path." }),
+      wait: t.bool({
+        default: true,
+        description: "Wait until every referenced asset has loaded or failed (default true)."
+      })
+    }),
+    handler: async (ctx, p) => {
+      const json = p.file ? await readJson(ctx, p.file) : p.json;
+      const id = p.id || p.file || "main";
+      const loaded = ctx.world.initResource(SceneIndex).has(id) ? reloadScene(ctx.world, id, json) : loadScene(ctx.world, json, { id });
+      if (p.wait !== false) await whenSceneReady(ctx.world, id);
+      const failed = assetServer(ctx.world).list({ state: "failed" }).map((e) => ({ path: e.path, error: e.error?.message }));
+      return {
+        id,
+        entities: Object.fromEntries(loaded.entities),
+        ...failed.length > 0 ? { failedAssets: failed } : {}
+      };
+    }
+  },
+  {
+    name: "scene.save",
+    description: "Serializes a loaded scene; unchanged fields keep their authored form. Optionally writes the file.",
+    params: s("SceneSaveParams", { id: t.string({ required: true }), write: t.bool() }),
+    handler: async (ctx, p) => {
+      const file = saveScene(ctx.world, p.id);
+      if (p.write) {
+        if (!ctx.options.platform?.fs.writable)
+          throw new ShardError("protocol/no-files", "This host can't write files");
+        await ctx.options.platform.fs.writeText(p.id, stringifyScene(file));
+      }
+      return file;
+    }
+  },
+  {
+    name: "prefab.spawn",
+    description: "Spawns a prefab instance (loading the prefab first). Returns the root entity and its generated entities by path relative to the root.",
+    params: s("PrefabSpawnParams", {
+      prefab: t.string({
+        required: true,
+        description: 'Prefab path or guid, e.g. "prefabs/ship.prefab.json".'
+      }),
+      transform: t.json({
+        description: 'Root Transform fields, e.g. { "translation": [0, 5, 0] }.'
+      }),
+      overrides: t.json({
+        description: 'Changes to generated entities: { "Exhaust": { "particles/ParticleSystem": { "timeScale": 2 } } }.'
+      }),
+      parent: t.entity({ description: "Optional parent entity or path." })
+    }),
+    handler: async ({ world }, p) => {
+      await loadPrefab(world, p.prefab);
+      const transform = p.transform;
+      const root = spawnPrefab(world, p.prefab, {
+        ...transform ? { transform } : {},
+        ...p.overrides ? { overrides: p.overrides } : {},
+        ...p.parent !== null && p.parent !== void 0 ? { parent: resolveEntity(world, p.parent) } : {}
+      });
+      return { root, paths: Object.fromEntries(instanceEntities(world, root)) };
+    }
+  },
+  {
+    name: "prefab.overrides",
+    description: "An instance's current differences from its prefab (or model), as the overrides a scene save would write.",
+    params: s("PrefabOverridesParams", { entity: entityRef() }),
+    handler: ({ world }, p) => {
+      const entity = resolveEntity(world, p.entity);
+      const overrides = currentOverrides(world, entity);
+      if (!overrides) {
+        throw new ShardError(
+          "prefab/not-an-instance",
+          `Entity ${JSON.stringify(p.entity)} isn't a spawned instance`,
+          {
+            hint: 'Pass the entity with scene/PrefabInstance or scene/SceneInstance, e.g. "player-ship".'
+          }
+        );
+      }
+      return { entity, overrides };
+    }
+  },
+  {
+    name: "prefab.apply",
+    description: "Apply to prefab: writes an instance's overrides into its prefab file and clears them. Every instance of the prefab picks up the change.",
+    params: s("PrefabApplyParams", { entity: entityRef() }),
+    handler: async ({ world, options }, p) => applyToPrefab(
+      world,
+      resolveEntity(world, p.entity),
+      options.platform?.fs.writable ? options.platform.fs : void 0
+    )
+  },
+  {
+    name: "asset.list",
+    description: "Assets in the catalog: path, type, and state (unloaded, loading, loaded, failed). Filter by type, path prefix, or state.",
+    params: s("AssetListParams", {
+      type: t.string({ description: 'e.g. "Mesh", "Material", "Texture".' }),
+      prefix: t.string({ description: 'Path prefix, e.g. "assets/ships/".' }),
+      state: t.string({ description: "unloaded, loading, loaded, or failed." }),
+      limit: t.u32({ default: 200 })
+    }),
+    handler: ({ world }, p) => {
+      const all = assetServer(world).list({
+        type: p.type || void 0,
+        prefix: p.prefix || void 0,
+        state: p.state || void 0
+      });
+      return {
+        total: all.length,
+        assets: all.slice(0, p.limit).map((e) => ({
+          path: e.path,
+          type: e.type,
+          state: e.state,
+          ...e.error ? { error: e.error.message } : {}
+        }))
+      };
+    }
+  },
+  {
+    name: "asset.get",
+    description: "Everything about one asset: guid, type, state, importer and settings, dependencies and dependents, sub-assets, facts (counts, bounds), warnings, and the last error. Data assets include their value, and variants their $extends chain and which file set each field.",
+    params: s("AssetGetParams", {
+      asset: t.string({ required: true, description: "Asset path or guid." })
+    }),
+    handler: async ({ world }, p) => {
+      const assets = assetServer(world);
+      const info = toJson(assets.info(p.asset));
+      if (info.source && assets.importerOf(info.source)?.schema && info.artifact)
+        info.value = (await assets.artifact(p.asset)).json;
+      return info;
+    }
+  },
+  {
+    name: "asset.import",
+    description: 'Re-imports one source (optionally with new import settings, merged into its .meta), or scans every asset root when "asset" is omitted.',
+    params: s("AssetImportParams", {
+      asset: t.string({ description: "Source path or sub-asset path. Omit to scan everything." }),
+      settings: t.json({ description: 'Import settings to change, e.g. { "scale": 0.01 }.' }),
+      force: t.bool({ description: "Re-import even if nothing changed." })
+    }),
+    handler: async ({ world }, p) => {
+      const assets = assetServer(world);
+      if (!p.asset) return toJson(await assets.scan({ force: p.force === true }));
+      const settings = p.settings;
+      return toJson(await assets.reimport(p.asset, settings ? { settings } : {}));
+    }
+  },
+  {
+    name: "asset.move",
+    description: "Moves an asset source and its .meta, then rewrites references to it in scenes and data assets. Returns the files it rewrote.",
+    params: s("AssetMoveParams", {
+      from: t.string({ required: true }),
+      to: t.string({ required: true })
+    }),
+    handler: ({ world }, p) => assetServer(world).move(p.from, p.to)
+  },
+  {
+    name: "asset.preview",
+    description: "A PNG of an asset: a texture (top mip), a material on a sphere, a mesh or scene framed from its bounds, or a noise graph in grayscale (options: domain plane|sphere, seed, size, node to see an intermediate node). Renders in a private world; the game is untouched.",
+    params: s("AssetPreviewParams", {
+      asset: t.string({ required: true, description: "Asset path or guid." }),
+      width: t.u32({ default: 256, min: 16, max: 2048 }),
+      height: t.u32({ default: 256, min: 16, max: 2048 }),
+      options: t.json({
+        description: 'Type-specific options. NoiseGraph: { domain: "plane" | "sphere", seed, size, node }.'
+      })
+    }),
+    handler: async ({ world }, p) => {
+      const image = await previewAsset(
+        world,
+        p.asset,
+        p.width,
+        p.height,
+        p.options ?? void 0
+      );
+      const png = await encodePng(image.data, image.width, image.height);
+      return { width: image.width, height: image.height, data: toBase64(png) };
+    }
+  },
+  {
+    name: "text.measure",
+    description: "Lays out a string without rendering it: width, height, and line breaks, in the units of size (world units for Text, pixels for ScreenText). Use it to size a label before placing it.",
+    params: s("TextMeasureParams", {
+      font: t.string({ required: true, description: "Font asset path or guid." }),
+      value: t.string({ required: true }),
+      size: t.f32({ default: 1, min: 0 }),
+      maxWidth: t.f32({ min: 0, description: "Wrap width (0: none)." }),
+      lineHeight: t.f32({ default: 1.2 }),
+      align: t.enum(["left", "center", "right"])
+    }),
+    handler: async ({ world }, p) => {
+      const server = assetServer(world);
+      const ref = server.resolve(p.font);
+      if (ref) await server.load(ref.path ?? p.font);
+      const font = world.resource(Fonts).get(ref);
+      if (!font) {
+        throw new ShardError("text/not-loaded", `No font "${p.font}"`, {
+          hint: "asset.list shows fonts (type Font); pass a .ttf or .otf path."
+        });
+      }
+      const m = measureText(font, p.value, {
+        size: p.size,
+        maxWidth: p.maxWidth,
+        lineHeight: p.lineHeight,
+        align: ["left", "center", "right"][p.align] ?? "left"
+      });
+      const value = p.value;
+      return {
+        width: m.width,
+        height: m.height,
+        lines: m.lines.map((l) => ({ text: value.slice(l.start, l.end), width: l.width }))
+      };
+    }
+  },
+  {
+    name: "log.tail",
+    description: "Recent log entries (errors from systems, the GPU, and shaders land here).",
+    params: s("LogParams", {
+      count: t.u32({ default: 50, min: 1 }),
+      level: t.enum(["debug", "info", "warn", "error"])
+    }),
+    handler: ({ world }, p) => world.resource(LogResource).tail(p.count, p.level)
+  },
+  {
+    name: "errors.recent",
+    description: "Recent errors with code, path, and hint.",
+    params: s("ErrorsParams", { count: t.u32({ default: 20, min: 1 }) }),
+    handler: ({ world }, p) => world.resource(LogResource).errors(p.count)
+  }
+];
+function createProtocolServer(app, options = {}) {
+  const ctx = { app, world: app.world, options };
+  const byName = new Map([...METHODS, ...options.methods ?? []].map((m) => [m.name, m]));
+  const listeners = /* @__PURE__ */ new Set();
+  const topics = /* @__PURE__ */ new Set();
+  const notify = (method, params) => {
+    for (const l of listeners) l({ jsonrpc: "2.0", method, params });
+  };
+  const offLog = app.world.resource(LogResource).subscribe((entry) => {
+    if (topics.has("log")) notify("log", entry);
+    if (topics.has("error") && entry.level === "error") notify("error", entry);
+  });
+  const offFrame = app.onFrame((frame) => {
+    if (topics.has("frame")) notify("frame", { frame });
+  });
+  const subscribe = {
+    name: "subscribe",
+    description: 'Subscribes to notifications: "log", "error", "frame", "project" (reloads).',
+    params: s("SubscribeParams", {
+      topics: t.list(t.enum(["log", "error", "frame", "project"])),
+      unsubscribe: t.bool()
+    }),
+    handler: (_, p) => {
+      for (const topic of p.topics) {
+        if (p.unsubscribe) topics.delete(topic);
+        else topics.add(topic);
+      }
+      return { topics: [...topics] };
+    }
+  };
+  byName.set(subscribe.name, subscribe);
+  const lookup = (name) => byName.get(name) ?? app.methods.find((m) => m.name === name);
+  return {
+    get methods() {
+      return [...byName.values(), ...app.methods.filter((m) => !byName.has(m.name))];
+    },
+    async handle(request) {
+      const id = request.id ?? null;
+      const isNotification = request.id === void 0;
+      const reply = (body) => isNotification ? void 0 : { jsonrpc: "2.0", id, ...body };
+      if (request?.jsonrpc !== "2.0" || typeof request.method !== "string") {
+        return reply({ error: { code: ERROR.invalid, message: "Invalid JSON-RPC request" } });
+      }
+      const method = lookup(request.method);
+      if (!method) {
+        return reply({
+          error: {
+            code: ERROR.notFound,
+            message: `Unknown method "${request.method}"`,
+            data: { methods: [...byName.keys(), ...app.methods.map((m) => m.name)] }
+          }
+        });
+      }
+      const raw = request.params ?? {};
+      const problems = method.params.validate(raw);
+      if (problems.length > 0) {
+        const err = new ShardError(
+          "protocol/invalid-params",
+          `${problems.length} invalid parameter(s): ${problems[0].message}`,
+          {
+            path: problems[0].path,
+            hint: problems[0].hint,
+            details: problems
+          }
+        );
+        return reply({ error: { code: ERROR.params, message: err.message, data: err.toJSON() } });
+      }
+      try {
+        const params = method.params.deserialize(raw, worldSchemaContext(app.world));
+        const result = await method.handler(ctx, params);
+        return reply({ result: result ?? null });
+      } catch (err) {
+        const shard = err instanceof ShardError ? err : new ShardError("protocol/internal", err instanceof Error ? err.message : String(err));
+        return reply({ error: { code: ERROR.shard, message: shard.message, data: shard.toJSON() } });
+      }
+    },
+    onNotification(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    publish(topic, params) {
+      if (topics.has(topic)) notify(topic, params);
+    },
+    close() {
+      offLog();
+      offFrame();
+      listeners.clear();
+    }
+  };
+}
+export {
+  METHODS,
+  createProtocolServer
+};