@aethervtt/shard-protocol 0.0.1 → 0.1.0

package/dist/preview.js

@@ -191,6 +191,7 @@ async function renderPreview(world, path, type, width, height) {
     return { width: image.width, height: image.height, data: image.data };
   } finally {
     releaseSceneHooks(app.world);
+    await app.dispose();
     target.destroy();
   }
 }

package/dist/server.d.ts

@@ -43,6 +43,12 @@ export interface ProtocolServerOptions {
     platform?: Platform;
     /** Extra methods from the host (e.g. `project.reload`), added to the built-in ones. */
     methods?: readonly MethodDef[];
+    /**
+     * The only methods this server answers (0061): everything else, `subscribe` included, fails with
+     * `protocol/method-not-allowed`. A host that forwards requests from hosted mods passes the few
+     * it allows; omit it for agents and tools, which get every method.
+     */
+    allow?: readonly string[];
 }
 export declare const METHODS: MethodDef[];
 export type Topic = 'log' | 'error' | 'frame' | 'project';

package/dist/server.js

@@ -15,6 +15,7 @@ import {
 import {
   describeInput,
   injectInput,
+  simulateGestures,
   startRecording,
   startReplay,
   stopRecording
@@ -87,7 +88,7 @@ function resolveEntity(world, ref) {
     hint: 'Pass an entity id from world.query, or a scene path like "ship/camera".'
   });
 }
