@aethervtt/shard-protocol 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @aethervtt/shard-protocol
+
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+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';
+export { connectToHub, DEFAULT_HUB_PORT, type HubConnectionOptions } from './transport.js';

package/dist/index.js

@@ -0,0 +1,18 @@
+import { decodePng, encodePng, toBase64 } from "./png.js";
+import { previewAsset, previewKtx2 } from "./preview.js";
+import {
+  createProtocolServer,
+  METHODS
+} from "./server.js";
+import { connectToHub, DEFAULT_HUB_PORT } from "./transport.js";
+export {
+  DEFAULT_HUB_PORT,
+  METHODS,
+  connectToHub,
+  createProtocolServer,
+  decodePng,
+  encodePng,
+  previewAsset,
+  previewKtx2,
+  toBase64
+};

package/dist/png.d.ts

@@ -0,0 +1,9 @@
+/** RGBA8 pixels → PNG bytes. Pure TS; zlib comes from the platform's CompressionStream. */
+export declare function encodePng(rgba: Uint8Array, width: number, height: number): Promise<Uint8Array>;
+/** Decodes a PNG (any color type or bit depth) to RGBA8. For tests and tools. */
+export declare function decodePng(png: Uint8Array): Promise<{
+    width: number;
+    height: number;
+    data: Uint8Array;
+}>;
+export declare function toBase64(bytes: Uint8Array): string;

package/dist/png.js

@@ -0,0 +1,69 @@
+import { decodePngImage } from "@aethervtt/shard-texture";
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+function crc32(bytes) {
+  let c = 4294967295;
+  for (let i = 0; i < bytes.length; i++) c = CRC_TABLE[(c ^ bytes[i]) & 255] ^ c >>> 8;
+  return (c ^ 4294967295) >>> 0;
+}
+async function streamBytes(input, stream) {
+  const out = new Response(new Blob([input]).stream().pipeThrough(stream));
+  return new Uint8Array(await out.arrayBuffer());
+}
+function chunk(type, data) {
+  const out = new Uint8Array(12 + data.length);
+  const view = new DataView(out.buffer);
+  view.setUint32(0, data.length);
+  for (let i = 0; i < 4; i++) out[4 + i] = type.charCodeAt(i);
+  out.set(data, 8);
+  view.setUint32(8 + data.length, crc32(out.subarray(4, 8 + data.length)));
+  return out;
+}
+async function encodePng(rgba, width, height) {
+  const raw = new Uint8Array((width * 4 + 1) * height);
+  for (let y = 0; y < height; y++) {
+    raw[y * (width * 4 + 1)] = 0;
+    raw.set(rgba.subarray(y * width * 4, (y + 1) * width * 4), y * (width * 4 + 1) + 1);
+  }
+  const ihdr = new Uint8Array(13);
+  const view = new DataView(ihdr.buffer);
+  view.setUint32(0, width);
+  view.setUint32(4, height);
+  ihdr[8] = 8;
+  ihdr[9] = 6;
+  const parts = [
+    new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]),
+    chunk("IHDR", ihdr),
+    chunk("IDAT", await streamBytes(raw, new CompressionStream("deflate"))),
+    chunk("IEND", new Uint8Array())
+  ];
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let offset = 0;
+  for (const p of parts) {
+    out.set(p, offset);
+    offset += p.length;
+  }
+  return out;
+}
+async function decodePng(png) {
+  const image = await decodePngImage(png);
+  return { width: image.width, height: image.height, data: image.data };
+}
+function toBase64(bytes) {
+  let s = "";
+  for (let i = 0; i < bytes.length; i += 32768)
+    s += String.fromCharCode(...bytes.subarray(i, i + 32768));
+  return btoa(s);
+}
+export {
+  decodePng,
+  encodePng,
+  toBase64
+};

package/dist/preview.d.ts

@@ -0,0 +1,10 @@
+import { type World } from '@aethervtt/shard-core';
+export interface PreviewImage {
+    width: number;
+    height: number;
+    data: Uint8Array;
+}
+/** The top mip of a KTX2 texture as RGBA8, fit into width × height (HDR tonemapped). */
+export declare function previewKtx2(bytes: Uint8Array, width: number, height: number): Promise<PreviewImage>;
+/** A preview image of any asset: textures on the CPU, everything else rendered. */
+export declare function previewAsset(world: World, path: string, width: number, height: number, options?: Readonly<Record<string, unknown>>): Promise<PreviewImage>;

