@aethervtt/shard-protocol 0.1.0 → 0.2.0

package/dist/ablate.d.ts

@@ -0,0 +1,2 @@
+import type { MethodDef } from './server.js';
+export declare const ABLATE_METHODS: MethodDef[];

package/dist/ablate.js

@@ -0,0 +1,62 @@
+import { defineSchema, Last, PostUpdate, t } from "@aethervtt/shard-core";
+import { ablatePasses, Gpu, Graph, Views } from "@aethervtt/shard-render";
+import { AppControlResource } from "@aethervtt/shard-runtime";
+function renderOnly(app) {
+  app.runSchedule(PostUpdate);
+  app.runSchedule(Last);
+}
+function nextFrame(app) {
+  return new Promise((resolve) => {
+    const off = app.onFrame(() => {
+      off();
+      resolve();
+    });
+  });
+}
+const ABLATE_METHODS = [
+  {
+    name: "perf.ablate",
+    description: "Each render-graph pass's GPU cost, measured honestly on any GPU: rounds alternate the pass disabled and enabled, and its cost is the median drop in gpu:frame (first pass start to last pass end). Use it where per-pass timestamps overlap (tile-based GPUs such as Apple's, where pass times add up to more than the frame). A disabled pass still begins and ends, so what reads its textures stays valid; the image is wrong while it runs. Needs timestamp-query. It runs (passes + 2) \xD7 rounds \xD7 (frames + 4) frames: three passes at the defaults take about 50 s at 60 fps.",
+    params: defineSchema("protocol/AblateParams", {
+      passes: t.list(t.string, {
+        description: "Render-graph nodes to measure (render.describe lists them). Default: every node the last frame ran."
+      }),
+      frames: t.u32({ default: 120, min: 1, max: 1e4, description: "Frames per measurement." }),
+      rounds: t.u32({ default: 5, min: 1, max: 100, description: "Interleaved rounds." }),
+      together: t.bool({ description: "Also measure every pass disabled at once." })
+    }),
+    handler: async ({ app, world, options }, p) => {
+      const manual = (options.frames ?? "manual") === "manual" || world.resource(AppControlResource).paused;
+      const frame = () => manual ? renderOnly(app) : nextFrame(app);
+      const graph = world.resource(Graph);
+      const gpu = world.resource(Gpu);
+      for (let i = 0; i < 20; i++) {
+        await frame();
+        await gpu.pipelines.whenIdle();
+        if (i > 0 && gpu.pipelines.pending === 0 && gpu.pipelines.skipped === 0) break;
+      }
+      let passes = p.passes ?? [];
+      if (passes.length === 0) {
+        const ran = /* @__PURE__ */ new Set();
+        const perView = graph.describe().perView;
+        for (const view of world.resource(Views).list) {
+          for (const name of perView[view.name]?.order ?? []) ran.add(name);
+        }
+        passes = [...ran];
+      }
+      return ablatePasses(
+        world,
+        {
+          passes,
+          frames: p.frames,
+          rounds: p.rounds,
+          together: p.together
+        },
+        frame
+      );
+    }
+  }
+];
+export {
+  ABLATE_METHODS
+};

package/dist/budgets.d.ts

@@ -0,0 +1,2 @@
+import type { MethodDef } from './server.js';
+export declare const BUDGET_METHODS: MethodDef[];

package/dist/budgets.js

@@ -0,0 +1,20 @@
+import { defineSchema, t } from "@aethervtt/shard-core";
+import { describeBudgets } from "@aethervtt/shard-runtime";
+const BUDGET_METHODS = [
+  {
+    name: "perf.budgets",
+    description: "Performance budgets (0075, bench/perf/budgets.json) for this app: the named machine it runs on (detected from the CPU model where the host exposes it, and the GPU adapter; null with a perf/unknown-machine warning when it can't tell, and then numbers are the closest machine's), every budget resolved for it with the profiler's latest p95 against it, over budget first; and the scenario's slices (the app's App.perfScenario, or `scenario`): each slice's measured share of the frame (from the profiler's aggregates, gpu:frame for GPU slices, frame for CPU) next to its budget share, over first. Hosts supply the files: the CLI loads them from the repo or project, shard dev serves them to its page.",
+    params: defineSchema("protocol/BudgetsParams", {
+      scenario: t.string({
+        description: "A scenario of budgets.json to measure (scatter-walk, crowd, planet-descent, tabletop-max). Default: the app's own (App.perfScenario)."
+      })
+    }),
+    handler: ({ world }, p) => {
+      const scenario = p.scenario;
+      return describeBudgets(world, { scenario: scenario ? scenario : void 0 });
+    }
+  }
+];
+export {
+  BUDGET_METHODS
+};

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { ABLATE_METHODS } from './ablate.js';
+export { BUDGET_METHODS } from './budgets.js';
 export { decodePng, encodePng, toBase64 } from './png.js';
 export { type PreviewImage, previewAsset, previewKtx2 } from './preview.js';
 export { createProtocolServer, type HandlerContext, type JsonRpcNotification, type JsonRpcRequest, type JsonRpcResponse, METHODS, type MethodDef, type ProtocolServer, type ProtocolServerOptions, type Topic, } from './server.js';

