@adobe/ecs 0.0.0-stage → 0.2.0

package/dist/interface/system/create.d.ts

@@ -0,0 +1,218 @@
+import type { Entity } from '../entity/entity.js';
+import type { Index } from '../indexes/index-type.js';
+import type { Condition } from '../resource/condition.js';
+import type { Body, Context } from './body.js';
+import type { CompositeDeclaration } from './composite-declaration.js';
+import type { Declaration } from './declaration.js';
+import type { CheckMembers, CompositeInputOf, InputOf, ResultOf, ReturnsNoPromise } from './input.js';
+import type { Listed, Property } from './property.js';
+import type { System } from './system.js';
+import type { OneThread, ThreadedBy, ThreadsOf } from './threads.js';
+import type { HeldBy } from './values.js';
+import type { Shared } from '../component/value.js';
+type Lookups<D> = Property<D, "lookup">;
+/** A lookup's `changed` names what it requires: a lookup by entity's `with`, an index lookup's what its index holds. */
+type LookupChanges<D> = {
+    readonly lookup?: {
+        readonly [N in keyof Lookups<D>]?: Lookups<D>[N] extends {
+            readonly index: Index<infer I>;
+        } ? {
+            readonly changed?: readonly HeldBy<I>[] | true;
+        } : {
+            readonly changed?: readonly Listed<Lookups<D>[N], "with">[];
+        };
+    };
+};
+/** What a body reads, writes and reduces into is inferred, never declared. */
+type Inferred = {
+    readonly components?: {
+        readonly read?: never;
+        readonly write?: never;
+        readonly has?: never;
+    };
+    readonly resources?: {
+        readonly read?: never;
+        readonly write?: never;
+        readonly reduce?: never;
+    };
+    readonly up?: {
+        readonly read?: never;
+    };
+    readonly reduce?: never;
+};
+/** A condition is in `is` or `not`, not both. */
+type Conditions<D> = {
+    readonly resources?: {
+        readonly not?: readonly Exclude<Condition, Listed<Property<D, "resources">, "is">>[];
+    };
+};
+/** What a GPU kernel can't use yet, beyond any kernel's limits. */
+type GpuKernel = {
+    readonly lookup?: {
+        readonly [name: string]: never;
+    };
+    readonly components?: {
+        readonly added?: never;
+        readonly changed?: never;
+    };
+    readonly resources?: {
+        readonly changed?: never;
+    };
+    readonly order?: {
+        readonly "error: GPU kernels have no order yet": true;
+    };
+};
+/**
+ * An observer system only reads, after a sync point: its row and resources are read-only, and it never compiles to a
+ * kernel, has no `up`, and is ordered with nothing. That it takes no input is checked at its body.
+ */
+type Observer = {
+    readonly kernel?: false;
+    readonly up?: never;
+    readonly before?: never;
+    readonly after?: never;
+    readonly during?: never;
+};
+/** A system on one entity runs on its row, in no order; that its target is an entity field of its input is checked at its body. */
+type Targeted = {
+    readonly kernel?: false;
+    readonly up?: never;
+    readonly order?: never;
+};
+/** `where` names only shared components, and keeps rows unordered across archetypes, so it's without `up`, `order` and a target. */
+type Where<D> = D extends {
+    readonly components: {
+        readonly where: infer W;
+    };
+} ? {
+    readonly components?: {
+        readonly where?: {
+            readonly [K in Exclude<keyof W, Shared>]: {
+                readonly "error: where names only shared components, which each archetype holds one value of": K;
+            };
+        };
+    };
+} & (D extends {
+    readonly up: object;
+} | {
+    readonly order: object;
+} | {
+    readonly target: string;
+} ? {
+    readonly components?: {
+        readonly where?: {
+            readonly "error: where can't be used with up, order or a target, which run rows across archetypes": true;
+        };
+    };
+} : {}) : {};
+/**
+ * Whether the threads a declaration's objects live on hold, once its type is known: never checked against the
+ * constraint itself, which TypeScript instantiates the parameter with while a predicate in `where` waits for its type.
+ */
+type Placed<D extends Declaration> = Declaration extends D ? {} : OneThread<ThreadsOf<D>, ThreadedBy<D>>;
+type Validate<D extends Declaration> = LookupChanges<D> & Where<D> & Conditions<D> & Inferred & (D extends {
+    readonly kernel: "gpu";
+} ? GpuKernel : {}) & (Property<D, "components"> extends undefined ? {
+    readonly up?: {
+        readonly [key: string]: never;
+    };
+    readonly order?: {
+        readonly "error: a system without components runs once, in no order": true;
+    };
+    readonly kernel?: false | {
+        readonly "error: a system without components runs once, so there's nothing to compile": true;
+    };
+} : {}) & (D extends {
+    readonly up: object;
+} ? {
+    readonly order?: {
+        readonly "error: up and order both decide the order of its rows": true;
+    };
+} : {}) & (D extends {
+    readonly components: {
+        readonly optional: readonly [unknown, ...unknown[]];
+    };
+} ? {
+    readonly kernel?: boolean | {
+        readonly "error: a GPU kernel can't have optional components yet": true;
+    };
+} : {}) & (D extends {
+    readonly observer: true;
+} ? Observer : {}) & (D extends {
+    readonly target: string;
+} ? Targeted : {}) & (D extends {
+    readonly target: string;
+} ? Property<D, "components"> extends undefined ? {
+    readonly target?: {
+        readonly "error: a system on one entity runs on its row, so it needs components": true;
+    };
+} : {} : {}) & {
+    readonly shader?: never;
+    readonly input?: never;
+};
+/** The fields of input `I` that hold an entity. */
+type EntityFields<I> = {
+    [K in keyof I]-?: [Exclude<I[K], undefined>] extends [Entity] ? K : never;
+}[keyof I] & string;
+/**
+ * What a declaration requires of the input its body takes, checked at the body, since the input is known only once the
+ * body is: a target names an entity field of it, and a system with input doesn't filter on added or changed, as its
+ * runs pass different input, nor is it an observer. Every check passes for `never`, the input before the body is
+ * inferred.
+ */
+type Checks<D, I> = [I] extends [never] ? unknown : (D extends {
+    readonly target: infer T extends string;
+} ? [I] extends [undefined] ? {
+    readonly "error: a system with a target takes its input after its context": T;
+} : T extends EntityFields<I> ? unknown : {
+    readonly "error: its target is no entity field of its input": T;
+} : unknown) & ([I] extends [undefined] ? unknown : (D extends {
+    readonly components: {
+        readonly added: object;
+    } | {
+        readonly changed: object;
+    };
+} ? {
+    readonly "error: a system with input can't filter on added or changed, as its runs pass different input; pass it through a resource": true;
+} : unknown) & (D extends {
+    readonly observer: true;
+} ? {
+    readonly "error: an observer system takes no input": true;
+} : unknown));
+/** The body of a system that declares nothing, which runs once per run with its resources and commands. */
+type Alone = (context: Context<{}>) => void;
+/** A composite: its list of members, or its declaration. */
+type Composition = readonly System<unknown>[] | CompositeDeclaration;
+/** A composite's members. */
+type MembersOf<C> = C extends CompositeDeclaration ? C["systems"] : C;
+/** A member whose input has a field of a different type than another member's becomes the error saying so. */
+type Checked<C> = C extends Alone ? ReturnsNoPromise<C> : C extends CompositeDeclaration ? {
+    readonly systems: CheckMembers<C["systems"]>;
+} : CheckMembers<C>;
+/**
+ * Declares a system and returns it; nothing runs. The arguments tell the forms apart:
+ * - `create(body)`: a system that declares nothing, whose body runs once per run with its resources and commands.
+ * - `create(declaration, body)`: a system.
+ * - `create([move, collide])`: a composite of the systems listed, which may live on different threads.
+ * - `create({ systems: [move, collide], after: [input] })`: a composite with constraints.
+ *
+ * What a body reads, writes and reduces into the build infers from it. Each run passes a composite's members one
+ * input, with every field of theirs. Throws if a system names a key that isn't registered as its kind, its body writes
+ * a reference, a lookup's rows are read where it writes them or it goes through an index keyed by what it writes, its
+ * rows are ordered by an index it isn't sorted or keyed by what it writes, its object components and resources live on
+ * different threads, or its reductions, conditions, `up`, `order` or placement can't hold, or it's an observer and
+ * writes, reduces, takes input, is a kernel, has `up` or is ordered; if the build couldn't follow how its body uses its
+ * resources, lookups or parent; or if a composite's member isn't a system a constructor returned, or two members
+ * declare an input field with different schemas. A composite's observer members run after its sync point, ordered
+ * with nothing.
+ *
+ * A run of a system without components resolves to what its body returns, or `undefined` when its conditions, resource
+ * change filters or index lookups' `changed: true` skip it; a run of any other system or a composite to nothing. A
+ * body returns no promise, by type and at runtime, where returning one fails its system: a run never waits for one.
+ *
+ * One argument, a body or a composite, is one overload, so a mistake in it is reported where it is rather than as no
+ * overload matching.
+ */
+export declare function create<const D extends Declaration, B extends Body<D, never>>(declaration: D & Validate<D> & Placed<D>, body: B & Checks<D, InputOf<D, B>> & ReturnsNoPromise<B>): System<InputOf<D, B>, ResultOf<D, B>>;
+export declare function create<const C extends Alone | Composition>(only: C & Checked<C>): C extends (context: Context<{}>) => infer R ? System<undefined, R> : System<CompositeInputOf<MembersOf<C>>>;
+export {};