package/dist/preview.js

@@ -0,0 +1,249 @@
+import { AssetServerResource, assetServer, findAssetPreview } from "@aethervtt/shard-assets";
+import {
+  Children,
+  findResource,
+  quat,
+  ShardError,
+  vec3
+} from "@aethervtt/shard-core";
+import {
+  captureView,
+  forwardPlugin,
+  Gpu,
+  Materials,
+  Mesh3d,
+  Meshes,
+  OffscreenTarget,
+  RenderStats,
+  renderPlugin,
+  Shaders
+} from "@aethervtt/shard-render";
+import { App } from "@aethervtt/shard-runtime";
+import {
+  loadScene,
+  PrefabAssets,
+  releaseSceneHooks,
+  SceneAssets,
+  ScenePlugin,
+  unloadScene,
+  whenSceneReady
+} from "@aethervtt/shard-scene";
+import { readKtx2, Textures, transcodeBasis } from "@aethervtt/shard-texture";
+import { GlobalTransform, TransformPlugin } from "@aethervtt/shard-transform";
+function halfToFloat(h) {
+  const s = h & 32768 ? -1 : 1;
+  const e = h >> 10 & 31;
+  const f = h & 1023;
+  if (e === 0) return s * 2 ** -14 * (f / 1024);
+  if (e === 31) return f ? Number.NaN : s * Number.POSITIVE_INFINITY;
+  return s * 2 ** (e - 15) * (1 + f / 1024);
+}
+function fit(src, sw, sh, width, height) {
+  const scale = Math.min(width / sw, height / sh);
+  const w = Math.max(1, Math.round(sw * scale));
+  const h = Math.max(1, Math.round(sh * scale));
+  const out = new Uint8Array(w * h * 4);
+  for (let y = 0; y < h; y++) {
+    const sy = Math.min(sh - 1, Math.floor(y / scale));
+    for (let x = 0; x < w; x++) {
+      const sx = Math.min(sw - 1, Math.floor(x / scale));
+      out.set(src.subarray((sy * sw + sx) * 4, (sy * sw + sx) * 4 + 4), (y * w + x) * 4);
+    }
+  }
+  return { width: w, height: h, data: out };
+}
+async function texturePreview(world, path, width, height) {
+  const artifact = await assetServer(world).artifact(path);
+  return previewKtx2(artifact.bytes, width, height);
+}
+async function previewKtx2(bytes, width, height) {
+  const ktx = readKtx2(bytes);
+  let rgba;
+  if (ktx.basis) {
+    rgba = (await transcodeBasis(ktx.bytes, "rgba8")).levels[0];
+  } else if (ktx.usage === "hdr") {
+    const half = new Uint16Array(ktx.levels[0].slice().buffer);
+    rgba = new Uint8Array(ktx.width * ktx.height * 4);
+    for (let i = 0; i < half.length; i++) {
+      const v = halfToFloat(half[i]);
+      const mapped = i % 4 === 3 ? 1 : (v / (1 + v)) ** (1 / 2.2);
+      rgba[i] = Math.round(Math.min(1, Math.max(0, mapped)) * 255);
+    }
+  } else {
+    rgba = ktx.levels[0];
+  }
+  return fit(rgba, ktx.width, ktx.height, width, height);
+}
+async function renderPreview(world, path, type, width, height) {
+  const gpu = world.resource(Gpu);
+  const server = assetServer(world);
+  const target = new OffscreenTarget(gpu, { label: "preview", width, height });
+  const app = new App();
+  app.world.insertResource(AssetServerResource, server);
+  for (const def of [Meshes, Materials, Textures, SceneAssets, PrefabAssets]) {
+    app.world.insertResource(def, world.initResource(def));
+  }
+  for (const name of ["procgen/Runtime", "procgen/Generators", "procgen/Data"]) {
+    const def = findResource(name);
+    if (def && world.hasResource(def)) app.world.insertResource(def, world.resource(def));
+  }
+  app.addPlugin(
+    TransformPlugin,
+    // The game's shader library, so materials with project shaders preview with them.
+    renderPlugin({ gpu, target, shaders: world.resource(Shaders) }),
+    forwardPlugin(),
+    ScenePlugin
+  );
+  try {
+    await app.init();
+    await server.load(path);
+    let min = [-1, -1, -1];
+    let max = [1, 1, 1];
+    const subject = { "core/Transform": {} };
+    if (type === "Material") {
+      subject["render/Mesh3d"] = { mesh: { path: "procedural:sphere?radius=1&segments=48" } };
+      subject["render/MeshMaterial"] = { material: { path } };
+    } else if (type === "Prefab") {
+      subject["scene/PrefabInstance"] = { prefab: { path } };
+    } else if (type === "Mesh") {
+      subject["render/Mesh3d"] = { mesh: { path } };
+      const b = world.resource(Meshes).get(server.resolve(path)).bounds;
+      min = [b[0], b[1], b[2]];
+      max = [b[3], b[4], b[5]];
+    } else {
+      subject["scene/SceneInstance"] = { scene: { path } };
+      const bounds = server.info(path).info?.bounds;
+      if (bounds) {
+        min = bounds.min;
+        max = bounds.max;
+      }
+    }
+    if (type === "Prefab") {
+      const probe = loadScene(
+        app.world,
+        { version: 1, entities: [{ name: "subject", components: subject }] },
+        { id: "preview-bounds" }
+      );
+      await whenSceneReady(app.world, "preview-bounds");
+      app.update(1 / 60);
+      const box = worldBounds(app.world, probe.entities.get("subject"));
+      if (box) {
+        min = box.min;
+        max = box.max;
+      }
+      unloadScene(app.world, "preview-bounds", { collect: false });
+    }
+    const center = [0, 1, 2].map((i) => (min[i] + max[i]) / 2);
+    const radius = Math.max(
+      1e-3,
+      Math.hypot(max[0] - min[0], max[1] - min[1], max[2] - min[2]) / 2
+    );
+    const fov = 40;
+    const distance = radius / Math.sin(fov / 2 * Math.PI / 180) * 1.05;
+    const dir = vec3.normalize(vec3.create(), vec3.create(1, 0.7, 1.2));
+    const eye = [0, 1, 2].map((i) => center[i] + dir[i] * distance);
+    const rotation = quat.lookRotation(
+      quat.create(),
+      vec3.create(-dir[0], -dir[1], -dir[2]),
+      vec3.create(0, 1, 0)
+    );
+    const scene = {
+      version: 1,
+      resources: { "render/AmbientLight": { color: [1, 1, 1], brightness: 3e3 } },
+      entities: [
+        {
+          name: "key",
+          components: {
+            "render/DirectionalLight": { illuminance: "daylight" },
+            "core/Transform": { rotationEuler: [-45, 35, 0] }
+          }
+        },
+        { name: "subject", components: subject },
+        {
+          name: "camera",
+          components: {
+            "render/Camera3d": {
+              fovY: fov,
+              near: Math.max(1e-4, distance - radius * 2) / 10,
+              clearColor: [0.05, 0.055, 0.07, 1]
+            },
+            "core/Transform": { translation: eye, rotation: [...rotation] }
+          }
+        }
+      ]
+    };
+    const { entities } = loadScene(app.world, scene, { id: "preview" });
+    await whenSceneReady(app.world, "preview");
+    for (let i = 0; i < 200; i++) {
+      app.update(1 / 60);
+      await app.world.resource(Shaders).whenIdle();
+      await gpu.pipelines.whenIdle();
+      const stats = [...app.world.tryResource(RenderStats)?.values() ?? []];
+      const pending = stats.reduce((n, v) => n + v.pending, 0);
+      if (i >= 3 && pending === 0 && gpu.pipelines.pending === 0 && gpu.pipelines.skipped === 0) {
+        break;
+      }
+      await new Promise((r) => setTimeout(r, 2));
+    }
+    const shot = captureView(app.world, `camera:${entities.get("camera")}`);
+    app.update(1 / 60);
+    const image = await shot;
+    return { width: image.width, height: image.height, data: image.data };
+  } finally {
+    releaseSceneHooks(app.world);
+    target.destroy();
+  }
+}
+function worldBounds(world, root) {
+  const meshes = world.resource(Meshes);
+  const min = [Infinity, Infinity, Infinity];
+  const max = [-Infinity, -Infinity, -Infinity];
+  const visit = (e) => {
+    const m = world.tryGet(e, Mesh3d);
+    const g = world.tryGet(e, GlobalTransform)?.matrix;
+    const mesh = m && meshes.get(m.mesh);
+    if (mesh && g) {
+      const b = mesh.bounds;
+      for (let c = 0; c < 8; c++) {
+        const x = c & 1 ? b[3] : b[0];
+        const y = c & 2 ? b[4] : b[1];
+        const z = c & 4 ? b[5] : b[2];
+        for (let r = 0; r < 3; r++) {
+          const v = g[r * 4] * x + g[r * 4 + 1] * y + g[r * 4 + 2] * z + g[r * 4 + 3];
+          if (v < min[r]) min[r] = v;
+          if (v > max[r]) max[r] = v;
+        }
+      }
+    }
+    for (const child of world.tryGet(e, Children)?.entities ?? []) if (child !== null) visit(child);
+  };
+  visit(root);
+  return min[0] <= max[0] ? { min, max } : void 0;
+}
+async function previewAsset(world, path, width, height, options) {
+  const entry = assetServer(world).entry(path);
+  if (!entry) {
+    throw new ShardError("assets/not-found", `No asset "${path}" in the catalog`, {
+      hint: "asset.list shows every asset."
+    });
+  }
+  if (entry.type === "Texture") return texturePreview(world, entry.path, width, height);
+  if (entry.type === "Material" || entry.type === "Mesh" || entry.type === "Scene" || entry.type === "Prefab") {
+    if (!world.tryResource(Gpu)) {
+      throw new ShardError(
+        "protocol/no-renderer",
+        "Previews of meshes, materials, and scenes need the renderer"
+      );
+    }
+    return renderPreview(world, entry.path, entry.type, width, height);
+  }
+  const custom = findAssetPreview(entry.type);
+  if (custom) return custom(world, entry.path, width, height, options);
+  throw new ShardError("protocol/no-preview", `${entry.type} assets have no preview`, {
+    hint: "Previews exist for textures, materials, meshes, scenes, and types that register one."
+  });
+}
+export {
+  previewAsset,
+  previewKtx2
+};

