@aethervtt/shard-core 0.0.1 → 0.2.0

package/dist/ecs/host-write.d.ts

@@ -0,0 +1,5 @@
+import type { ComponentDef } from '../schema/component.js';
+/** Runs `fn` with `hostOnly` component writes allowed. */
+export declare function withHostWrite<T>(fn: () => T): T;
+/** Throws unless a host grant is open. The world calls it before writing a `hostOnly` component. */
+export declare function assertHostWrite(def: ComponentDef): void;

package/dist/ecs/host-write.js

@@ -0,0 +1,24 @@
+import { ShardError } from "../error.js";
+let depth = 0;
+function withHostWrite(fn) {
+  depth++;
+  try {
+    return fn();
+  } finally {
+    depth--;
+  }
+}
+function assertHostWrite(def) {
+  if (depth > 0) return;
+  throw new ShardError(
+    "core/owner-not-authorable",
+    `"${def.name}" can only be written by the host`,
+    {
+      hint: "Ownership is a grant from host code: spawn with world.owners.spawn(owner, ...) or world.owners.adopt(owner, entity)."
+    }
+  );
+}
+export {
+  assertHostWrite,
+  withHostWrite
+};

package/dist/ecs/index.d.ts

@@ -3,6 +3,7 @@ export { type Entity, entityGeneration, entityIndex, formatEntity, MAX_ENTITIES,
 export { EventQueue, EventReader } from './events.js';
 export { ChildOf, Children, Derived } from './hierarchy.js';
 export { type LifecycleEvent, type LifecycleKind, type LifecycleObserver, type LifecycleTrigger, onAdd, onRemove, onSet, type TriggerEvent, type TriggerObserver, } from './observers.js';
+export { OwnedBy, Owner, type OwnerDescription, type OwnerLimits, type OwnerQuota, OwnerReleased, Owners, type OwnerUsage, } from './owners.js';
 export { Query, type QueryDescriptor } from './query.js';
 export { type ColumnOf, ComponentStorage, Table, type TickSource } from './table.js';
 export { type ComponentInit, World, type WorldStats } from './world.js';

package/dist/ecs/index.js

@@ -13,6 +13,12 @@ import {
   onRemove,
   onSet
 } from "./observers.js";
+import {
+  OwnedBy,
+  Owner,
+  OwnerReleased,
+  Owners
+} from "./owners.js";
 import { Query } from "./query.js";
 import { ComponentStorage, Table } from "./table.js";
 import { World } from "./world.js";
@@ -25,6 +31,10 @@ export {
   EventQueue,
   EventReader,
   MAX_ENTITIES,
+  OwnedBy,
+  Owner,
+  OwnerReleased,
+  Owners,
   Query,
   Table,
   World,

package/dist/ecs/owners.d.ts

@@ -0,0 +1,113 @@
+import type { Entity } from './entity.js';
+import type { ComponentInit, World } from './world.js';
+/** What an owner may hold at most, itself and its child owners together. */
+export interface OwnerLimits {
+    entities?: number;
+    triangles?: number;
+    textures?: number;
+    bytes?: number;
+}
+export type OwnerQuota = keyof OwnerLimits;
+/** What an owner holds now: its own and its child owners' together. */
+export interface OwnerUsage {
+    entities: number;
+    triangles: number;
+    textures: number;
+    bytes: number;
+}
+export interface OwnerDescription {
+    name: string;
+    parent: string | undefined;
+    children: string[];
+    released: boolean;
+    /** Usage including child owners, which is what limits apply to. */
+    usage: OwnerUsage;
+    limits: OwnerLimits;
+    /** Sections other packages add: asset leases, GPU objects. */
+    [section: string]: unknown;
+}
+export declare const OwnedBy: import("..").ComponentDef<{
+    readonly owner: import("..").FieldType<number, "u32">;
+    readonly inherited: import("..").FieldType<boolean, "u8">;
+}>;
+export declare const OwnerReleased: import("..").EventDef<{
+    name: string;
+    entities: number;
+}>;
+/** Created by `world.owners.create`; held by host code, never serialized. */
+export declare class Owner {
+    readonly name: string;
+    readonly parent: Owner | undefined;
+    readonly limits: Readonly<OwnerLimits>;
+    /** @internal The value `OwnedBy.owner` stores. */
+    readonly id: number;
+    /** @internal Use `world.owners.create`. */
+    constructor(token: symbol, id: number, name: string, parent: Owner | undefined, limits: OwnerLimits);
+}
+type ReleaseHook = (owner: Owner) => void;
+type Describer = (owner: Owner) => unknown;
+/** The world's owners (`world.owners`). */
+export declare class Owners {
+    private readonly world;
+    private readonly states;
+    private readonly issued;
+    private readonly releaseHooks;
+    private readonly describers;
+    private nextId;
+    private live;
+    constructor(world: World);
+    /** A new owner. With `parent`, its usage counts toward the parent's limits too. */
+    create(name: string, options?: {
+        parent?: Owner;
+        limits?: OwnerLimits;
+    }): Owner;
+    /** Spawns an entity owned by `owner`: the only way to create an owned entity. */
+    spawn(owner: Owner, ...inits: readonly ComponentInit[]): Entity;
+    /** Gives an existing entity, and the descendants that had no owner of their own, to `owner`. */
+    adopt(owner: Owner, entity: Entity): void;
+    /**
+     * Despawns everything `owner` and its child owners hold (with descendants), drops their leases
+     * (unloading assets no one else leases, and their GPU objects), and sends `OwnerReleased`. The
+     * owner and its children are unusable afterwards (`core/owner-released`).
+     */
+    release(owner: Owner): void;
+    /** Counts, limits and the sections other packages add (asset leases, GPU objects). */
+    describe(owner: Owner): OwnerDescription;
+    /** Every live owner, for agents (`owners.describe` with no name). */
+    list(): {
+        name: string;
+        parent: string | undefined;
+        usage: OwnerUsage;
+    }[];
+    /** The live owner named `name`, for host code that keeps names rather than objects. */
+    find(name: string): Owner | undefined;
+    /** The name of the entity's owner, or undefined. Reading ownership needs no grant. */
+    nameOf(entity: Entity): string | undefined;
+    isReleased(owner: Owner): boolean;
+    /**
+     * Reserves `amount` of a quota for work about to happen (an asset lease, a GPU upload): throws
+     * `core/owner-quota` and changes nothing if it would exceed a limit of the owner or an ancestor.
+     */
+    charge(owner: Owner, quota: Exclude<OwnerQuota, 'entities'>, amount: number): void;
+    /**
+     * Throws `core/owner-quota` unless `amount` more of `quota` fits `owner` and its ancestors. For work
+     * that makes many things at once (a scene load) and must create nothing if it doesn't fit.
+     */
+    ensureCapacity(owner: Owner, quota: OwnerQuota, amount: number): void;
+    /** Gives back what `charge` reserved. */
+    refund(owner: Owner, quota: Exclude<OwnerQuota, 'entities'>, amount: number): void;
+    /** Runs when an owner is released, after its entities are gone (assets drop its leases here). */
+    onRelease(hook: ReleaseHook): () => void;
+    /** Adds a section to `describe` (e.g. `leases`, `gpu`). */
+    addDescriber(section: string, describe: Describer): () => void;
+    /** Throws `core/owner-released` or `core/owner-invalid` unless `owner` is live and issued here. */
+    private state;
+    private check;
+    private adjust;
+    private ownerIdOf;
+    /** The entity and its descendants that are unowned or owned by `from` through inheritance. */
+    private collect;
+    /** A new child of an owned parent takes the parent's owner, unless it has its own. */
+    private inherit;
+}
+export {};

package/dist/ecs/owners.js

@@ -0,0 +1,297 @@
+import { ShardError } from "../error.js";
+import { defineComponent } from "../schema/component.js";
+import { t } from "../schema/field.js";
+import { defineEvent } from "../schema/resource.js";
+import { ChildOf, Children } from "./hierarchy.js";
+import { withHostWrite } from "./host-write.js";
+import { onAdd, onRemove, onSet } from "./observers.js";
+const OwnedBy = defineComponent(
+  "core/OwnedBy",
+  {
+    owner: t.u32({ description: "The owner id; world.owners.nameOf(entity) gives its name." }),
+    inherited: t.bool({ description: "Set when the entity took its parent's owner." })
+  },
+  {
+    description: "Who owns this entity (0061). Only host code holding the Owner writes it (world.owners.spawn / adopt); children take their parent's owner. Never in scene files.",
+    hostOnly: true
+  }
+);
+const OwnerReleased = defineEvent("core/OwnerReleased", {
+  description: "An owner was released: its entities despawned, its leases dropped."
+});
+const QUOTAS = ["entities", "triangles", "textures", "bytes"];
+const ISSUE = /* @__PURE__ */ Symbol("owner");
+class Owner {
+  name;
+  parent;
+  limits;
+  /** @internal The value `OwnedBy.owner` stores. */
+  id;
+  /** @internal Use `world.owners.create`. */
+  constructor(token, id, name, parent, limits) {
+    if (token !== ISSUE) {
+      throw new ShardError("core/owner-invalid", "Owners are created with world.owners.create", {
+        hint: "An Owner is a grant from host code; it cannot be constructed or copied."
+      });
+    }
+    this.id = id;
+    this.name = name;
+    this.parent = parent;
+    this.limits = Object.freeze({ ...limits });
+  }
+}
+class Owners {
+  world;
+  states = /* @__PURE__ */ new Map();
+  issued = /* @__PURE__ */ new WeakMap();
+  releaseHooks = /* @__PURE__ */ new Set();
+  describers = /* @__PURE__ */ new Map();
+  nextId = 1;
+  live = 0;
+  constructor(world) {
+    this.world = world;
+    world.observe(onAdd(OwnedBy), ({ entity }) => {
+      const state = this.states.get(world.get(entity, OwnedBy).owner);
+      if (state) this.adjust(state, "entities", 1);
+    });
+    world.observe(onRemove(OwnedBy), ({ entity }) => {
+      const state = this.states.get(world.get(entity, OwnedBy).owner);
+      if (state) this.adjust(state, "entities", -1);
+    });
+    world.observe(onSet(OwnedBy), ({ entity, previous }) => {
+      const before = previous && this.states.get(previous.owner);
+      const after = this.states.get(world.get(entity, OwnedBy).owner);
+      if (before === after) return;
+      if (before) this.adjust(before, "entities", -1);
+      if (after) this.adjust(after, "entities", 1);
+    });
+    world.observe(onAdd(ChildOf), ({ entity }) => this.inherit(entity));
+    world.observe(onSet(ChildOf), ({ entity }) => this.inherit(entity));
+  }
+  /** A new owner. With `parent`, its usage counts toward the parent's limits too. */
+  create(name, options = {}) {
+    const parent = options.parent ? this.state(options.parent) : void 0;
+    for (const [key, value] of Object.entries(options.limits ?? {})) {
+      if (!QUOTAS.includes(key) || !(typeof value === "number" && value >= 0)) {
+        throw new ShardError("core/owner-invalid", `Invalid owner limit ${key}: ${value}`, {
+          hint: `Limits are non-negative numbers for ${QUOTAS.join(", ")}.`
+        });
+      }
+    }
+    const owner = new Owner(ISSUE, this.nextId++, name, parent?.owner, options.limits ?? {});
+    const state = {
+      owner,
+      children: /* @__PURE__ */ new Set(),
+      parent,
+      usage: { entities: 0, triangles: 0, textures: 0, bytes: 0 },
+      released: false
+    };
+    parent?.children.add(state);
+    this.states.set(owner.id, state);
+    this.issued.set(owner, state);
+    this.live++;
+    return owner;
+  }
+  /** Spawns an entity owned by `owner`: the only way to create an owned entity. */
+  spawn(owner, ...inits) {
+    const state = this.state(owner);
+    this.check(state, "entities", 1);
+    const spawn = this.world.spawn.bind(this.world);
+    return withHostWrite(() => spawn(...inits, [OwnedBy, { owner: owner.id, inherited: false }]));
+  }
+  /** Gives an existing entity, and the descendants that had no owner of their own, to `owner`. */
+  adopt(owner, entity) {
+    const state = this.state(owner);
+    const previous = this.world.tryGet(entity, OwnedBy)?.owner;
+    const moving = [];
+    this.collect(entity, previous, moving);
+    this.check(state, "entities", moving.filter((e) => this.ownerIdOf(e) !== owner.id).length);
+    withHostWrite(() => {
+      for (let i = 0; i < moving.length; i++) {
+        const e = moving[i];
+        const value = { owner: owner.id, inherited: e !== entity };
+        if (this.world.has(e, OwnedBy)) this.world.set(e, OwnedBy, value);
+        else this.world.add(e, OwnedBy, value);
+      }
+    });
+  }
+  /**
+   * Despawns everything `owner` and its child owners hold (with descendants), drops their leases
+   * (unloading assets no one else leases, and their GPU objects), and sends `OwnerReleased`. The
+   * owner and its children are unusable afterwards (`core/owner-released`).
+   */
+  release(owner) {
+    const state = this.state(owner);
+    const all = [];
+    const gather = (s) => {
+      for (const child of s.children) gather(child);
+      all.push(s);
+    };
+    gather(state);
+    const ids = new Set(all.map((s) => s.owner.id));
+    const world = this.world;
+    const doomed = [];
+    const q = world.query({ with: [OwnedBy] });
+    for (const table of q.tables) {
+      const column = table.column(OwnedBy, "owner");
+      for (let i = 0; i < table.count; i++) {
+        if (ids.has(column[i])) doomed.push(table.entities[i]);
+      }
+    }
+    const counts = /* @__PURE__ */ new Map();
+    for (const s of all) counts.set(s.owner.id, s.usage.entities);
+    for (const e of doomed) if (world.isAlive(e)) world.despawn(e);
+    for (const s of all) {
+      for (const hook of this.releaseHooks) hook(s.owner);
+      s.released = true;
+      this.states.delete(s.owner.id);
+      this.live--;
+      world.send(OwnerReleased, { name: s.owner.name, entities: counts.get(s.owner.id) ?? 0 });
+    }
+    state.parent?.children.delete(state);
+  }
+  /** Counts, limits and the sections other packages add (asset leases, GPU objects). */
+  describe(owner) {
+    const state = this.issued.get(owner);
+    if (!state) throw invalid();
+    const out = {
+      name: owner.name,
+      parent: owner.parent?.name,
+      children: [...state.children].map((c) => c.owner.name),
+      released: state.released,
+      usage: { ...state.usage },
+      limits: { ...owner.limits }
+    };
+    if (!state.released) for (const [key, fn] of this.describers) out[key] = fn(owner);
+    return out;
+  }
+  /** Every live owner, for agents (`owners.describe` with no name). */
+  list() {
+    return [...this.states.values()].map((s) => ({
+      name: s.owner.name,
+      parent: s.owner.parent?.name,
+      usage: { ...s.usage }
+    }));
+  }
+  /** The live owner named `name`, for host code that keeps names rather than objects. */
+  find(name) {
+    for (const s of this.states.values()) if (s.owner.name === name) return s.owner;
+    return void 0;
+  }
+  /** The name of the entity's owner, or undefined. Reading ownership needs no grant. */
+  nameOf(entity) {
+    const id = this.ownerIdOf(entity);
+    return id === void 0 ? void 0 : this.states.get(id)?.owner.name;
+  }
+  isReleased(owner) {
+    return this.issued.get(owner)?.released ?? true;
+  }
+  /**
+   * Reserves `amount` of a quota for work about to happen (an asset lease, a GPU upload): throws
+   * `core/owner-quota` and changes nothing if it would exceed a limit of the owner or an ancestor.
+   */
+  charge(owner, quota, amount) {
+    const state = this.state(owner);
+    this.check(state, quota, amount);
+    this.adjust(state, quota, amount);
+  }
+  /**
+   * Throws `core/owner-quota` unless `amount` more of `quota` fits `owner` and its ancestors. For work
+   * that makes many things at once (a scene load) and must create nothing if it doesn't fit.
+   */
+  ensureCapacity(owner, quota, amount) {
+    this.check(this.state(owner), quota, amount);
+  }
+  /** Gives back what `charge` reserved. */
+  refund(owner, quota, amount) {
+    const state = this.issued.get(owner);
+    if (state && !state.released) this.adjust(state, quota, -amount);
+  }
+  /** Runs when an owner is released, after its entities are gone (assets drop its leases here). */
+  onRelease(hook) {
+    this.releaseHooks.add(hook);
+    return () => this.releaseHooks.delete(hook);
+  }
+  /** Adds a section to `describe` (e.g. `leases`, `gpu`). */
+  addDescriber(section, describe) {
+    this.describers.set(section, describe);
+    return () => this.describers.delete(section);
+  }
+  /** Throws `core/owner-released` or `core/owner-invalid` unless `owner` is live and issued here. */
+  state(owner) {
+    const state = this.issued.get(owner);
+    if (!state) throw invalid();
+    if (state.released) {
+      throw new ShardError("core/owner-released", `Owner "${owner.name}" was released`, {
+        hint: "Create a new owner; a released one holds nothing and accepts nothing."
+      });
+    }
+    return state;
+  }
+  check(state, quota, amount) {
+    if (amount <= 0) return;
+    for (let s = state; s; s = s.parent) {
+      const limit = s.owner.limits[quota];
+      if (limit !== void 0 && s.usage[quota] + amount > limit) {
+        throw new ShardError(
+          "core/owner-quota",
+          `Owner "${s.owner.name}" is at its ${quota} limit (${s.usage[quota]} of ${limit}; ${amount} more requested)`,
+          {
+            path: quota,
+            hint: s === state ? "Release what it no longer needs, or create it with a higher limit." : `The limit belongs to "${s.owner.name}", which counts its child owners' usage.`
+          }
+        );
+      }
+    }
+  }
+  adjust(state, quota, amount) {
+    for (let s = state; s; s = s.parent) s.usage[quota] += amount;
+  }
+  ownerIdOf(entity) {
+    return this.world.tryGet(entity, OwnedBy)?.owner;
+  }
+  /** The entity and its descendants that are unowned or owned by `from` through inheritance. */
+  collect(entity, from, out) {
+    out.push(entity);
+    const children = this.world.tryGet(entity, Children);
+    if (!children) return;
+    for (const child of children.entities) {
+      if (child === null || !this.world.isAlive(child)) continue;
+      const own = this.world.tryGet(child, OwnedBy);
+      if (own && !(own.inherited && own.owner === from)) continue;
+      this.collect(child, from, out);
+    }
+  }
+  /** A new child of an owned parent takes the parent's owner, unless it has its own. */
+  inherit(entity) {
+    if (this.live === 0) return;
+    const world = this.world;
+    const own = world.tryGet(entity, OwnedBy);
+    if (own && !own.inherited) return;
+    const parent = world.get(entity, ChildOf).parent;
+    const from = parent !== null && world.isAlive(parent) ? world.tryGet(parent, OwnedBy) : void 0;
+    if (!from || !this.states.has(from.owner)) return;
+    if (own?.owner === from.owner) return;
+    const moving = [];
+    this.collect(entity, own?.owner, moving);
+    withHostWrite(() => {
+      for (let i = 0; i < moving.length; i++) {
+        const e = moving[i];
+        const value = { owner: from.owner, inherited: true };
+        if (world.has(e, OwnedBy)) world.set(e, OwnedBy, value);
+        else world.add(e, OwnedBy, value);
+      }
+    });
+  }
+}
+function invalid() {
+  return new ShardError("core/owner-invalid", "Not an owner of this world", {
+    hint: "Pass the Owner object world.owners.create returned, in the same world."
+  });
+}
+export {
+  OwnedBy,
+  Owner,
+  OwnerReleased,
+  Owners
+};

package/dist/ecs/world.d.ts

@@ -5,6 +5,7 @@ import type { EventDef, ResourceDef } from '../schema/resource.js';
 import { type Entity } from './entity.js';
 import { EventReader } from './events.js';
 import { type LifecycleObserver, type LifecycleTrigger, type TriggerObserver } from './observers.js';
+import { Owners } from './owners.js';
 import { Query, type QueryDescriptor } from './query.js';
 import { Table, type TickSource } from './table.js';
 /** A component to spawn/add with: the bare definition (defaults), or `[definition, values]`. */
@@ -29,6 +30,14 @@ export declare class World implements TickSource {
     /** Change-detection clock. The scheduler advances it once per system run. */
     tick: number;
     readonly registry: Registry;
+    /**
+     * While true, the next write (`set`, `add`, `remove`, `spawn`, `despawn`, `insertResource`,
+     * `removeResource`, `send`, `patchResource`, `touchResource`) clears it and calls `onWake`. The
+     * on-demand runner sets it when a frame ends and nothing asks for another (0052).
+     */
+    asleep: boolean;
+    /** Called by the first write while `asleep`. Set by the on-demand runner. */
+    onWake: (() => void) | undefined;
     private generations;
     private tableOf;
     private rowOf;
@@ -40,11 +49,21 @@ export declare class World implements TickSource {
     private readonly emptyTable;
     private readonly queries;
     private readonly resources;
+    /** Change tick per resource id: set by insertResource, patchResource, and touchResource. */
+    private readonly resourceTicks;
     private readonly eventQueues;
     private readonly observers;
     private readonly registered;
+    private owners_;
     constructor();
+    /**
+     * Who made what (0061): owners hold entities and asset leases, and release them together.
+     * Only code holding an `Owner` can spawn into it, lease for it, or release it.
+     */
+    get owners(): Owners;
     incrementTick(): number;
+    /** Wakes the world as a write would: if it's asleep, clears `asleep` and calls `onWake`. */
+    wake(): void;
     spawn<const T extends readonly Fields[]>(...inits: {
         [K in keyof T]: ComponentInit<T[K]>;
     }): Entity;
@@ -81,6 +100,18 @@ export declare class World implements TickSource {
     /** Returns a cached query; the same descriptor always gives the same `Query`. */
     query(desc: QueryDescriptor): Query;
     insertResource<T>(def: ResourceDef<T>, value: T): void;
+    /**
+     * Assigns `partial`'s fields onto the resource, marks it changed, and wakes the world. How code
+     * outside a frame writes a resource; a bare field assignment is invisible to both (0052).
+     */
+    patchResource<T extends object>(def: ResourceDef<T>, partial: Partial<T>): T;
+    /** Marks the resource changed and wakes the world, after editing it in place. */
+    touchResource(def: ResourceDef<unknown>): void;
+    /**
+     * Whether the resource was inserted, patched, or touched after tick `since` (a system passes
+     * `ctx.lastRunTick`), like component change detection.
+     */
+    resourceChanged(def: ResourceDef<unknown>, since: number): boolean;
     /** Inserts the resource from its `init` if it isn't present yet, and returns it. */
     initResource<T>(def: ResourceDef<T>): T;
     resource<T>(def: ResourceDef<T>): T;