@aethervtt/shard-core 0.0.1

package/dist/scheduler/system.d.ts

@@ -0,0 +1,74 @@
+import type { Commands } from '../ecs/commands.js';
+import type { EventReader } from '../ecs/events.js';
+import type { World } from '../ecs/world.js';
+import type { EventDef } from '../schema/resource.js';
+export interface SystemContext {
+    /** Deferred changes, applied right after this system runs. */
+    readonly commands: Commands;
+    /** World tick when this system last ran (0 before its first run). Use for added/changed. */
+    readonly lastRunTick: number;
+    /** World tick of the current run. */
+    readonly thisRunTick: number;
+    /** This system's own reader for an event (created on first use, then reused). */
+    reader<T>(event: EventDef<T>): EventReader<T>;
+}
+/** A run condition. Give it a `label` (see `condition`) so it shows up readably in `describe()`. */
+export type Condition = ((world: World) => boolean) & {
+    readonly label?: string;
+};
+export declare function condition(label: string, fn: (world: World) => boolean): Condition;
+export declare function not(inner: Condition): Condition;
+export declare function conditionLabel(c: Condition): string;
+export interface SystemSpec<S> {
+    /** Unique, namespaced (`game/movement`). Shows up in the profiler, logs, and agent API. */
+    name: string;
+    description?: string;
+    /** Runs once before the first run. Returns the system's local state (queries, scratch). */
+    setup?(world: World): S;
+    run(state: S, world: World, ctx: SystemContext): void;
+}
+export type Label = SystemDef<unknown> | SystemSetDef;
+interface Orderable<Self> {
+    after(...labels: Label[]): Self;
+    before(...labels: Label[]): Self;
+    runIf(...conditions: Condition[]): Self;
+}
+export interface SystemDef<S = unknown> extends Orderable<SystemConfig> {
+    readonly kind: 'system';
+    readonly name: string;
+    readonly description: string | undefined;
+    setup?(world: World): S;
+    run(state: S, world: World, ctx: SystemContext): void;
+    inSet(...sets: SystemSetDef[]): SystemConfig;
+}
+export interface SystemSetDef extends Orderable<SystemSetConfig> {
+    readonly kind: 'set';
+    readonly name: string;
+}
+/** A system plus its scheduling constraints. Immutable; every method returns a new config. */
+export declare class SystemConfig implements Orderable<SystemConfig> {
+    readonly system: SystemDef<unknown>;
+    readonly afterLabels: readonly Label[];
+    readonly beforeLabels: readonly Label[];
+    readonly conditions: readonly Condition[];
+    readonly sets: readonly SystemSetDef[];
+    constructor(system: SystemDef<unknown>, after?: readonly Label[], before?: readonly Label[], conditions?: readonly Condition[], sets?: readonly SystemSetDef[]);
+    after(...labels: Label[]): SystemConfig;
+    before(...labels: Label[]): SystemConfig;
+    runIf(...more: Condition[]): SystemConfig;
+    inSet(...more: SystemSetDef[]): SystemConfig;
+}
+/** Constraints applied to every system in a set. */
+export declare class SystemSetConfig implements Orderable<SystemSetConfig> {
+    readonly set: SystemSetDef;
+    readonly afterLabels: readonly Label[];
+    readonly beforeLabels: readonly Label[];
+    readonly conditions: readonly Condition[];
+    constructor(set: SystemSetDef, after?: readonly Label[], before?: readonly Label[], conditions?: readonly Condition[]);
+    after(...labels: Label[]): SystemSetConfig;
+    before(...labels: Label[]): SystemSetConfig;
+    runIf(...more: Condition[]): SystemSetConfig;
+}
+export declare function defineSystem<S = undefined>(spec: SystemSpec<S>): SystemDef<S>;
+export declare function defineSystemSet(name: string): SystemSetDef;
+export {};

package/dist/scheduler/system.js