package/dist/server.d.ts

@@ -0,0 +1,59 @@
+import { type ComponentDef, type World } from '@aethervtt/shard-core';
+import type { Platform } from '@aethervtt/shard-platform';
+import { type App } from '@aethervtt/shard-runtime';
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: number | string | null;
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: number | string | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export interface JsonRpcNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params: unknown;
+}
+export interface MethodDef {
+    name: string;
+    description: string;
+    params: ComponentDef;
+    handler(ctx: HandlerContext, params: Record<string, unknown>): unknown;
+}
+export interface HandlerContext {
+    app: App;
+    world: World;
+    options: ProtocolServerOptions;
+}
+export interface ProtocolServerOptions {
+    /**
+     * 'manual': the host has no frame loop (headless servers, tests); `time.step` runs frames itself.
+     * 'loop': a runner drives frames; `time.step` waits for it. Default 'manual'.
+     */
+    frames?: 'manual' | 'loop';
+    /** For scene files by path. */
+    platform?: Platform;
+    /** Extra methods from the host (e.g. `project.reload`), added to the built-in ones. */
+    methods?: readonly MethodDef[];
+}
+export declare const METHODS: MethodDef[];
+export type Topic = 'log' | 'error' | 'frame' | 'project';
+export interface ProtocolServer {
+    readonly methods: readonly MethodDef[];
+    handle(request: JsonRpcRequest): Promise<JsonRpcResponse | undefined>;
+    /** Receives notifications for subscribed topics. Returns an unsubscribe function. */
+    onNotification(listener: (notification: JsonRpcNotification) => void): () => void;
+    /** Sends a notification on `topic` to subscribers (hosts use it for e.g. project reloads). */
+    publish(topic: Topic, params: unknown): void;
+    close(): void;
+}
+/** Serves the protocol for one app. Transports feed requests into `handle`. */
+export declare function createProtocolServer(app: App, options?: ProtocolServerOptions): ProtocolServer;