@adobe/ecs 0.1.0 → 0.2.0

package/dist/implementation/world/up.js

@@ -1,6 +1,6 @@
 import { generationOf } from './entities.js';
 import { journalEnd } from './journal.js';
-import { chunkShift } from './kernel.js';
+import { forEachNewerRow } from './ranges.js';
 import { idOf } from './state.js';
 import { allocateArray, freeArray } from './arrays.js';
 import { createOrder } from './order.js';
@@ -32,20 +32,40 @@ const extend = (array, length, value) => {
     grown.fill(value, array.length);
     return grown;
 };
+// Scratch of an order build, shared by every `up` of a thread, since a build runs start to end without yielding: a
+// second system reuses the first one's arrays rather than allocating its own.
+/** By index among the matched rows: its entity index, depth, archetype, parent row, and parent's archetype id when readable or -1. */
+let rowEntities = new Int32Array(0);
+let depths = new Int32Array(0);
+let rowParents = new Int32Array(0);
+let keys = new Int32Array(0);
+let owners = new Int32Array(0);
+/** The matched rows' indexes, by depth, and where each depth ends. */
+let sortedRows = new Int32Array(0);
+let counts = new Int32Array(0);
+/** By index in `matches`: the index of its first row among the matched rows. */
+let bases = new Int32Array(0);
+/** The groups of a build, laid out one after another, before the order lays them out with spare slots. */
+let builtRows = new Int32Array(0);
+let builtParents = new Int32Array(0);
+let builtEntities = new Int32Array(0);
+let groupEnds = new Int32Array(0);
+let groupDepths = new Int32Array(0);
+let groupOwners = new Int32Array(0);
+let groupParents = new Int32Array(0);
+/** The tree's arrays before its first update. */
+const noTree = { levelOf: new Int32Array(0), parentOf: new Int32Array(0), firstChild: new Int32Array(0), nextChild: new Int32Array(0), ownerOf: new Int32Array(0) };
 /**
- * Orders an `up` system's rows by depth through its `through` reference. A row's depth is one more than its parent's
- * when its parent is among the matched rows, and 0 otherwise, so rows of one depth never read each other's writes.
- *
- * The tree is kept by entity index, current with the journal of what sync points changed: each matched entity's
- * parent, its level, and the matched entities holding it as their parent, as linked lists. A full run reads an order
- * of every row, patched for the entities whose row, level or parent changed. A filtered run marks the rows that may
- * pass, by depth, and lists only those.
+ * The tree of `up`s sharing it, kept by entity index, current with the journal of what sync points changed: each
+ * matched entity's parent, its level, and the matched entities holding it as their parent, as linked lists; and the
+ * order of every row by depth, patched for the entities whose row, level or parent changed.
  */
