feat(data): value-partitioned archetypes (shared components)#143
Open
krisnye wants to merge 4 commits into
Open
feat(data): value-partitioned archetypes (shared components)#143krisnye wants to merge 4 commits into
krisnye wants to merge 4 commits into
Conversation
Components declared `partition: true` store each distinct runtime value in its own archetype, whose partition column is a zero-per-row const buffer — entities sharing a value are contiguous (a storage-level spatial broad phase). Adds a discriminated `ensureArchetype` (Archetype | Router), routing insert, partition-value migration on update, a partition `where` on queryArchetypes, and full discrimination through the store/database/ transaction-context types. Index maintenance is wired via in-place insert decoration (no Proxy). Also removes the unused `observeDependentValue`. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… code Fixes the root type issues the casts were hiding rather than casting: - align ArchetypeQueryOptions.exclude domain (drops `options.exclude as any` in selectEntities) - thread IX through createStore's return type - fix Store.extend to resolve component/resource schemas (C & FromSchemas<XC>) Partition tests are now fully typed and cast-free (no `as number`/`as any`); also drops an identity cast in the core router. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
When the leading run of order keys are partition components, each archetype holds a constant value for them, so the archetypes already bucket the rows on that leading key: sort the buckets by value, sort only the remaining keys within each bucket, and concatenate in bucket order. Turns the O(N log N) sort into O(N log(N/K)), and O(N) when a partition key is the sole order key. Falls back to the full sort when no leading order key is a partition component, with identical output. Tests compare against a naive full sort across leading, compound, descending, where-filtered, fallback, large-K, and tie cases. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Router was too general a name to sit peer to Archetype and forced an extra import at every use site. Move it under the Archetype namespace via declaration merging so it reads Archetype.Router and rides the existing Archetype import. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds value-partitioned archetypes (the "shared components" pattern) to the ECS. A component declared
partition: truestores every distinct runtime value in its own archetype, whose partition column is a zero-per-rowConstTypedBuffer— so entities sharing a value are contiguous in memory (a storage-level coarse spatial broad phase).Public surface
partition: trueschema marker (primitive components).ensureArchetype(keys, values?)— discriminated return: aRouter(write-only) when the key set includes a partition component without a value; a concreteArchetypewhen a value is supplied or no partition key is present.Router— routes eachinsertby the row's partition value to the concrete child (created on first use).queryArchetypes(include, { where })— partition-value filter, decided at archetype granularity (O(archetypes), no row scan).store.archetypes.<Name>and the transaction contexttdiscriminate partitioned vs concrete per declared archetype.updatemigrates an entity between value-children when its partition value changes.Internals
resolveArchetype(keys, partitionValues?)primitive backs ensureArchetype, routing, migration, and restore.insertdecoration at archetype creation (onArchetypeCreatedhook) — no Proxy, no forwarding wrapper. This also removes the pre-existing Proxy that wrapped concrete archetypes.Type-perf
Flat, sub-quadratic scaling preserved — no
TS7056cliff (verified viascripts/typeperf). ~4% flat instantiation overhead when unused, from carryingPKthrough the composition types.Also
Removes the unused, orphaned
observeDependentValuehelper (no internal, cross-package, or firefly-platform consumers) — which also removes a runtimeProxy.Tests
Red/green compile-time type tests (positive + negative
@ts-expect-error) at the isolated-helper, store, and transaction-context levels, plus runtime tests at the core, store, and database/transaction layers — including dynamicextend, N-distinct-values → N-archetypes with const columns, unique-index enforcement across value-children, and migration.🤖 Generated with Claude Code