@aethervtt/shard-core 0.0.1

package/dist/schema/registry.d.ts

@@ -0,0 +1,38 @@
+import type { JsonSchema } from '../json.js';
+import type { ComponentDef } from './component.js';
+import type { EventDef, ResourceDef } from './resource.js';
+type Def = ComponentDef | ResourceDef<unknown> | EventDef<unknown>;
+export interface RegistryDescription {
+    components: {
+        name: string;
+        description?: string;
+        version: number;
+        tag: boolean;
+        requires: string[];
+        schema: JsonSchema;
+    }[];
+    resources: {
+        name: string;
+        description?: string;
+    }[];
+    events: {
+        name: string;
+        description?: string;
+    }[];
+}
+/**
+ * Names in use by one world. Registering the same definition twice is fine; registering a
+ * different definition under a taken name is an error.
+ */
+export declare class Registry {
+    private readonly byName;
+    private readonly byId;
+    register(def: Def): void;
+    /** Swaps in a definition that reuses an existing one's id (hot reload). */
+    replace(def: Def): void;
+    isRegistered(def: Def): boolean;
+    get(name: string): Def | undefined;
+    component(name: string): ComponentDef | undefined;
+    describe(): RegistryDescription;
+}
+export {};

package/dist/schema/registry.js

@@ -0,0 +1,58 @@
+import { ShardError } from "../error.js";
+class Registry {
+  byName = /* @__PURE__ */ new Map();
+  byId = [];
+  register(def) {
+    if (this.byId[def.id] === def) return;
+    const existing = this.byName.get(def.name);
+    if (existing && existing !== def) {
+      throw new ShardError("schema/duplicate-name", `"${def.name}" is already registered`, {
+        hint: "Two definitions share a name. Rename one, or import the existing definition."
+      });
+    }
+    this.byName.set(def.name, def);
+    this.byId[def.id] = def;
+  }
+  /** Swaps in a definition that reuses an existing one's id (hot reload). */
+  replace(def) {
+    const old = this.byId[def.id];
+    if (old && this.byName.get(old.name) === old) this.byName.delete(old.name);
+    this.byName.set(def.name, def);
+    this.byId[def.id] = def;
+  }
+  isRegistered(def) {
+    return this.byId[def.id] === def;
+  }
+  get(name) {
+    return this.byName.get(name);
+  }
+  component(name) {
+    const def = this.byName.get(name);
+    return def?.kind === "component" ? def : void 0;
+  }
+  describe() {
+    const out = { components: [], resources: [], events: [] };
+    const sorted = [...this.byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+    for (const def of sorted) {
+      const description = def.description ? { description: def.description } : {};
+      if (def.kind === "component") {
+        out.components.push({
+          name: def.name,
+          ...description,
+          version: def.version,
+          tag: def.isTag,
+          requires: def.requires.map((r) => r.name),
+          schema: def.jsonSchema()
+        });
+      } else if (def.kind === "resource") {
+        out.resources.push({ name: def.name, ...description });
+      } else {
+        out.events.push({ name: def.name, ...description });
+      }
+    }
+    return out;
+  }
+}
+export {
+  Registry
+};

package/dist/schema/resource.d.ts

@@ -0,0 +1,48 @@
+import type { ComponentDef } from './component.js';
+export interface ResourceDef<T> {
+    readonly kind: 'resource';
+    readonly id: number;
+    readonly name: string;
+    readonly description: string | undefined;
+    /** Creates the initial value for `world.initResource`. */
+    readonly init: (() => T) | undefined;
+    /**
+     * What hot reload does with the value when the defining code reloads: 'keep' (default) keeps it,
+     * since it's game state; 'replace' takes whatever the new code inserts (configuration, such as
+     * action maps).
+     */
+    readonly reload: 'keep' | 'replace';
+    /**
+     * The value's schema (`defineSchema`), for resources that are plain data: it validates,
+     * serializes, and migrates them. Settings and saved resources have one.
+     */
+    readonly schema: ComponentDef | undefined;
+    /** Saved games include it (0038). Needs `schema`. */
+    readonly persist: boolean;
+    readonly __type?: T;
+}
+export interface ResourceOptions<T> {
+    description?: string;
+    init?: () => T;
+    reload?: 'keep' | 'replace';
+    schema?: ComponentDef;
+    persist?: boolean;
+}
+export declare function defineResource<T>(name: string, options?: ResourceOptions<T>): ResourceDef<T>;
+/** Every resource defined in this process (latest definitions), sorted by name. */
+export declare function allResources(): ResourceDef<unknown>[];
+/** The resource defined under `name` (the latest definition), or undefined. */
+export declare function findResource(name: string): ResourceDef<unknown> | undefined;
+export interface EventDef<T> {
+    readonly kind: 'event';
+    readonly id: number;
+    readonly name: string;
+    readonly description: string | undefined;
+    readonly __type?: T;
+}
+export declare function defineEvent<T = undefined>(name: string, options?: {
+    description?: string;
+}): EventDef<T>;
+/** The event defined under `name` (the latest definition), or undefined. */
+export declare function allEvents(): EventDef<unknown>[];
+export declare function findEvent(name: string): EventDef<unknown> | undefined;

package/dist/schema/resource.js

@@ -0,0 +1,79 @@
+import { ShardError } from "../error.js";
+import { allocateId, assertName, isRedefinable, recordRedefinition } from "./names.js";
+const resources = /* @__PURE__ */ new Map();
+function defineResource(name, options = {}) {
+  assertName("resource", name);
+  if (options.persist && !options.schema) {
+    throw new ShardError(
+      "schema/persist-needs-schema",
+      `Resource "${name}" persists but has no schema`,
+      {
+        hint: "Give it a schema (defineSchema) so saves can validate and migrate it."
+      }
+    );
+  }
+  const previous = isRedefinable(name) ? resources.get(name) : void 0;
+  const def = {
+    kind: "resource",
+    id: previous?.id ?? allocateId(),
+    name,
+    description: options.description,
+    init: options.init,
+    reload: options.reload ?? "keep",
+    schema: options.schema,
+    persist: options.persist ?? false
+  };
+  resources.set(name, def);
+  if (previous) {
+    recordRedefinition({
+      kind: "resource",
+      name,
+      previous,
+      next: def,
+      undo: () => resources.set(name, previous)
+    });
+  }
+  return def;
+}
+function allResources() {
+  return [...resources.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+function findResource(name) {
+  return resources.get(name);
+}
+function defineEvent(name, options = {}) {
+  assertName("event", name);
+  const previous = isRedefinable(name) ? events.get(name) : void 0;
+  const def = {
+    kind: "event",
+    id: previous?.id ?? allocateId(),
+    name,
+    description: options.description
+  };
+  events.set(name, def);
+  if (previous) {
+    recordRedefinition({
+      kind: "event",
+      name,
+      previous,
+      next: def,
+      undo: () => events.set(name, previous)
+    });
+  }
+  return def;
+}
+const events = /* @__PURE__ */ new Map();
+function allEvents() {
+  return [...events.values()];
+}
+function findEvent(name) {
+  return events.get(name);
+}
+export {
+  allEvents,
+  allResources,
+  defineEvent,
+  defineResource,
+  findEvent,
+  findResource
+};

package/dist/test-env.d.ts

@@ -0,0 +1,31 @@
+/**
+ * How strict tests are about time, in one place.
+ *
+ * - `pnpm bench` (`SHARD_BENCH`) holds the exact budgets from the specs, one file at a time.
+ * - `pnpm test` allows 3×, for a machine busy running test files in parallel.
+ * - CI (`SHARD_CI`) checks correctness only. Shared runners render with a software GPU, so their
+ *   timings say nothing about the engine; budgets are unlimited there and timeouts are 5× longer.
+ */
+export type TimingMode = 'bench' | 'test' | 'ci';
+export declare const timingMode: TimingMode;
+/** The factor budgets are multiplied by (and rate floors divided by) in this mode. */
+export declare const slack: number;
+/** A time budget in ms: exact under `pnpm bench`, 3× in `pnpm test`, unlimited in CI. */
+export declare function budget(ms: number): number;
+/** A test or hook timeout in ms: 5× in CI, unchanged everywhere else. */
+export declare function timeout(ms: number): number;
+/**
+ * Counts the garbage collections that start between now and `end()`, for "allocates nothing"
+ * checks. GC entries are delivered asynchronously, so `end()` waits for them, but it only counts
+ * the ones that started inside the window: what the test runner allocates while we wait isn't the
+ * code under test. Collect garbage (`gc()`, with `--expose-gc`) before opening the window.
+ */
+export declare function gcWindow(): {
+    end(): Promise<number>;
+};
+/**
+ * Whether "allocates nothing" checks run. They hold under `pnpm bench` and `pnpm test`; CI turns them
+ * off with the time budgets, since when V8 optimizes (and so whether a call boxes its result) depends
+ * on the runner's CPU and timing.
+ */
+export declare const allocationChecks: boolean;

package/dist/test-env.js

@@ -0,0 +1,37 @@
+const env = globalThis.process?.env ?? {};
+const timingMode = env.SHARD_BENCH ? "bench" : env.SHARD_CI ? "ci" : "test";
+const slack = timingMode === "bench" ? 1 : timingMode === "test" ? 3 : Number.POSITIVE_INFINITY;
+function budget(ms) {
+  return ms * slack;
+}
+function timeout(ms) {
+  return timingMode === "ci" ? ms * 5 : ms;
+}
+const host = globalThis;
+function gcWindow() {
+  const starts = [];
+  const observer = new host.PerformanceObserver((list) => {
+    for (const entry of list.getEntries()) starts.push(entry.startTime);
+  });
+  observer.observe({ entryTypes: ["gc"] });
+  const from = host.performance.now();
+  return {
+    async end() {
+      const to = host.performance.now();
+      await new Promise((resolve) => host.setTimeout(resolve, 50));
+      observer.disconnect();
+      let count = 0;
+      for (const start of starts) if (start >= from && start <= to) count++;
+      return count;
+    }
+  };
+}
+const allocationChecks = timingMode !== "ci";
+export {
+  allocationChecks,
+  budget,
+  gcWindow,
+  slack,
+  timeout,
+  timingMode
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@aethervtt/shard-core",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./math": {
+      "types": "./dist/math/index.d.ts",
+      "default": "./dist/math/index.js"
+    },
+    "./test-env": {
+      "types": "./dist/test-env.d.ts",
+      "default": "./dist/test-env.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aethervtt/shard.git",
+    "directory": "packages/core"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "shard": {
+    "buildSha": "d6c5c6aef4675575c878b02cf2c8f738b4190229"
+  }
+}