package/dist/interface/system/create.js

@@ -0,0 +1,55 @@
+import { takeIdOfDeclaration } from '../registry/ids.js';
+import { nameOf } from '../registry/items.js';
+import { claimSystem } from '../registry/program.js';
+import { checkComposite, checkLeaf, inputSchemaOf } from './check.js';
+import { accessOf, compact, componentLists, lookupsLists, resourceUses, upReads, whereReadsOf } from './resolve.js';
+// The plugin passes the schema of the body's input as a third argument.
+export function create(first, second, input) {
+    // The plugin gives its id to the call's first argument: the declaration, the members, or the body made into a
+    // system alone.
+    const id = takeIdOfDeclaration(first);
+    if (isList(first))
+        return compose(first, { systems: first }, id);
+    if (typeof first !== "function" && second === undefined && "systems" in first)
+        return compose(first, first, id);
+    const declared = typeof first === "function" ? {} : first;
+    const body = typeof first === "function" ? first : second;
+    if (body === undefined)
+        throw new Error("A system needs a body, and a composite its systems.");
+    const name = nameOf(first, id, "system");
+    const declaration = resolve(`System "${name}"`, declared, accessOf(`System "${name}"`, first));
+    const schema = inputSchemaOf(name, body, declaration.components === undefined ? 1 : 2, input);
+    const system = { kind: "system", name, declaration, input: schema, body };
+    checkLeaf(system);
+    claimSystem(system, id);
+    return system;
+}
+/** A declaration as the world takes it, with what the build inferred its body uses. */
+const resolve = (what, declared, access) => {
+    const reading = declared.observer === true;
+    const { components, lookup, up, resources, ...rest } = declared;
+    const uses = resourceUses(what, access, resources?.is);
+    // What `where`'s predicates read counts as the system's reads, for its order, conflicts and placement.
+    const whereReads = whereReadsOf(what, components, access);
+    const conditions = resources?.is ?? [];
+    for (const key of whereReads)
+        if (!uses.read.includes(key) && !uses.write.includes(key) && !conditions.includes(key))
+            uses.read.push(key);
+    const resolved = {
+        ...rest,
+        ...components === undefined ? {} : { components: componentLists(components, access.components, reading, whereReads) },
+        ...lookup === undefined ? {} : { lookup: lookupsLists(lookup, access) },
+        ...up === undefined ? {} : { up: { through: up.through, read: upReads(what, access) } },
+    };
+    const lists = compact({ read: uses.read, write: uses.write, reduce: uses.reduce, changed: resources?.changed, is: resources?.is, not: resources?.not });
+    return Object.keys(lists).length === 0 ? resolved : { ...resolved, resources: lists };
+};
+const isList = (value) => Array.isArray(value);
+/** A composite of `declaration`, labeled by `first`, the argument the plugin labeled. */
+const compose = (first, declaration, id) => {
+    const system = { kind: "composite", name: nameOf(first, id, "system"), declaration };
+    checkComposite(system);
+    claimSystem(system, id);
+    return system;
+};
+//# sourceMappingURL=create.js.map