@@ -0,0 +1,106 @@
+function condition(label, fn) {
+  return Object.assign((world) => fn(world), { label });
+}
+function not(inner) {
+  return condition(`not(${conditionLabel(inner)})`, (world) => !inner(world));
+}
+function conditionLabel(c) {
+  return c.label ?? (c.name || "anonymous");
+}
+class SystemConfig {
+  system;
+  afterLabels;
+  beforeLabels;
+  conditions;
+  sets;
+  constructor(system, after = [], before = [], conditions = [], sets = []) {
+    this.system = system;
+    this.afterLabels = after;
+    this.beforeLabels = before;
+    this.conditions = conditions;
+    this.sets = sets;
+  }
+  after(...labels) {
+    const { system, afterLabels, beforeLabels, conditions, sets } = this;
+    return new SystemConfig(system, [...afterLabels, ...labels], beforeLabels, conditions, sets);
+  }
+  before(...labels) {
+    const { system, afterLabels, beforeLabels, conditions, sets } = this;
+    return new SystemConfig(system, afterLabels, [...beforeLabels, ...labels], conditions, sets);
+  }
+  runIf(...more) {
+    const { system, afterLabels, beforeLabels, conditions, sets } = this;
+    return new SystemConfig(system, afterLabels, beforeLabels, [...conditions, ...more], sets);
+  }
+  inSet(...more) {
+    const { system, afterLabels, beforeLabels, conditions, sets } = this;
+    return new SystemConfig(system, afterLabels, beforeLabels, conditions, [...sets, ...more]);
+  }
+}
+class SystemSetConfig {
+  set;
+  afterLabels;
+  beforeLabels;
+  conditions;
+  constructor(set, after = [], before = [], conditions = []) {
+    this.set = set;
+    this.afterLabels = after;
+    this.beforeLabels = before;
+    this.conditions = conditions;
+  }
+  after(...labels) {
+    return new SystemSetConfig(
+      this.set,
+      [...this.afterLabels, ...labels],
+      this.beforeLabels,
+      this.conditions
+    );
+  }
+  before(...labels) {
+    return new SystemSetConfig(
+      this.set,
+      this.afterLabels,
+      [...this.beforeLabels, ...labels],
+      this.conditions
+    );
+  }
+  runIf(...more) {
+    return new SystemSetConfig(this.set, this.afterLabels, this.beforeLabels, [
+      ...this.conditions,
+      ...more
+    ]);
+  }
+}
+function defineSystem(spec) {
+  const def = {
+    kind: "system",
+    name: spec.name,
+    description: spec.description,
+    run: spec.run,
+    after: (...labels) => new SystemConfig(def).after(...labels),
+    before: (...labels) => new SystemConfig(def).before(...labels),
+    runIf: (...conditions) => new SystemConfig(def).runIf(...conditions),
+    inSet: (...sets) => new SystemConfig(def).inSet(...sets)
+  };
+  if (spec.setup) def.setup = spec.setup;
+  return def;
+}
+function defineSystemSet(name) {
+  const def = {
+    kind: "set",
+    name,
+    after: (...labels) => new SystemSetConfig(def).after(...labels),
+    before: (...labels) => new SystemSetConfig(def).before(...labels),
+    runIf: (...conditions) => new SystemSetConfig(def).runIf(...conditions)
+  };
+  return def;
+}
+export {
+  SystemConfig,
+  SystemSetConfig,
+  condition,
+  conditionLabel,
+  defineSystem,
+  defineSystemSet,
+  not
+};

package/dist/schema/color.d.ts

@@ -0,0 +1,7 @@
+export declare function srgbToLinear(c: number): number;
+export declare function linearToSrgb(c: number): number;
+export declare const HEX_COLOR: RegExp;
+/** Parses `#rrggbb` or `#rrggbbaa` (sRGB) into linear RGBA. */
+export declare function hexToLinear(hex: string): [number, number, number, number];
+/** Formats linear RGBA as sRGB hex, or returns undefined if hex can't represent it exactly. */
+export declare function linearToHex(color: readonly number[]): string | undefined;

package/dist/schema/color.js