package/dist/index.js

@@ -1,3 +1,5 @@
+import { ABLATE_METHODS } from "./ablate.js";
+import { BUDGET_METHODS } from "./budgets.js";
 import { decodePng, encodePng, toBase64 } from "./png.js";
 import { previewAsset, previewKtx2 } from "./preview.js";
 import {
@@ -6,6 +8,8 @@ import {
 } from "./server.js";
 import { connectToHub, DEFAULT_HUB_PORT } from "./transport.js";
 export {
+  ABLATE_METHODS,
+  BUDGET_METHODS,
   DEFAULT_HUB_PORT,
   METHODS,
   connectToHub,

package/dist/server.js

@@ -9,6 +9,7 @@ import {
   isPlainObject,
   Last,
   PostUpdate,
+  ProfilerResource,
   ShardError,
   t
 } from "@aethervtt/shard-core";
@@ -42,6 +43,8 @@ import {
 } from "@aethervtt/shard-render";
 import {
   AppControlResource,
+  capturePerf,
+  describePerf,
   LogResource,
   Time
 } from "@aethervtt/shard-runtime";
@@ -74,6 +77,8 @@ import {
   Transform,
   worldPosition64
 } from "@aethervtt/shard-transform";
+import { ABLATE_METHODS } from "./ablate.js";
+import { BUDGET_METHODS } from "./budgets.js";
 import { encodePng, toBase64 } from "./png.js";
 const CAPTURE_DEBUG_VIEWS = ["clusters", "cascades", "lod", "culling", "none"];
 import { previewAsset } from "./preview.js";
@@ -599,7 +604,7 @@ const METHODS = [
         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."
+        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; bloom's glow is added by the tonemap, so it's not in it), 'depth', 'velocity' (screen motion in uv units, TAA and motion blur), 'ssao' (ambient occlusion and view depth, at half resolution), '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) => {
@@ -1038,6 +1043,87 @@ const METHODS = [
       };
     }
   },