package/dist/interface/system/create.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../../../src/interface/system/create.ts"],"names":[],"mappings":"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"}

package/dist/interface/system/declaration.d.ts

@@ -0,0 +1,75 @@
+import type { Index } from '../indexes/index-type.js';
+import type { ComponentAccess, ComponentLists, ResourceAccess, ResourceLists, SystemLookup, SystemLookupLists, Up, UpLists } from './access.js';
+import type { Shader } from './render.js';
+import type { System } from './system.js';
+/**
+ * A system never declares its thread: it runs on the one its object components and resources live on, those it
+ * reads, writes or filters on by change, through its row, lookups, `up` and resources. Without them, a kernel runs on
+ * the kernel pool and any other system on `"world"`. A declaration says only what its body can't show: which entities
+ * it runs over, its filters and conditions, and its order; the build infers what the body reads, writes and reduces.
+ */
+export type Declaration = {
+    /**
+     * Whether its body compiles to a kernel, a function the build compiles to run on every matched row, in parallel, on
+     * the kernel pool. Values in `components` and `lookup` must be structs and resources read-only.
+     * - Without it, a system with components compiles when its body is in the kernel subset and its declaration allows
+     *   it, and otherwise runs as written, computing as the body as written does. A system without components runs once,
+     *   as written.
+     * - `true`: compiles, or the build fails saying why. Its arithmetic may round each step to storage precision, as
+     *   WASM's f32 SIMD lanes do, so its results may differ from the body as written.
+     * - `false`: runs as written, on its thread.
+     * - `"gpu"`: also has no lookups, change filters, commands or loops, and only 4-byte scalar values, its `up`
+     *   included. It runs as a compute shader in a world with a GPU, and as a kernel on the pool in one without. Every
+     *   matched row counts as changed in what it writes.
+     */
+    readonly kernel?: boolean | "gpu";
+    /** The entities it runs over. Omitted for a system that runs once per run. */
+    readonly components?: ComponentAccess;
+    readonly lookup?: {
+        readonly [name: string]: SystemLookup;
+    };
+    /**
+     * Runs rows in depth order through `through`, so each reads its parent's values after the parent ran, as the
+     * context's `up`, or null for a row without a parent. With change filters, a row also passes when its parent, or
+     * what it reads of its parent, changed since the system last ran, or it moved to another archetype, as removing its
+     * parent moves it. Rows on or under a parent cycle don't run.
+     */
+    readonly up?: Up;
+    /**
+     * Runs the rows it matches that this sorted index holds, in key order and then entity order; with change filters,
+     * the rows that pass, in that order. Commands, reductions and side effects follow it. Like a lookup through the
+     * index, it reads the index's key parts and doesn't write them. Not with `up`.
+     */
+    readonly order?: Index<{
+        readonly sorted: true;
+    }>;
+    readonly resources?: ResourceAccess;
+    /**
+     * The field of its body's input naming the one entity it runs on: its body runs once, on that entity's row, when
+     * the entity is alive and matches `components`, and not at all otherwise. Needs `components`; not with `kernel`,
+     * `up` or `order`, nor with a body that reduces.
+     */
+    readonly target?: string;
+    /** Makes this a render system (see `render`): its body records GPU work over the GPU copy of the components it names. */
+    readonly shader?: Shader;
+    /** Hard constraint. */
+    readonly before?: readonly System<unknown>[];
+    /** Hard constraint. */
+    readonly after?: readonly System<unknown>[];
+    /** Runs inside the span of the systems listed: after what they follow and before what follows them. */
+    readonly during?: readonly System<unknown>[];
+    /**
+     * Runs after the last sync point of each run and tick (a tick is a run of the added composite), reading the settled
+     * state; changes nothing; never ordered; doesn't keep the loop ticking.
+     */
+    readonly observer?: true;
+};
+/** A declaration as the world takes it: the build's inferred reads, writes and reductions joined with what it declares. */
+export type Resolved = Omit<Declaration, "components" | "lookup" | "up" | "resources"> & {
+    readonly components?: ComponentLists;
+    readonly lookup?: {
+        readonly [name: string]: SystemLookupLists;
+    };
+    readonly up?: UpLists;
+    readonly resources?: ResourceLists;
+};

