@adobe/ecs 0.0.0-stage → 0.1.0

package/src/guide/guide.md

@@ -0,0 +1,551 @@
+# ecs guide
+
+How to use the ECS. Each excerpt comes from a test in this folder; the link under it opens the whole file.
+
+[Setup](#setup)
+
+**Basics**
+
+1. [Resources](#1-resources)
+2. [Entities, components and archetypes](#2-entities-components-and-archetypes)
+3. [Systems](#3-systems)
+4. [Ticks and cadence](#4-ticks-and-cadence)
+
+**Intermediate**
+
+5. [Scheduling and composites](#5-scheduling-and-composites)
+6. [Sync points](#6-sync-points)
+7. [Change filters and conditions](#7-change-filters-and-conditions)
+8. [Input](#8-input)
+9. [Rules](#9-rules)
+10. [Finalizers and change sets](#10-finalizers-and-change-sets)
+11. [Traits, within and references](#11-traits-within-and-references)
+
+**Advanced**
+
+12. [Lookups](#12-lookups)
+13. [Indexes](#13-indexes)
+14. [Kernels](#14-kernels)
+15. [Reductions](#15-reductions)
+16. [GPU kernels and render systems](#16-gpu-kernels-and-render-systems)
+17. [Hierarchies](#17-hierarchies)
+18. [Identity and ids](#18-identity-and-ids)
+19. [Threads](#19-threads)
+
+## Setup
+
+```ts
+// vite.config.ts: compiles kernels, checks each system's declaration against its body, and gives keys and systems ids.
+import { kernelPlugin } from "@adobe/ecs/compiler";
+export default defineConfig({ plugins: [kernelPlugin()] });
+```
+
+Each component and resource is declared once, by augmenting `Components` or `Resources` in `@adobe/ecs` with its
+traits, `type` among them, and registered once with the same traits. Registration's types check the two match.
+`type` is registered as a JSON Schema for the value, in which `{ type: "set", items }` and
+`{ type: "map", keys, values }` describe a `ReadonlySet` and a `ReadonlyMap`. Traits of your own augment `Traits`.
+The examples create worlds with `World.create()`.
+
+## Basics
+
+Resources, values a world holds once, and entities, each holding a set of components, are the whole data model.
+Systems change that data, once per run or on every tick.
+
+### 1. Resources
+
+```ts
+export const gravity = Symbol("gravity");
+export const names = Symbol("names");
+export const audio = Symbol("audio");
+export const focused = Symbol("focused");
+
+// Its traits are declared; `type` is the value's type.
+declare module "@adobe/ecs" {
+    interface Resources {
+        [gravity]: { type: number };
+        [names]: { type: ReadonlyMap<string, number> };
+        [audio]: { type: AudioContext | null };
+        [focused]: { type: Entity };
+    }
+}
+
+// Registration gives the same traits, with a schema that describes exactly the declared type. A resource always has a
+// value: its schema's default, or one beside it.
+Resource.register(gravity, { type: { type: "number", default: -9.8 } });
+Resource.register(names, { type: { type: "map", keys: { type: "string" }, values: { type: "number" } }, default: new Map() });
+// A value that isn't data has no schema and is stored as it is. A type that allows null starts there.
+Resource.register(audio, {});
+// No entity is Entity.none rather than null, so an entity stays data every thread reads.
+Resource.register(focused, { type: { ...Entity.schema, default: Entity.none } });
+
+// Systems read a world: an observer only reads, after the world's changes apply.
+let values: readonly unknown[] = [];
+const read = System.create({ observer: true, resources: { read: [gravity, names, audio, focused] } }, ({ resources }) => {
+    values = [resources[gravity], resources[names], resources[audio], resources[focused]];
+});
+
+await using moon = World.create({ [gravity]: -1.6 });
+// run: runs a system once.
+await moon.run(read);
+expect(values[0]).toBe(-1.6);
+```
+
+[`01-resources.test.ts`](01-resources.test.ts#L5-L45)
+
+### 2. Entities, components and archetypes
+
+```ts
+export const position = Symbol("position");
+export const velocity = Symbol("velocity");
+export const enemy = Symbol("enemy");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [position]: { type: Vec3 };
+        [velocity]: { type: Vec3 };
+        // A tag: present or not, with no value.
+        [enemy]: { type: true };
+    }
+}
+
+Component.register(position, { type: Vec3.schema });
+Component.register(velocity, { type: Vec3.schema });
+Component.register(enemy, { type: { const: true } });
+
+// An archetype names a list of components, once at module scope; it goes wherever a list of components does.
+export const Particle = Archetype.create([position, velocity]);
+
+// Systems spawn entities: name the components, then give their values.
+export const spawn = System.create(({ commands }) => {
+    commands.spawn([position, enemy])({ [position]: [0, 10, 0] });
+    commands.spawn(Particle)({ [position]: [0, 0, 0], [velocity]: [1, 0, 0] });
+});
+
+// Commands also add and remove components, and despawn entities.
+export const defeat = System.create({ components: { has: [enemy] } }, (row, { commands }) => {
+    commands.remove(row.entity, enemy);
+});
+
+// An observer system reads them back, once per entity with its components.
+const foes: Vec3[] = [];
+const readFoes = System.create({ observer: true, components: { read: [position], has: [enemy] } }, row => {
+    foes.push(row[position]);
+});
+let particles = 0;
+const countParticles = System.create({ observer: true, components: { has: Particle } }, () => {
+    particles += 1;
+});
+
+await world.run(spawn);
+await world.run(readFoes);
+await world.run(countParticles);
+expect(foes).toEqual([[0, 10, 0]]);
+expect(particles).toBe(1);
+```
+
+[`02-entities.test.ts`](02-entities.test.ts#L5-L58)
+
+### 3. Systems
+
+```ts
+// Runs once per entity with every component in read and write, and none in not.
+const move = System.create({
+    // Optional: labels the system in reports.
+    name: "physics/move",
+    components: { read: [velocity], write: [position], not: [frozen] },
+    resources: { read: [delta] },
+}, (row, { resources }) => {
+    // Values are replaced whole, never edited in place.
+    row[position] = Vec3.add(row[position], Vec3.scale(row[velocity], resources[delta]));
+});
+
+// Without components, a system runs once per run.
+const count = System.create({ resources: { write: [frames] } }, ({ resources }) => {
+    resources[frames] += 1;
+});
+
+// An observer system reads what the runs before it left, and changes nothing: run one to read the world, or add one to
+// react to it.
+const moved: Vec3[] = [];
+let counted = 0;
+const read = System.create({ observer: true, components: { read: [position], not: [frozen] }, resources: { read: [frames] } }, (row, { resources }) => {
+    moved.push(row[position]);
+    counted = resources[frames];
+});
+
+await world.run(move);
+await world.run(count);
+await world.run(read);
+expect(moved).toEqual([[1, 0, 0]]);
+```
+
+[`03-systems.test.ts`](03-systems.test.ts#L34-L68)
+
+```ts
+const fail = System.create({ name: "fail" }, () => {
+    throw new Error("broken");
+});
+
+// A run resolves to its number. Every run and tick has a report, an entity: `Report.run` says what it ran and how long
+// it took, and `Report.errors` is there only when something went wrong. An observer system added to follow errors as
+// they change logs them; what observer systems throw is in the next run's report.
+const logged: string[] = [];
+const logFailures = System.create({ observer: true, components: { read: [Report.errors], changed: [Report.errors] } }, row => {
+    for (const failure of row[Report.errors].failures) logged.push(`${failure.name}: ${failure.message}`);
+});
+
+world.add(logFailures);
+const run: number = await world.run(fail);
+expect(run).toBe(1);
+expect(logged).toEqual(["fail: broken"]);
+```
+
+[`03-systems.test.ts`](03-systems.test.ts#L70-L86)
+
+### 4. Ticks and cadence
+
+```ts
+// clock is the current tick's: delta is the milliseconds since the last one.
+const advance = System.create({ resources: { read: [clock], write: [elapsed] } }, ({ resources }) => {
+    resources[elapsed] += resources[clock].delta;
+});
+
+// Added, an observer system reacts to changes: with elapsed in changed, it runs after each tick that changed it.
+let reached: (value: number) => void = () => {};
+const watch = System.create({ observer: true, resources: { read: [elapsed], changed: [elapsed] } }, ({ resources }) => {
+    if (resources[elapsed] >= 30) reached(resources[elapsed]);
+});
+
+// cadence ticks once per animation frame by default; fixed ticks every step milliseconds, each with that delta.
+// A tick runs only after a run arrives, unless always is set.
+await using world = World.create({ [cadence]: { kind: "fixed", step: 10 }, [always]: true });
+const ticked = new Promise<number>(resolve => { reached = resolve; });
+// add: runs a system on every tick.
+world.add(advance);
+world.add(watch);
+expect(await ticked).toBeGreaterThanOrEqual(30);
+// remove: takes a system added off every tick again.
+world.remove(advance);
+```
+
+[`04-ticks.test.ts`](04-ticks.test.ts#L17-L51)
+
+```ts
+// A system asks for another tick by contributing a time to wake: the first tick at or after it runs. Work that a tick's
+// commands start and a later tick finishes asks for the next one this way.
+const step = System.create({ resources: { read: [clock], write: [steps] }, reduce: { [wake]: "min" } }, ({ resources, reduce }) => {
+    resources[steps] += 1;
+    if (resources[steps] < 3) reduce[wake](resources[clock].now);
+});
+
+await using world = World.create({ [cadence]: { kind: "fixed", step: 10 } });
+world.add(step);
+// One run arriving ticks once; step's wakes tick twice more.
+await world.run(System.create(() => {}));
+```
+
+[`04-ticks.test.ts`](04-ticks.test.ts#L53-L74)
+
+## Intermediate
+
+### 5. Scheduling and composites
+
+```ts
+const hit = System.create({ components: { read: [damage], write: [health] } }, row => {
+    row[health] -= row[damage];
+});
+// before, after and during list the systems themselves.
+const heal = System.create({ components: { write: [health] }, after: [hit] }, row => {
+    row[health] = Math.min(row[health] * 2, 10);
+});
+// A list of systems is a composite: it runs its members as one system, in their order; members without an order
+// between them may run in parallel. { systems, after, ... } declares one with a name or constraints.
+const frame = System.create([heal, hit]);
+```
+
+[`05-scheduling.test.ts`](05-scheduling.test.ts#L18-L42)
+
+```ts
+// Phases are systems that do nothing; a system during one runs after what the phase follows and before what follows it.
+const update = System.create(() => {});
+const render = System.create({ after: [update] }, () => {});
+const poison = System.create({ components: { write: [health] }, during: [update] }, row => {
+    row[health] -= 1;
+});
+const report = System.create({ components: { read: [health] }, during: [render] }, row => {
+    seen.push(row[health]);
+});
+const phased = System.create([report, poison, update, render]);
+```
+
+[`05-scheduling.test.ts`](05-scheduling.test.ts#L44-L61)
+
+### 6. Sync points
+
+```ts
+// Value writes apply at once; commands wait for the sync point that ends each run, then apply in the order issued.
+const spawn = System.create(({ commands }) => {
+    // spawn gives the entity at once, so later commands can name it.
+    const hero = commands.spawn([health])({ [health]: 3 });
+    commands.add(hero, health, 5);
+    // Spawned and despawned before the sync point, it never exists.
+    commands.despawn(commands.spawn([health])({ [health]: 1 }));
+});
+// A composite is one run with one sync point: count runs after spawn, before its entities exist.
+const count = System.create({ components: { has: [health] }, resources: { write: [seen] }, after: [spawn] }, (row, { resources }) => {
+    resources[seen] += 1;
+});
+const frame = System.create([spawn, count]);
+```
+
+[`06-sync-points.test.ts`](06-sync-points.test.ts#L20-L52)
+
+```ts
+// An observer runs after the sync point of every run and tick it's added to, reading what it left; it writes nothing.
+const watch = System.create({ observer: true, components: { read: [health] } }, row => {
+    healths.push(row[health]);
+});
+```
+
+[`06-sync-points.test.ts`](06-sync-points.test.ts#L35-L38)
+
+### 7. Change filters and conditions
+
+```ts
+// A resource in changed passes the first run and each run after it changes: no run-once flag needed.
+const load = System.create({ resources: { read: [level], changed: [level] } }, ({ resources, commands }) => {
+    commands.spawn([score, shown, boss])({ [score]: 0, [shown]: -1 });
+    for (let i = 0; i < resources[level]; i++) commands.spawn([score, shown])({ [score]: 0, [shown]: -1 });
+});
+// A component in changed passes only rows written since this system last ran.
+const show = System.create({ components: { read: [score], write: [shown], changed: [score] } }, row => {
+    row[shown] = row[score];
+});
+```
+
+[`07-change-filters.test.ts`](07-change-filters.test.ts#L35-L65)
+
+```ts
+// Runs only while each resource in is is neither null nor false, and each in not is; is reads it narrowed.
+const step = System.create({ resources: { is: [map], not: [paused], write: [steps] } }, ({ resources }) => {
+    resources[steps] += resources[map].width;
+});
+```
+
+[`07-change-filters.test.ts`](07-change-filters.test.ts#L67-L88)
+
+### 8. Input
+
+```ts
+// input is an object schema of named fields; each run passes a value of it.
+const hit = System.create({
+    components: { write: [health] },
+    input: { type: "object", properties: { amount: { type: "number" } } },
+}, (row, { input }) => {
+    row[health] -= input.amount;
+});
+
+// target names an input field holding an entity: the system runs on that entity's row alone, or on none once it's gone.
+const heal = System.create({
+    components: { write: [health] },
+    input: { type: "object", properties: { entity: Entity.schema, amount: { type: "number" } } },
+    target: "entity",
+}, (row, { input }) => {
+    row[health] += input.amount;
+});
+
+// Systems with input are run, not added; a composite's input has every field its members declare.
+await world.run(hit, { amount: 3 });
+await world.run(heal, { entity: player, amount: 1 });
+```
+
+[`08-input.test.ts`](08-input.test.ts#L18-L48)
+
+### 9. Rules
+
+```ts
+declare module "@adobe/ecs" {
+    interface Components {
+        // Only rules add derived components, starting at their schema's default.
+        [drawn]: { type: true; derived: true };
+        [layer]: { type: number; derived: true };
+    }
+}
+
+Component.register(drawn, { type: { const: true }, derived: true });
+Component.register(layer, { type: { type: "number", default: 1 }, derived: true });
+
+// Entities matching a rule have what it derives, only while they match.
+Rule.create({ components: { has: [mesh], not: [hidden] }, derive: [drawn] });
+// Several rules may derive one component, present while any matches.
+Rule.create({ components: { has: [sprite], not: [hidden] }, derive: [drawn] });
+// Rules build on what others derive.
+Rule.create({ components: { has: [drawn] }, derive: [layer] });
+```
+
+[`09-rules.test.ts`](09-rules.test.ts#L10-L58)
+
+### 10. Finalizers and change sets
+
+```ts
+// Runs for each entity that stops matching, whatever the cause, reading its values from before.
+Finalizer.create({ components: { read: [handle] } }, row => {
+    open.delete(row[handle]);
+});
+
+// dispose runs every finalizer for the entities it still matches.
+await world.dispose();
+```
+
+[`10-finalizers.test.ts`](10-finalizers.test.ts#L15-L47)
+
+```ts
+// Sees each sync point's structural changes to the components it watches, grouped by how entities changed, with
+// values before and after: for saving and undo.
+Finalizer.changes({ watch: [handle] }, changes => {
+    for (const group of changes.groups) {
+        for (const entity of group.entities) saved.push(`${changes.previous(entity, handle)} → ${changes.next(entity, handle)}`);
+    }
+});
+```
+
+[`10-finalizers.test.ts`](10-finalizers.test.ts#L49-L65)
+
+### 11. Traits, within and references
+
+```ts
+// Traits are the fields of a key's declaration; type is one. Registration repeats them.
+declare module "@adobe/ecs" {
+    interface Components {
+        [ship]: { type: true };
+        // Despawned with the entity it points to.
+        [parent]: { type: Entity; reference: "owner" };
+        // Removed when the entity it points to despawns.
+        [target]: { type: Entity; reference: "weak" };
+        [selected]: { type: true };
+        // Removed with selected.
+        [outline]: { type: number; within: typeof selected };
+    }
+}
+
+Component.register(ship, { type: { const: true } });
+Component.register(parent, { type: Entity.schema, reference: "owner" });
+Component.register(target, { type: Entity.schema, reference: "weak" });
+Component.register(selected, { type: { const: true } });
+Component.register(outline, { type: { type: "number" }, within: selected });
+
+const spawn = System.create(({ commands }) => {
+    const mothership = commands.spawn([ship, selected, outline])({ [outline]: 2 });
+    commands.spawn([parent])({ [parent]: mothership });
+    commands.spawn([target])({ [target]: mothership });
+});
+```
+
+[`11-traits.test.ts`](11-traits.test.ts#L11-L59)
+
+```ts
+// A trait of your own is a member of Traits<N>: the value it allows on key N, or never where it doesn't apply.
+export const instanced = Symbol("instanced");
+declare module "@adobe/ecs" {
+    interface Traits<N> {
+        readonly [instanced]: N extends Component.Key ? ([Component.Value<N>] extends [readonly number[]] ? true : never) : never;
+    }
+}
+Trait.register(instanced);
+
+// Types select components by trait.
+check<Equal<Extract<Component.With<typeof instanced>, typeof transform | typeof name>, typeof transform>>();
+```
+
+[`11-traits.type-test.ts`](11-traits.type-test.ts#L6-L27)
+
+## Advanced
+
+### 12. Lookups
+
+Reading another entity's components by id, from a system. To be written.
+
+### 13. Indexes
+
+```ts
+// An index finds entities by their components' values: here, those with a crowded count, by their cell.
+const grid = Index.create({ key: [cell], components: { has: [crowded] } });
+
+// A lookup through it gives the rows with a key, in entity order.
+const count = System.create({ components: { read: [cell], write: [crowded] }, lookup: { at: { index: grid } } }, (row, { lookup }) => {
+    const [x, y] = row[cell];
+    row[crowded] = lookup.at([x, y]).length;
+});
+```
+
+[`13-indexes.test.ts`](13-indexes.test.ts#L27-L34)
+
+```ts
+// A sorted index keeps its key's order: lookups take a range, and `order` runs a system's rows in it.
+const byScore = Index.create({ key: [score], sorted: true, components: { has: [player] } });
+
+const winners: string[] = [];
+const leaders = System.create({ observer: true, lookup: { scores: { index: byScore, read: [player] } } }, ({ lookup }) => {
+    winners.length = 0;
+    const high = lookup.scores({ ">=": 90 });
+    for (let i = 0; i < high.length; i++) winners.push(high.at(i)[player]);
+});
+
+const board: string[] = [];
+const list = System.create({ observer: true, components: { read: [player] }, order: byScore }, row => {
+    board.push(row[player]);
+});
+```
+
+[`13-indexes.test.ts`](13-indexes.test.ts#L36-L49)
+
+```ts
+// A unique index gives one row, or null.
+const byServerId = Index.create({ key: [serverId], unique: true });
+let found: number | null = null;
+const find = System.create({ input: { type: "object", properties: { id: { type: "integer" } } }, lookup: { byId: { index: byServerId } } }, ({ input, lookup }) => {
+    found = lookup.byId(input.id)?.entity ?? null;
+});
+```
+
+[`13-indexes.test.ts`](13-indexes.test.ts#L51-L56)
+
+```ts
+// An index without a key holds every entity with its components, in entity order. With changed: true, this observer
+// system runs only when an entity entered or left the index, so added, it keeps a count as players come and go.
+const players = Index.create({ key: [], components: { has: [player] } });
+let playerCount = 0;
+const countPlayers = System.create({ observer: true, lookup: { players: { index: players, changed: true } } }, ({ lookup }) => {
+    playerCount = lookup.players().length;
+});
+```
+
+[`13-indexes.test.ts`](13-indexes.test.ts#L58-L64)
+
+A list stays valid until its call site runs again. Lists and rows read only what the index holds and its lookup's
+`read` names, and `list.changed` tells whether an entity entered, left or moved in it since the system last ran. A
+lookup's `changed: true` runs its system only when that happened anywhere in the index.
+
+### 14. Kernels
+
+Systems compiled to run across workers. To be written.
+
+### 15. Reductions
+
+One value computed from many rows. To be written.
+
+### 16. GPU kernels and render systems
+
+Systems that run or draw on the GPU. To be written.
+
+### 17. Hierarchies
+
+Running rows parent first, through a reference. To be written.
+
+### 18. Identity and ids
+
+How systems and keys stay the same across reloads. To be written.
+
+### 19. Threads
+
+Sharing a world with another thread, which joins it to run systems and add observers. To be written.

package/src/implementation/compiler/access.ts

@@ -0,0 +1,143 @@
+import type { Node } from 'estree';
+import { entityRead } from './columns.js';
+import { fail } from './failure.js';
+import type { Key } from './key.js';
+import { local, number, type Expression } from './ir.js';
+import { mathConstants, mathFunctions } from './math.js';
+import { scalar } from './scalar.js';
+import type { Scope } from './scope.js';
+import { resolveExport } from './link.js';
+import { resolvedValue } from './module-value.js';
+import type { Out } from './out.js';
+import { describeValue, scalarValue, type Value } from './value.js';
+
+const commandNames: ReadonlySet<string> = new Set(["spawn", "despawn", "add", "remove"]);
+
+const literal = (key: Key): number | string | undefined => key.kind === "static" ? key.name : undefined;
+
+/** Indexes a plain JS value. A static index into a resource or the input extends its path. */
+const element = (node: Node, scope: Scope, object: Expression, key: Key, optional: boolean): Expression => {
+    if (key.kind === "static" && !optional && (object.kind === "resource" || object.kind === "args")) {
+        return { ...object, path: [...object.path, key.name] };
+    }
+    const index: Expression = key.kind === "static"
+        ? typeof key.name === "number" ? number(key.name) : { kind: "string", value: key.name }
+        : key.kind === "value" ? scalar(key.value, node, scope)
+        : fail(node, `${key.name} is not an index here`);
+    return { kind: "element", object, index, optional };
+};
+
+const mathConstant = (name: string): Expression => {
+    const value: unknown = Reflect.get(Math, name);
+    return number(typeof value === "number" ? value : NaN);
+};
+
+/** `value[key]`, resolved at compile time where the kernel subset allows. */
+export const access = (value: Value, key: Key, node: Node, scope: Scope, optional: boolean): Value => {
+    const signature = scope.unit.signature;
+    const name = literal(key);
+    switch (value.kind) {
+        case "row":
+            if (key.kind === "binding") {
+                if (!signature.read.has(key.name) && !signature.write.has(key.name)) fail(node, `${key.name} is not in components read or write`);
+                return { kind: "component", component: key.name, path: [] };
+            }
+            if (name === "entity") return scalarValue(entityRead(scope.unit));
+            return fail(node, "row is indexed by a component in components read or write, or .entity");
+        case "context":
+            if (name === "resources") return { kind: "resources" };
+            if (name === "lookup") return { kind: "lookups" };
+            if (name === "reduce") return { kind: "reducers" };
+            if (name === "commands") return { kind: "commands" };
+            if (name === "input" && signature.input) return { kind: "dynamic", expression: { kind: "args", path: [] } };
+            if (name === "up" && scope.unit.up !== null) return { kind: "found", lookup: signature.lookups.length, expression: local(scope.unit.up) };
+            return fail(node, "the context holds the declared resources, lookup, reduce, input and up, and commands");
+        case "resources": {
+            const index = key.kind === "binding" ? signature.resources.indexOf(key.name) : -1;
+            if (key.kind !== "binding" || index < 0) return fail(node, `${key.kind === "binding" ? key.name : "resources"} is not in resources read`);
+            scope.unit.used.resources.add(key.name);
+            return { kind: "dynamic", expression: { kind: "resource", index, path: [] } };
+        }
+        case "reducers": {
+            const reduced = key.kind === "binding" ? signature.reduced.findIndex(entry => entry.resource === key.name) : -1;
+            return reduced >= 0 ? { kind: "reducer", reduced } : fail(node, "reduce is indexed by a resource in the declaration's reduce");
+        }
+        case "lookups": {
+            const lookup = signature.lookups.findIndex(entry => entry.name === name);
+            return lookup >= 0 ? { kind: "lookup", lookup } : fail(node, "lookup holds the declaration's lookups, by name");
+        }
+        case "found": {
+            // The lookup after the declaration's is `up`'s.
+            const up = value.lookup === signature.lookups.length ? signature.up : null;
+            const lookup = up ?? signature.lookups[value.lookup];
+            // A lookup by entity with `changed` gives it after what it reads.
+            if (up === null && lookup !== undefined && "watches" in lookup && lookup.watches && name === "changed") {
+                return { kind: "dynamic", expression: { kind: "element", object: value.expression, index: number(lookup.read.length), optional } };
+            }
+            const index = key.kind === "binding" ? (lookup?.read ?? []).indexOf(key.name) : -1;
+            if (lookup === undefined || key.kind !== "binding" || index < 0) return fail(node, up === null ? "a lookup result is indexed by a component in that lookup's read, or by changed with changed declared" : "up is indexed by a component in up.read");
+            if (up !== null) {
+                // Read straight from the parent's columns, at the parent's row.
+                if (optional) return fail(node, "up is read only where it isn't null: test up === null first");
+                scope.unit.used.up.add(key.name);
+                return { kind: "component", component: key.name, path: [], up: true };
+            }
+            else {
+                const used = scope.unit.used.lookups;
+                const name = signature.lookups[value.lookup]?.name ?? "";
+                used.set(name, (used.get(name) ?? new Set()).add(key.name));
+            }
+            return { kind: "dynamic", expression: { kind: "element", object: value.expression, index: number(index), optional } };
+        }
+        case "indexed":
+            // A unique index's result is its first row.
+            if (name === "length") return scalarValue({ kind: "listLength", list: value.list, lookup: value.lookup });
+            if (name === "changed") return scalarValue({ kind: "listChanged", list: value.list, lookup: value.lookup });
+            if (name === "at") return { kind: "listAt", lookup: value.lookup, list: value.list };
+            return access({ kind: "indexRow", lookup: value.lookup, row: value.first }, key, node, scope, optional);
+        case "indexRow": {
+            if (name === "entity") return scalarValue({ kind: "rowEntity", row: value.row, lookup: value.lookup });
+            const lookup = signature.lookups[value.lookup];
+            const read = key.kind === "binding" ? (lookup?.read ?? []).indexOf(key.name) : -1;
+            if (lookup === undefined || key.kind !== "binding" || read < 0) return fail(node, "a lookup's row is indexed by a component in that lookup's read, or .entity");
+            const used = scope.unit.used.lookups;
+            used.set(lookup.name, (used.get(lookup.name) ?? new Set()).add(key.name));
+            return { kind: "rowRead", lookup: value.lookup, row: value.row, read, path: [] };
+        }
+        case "rowRead":
+            return name === undefined
+                ? fail(node, "component values are indexed by literal elements or field names")
+                : { ...value, path: [...value.path, name] };
+        case "dynamic":
+            return { kind: "dynamic", expression: element(node, scope, value.expression, key, optional) };
+        case "tuple":
+            return typeof name === "number" && value.items[name] !== undefined
+                ? value.items[name]
+                : fail(node, "tuple elements are indexed by an in-range literal");
+        case "struct": {
+            const field = value.fields.find(([fieldName]) => fieldName === name);
+            return field ? field[1] : fail(node, `no field ${String(name)}`);
+        }
+        case "component":
+        case "snapshot":
+            return name === undefined
+                ? fail(node, "component values are indexed by literal elements or field names")
+                : { ...value, path: [...value.path, name] };
+        case "math":
+            if (typeof name === "string" && mathConstants.has(name)) return scalarValue(mathConstant(name));
+            if (typeof name === "string" && mathFunctions.has(name)) return { kind: "method", owner: "math", name };
+            return fail(node, `Math.${String(name)} is not in the kernel subset`);
+        case "namespace": {
+            const link = scope.unit.link;
+            if (typeof name !== "string" || link === null) return fail(node, "namespaces are indexed by an export name");
+            const out: Out = [];
+            const member = resolvedValue(node, resolveExport(link, value.file, name), scope, out);
+            return out.length === 0 ? member : fail(node, `${name} must be a function or a literal constant`);
+        }
+        case "commands":
+            if (typeof name === "string" && commandNames.has(name)) return { kind: "method", owner: "commands", name };
+            return fail(node, "commands has spawn, despawn, add and remove");
+        default:
+            return fail(node, `${describeValue(value)} can't be indexed`);
+    }
+};