-export const createUp = (state, up, isFiltered) => {
-    const through = idOf(state, up.through);
-    const readKeys = up.read ?? [];
-    const read = readKeys.map(key => idOf(state, key));
+const createShared = (state, through, read, matching) => {
     state.journal.readers++;
+    /** The `up`s reading it; the first's `read` and matches are the ones the others agree with. */
+    const readers = [];
+    /** Archetypes, by id, every reader was checked to agree on up to. */
+    let agreed = 0;
     /** By entity index: the parent's entity index or -1, the level, and the first child, next and previous sibling as index + 1, or 0. */
     let parentOf = new Int32Array(0);
     let levelOf = new Int32Array(0);
@@ -59,15 +79,35 @@ export const createUp = (state, up, isFiltered) => {
     let position = -1;
     /** By archetype id: its index in `matches`, or -1. */
     let ownerOf = new Int32Array(0);
-    let ownersOf = null;
     let ownersFor = -1;
     let ownersAmong = -1;
     /** By archetype id: 1 when it has every component `read` lists, 2 when it doesn't, 0 until checked. */
     let readable = new Int8Array(0);
-    /** Entities whose parent changed since the last filtered run, which then pass. */
-    let touched = [];
-    /** Whether the journal lost entries since the last filtered run, which then runs every row. */
-    let rebuilt = false;
+    /** Whether some reader is filtered, and so is told which entities' parents changed. */
+    let anyFiltered = false;
+    /**
+     * Tells every filtered reader an entity's parent changed, so it passes their next run. A reader holds at most a
+     * journal's worth: past that, it drops them and runs every row next, which costs about what reading them would.
+     */
+    const touch = (index) => {
+        for (let k = 0; k < readers.length; k++) {
+            const reader = readers[k];
+            if (!reader.filtered || reader.rebuilt)
+                continue;
+            reader.touched.push(index);
+            if (reader.touched.length > Math.max(4096, state.entities.length)) {
+                reader.touched = [];
+                reader.rebuilt = true;
+            }
+        }
+    };
+    /** Tells every filtered reader the tree was built again, so their next run runs every row. */
+    const rebuiltAll = () => {
+        for (const reader of readers) {
+            reader.touched = [];
+            reader.rebuilt = reader.filtered;
+        }
+    };
     /** By entity index: its archetype id when the tree last saw it, or -1. */
     let archetypeAt = new Int32Array(0);
     /** Entities whose slot in the order may have changed since it was last patched, once each. */
@@ -77,6 +117,8 @@ export const createUp = (state, up, isFiltered) => {
     /** Whether the order must be built again from every row. */
     let unordered = true;
     const order = createOrder(state.memory);
+    /** The arrays readers read, as of the last update. */
+    const tree = { parentOf, levelOf, firstChild, nextChild, ownerOf };
     /** Whether an archetype holds every component `read` lists, so a parent in it has `up` values. */
     const isReadable = (id) => {
         if (readable.length <= id) {
@@ -85,18 +127,20 @@ export const createUp = (state, up, isFiltered) => {
             readable = grown;
         }
         if (readable[id] === 0) {
-            const archetype = state.archetypes[id];
-            readable[id] = archetype !== undefined && !archetype.resource && read.every(component => archetype.storageById[component] !== undefined) ? 1 : 2;
+            readable[id] = readableBy(state, read, id) ? 1 : 2;
         }
         return readable[id] === 1;
     };
+    /** The list owners were found for: a runner's list is new once archetypes left it (`reclaim.ts`). */
+    let ownersList = null;
+    // Readers agree on every archetype, so lists of the same length are the same.
     const refreshOwners = (matches) => {
-        if (ownersOf === matches && ownersFor === matches.length && ownersAmong === state.archetypes.length)
+        if (ownersList === matches && ownersFor === matches.length && ownersAmong === state.archetypes.length)
             return;
+        ownersList = matches;
         ownerOf = fit(ownerOf, state.archetypes.length);
         ownerOf.fill(-1);
         matches.forEach((archetype, owner) => { ownerOf[archetype.id] = owner; });
-        ownersOf = matches;
         ownersFor = matches.length;
         ownersAmong = state.archetypes.length;
     };
@@ -250,21 +294,80 @@ export const createUp = (state, up, isFiltered) => {
             count += archetype.count;
         const all = new Int32Array(count);
         let at = 0;
+        const levels = levelOf;
         for (const archetype of matches) {
-            for (let row = 0; row < archetype.count; row++) {
-                const index = archetype.entities[row] >>> 0;
-                levelOf[index] = 1;
+            const rows = archetype.entities;
+            for (let row = 0, end = archetype.count; row < end; row++) {
+                const index = rows[row] >>> 0;
+                levels[index] = 1;
                 all[at++] = index;
             }
         }
-        for (let k = 0; k < count; k++)
-            link(all[k], parentAt(all[k]));
-        settle(all, count);
+        // Each archetype's parent column is found once, as `parentAt` finds it per entity.
+        const { generation, archetype: archetypeOf, length: entityCount } = state.entities;
+        const parents = parentOf;
+        at = 0;
+        for (const archetype of matches) {
+            const storage = archetype.storageById[through];
+            const layout = storage?.layout;
+            const leaf = layout?.kind === "linear" ? layout.leaves[0] : undefined;
+            if (storage === undefined || leaf === undefined) {
+                for (let row = 0; row < archetype.count; row++)
+                    parents[all[at++]] = -1;
+                continue;
+            }
+            const view = storage.views[leaf.view];
+            const stride = leaf.unitStride, offset = leaf.unitOffset;
+            for (let row = 0, end = archetype.count; row < end; row++) {
+                const index = all[at++];
+                const parent = view[row * stride + offset];
+                const target = parent >>> 0;
+                link(index, parent > 0 && target < entityCount && archetypeOf[target] >= 0 && generation[target] === generationOf(parent) ? target : -1);
+            }
+        }
+        settleAll(all, count);
+    };
+    /**
+     * Sets the level of every matched entity in `all`, the whole tree: each walks up to a root or to an entity already
+     * set, then sets the levels on its way back down, so each entity is walked once. A walk meeting itself is a cycle,
+     * and it and everything below it on the walk is cyclic.
+     */
+    const settleAll = (all, count) => {
+        const walking = ++pass;
+        const done = ++pass;
+        stack = extend(stack, count, 0);
+        const levels = levelOf, parents = parentOf, seen = stamps, path = stack;
+        for (let k = 0; k < count; k++) {
+            let current = all[k];
+            if (seen[current] === done)
+                continue;
+            let height = 0;
+            for (; current >= 0 && levels[current] !== unmatched; current = parents[current]) {
+                const stamp = seen[current];
+                if (stamp === done || stamp === walking)
+                    break;
+                seen[current] = walking;
+                path[height++] = current;
+            }
+            let level = current < 0 || levels[current] === unmatched ? 0 : seen[current] === done ? levels[current] : cyclic;
+            for (let h = height - 1; h >= 0; h--) {
+                const node = path[h];
+                if (level !== cyclic)
+                    level++;
+                levels[node] = level;
+                seen[node] = done;
+            }
+        }
     };
     /** Brings the tree up to date with the journal. */
     const update = (matches) => {
         refreshOwners(matches);
         grow();
+        tree.parentOf = parentOf;
+        tree.levelOf = levelOf;
+        tree.firstChild = firstChild;
+        tree.nextChild = nextChild;
+        tree.ownerOf = ownerOf;
         const { journal } = state;
         const end = journalEnd(journal);
         if (position === end)
@@ -272,8 +375,7 @@ export const createUp = (state, up, isFiltered) => {
         if (position < journal.first) {
             build(matches);
             position = end;
-            rebuilt = isFiltered;
-            touched = [];
+            rebuiltAll();
             unordered = true;
             return;
         }
@@ -300,8 +402,8 @@ export const createUp = (state, up, isFiltered) => {
                 // Its children's parent no longer runs: they're roots now.
                 for (let child = firstChild[index]; child !== 0; child = nextChild[child - 1]) {
                     pending.push(child - 1);
-                    if (isFiltered)
-                        touched.push(child - 1);
+                    if (anyFiltered)
+                        touch(child - 1);
                 }
                 continue;
             }
@@ -318,37 +420,18 @@ export const createUp = (state, up, isFiltered) => {
             else if (!otherArchetype)
                 continue;
             pending.push(index);
-            if (!isFiltered)
+            if (!anyFiltered)
                 continue;
-            touched.push(index);
+            touch(index);
             // What its children read of it may differ in another archetype. A child whose reference changed is
             // journaled itself, as is one whose parent is gone, since `through` has a reference policy.
             if (otherArchetype)
                 for (let child = firstChild[index]; child !== 0; child = nextChild[child - 1])
-                    touched.push(child - 1);
+                    touch(child - 1);
         }
         position = end;
         settle(pending, pending.length);
     };
-    /** By index among the matched rows: its entity index, depth, archetype, parent row, and parent's archetype id when readable or -1. */
-    let rowEntities = new Int32Array(0);
-    let depths = new Int32Array(0);
-    let rowParents = new Int32Array(0);
-    let keys = new Int32Array(0);
-    let owners = new Int32Array(0);
-    /** The matched rows' indexes, by depth, and where each depth ends. */
-    let sortedRows = new Int32Array(0);
-    let counts = new Int32Array(0);
-    /** By index in `matches`: the index of its first row among the matched rows. */
-    let bases = new Int32Array(0);
-    /** The groups of a build, laid out one after another, before the order lays them out with spare slots. */
-    let builtRows = new Int32Array(0);
-    let builtParents = new Int32Array(0);
-    let builtEntities = new Int32Array(0);
-    let groupEnds = new Int32Array(0);
-    let groupDepths = new Int32Array(0);
-    let groupOwners = new Int32Array(0);
-    let groupParents = new Int32Array(0);
     /** The matched rows in depth order from the roots. Rows on or under a parent cycle are in none. */
     const levels = (matches) => {
         update(matches);
@@ -534,6 +617,97 @@ export const createUp = (state, up, isFiltered) => {
         }
         return groups;
     };
+    /** Whether `read` and `matches` agree with the first reader's on every archetype so far. */
+    const agreesOn = (other, id) => {
+        const archetype = state.archetypes[id];
+        return other.matching(archetype) === matching(archetype) && readableBy(state, other.read, id) === isReadable(id);
+    };
+    const agrees = (other) => {
+        for (let id = 0; id < agreed; id++)
+            if (!agreesOn(other, id))
+                return false;
+        return true;
+    };
+    /** Checks every archetype since the last check; a reader disagreeing on one leaves, to build a tree of its own. */
+    const checkAgreement = () => {
+        for (; agreed < state.archetypes.length; agreed++) {
+            for (let k = readers.length - 1; k >= 0; k--)
+                if (!agreesOn(readers[k], agreed))
+                    leave(readers[k]);
+        }
+    };
+    const join = (reader) => {
+        readers.push(reader);
+        reader.shared = shared;
+        reader.touched = [];
+        reader.rebuilt = reader.filtered;
+        anyFiltered ||= reader.filtered;
+    };
+    /** Takes `reader` out, releasing what it holds once no reader is left. */
+    const leave = (reader) => {
+        const at = readers.indexOf(reader);
+        if (at < 0)
+            return;
+        readers.splice(at, 1);
+        reader.shared = null;
+        anyFiltered = readers.some(each => each.filtered);
+        if (readers.length > 0)
+            return;
+        state.journal.readers--;
+        order.release();
+        const all = sharedOf.get(state);
+        if (all !== undefined)
+            all.splice(all.indexOf(shared), 1);
+    };
+    const shared = { through, tree, readers, agrees, checkAgreement, join, leave, update, levels, isReadable };
+    return shared;
+};
+/** Whether an archetype holds every component `read` lists, so a parent in it has `up` values. */
+const readableBy = (state, read, id) => {
+    const archetype = state.archetypes[id];
+    return archetype !== undefined && !archetype.resource && read.every(component => archetype.storageById[component] !== undefined);
+};
+/** By thread: its trees, each shared by the `up`s whose `through`, matches and readable parents agree. */
+const sharedOf = new WeakMap();
+/** The tree `reader` reads: the one it's in while it agrees, else one it agrees with, else a new one. */
+const sharedFor = (state, reader, through) => {
+    const current = reader.shared;
+    if (current !== null) {
+        current.checkAgreement();
+        if (reader.shared === current)
+            return current;
+    }
+    let all = sharedOf.get(state);
+    if (all === undefined)
+        sharedOf.set(state, all = []);
+    for (const candidate of all) {
+        if (candidate.through !== through)
+            continue;
+        candidate.checkAgreement();
+        if (candidate.readers.length > 0 && candidate.agrees(reader)) {
+            candidate.join(reader);
+            return candidate;
+        }
+    }
+    const created = createShared(state, through, reader.read, reader.matching);
+    all.push(created);
+    created.join(reader);
+    created.checkAgreement();
+    return created;
+};
+/**
+ * Orders an `up` system's rows by depth through its `through` reference. A row's depth is one more than its parent's
+ * when its parent is among the matched rows, and 0 otherwise, so rows of one depth never read each other's writes.
+ * `matching` is whether its query matches an archetype.
+ *
+ * Its tree and order are shared with every `up` of the thread whose `through` is the same and that agrees on which
+ * archetypes match and which parents are readable, so each is built and kept current once. A filtered run marks the
+ * rows that may pass, by depth, and lists only those.
+ */
+export const createUp = (state, up, isFiltered, matching) => {
+    const through = idOf(state, up.through);
+    const readKeys = up.read ?? [];
+    const self = { filtered: isFiltered, read: readKeys.map(key => idOf(state, key)), matching, shared: null, touched: [], rebuilt: false };
     /** By entity index: whether the current filtered run marked it. */
     let dirty = new Uint8Array(0);
     /** By depth: the entities the current filtered run marked. */
@@ -544,6 +718,8 @@ export const createUp = (state, up, isFiltered) => {
     let list = new Int32Array(0);
     let parentList = new Int32Array(0);
     let sortKeys = new Float64Array(0);
+    /** The tree's arrays, bound once a filtered run brought it up to date. */
+    let { levelOf, parentOf, firstChild, nextChild, ownerOf } = noTree;
     const mark = (index) => {
         const level = levelOf[index];
         if (level < 1 || dirty[index] !== 0)
@@ -563,17 +739,15 @@ export const createUp = (state, up, isFiltered) => {
         const storage = archetype.storageById[id];
         if (storage === undefined)
             return;
-        const whole = storage.columnChanged > since;
-        const ticks = added ? storage.added : storage.changed;
-        const chunks = added ? storage.chunkAdded : storage.chunkChanged;
-        for (let chunk = 0, count = Math.ceil(archetype.count / 2 ** chunkShift); chunk < count; chunk++) {
-            if (!whole && !(chunks[chunk] > since))
-                continue;
-            for (let row = chunk << chunkShift, end = Math.min(archetype.count, (chunk + 1) << chunkShift); row < end; row++) {
-                if (whole || ticks[row] > since)
-                    each(row);
-            }
+        if (storage.columnChanged > since) {
+            for (let row = 0; row < archetype.count; row++)
+                each(row);
+            return;
         }
+        if (added)
+            forEachNewerRow(storage.added, storage.chunkAdded, storage.blockAdded, archetype.count, since, each);
+        else
+            forEachNewerRow(storage.changed, storage.chunkChanged, storage.blockChanged, archetype.count, since, each);
     };
     /**
      * Marks the rows of a filtered run that may pass after `since`: those passing `added` or `changed`, whose parent
@@ -581,7 +755,17 @@ export const createUp = (state, up, isFiltered) => {
      * null when none do. Each listed row marks its children, so a change reaches every row under it.
      */
     const filtered = (matches, added, changed, since) => {
-        update(matches);
+        const shared = sharedFor(state, self, through);
+        shared.update(matches);
+        // Every row passes after a rebuild, so the pass is the whole order, with nothing to mark.
+        if (self.rebuilt) {
+            self.touched = [];
+            self.rebuilt = false;
+            const ordered = shared.levels(matches);
+            return ordered.levels === 0 ? null : wholePass(ordered);
+        }
+        ({ levelOf, parentOf, firstChild, nextChild, ownerOf } = shared.tree);
+        const { isReadable } = shared;
         const length = state.entities.length;
         if (dirty.length < length)
             dirty = new Uint8Array(Math.max(length, 2 * dirty.length));
@@ -593,14 +777,12 @@ export const createUp = (state, up, isFiltered) => {
         for (const archetype of matches) {
             const { entities } = archetype;
             const markRow = (row) => mark(entities[row] >>> 0);
-            if (rebuilt)
-                for (let row = 0; row < archetype.count; row++)
-                    markRow(row);
             for (const id of added)
                 changedRows(archetype, id, true, since, markRow);
             for (const id of [...changed, through])
                 changedRows(archetype, id, false, since, markRow);
         }
+        const { read } = self;
         if (read.length > 0) {
             for (const archetype of state.archetypes) {
                 if (archetype.count === 0 || !isReadable(archetype.id))
@@ -610,10 +792,9 @@ export const createUp = (state, up, isFiltered) => {
                     changedRows(archetype, id, false, since, row => markChildren(entities[row] >>> 0));
             }
         }
-        for (const index of touched)
+        for (const index of self.touched)
             mark(index);
-        touched = [];
-        rebuilt = false;
+        self.touched = [];
         if (marked.length === 0)
             return null;
         let matched = 0;
@@ -626,7 +807,7 @@ export const createUp = (state, up, isFiltered) => {
         const { archetype: archetypeOf, row: rowOf } = state.entities;
         /** Lists a depth's marked rows by scanning its groups in order. */
         const scan = (runs) => {
-            const ordered = levels(matches);
+            const ordered = shared.levels(matches);
             if (depth >= ordered.levels)
                 return;
             for (let group = ordered.depthGroups[depth]; group < ordered.depthGroups[depth + 1]; group++) {
@@ -708,16 +889,51 @@ export const createUp = (state, up, isFiltered) => {
         };
         return { next, clear };
     };
-    /** Frees what it holds in the arena and stops its reading of the journal, once nothing runs it again. */
+    /** The matched rows in depth order from the roots. Rows on or under a parent cycle are in none. */
+    const levels = (matches) => {
+        const ordered = sharedFor(state, self, through).levels(matches);
+        // Every row runs, so a filtered `up` needs none of what changed before.
+        if (self.filtered) {
+            self.touched = [];
+            self.rebuilt = false;
+        }
+        return ordered;
+    };
+    /** Frees what it holds in the arena and leaves its tree, once nothing runs it again. */
     const release = () => {
-        state.journal.readers--;
-        order.release();
+        self.shared?.leave(self);
         if (list.length > 0)
             freeArray(state.memory, list);
         if (parentList.length > 0)
             freeArray(state.memory, parentList);
         list = parentList = new Int32Array(0);
     };
-    return { levels, filtered, release };
+    return { levels, filtered, wholePass, release };
+};
+/** Every row of `ordered`, a depth at a time. */
+const wholePass = (ordered) => {
+    let depth = 0;
+    const next = () => {
+        if (depth >= ordered.levels)
+            return null;
+        const runs = [];
+        for (let group = ordered.depthGroups[depth]; group < ordered.depthGroups[depth + 1]; group++) {
+            if (ordered.groupEnds[group] === ordered.groupStarts[group])
+                continue;
+            runs.push({ owner: ordered.groupOwners[group], parent: ordered.groupParents[group], rows: ordered.rows, parents: ordered.parents, start: ordered.groupStarts[group], end: ordered.groupEnds[group] });
+        }
+        depth++;
+        return runs;
+    };
+    return { next, clear: noClear };
+};
+const noClear = () => { };
+/** For tests: how many entities a thread's filtered `up`s were told changed, held until their next run. */
+export const touchedHeld = (state) => {
+    let held = 0;
+    for (const shared of sharedOf.get(state) ?? [])
+        for (const reader of shared.readers)
+            held += reader.touched.length;
+    return held;
 };
 //# sourceMappingURL=up.js.map