package/dist/interface/system/declaration.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=declaration.js.map

package/dist/interface/system/declaration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declaration.js","sourceRoot":"","sources":["../../../src/interface/system/declaration.ts"],"names":[],"mappings":""}

package/dist/interface/system/definition.d.ts

@@ -0,0 +1,4 @@
+import type { Composite } from './composite.js';
+import type { Leaf } from './leaf.js';
+/** What the implementation knows of a system: the value a constructor returned, with its kind, declaration and body. */
+export type Definition = Leaf | Composite;

package/dist/interface/system/definition.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=definition.js.map

package/dist/interface/system/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../../src/interface/system/definition.ts"],"names":[],"mappings":""}

package/dist/interface/system/index.d.ts

@@ -0,0 +1,3 @@
+export type { Commands } from './commands.js';
+export * from './create.js';
+export { render, type RenderContext, type RenderTable } from './render.js';

package/dist/interface/system/index.js

@@ -0,0 +1,3 @@
+export * from './create.js';
+export { render } from './render.js';
+//# sourceMappingURL=index.js.map

package/dist/interface/system/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/interface/system/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,MAAM,EAAwC,MAAM,aAAa,CAAC"}

package/dist/interface/system/input.d.ts

@@ -0,0 +1,59 @@
+import type { Property } from './property.js';
+import type { System } from './system.js';
+/** How many parameters come before a body's input: the row and the context, or the context alone. */
+type Before<D> = D extends {
+    readonly components: object;
+} ? 2 : 1;
+/** The input body `B` of declaration `D` takes: the type of its parameter after the context, or `undefined` without one. */
+export type InputOf<D, B> = B extends (...parameters: infer P) => void ? P["length"] extends Before<D> ? undefined : P[Before<D>] : undefined;
+/** Whether a declaration's conditions, resource change filters or index lookups' `changed: true` can skip its body. */
+type Skippable<D> = D extends {
+    readonly resources: {
+        readonly is: object;
+    } | {
+        readonly not: object;
+    } | {
+        readonly changed: object;
+    };
+} ? true : true extends {
+    [N in keyof Property<D, "lookup">]: Property<D, "lookup">[N] extends {
+        readonly changed: true;
+    } ? true : false;
+}[keyof Property<D, "lookup">] ? true : false;
+/**
+ * What a run of a system of declaration `D` and body `B` resolves to: for one without components, what its body
+ * returns, or `undefined` too when its body may be skipped; for one with components, nothing.
+ */
+export type ResultOf<D, B> = D extends {
+    readonly components: object;
+} ? void : B extends (...parameters: never[]) => infer R ? [R] extends [void] ? R : Skippable<D> extends true ? R | undefined : R : void;
+/** Whether `R` is exactly `unknown` or `object`, return types wide enough to hide a promise. */
+type Hides<R> = unknown extends R ? true : [R] extends [object] ? [object] extends [R] ? [keyof R] extends [never] ? string extends R ? false : true : false : false : false;
+/**
+ * A body returning a promise or another `PromiseLike`, or declared to return `unknown` or `object`, which may be one,
+ * becomes the error saying it returns none: a run never waits for one, so a body starts the work and a later run
+ * finishes it. Types can't tell a body returning `any`, nor an async function typed as returning `void`.
+ */
+export type ReturnsNoPromise<B> = B extends (...parameters: never[]) => infer R ? 0 extends (1 & R) ? unknown : [Extract<R, PromiseLike<unknown>>] extends [never] ? Hides<R> extends true ? NoPromise : unknown : NoPromise : unknown;
+type NoPromise = {
+    readonly "error: a body returns no promise; start the work, and finish it in a later run": true;
+};
+/** What `run` takes after a system: nothing, or one value. */
+export type Input<I> = [I] extends [undefined] ? [] : [input: I];
+/** A member's input fields, or `unknown` without input. */
+type Fields<S> = S extends System<infer I> ? [Exclude<I, undefined>] extends [never] ? unknown : Exclude<I, undefined> : unknown;
+type Merged<T, A = unknown> = T extends readonly [infer S, ...infer R] ? Merged<R, A & Fields<S>> : A;
+/** The input a composite of `T` takes: every field of its members' inputs, or `undefined` when none has input. */
+export type CompositeInputOf<T> = unknown extends Merged<T> ? undefined : {
+    [K in keyof Merged<T>]: Merged<T>[K];
+};
+/** The fields of `M` whose type differs from the one the composite's input `I` gives them. */
+type Conflicts<M, I> = {
+    [K in keyof M]-?: [Exclude<M[K], undefined>] extends [Exclude<I[K & keyof I], undefined>] ? never : K;
+}[keyof M];
+type Checked<S, I> = [Conflicts<Fields<S>, I>] extends [never] ? S : `Input field "${Extract<Conflicts<Fields<S>, I>, string>}" has a different type in another member of this composite.`;
+/** Members whose input has a field of a different type than another member's. */
+export type CheckMembers<T> = {
+    readonly [P in keyof T]: Checked<T[P], Merged<T>>;
+};
+export {};