+  {
+    name: "perf.describe",
+    description: 'Profiler aggregates (0074) over the last 120 runs of each span (last, avg, p95, max ms): the frame, each schedule and its command application, systems and other main-thread spans, GPU passes and the GPU frame ("unavailable" without timestamp queries), worker jobs, async spans; memory (GPU ledger by category, JS heap, ECS tables); and the clock (resolution, isolated, timings under four steps are "coarse").',
+    params: s("PerfDescribeParams", {
+      spans: t.list(t.string, {
+        description: 'Only spans these keys cover: a key covers a span it equals or prefixes up to a "/" ("render" covers "render/opaque").'
+      }),
+      top: t.u32({ default: 30, min: 1, max: 1e3, description: "Most spans listed per track." })
+    }),
+    handler: ({ world }, p) => {
+      const spans = p.spans;
+      return toJson(
+        describePerf(world, {
+          spans: spans && spans.length > 0 ? spans : void 0,
+          top: p.top
+        })
+      );
+    }
+  },
+  {
+    name: "perf.capture",
+    description: 'Captures a span timeline (0074) over the next `frames` frames, or with `until.frameMs` a flight recorder that keeps `before` frames and stops `after` frames past the first frame over it. Returns a summary: frame CPU/GPU/interval p50/p95/max, the top spans, and the 5 worst frames, each with the spans most above their median ("over"): the lead for a hitch. The Chrome trace (Perfetto, chrome://tracing) goes to .shard/captures/ (tracePath) where the host can write, else inline (trace).',
+    params: s("PerfCaptureParams", {
+      frames: t.u32({ min: 0, max: 1e5, description: "Frames to capture (default 300)." }),
+      until: t.struct({
+        frameMs: t.f32({
+          min: 0,
+          description: "Flight recorder: stop after the first frame whose CPU time is over this."
+        })
+      }),
+      before: t.u32({
+        default: 120,
+        max: 1e5,
+        description: "Flight recorder: frames kept before."
+      }),
+      after: t.u32({ default: 30, max: 1e5, description: "Flight recorder: frames after." }),
+      timeout: t.f32({
+        default: 60,
+        min: 0,
+        description: "Flight recorder: seconds to wait for a slow frame."
+      }),
+      sample: t.bool({
+        description: "Also sample JavaScript (V8's profiler in Node, JS Self-Profiling in browsers): the hottest functions join the summary."
+      }),
+      devtools: t.bool({
+        description: "Also show spans in Chrome's Performance panel (performance.measure)."
+      }),
+      write: t.bool({ default: true, description: "Write the trace file when the host can." })
+    }),
+    handler: async ({ app, world, options }, p) => {
+      const frameMs = p.until?.frameMs ?? 0;
+      const manual = (options.frames ?? "manual") === "manual";
+      const gpu = world.tryResource(Gpu) !== void 0;
+      return toJson(
+        await capturePerf(world, {
+          frames: p.frames || 300,
+          until: frameMs > 0 ? { frameMs } : void 0,
+          before: p.before,
+          after: p.after,
+          timeout: p.timeout,
+          sample: p.sample,
+          devtools: p.devtools,
+          write: p.write,
+          // Headless: run the frames here, letting GPU readbacks land between them.
+          step: manual ? async () => {
+            app.update(1 / app.fixedHz);
+            if (gpu) await new Promise((resolve) => setTimeout(resolve, 0));
+          } : void 0
+        })
+      );
+    }
+  },
+  {
+    name: "perf.reset",
+    description: "Clears the profiler's aggregates: perf.describe starts over.",
+    params: none,
+    handler: ({ world }) => {
+      world.resource(ProfilerResource).reset();
+      return null;
+    }
+  },
   {
     name: "log.tail",
     description: "Recent log entries (errors from systems, the GPU, and shaders land here).",
@@ -1052,7 +1138,9 @@ const METHODS = [
     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)
-  }
+  },
+  ...ABLATE_METHODS,
+  ...BUDGET_METHODS
 ];
 function createProtocolServer(app, options = {}) {
   const ctx = { app, world: app.world, options };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aethervtt/shard-protocol",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -16,16 +16,16 @@
     "README.md"
   ],
   "dependencies": {
-    "@aethervtt/shard-assets": "0.1.0",
-    "@aethervtt/shard-core": "0.1.0",
-    "@aethervtt/shard-input": "0.1.0",
-    "@aethervtt/shard-platform": "0.1.0",
-    "@aethervtt/shard-render": "0.1.0",
-    "@aethervtt/shard-runtime": "0.1.0",
-    "@aethervtt/shard-scene": "0.1.0",
-    "@aethervtt/shard-text": "0.1.0",
-    "@aethervtt/shard-texture": "0.1.0",
-    "@aethervtt/shard-transform": "0.1.0"
+    "@aethervtt/shard-assets": "0.2.0",
+    "@aethervtt/shard-core": "0.2.0",
+    "@aethervtt/shard-input": "0.2.0",
+    "@aethervtt/shard-platform": "0.2.0",
+    "@aethervtt/shard-render": "0.2.0",
+    "@aethervtt/shard-runtime": "0.2.0",
+    "@aethervtt/shard-scene": "0.2.0",
+    "@aethervtt/shard-text": "0.2.0",
+    "@aethervtt/shard-texture": "0.2.0",
+    "@aethervtt/shard-transform": "0.2.0"
   },
   "repository": {
     "type": "git",
@@ -37,6 +37,6 @@
     "provenance": true
   },
   "shard": {
-    "buildSha": "8e14c9896f82a3554b156f1ffdd68f2cc3e7d78a"
+    "buildSha": "32c22a3944ed23f5d1baa90bf7cc9fae724f5fd8"
   }
 }