-function requireComponent(name) {
+function knownComponent(name) {
   const def = findComponent(name);
   if (!def) {
     throw new ShardError("protocol/unknown-component", `Unknown component "${name}"`, {
@@ -96,6 +97,28 @@ function requireComponent(name) {
   }
   return def;
 }
+function requireOwner(world, name) {
+  const owner = world.owners.find(name);
+  if (!owner) {
+    throw new ShardError("protocol/unknown-owner", `No live owner "${name}"`, {
+      hint: "owners.describe with no name lists every live owner."
+    });
+  }
+  return owner;
+}
+function requireComponent(name) {
+  const def = knownComponent(name);
+  if (def.hostOnly) {
+    throw new ShardError(
+      "core/owner-not-authorable",
+      `"${name}" can't be written through the protocol`,
+      {
+        hint: "Ownership comes from host code holding an Owner (world.owners)."
+      }
+    );
+  }
+  return def;
+}
 function toJson(value) {
   const seen = /* @__PURE__ */ new WeakSet();
   return JSON.parse(
@@ -346,7 +369,7 @@ const METHODS = [
     params: s("SchemaGetParams", {
       name: t.string({ required: true, description: 'Component name, e.g. "render/Camera3d".' })
     }),
-    handler: (_, p) => requireComponent(p.name).jsonSchema()
+    handler: (_, p) => knownComponent(p.name).jsonSchema()
   },
   {
     name: "world.stats",
@@ -439,6 +462,23 @@ const METHODS = [
       return entityJson(world, entity);
     }
   },
+  {
+    name: "owners.describe",
+    description: "Owners (0061). With a name: its usage (entities, triangles, textures, bytes), limits, child owners, asset leases and GPU objects. Without: every live owner.",
+    params: s("OwnersDescribeParams", { name: t.string() }),
+    handler: ({ world }, p) => p.name ? world.owners.describe(requireOwner(world, p.name)) : { owners: world.owners.list() }
+  },
+  {
+    name: "owners.release",
+    description: "Releases an owner and its child owners: despawns their entities, drops their asset leases (unloading assets nobody else leases, with their GPU objects).",
+    params: s("OwnersReleaseParams", { name: t.string({ required: true }) }),
+    handler: ({ world }, p) => {
+      const owner = requireOwner(world, p.name);
+      const entities = world.owners.describe(owner).usage.entities;
+      world.owners.release(owner);
+      return { released: owner.name, entities };
+    }
+  },
   {
     name: "entity.despawn",
     description: "Despawns an entity (and its children unless recursive is false).",
@@ -467,10 +507,19 @@ const METHODS = [
   },
   {
     name: "resource.set",
-    description: "Merges fields into a plain-object resource (e.g. render/AmbientLight).",
+    description: "Merges fields into a plain-object resource (e.g. render/AmbientLight), marking it changed and waking an on-demand app.",
     params: s("ResourceSetParams", { name: t.string({ required: true }), value: t.json() }),
     handler: ({ world }, p) => {
       const def = findResource(p.name);
+      if (def?.hostOnly) {
+        throw new ShardError(
+          "core/owner-not-authorable",
+          `Resource "${p.name}" is written by the host only`,
+          {
+            hint: "Host code sets it; the protocol can read it with resource.get."
+          }
+        );
+      }
       const current = def && world.tryResource(def);
       if (!def || !isPlainObject(current)) {
         throw new ShardError(
@@ -485,7 +534,7 @@ const METHODS = [
         throw new ShardError("schema/type-mismatch", '"value" must be an object', {
           path: "/value"
         });
-      Object.assign(current, p.value);
+      world.patchResource(def, p.value);
       return toJson(current);
     }
   },
@@ -502,10 +551,11 @@ const METHODS = [
     name: "time.resume",
     description: "Resumes a paused game.",
     params: none,
-    handler: ({ world }) => {
+    handler: ({ app, world }) => {
       const control = world.resource(AppControlResource);
       control.paused = false;
       control.pausedByError = false;
+      app.requestFrame();
       return { paused: false, frame: world.resource(Time).frame };
     }
   },
@@ -732,6 +782,20 @@ const METHODS = [
       return { queued: true };
     }
   },
+  {
+    name: "input.simulate",
+    description: "Plays pointer gestures a step per frame, in CSS pixels, so controls and drags run headless (0060): [{ drag: { from: [x, y], to: [x, y], button, pointer, modifiers, frames, cancel } }, { pinch: { center, from, to, twist, pan, frames } }, { wheel: { at, dy, dx, modifiers } }, { tap: [x, y] }, { wait: frames }]. Needs gesturesPlugin. Returns how many frames they take.",
+    params: s("SimulateParams", {
+      gestures: t.json({ required: true, description: "The gestures, played one after another." })
+    }),
+    handler: ({ world }, p) => {
+      if (!Array.isArray(p.gestures))
+        throw new ShardError("protocol/invalid-params", "gestures must be a list", {
+          path: "/gestures"
+        });
+      return { frames: simulateGestures(world, p.gestures) };
+    }
+  },
   {
     name: "input.record",
     description: "Starts recording input, or stops and returns the recording.",
@@ -1021,10 +1085,12 @@ function createProtocolServer(app, options = {}) {
     }
   };
   byName.set(subscribe.name, subscribe);
-  const lookup = (name) => byName.get(name) ?? app.methods.find((m) => m.name === name);
-  return {
+  const allow = options.allow ? new Set(options.allow) : void 0;
+  const lookup = (name) => allow && !allow.has(name) ? void 0 : byName.get(name) ?? app.methods.find((m) => m.name === name);
+  const allowed = (m) => !allow || allow.has(m.name);
+  const server = {
     get methods() {
-      return [...byName.values(), ...app.methods.filter((m) => !byName.has(m.name))];
+      return [...byName.values(), ...app.methods.filter((m) => !byName.has(m.name))].filter(allowed);
     },
     async handle(request) {
       const id = request.id ?? null;
@@ -1033,13 +1099,21 @@ function createProtocolServer(app, options = {}) {
       if (request?.jsonrpc !== "2.0" || typeof request.method !== "string") {
         return reply({ error: { code: ERROR.invalid, message: "Invalid JSON-RPC request" } });
       }
+      if (allow && !allow.has(request.method)) {
+        const err = new ShardError(
+          "protocol/method-not-allowed",
+          `"${request.method}" isn't allowed on this server`,
+          { hint: `This host allows: ${[...allow].join(", ")}.` }
+        );
+        return reply({ error: { code: ERROR.shard, message: err.message, data: err.toJSON() } });
+      }
       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)] }
+            data: { methods: server.methods.map((m) => m.name) }
           }
         });
       }
@@ -1079,6 +1153,7 @@ function createProtocolServer(app, options = {}) {
       listeners.clear();
     }
   };
+  return server;
 }
 export {
   METHODS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aethervtt/shard-protocol",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -16,16 +16,16 @@
     "README.md"
   ],
   "dependencies": {
-    "@aethervtt/shard-assets": "0.0.1",
-    "@aethervtt/shard-core": "0.0.1",
-    "@aethervtt/shard-input": "0.0.1",
-    "@aethervtt/shard-platform": "0.0.1",
-    "@aethervtt/shard-render": "0.0.1",
-    "@aethervtt/shard-runtime": "0.0.1",
-    "@aethervtt/shard-scene": "0.0.1",
-    "@aethervtt/shard-text": "0.0.1",
-    "@aethervtt/shard-texture": "0.0.1",
-    "@aethervtt/shard-transform": "0.0.1"
+    "@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"
   },
   "repository": {
     "type": "git",
@@ -37,6 +37,6 @@
     "provenance": true
   },
   "shard": {
-    "buildSha": "d6c5c6aef4675575c878b02cf2c8f738b4190229"
+    "buildSha": "8e14c9896f82a3554b156f1ffdd68f2cc3e7d78a"
   }
 }