package/dist/interface/system/input.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=input.js.map

package/dist/interface/system/input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.js","sourceRoot":"","sources":["../../../src/interface/system/input.ts"],"names":[],"mappings":""}

package/dist/interface/system/leaf.d.ts

@@ -0,0 +1,19 @@
+import type { Schema } from '../schema/schema.js';
+import type { Resolved } from './declaration.js';
+import type { Name } from './name.js';
+/** The schema of a body's input: an object of named fields. */
+export type InputSchema = Extract<Schema, {
+    readonly type: "object";
+}>;
+/**
+ * A system that runs a body: `"render"` for one made by `render`, `"system"` otherwise. Its body's parameters are
+ * checked where it's created, so a leaf holds any body. `input` is the schema of its body's input, which the plugin
+ * gives from the type of the body's parameter after its context, or undefined; every leaf has it, so leaves share a shape.
+ */
+export type Leaf = {
+    readonly kind: "system" | "render";
+    readonly name: Name;
+    readonly declaration: Resolved;
+    readonly input: InputSchema | undefined;
+    readonly body: (...parameters: never[]) => void;
+};

package/dist/interface/system/leaf.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=leaf.js.map

package/dist/interface/system/leaf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"leaf.js","sourceRoot":"","sources":["../../../src/interface/system/leaf.ts"],"names":[],"mappings":""}