@@ -0,0 +1,34 @@
+function srgbToLinear(c) {
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+function linearToSrgb(c) {
+  return c <= 31308e-7 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055;
+}
+const HEX_COLOR = /^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+function hexToLinear(hex) {
+  const byte = (i) => Number.parseInt(hex.slice(i, i + 2), 16) / 255;
+  const a = hex.length === 9 ? byte(7) : 1;
+  return [srgbToLinear(byte(1)), srgbToLinear(byte(3)), srgbToLinear(byte(5)), a];
+}
+function linearToHex(color) {
+  const channels = [];
+  for (let i = 0; i < 4; i++) {
+    const c = color[i];
+    if (c < 0 || c > 1) return void 0;
+    channels.push(Math.round((i === 3 ? c : linearToSrgb(c)) * 255));
+  }
+  const alpha = channels[3] === 255 ? "" : channels[3].toString(16).padStart(2, "0");
+  const hex = `#${channels.slice(0, 3).map((c) => c.toString(16).padStart(2, "0")).join("")}${alpha}`;
+  const back = hexToLinear(hex);
+  for (let i = 0; i < 4; i++) {
+    if (Math.fround(back[i]) !== Math.fround(color[i])) return void 0;
+  }
+  return hex;
+}
+export {
+  HEX_COLOR,
+  hexToLinear,
+  linearToHex,
+  linearToSrgb,
+  srgbToLinear
+};

package/dist/schema/component.d.ts

@@ -0,0 +1,71 @@
+import { ShardError } from '../error.js';
+import type { JsonObject, JsonSchema } from '../json.js';
+import { type AnyField, type Fields, type InferFields, type SchemaContext, type Storage } from './field.js';
+export interface ColumnLayout {
+    readonly name: string;
+    readonly field: AnyField;
+    readonly storage: Storage;
+    readonly stride: number;
+}
+export interface ComponentOptions {
+    description?: string;
+    /** Defaults to 1. Versions above 1 need `migrate`. */
+    version?: number;
+    /** Upgrades JSON written at version `from` to version `from + 1`. */
+    migrate?: (from: number, json: unknown) => unknown;
+    /**
+     * Components added automatically (with defaults) whenever this one is added, transitively.
+     * Spawning `Mesh3d` brings `Transform`, which brings `GlobalTransform`.
+     */
+    requires?: readonly ComponentDef[];
+    /** False for derived components (computed each frame), which scene files never contain. */
+    serialize?: boolean;
+    /**
+     * False leaves the component out of saved games (0038) while scenes still write it: state that
+     * rebuilds itself, or that belongs to the session rather than the playthrough.
+     */
+    save?: boolean;
+}
+export interface ComponentDef<F extends Fields = Fields> {
+    readonly kind: 'component';
+    /** Process-wide numeric id, used internally by the ECS. Never serialized. */
+    readonly id: number;
+    readonly name: string;
+    readonly fields: F;
+    readonly isTag: boolean;
+    readonly description: string | undefined;
+    readonly version: number;
+    /** Column descriptors, in field order. ECS tables are built from this alone. */
+    readonly layout: readonly ColumnLayout[];
+    /** Components added along with this one. */
+    readonly requires: readonly ComponentDef[];
+    /** Whether scene files and the protocol write this component. */
+    readonly serializable: boolean;
+    /** Whether saved games include it: serializable, and not `save: false`. */
+    readonly saved: boolean;
+    defaults(): InferFields<F>;
+    serialize(value: InferFields<F>): JsonObject;
+    /** Validates, then converts. Throws the first validation error. */
+    deserialize(json: unknown, ctx?: SchemaContext): InferFields<F>;
+    validate(json: unknown, ctx?: SchemaContext): ShardError[];
+    jsonSchema(): JsonSchema;
+    /** Runs migrations from `fromVersion` up to the current version. */
+    upgrade(json: unknown, fromVersion: number): unknown;
+}
+export type TagDef = ComponentDef<Record<never, never>>;
+/**
+ * The component defined under `name`, or undefined. Throws `schema/ambiguous-name` if two different
+ * definitions share the name (a world's registry would reject that too).
+ */
+export declare function findComponent(name: string): ComponentDef | undefined;
+/** All component definitions, sorted by name. */
+export declare function allComponents(): ComponentDef[];
+export type Infer<C> = C extends ComponentDef<infer F> ? InferFields<F> : never;
+export declare function defineComponent<const F extends Fields>(name: string, fields: F, options?: ComponentOptions): ComponentDef<F>;
+/**
+ * A schema for data that isn't an entity component (file formats, protocol parameters, settings):
+ * validation, defaults, (de)serialization, and JSON Schema, without joining the component catalog.
+ */
+export declare function defineSchema<const F extends Fields>(name: string, fields: F, options?: Pick<ComponentOptions, 'description' | 'version' | 'migrate'>): ComponentDef<F>;
+/** A component with no fields. Takes part in queries; stores nothing. */
+export declare function defineTag(name: string, options?: Omit<ComponentOptions, 'version' | 'migrate'>): TagDef;

package/dist/schema/component.js

@@ -0,0 +1,120 @@
+import { ShardError } from "../error.js";
+import {
+  defaultsOf,
+  objectFromJson,
+  objectSchema,
+  objectToJson,
+  validateObject
+} from "./field.js";
+import { allocateId, assertName, isRedefinable, recordRedefinition } from "./names.js";
+const definitions = /* @__PURE__ */ new Map();
+function findComponent(name) {
+  const defs = definitions.get(name);
+  if (!defs || defs.length === 0) return void 0;
+  if (defs.length > 1) {
+    throw new ShardError("schema/ambiguous-name", `Several components are defined as "${name}"`, {
+      hint: "Two modules define the same name. Rename one, or import the shared definition."
+    });
+  }
+  return defs[0];
+}
+function allComponents() {
+  return [...definitions.values()].flat().sort((a, b) => a.name.localeCompare(b.name));
+}
+function defineComponent(name, fields, options = {}) {
+  const existing = definitions.get(name);
+  const previous = existing && isRedefinable(name) ? existing.at(-1) : void 0;
+  const def = buildSchema(name, fields, options, previous?.id);
+  if (previous) {
+    definitions.set(name, [def]);
+    recordRedefinition({
+      kind: "component",
+      name,
+      previous,
+      next: def,
+      undo: () => definitions.set(name, [previous])
+    });
+  } else if (existing) existing.push(def);
+  else definitions.set(name, [def]);
+  return def;
+}
+function defineSchema(name, fields, options = {}) {
+  return buildSchema(name, fields, { ...options, serialize: false });
+}
+function buildSchema(name, fields, options, reuseId) {
+  assertName("component", name);
+  const version = options.version ?? 1;
+  if (!Number.isInteger(version) || version < 1) {
+    throw new ShardError("schema/invalid-version", `Component "${name}" has invalid version`, {
+      hint: "Versions are integers starting at 1."
+    });
+  }
+  if (version > 1 && !options.migrate) {
+    throw new ShardError(
+      "schema/missing-migration",
+      `Component "${name}" is at version ${version} but has no migrate function`
+    );
+  }
+  const layout = Object.entries(fields).map(([fieldName, field]) => ({
+    name: fieldName,
+    field,
+    storage: field.storage,
+    stride: field.stride
+  }));
+  const validate = (json, ctx) => {
+    const errors = [];
+    validateObject(fields, json, "", errors, ctx);
+    return errors;
+  };
+  const def = {
+    kind: "component",
+    id: reuseId ?? allocateId(),
+    name,
+    fields,
+    isTag: layout.length === 0,
+    description: options.description,
+    version,
+    layout,
+    requires: options.requires ?? [],
+    serializable: options.serialize ?? true,
+    saved: (options.serialize ?? true) && (options.save ?? true),
+    defaults: () => defaultsOf(fields),
+    serialize: (value) => objectToJson(fields, value),
+    deserialize(json, ctx) {
+      const errors = validate(json, ctx);
+      if (errors.length > 0) throw errors[0];
+      return objectFromJson(fields, json, ctx);
+    },
+    validate,
+    jsonSchema: () => {
+      const schema = {
+        $schema: "https://json-schema.org/draft/2020-12/schema",
+        title: name
+      };
+      if (options.description) schema.description = options.description;
+      return { ...schema, ...objectSchema(fields), "x-version": version };
+    },
+    upgrade(json, fromVersion) {
+      if (fromVersion > version) {
+        throw new ShardError(
+          "schema/future-version",
+          `"${name}" data is version ${fromVersion}, newer than this build's version ${version}`
+        );
+      }
+      let current = json;
+      for (let v = fromVersion; v < version; v++) current = options.migrate(v, current);
+      return current;
+    }
+  };
+  return def;
+}
+function defineTag(name, options = {}) {
+  return defineComponent(name, {}, options);
+}
+export {
+  allComponents,
+  defineComponent,
+  defineSchema,
+  defineTag,
+  findComponent
+};

package/dist/schema/field.d.ts

@@ -0,0 +1,145 @@
+import type { Entity } from '../ecs/entity.js';
+import { ShardError } from '../error.js';
+import { type JsonSchema, type JsonValue } from '../json.js';
+export type NumericStorage = 'f32' | 'f64' | 'i8' | 'i16' | 'i32' | 'u8' | 'u16' | 'u32';
+export type Storage = NumericStorage | 'object';
+export type TypedArrayFor<S extends Storage> = S extends 'f32' ? Float32Array : S extends 'f64' ? Float64Array : S extends 'i8' ? Int8Array : S extends 'i16' ? Int16Array : S extends 'i32' ? Int32Array : S extends 'u8' ? Uint8Array : S extends 'u16' ? Uint16Array : S extends 'u32' ? Uint32Array : never;
+export type TypedArray = TypedArrayFor<NumericStorage>;
+export type Column = TypedArray | unknown[];
+export type FieldKind = NumericStorage | 'bool' | 'vec2' | 'vec3' | 'vec4'
+/** Three i32 components (grid cells). */
+ | 'ivec3' | 'quat' | 'mat3' | 'mat4' | 'affine3x4' | 'color' | 'enum' | 'entity' | 'string' | 'handle' | 'list' | 'struct' | 'json'
+/** A size with a unit: pixels, a percent, or auto (`@aethervtt/shard-ui`'s `uiLength`). */
+ | 'length';
+export interface FieldOptions<V> {
+    /** Written for agents and tools: what the field means, not its type. */
+    description?: string;
+    default?: V;
+    /** Numeric fields and each component of vectors. */
+    min?: number;
+    max?: number;
+    unit?: string;
+    hidden?: boolean;
+    readonly?: boolean;
+    /** Missing values are an error instead of taking the default. */
+    required?: boolean;
+    /**
+     * Named values for number fields. Files may write the name (`"illuminance": "daylight"`); it
+     * resolves to the number on load. The JSON Schema lists the names as alternatives.
+     */
+    presets?: Readonly<Record<string, number>>;
+}
+/** A reference to an asset. `guid` is the identity; `path` is for readers. */
+export interface AssetRef<T extends string = string> {
+    readonly type: T;
+    guid: string | undefined;
+    path: string | undefined;
+}
+export interface ResolvedAsset {
+    readonly guid: string;
+    readonly path: string;
+    readonly type: string;
+}
+/** Optional hooks for things the schema can't know on its own. */
+export interface SchemaContext {
+    /** Resolves an entity path (e.g. `lobby/sofa_02`) to an entity. */
+    resolveEntity?(path: string): Entity | undefined;
+    /** Looks up an asset by guid or path, for validation and to fill in the other half. */
+    resolveAsset?(ref: {
+        guid?: string;
+        path?: string;
+    }): ResolvedAsset | undefined;
+}
+export interface FieldType<V = unknown, S extends Storage = Storage> {
+    readonly kind: FieldKind;
+    readonly storage: S;
+    /** Values per row in the column (3 for vec3). */
+    readonly stride: number;
+    readonly options: FieldOptions<V>;
+    /** A struct's fields. */
+    readonly fields?: Fields;
+    /** A list's item type. */
+    readonly item?: AnyField;
+    /** The asset type a handle refers to. */
+    readonly assetType?: string;
+    /** Phantom, for type inference only. */
+    readonly __value?: V;
+    defaultValue(): V;
+    read(column: Column, row: number): V;
+    write(column: Column, row: number, value: V): void;
+    validate(json: unknown, path: string, errors: ShardError[], ctx: SchemaContext | undefined): void;
+    toJson(value: V): JsonValue;
+    fromJson(json: unknown, ctx: SchemaContext | undefined): V;
+    jsonSchema(): JsonSchema;
+}
+export type AnyField = FieldType<unknown, Storage>;
+export type Fields = Record<string, AnyField>;
+export type FieldValue<T> = T extends FieldType<infer V, Storage> ? V : never;
+export type InferFields<F extends Fields> = {
+    -readonly [K in keyof F]: FieldValue<F[K]>;
+};
+/** What you may pass in: arrays can be readonly, since values are copied into columns. */
+export type FieldInput<V> = V extends unknown[] ? Readonly<V> : V;
+/** Input for spawn/add/set: any subset of fields; missing ones take defaults or stay unchanged. */
+export type InitFields<F extends Fields> = {
+    [K in keyof F]?: FieldInput<FieldValue<F[K]>>;
+};
+type Factory<V, S extends Storage> = FieldType<V, S> & ((options?: FieldOptions<V>) => FieldType<V, S>);
+/**
+ * The shortest decimal that reads back as the same 32-bit float, so f32 values serialize as `0.4`
+ * rather than `0.4000000059604645` (what a Float32Array hands back).
+ */
+export declare function f32ToJson(v: number): number;
+export type Vec2 = [number, number];
+export type Vec3 = [number, number, number];
+export type Vec4 = [number, number, number, number];
+export type IVec3 = [number, number, number];
+export type Quat = [number, number, number, number];
+export type Color = [number, number, number, number];
+type Tuple<N extends number, Acc extends number[] = []> = Acc['length'] extends N ? Acc : Tuple<N, [...Acc, number]>;
+/** Column-major 3x3. */
+export type Mat3 = Tuple<9>;
+/** Column-major 4x4. */
+export type Mat4 = Tuple<16>;
+/** Top three rows of an affine 4x4, row by row (see `affine` in math). */
+export type Affine3x4 = Tuple<12>;
+declare function enumField<const T extends readonly string[]>(values: T, options?: FieldOptions<T[number]>): FieldType<T[number], 'u8'>;
+declare function handle<const T extends string>(type: T, options?: FieldOptions<AssetRef<T> | null>): FieldType<AssetRef<T> | null, 'object'>;
+declare function list<I extends AnyField>(inner: I, options?: FieldOptions<FieldValue<I>[]>): FieldType<FieldValue<I>[], 'object'>;
+declare function struct<F extends Fields>(fields: F, options?: FieldOptions<InferFields<F>>): FieldType<InferFields<F>, 'object'>;
+export declare function defaultsOf<F extends Fields>(fields: F): InferFields<F>;
+export declare function validateObject(fields: Fields, json: unknown, path: string, errors: ShardError[], ctx: SchemaContext | undefined): void;
+export declare function objectToJson(fields: Fields, value: Record<string, unknown>): {
+    [key: string]: JsonValue;
+};
+export declare function objectFromJson<F extends Fields>(fields: F, json: Record<string, unknown>, ctx: SchemaContext | undefined): InferFields<F>;
+export declare function objectSchema(fields: Fields): JsonSchema;
+/** Field type constructors. Bare (`t.f32`) or with options (`t.f32({ default: 1 })`). */
+export declare const t: {
+    f32: Factory<number, "f32">;
+    f64: Factory<number, "f64">;
+    i8: Factory<number, "i8">;
+    i16: Factory<number, "i16">;
+    i32: Factory<number, "i32">;
+    u8: Factory<number, "u8">;
+    u16: Factory<number, "u16">;
+    u32: Factory<number, "u32">;
+    bool: Factory<boolean, "u8">;
+    vec2: Factory<Vec2, "f32">;
+    vec3: Factory<Vec3, "f32">;
+    vec4: Factory<Vec4, "f32">;
+    ivec3: Factory<IVec3, "i32">;
+    quat: Factory<Quat, "f32">;
+    mat3: Factory<[number, number, number, number, number, number, number, number, number], "f32">;
+    mat4: Factory<[number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number], "f32">;
+    affine3x4: Factory<[number, number, number, number, number, number, number, number, number, number, number, number], "f32">;
+    color: Factory<Color, "f32">;
+    enum: typeof enumField;
+    entity: Factory<number | null, "f64">;
+    string: Factory<string, "object">;
+    handle: typeof handle;
+    list: typeof list;
+    struct: typeof struct;
+    json: Factory<JsonValue, "object">;
+};
+export {};