package/dist/interface/system/name.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The label errors give it, for display: its binding, from the id the plugin gave it; for one made in a
+ * function, the binding or function the plugin found it in; else its kind numbered. The value its constructor returns
+ * is its identity, so labels needn't be unique.
+ */
+export type Name = string;

package/dist/interface/system/name.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=name.js.map

package/dist/interface/system/name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"name.js","sourceRoot":"","sources":["../../../src/interface/system/name.ts"],"names":[],"mappings":""}

package/dist/interface/system/property.d.ts

@@ -0,0 +1,4 @@
+export type Property<T, K extends PropertyKey> = T extends {
+    readonly [P in K]?: infer V;
+} ? V : undefined;
+export type Listed<T, K extends PropertyKey> = Property<T, K> extends readonly (infer E)[] ? E : never;

package/dist/interface/system/property.js

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export {};
+//# sourceMappingURL=property.js.map

package/dist/interface/system/property.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"property.js","sourceRoot":"","sources":["../../../src/interface/system/property.ts"],"names":[],"mappings":"AAAA,uDAAuD"}

package/dist/interface/system/render.d.ts

@@ -0,0 +1,84 @@
+import type { Component } from '../component/component.js';
+import type { Index } from '../indexes/index-type.js';
+import type { Condition } from '../resource/condition.js';
+import type { ThreadOfResource } from '../resource/value.js';
+import { gpuDevice } from '../resources/gpu-device.js';
+import type { Body } from './body.js';
+import type { ReturnsNoPromise } from './input.js';
+import type { StructComponent } from './struct.js';
+import type { Shared } from '../component/value.js';
+import type { System } from './system.js';
+import type { OneThread, ThreadedBy, ThreadsOf } from './threads.js';
+/**
+ * How a render system's shaders reach its components: `accessors` names a WGSL function for each component it reads,
+ * generated by `Gpu.wgsl` at bind group `group` (0 by default). A shared component has no column for one to read.
+ */
+export type Shader = {
+    readonly group?: number;
+    readonly accessors: {
+        readonly [name: string]: Exclude<StructComponent, Shared>;
+    };
+};
+/**
+ * One group of matching rows, `0` to `count`: an archetype's, or with `order` every matching row in its order. `bind`
+ * sets the world's bind group for it on a pass.
+ */
+export type RenderTable = {
+    readonly count: number;
+    readonly bind: (pass: GPURenderPassEncoder | GPUComputePassEncoder) => void;
+};
+/**
+ * What a render body records with. `encoder` is the run's: the world submits it, after the run's GPU kernels and
+ * uploads, when the run ends. Acquire canvas textures inside the body.
+ */
+export type RenderContext = {
+    readonly device: GPUDevice;
+    readonly encoder: GPUCommandEncoder;
+    readonly tables: readonly RenderTable[];
+};
+type RenderDeclaration = {
+    /** It matches the components its accessors name, and those in `with`, and none in `not`. */
+    readonly components?: {
+        readonly with?: readonly Component.Key[];
+        readonly not?: readonly Component.Key[];
+    };
+    /** It runs only while `gpuDevice` is set, as if `is` listed it. What its body reads of resources the build infers. */
+    readonly resources?: {
+        readonly is?: readonly Condition[];
+        readonly not?: readonly Condition[];
+    };
+    /**
+     * Draws every matching row as one table, in this sorted index's order: key order, then entity order. Its shaders'
+     * accessors then take a row's position in that order.
+     */
+    readonly order?: Index<{
+        readonly sorted: true;
+        readonly key: readonly Component.Key[];
+    }>;
+    readonly shader: Shader;
+    readonly before?: readonly System<unknown>[];
+    readonly after?: readonly System<unknown>[];
+    readonly during?: readonly System<unknown>[];
+};
+/** What a render body reads of resources is inferred, and what it reads of components its accessors name. */
+type Inferred = {
+    readonly components?: {
+        readonly read?: never;
+        readonly has?: never;
+    };
+    readonly resources?: {
+        readonly read?: never;
+    };
+};
+/**
+ * Declares a render system: it runs once per run on `gpuDevice`'s thread, in schedule order, and records GPU work over
+ * the GPU copy of the components its accessors name, which the world uploads first as needed. It runs only while the
+ * world has a `gpuDevice`. Its body's `tables` hold one table per matching archetype, each in row order; with `order`,
+ * exactly one table of every matching row, across archetypes, in the index's order, so instance `i` is the i-th: a
+ * shader's accessors take that position as their `row`, with the same names and signatures. Throws as `create` does,
+ * for an `order` that isn't a sorted index, and for an accessor its shader can't read on the GPU. A system with `order`
+ * fails its run when a matching archetype holds more rows than 32 bits name beside its slot: 2^31 with up to two
+ * matching archetypes, 2^30 with up to four, and so on.
+ */
+export declare const render: <const D extends RenderDeclaration, B extends Body<D>>(declaration: D & Inferred & OneThread<ThreadsOf<D> | ThreadOfResource<typeof gpuDevice>, ThreadedBy<D>>, body: B & ReturnsNoPromise<B>) => System;
+export {};