archetype-ecs 1.3.1 → 1.3.2

package/src/EntityManager.js

@@ -1,578 +0,0 @@
-import { TYPED, componentSchemas, toSym } from './ComponentRegistry.js';
-
-const INITIAL_CAPACITY = 64;
-
-function createSoAStore(schema, capacity) {
-  const store = { [TYPED]: true, _schema: schema, _capacity: capacity };
-  for (const [field, Ctor] of Object.entries(schema)) {
-    store[field] = new Ctor(capacity);
-  }
-  return store;
-}
-
-function growSoAStore(store, newCapacity) {
-  store._capacity = newCapacity;
-  for (const [field, Ctor] of Object.entries(store._schema)) {
-    const old = store[field];
-    store[field] = new Ctor(newCapacity);
-    if (Ctor === Array) {
-      for (let i = 0; i < old.length; i++) store[field][i] = old[i];
-    } else {
-      store[field].set(old);
-    }
-  }
-}
-
-function soaWrite(store, idx, data) {
-  for (const field in store._schema) {
-    store[field][idx] = data[field];
-  }
-}
-
-function soaRead(store, idx) {
-  const obj = {};
-  for (const field in store._schema) {
-    obj[field] = store[field][idx];
-  }
-  return obj;
-}
-
-function soaSwap(store, idxA, idxB) {
-  for (const field in store._schema) {
-    const arr = store[field];
-    const tmp = arr[idxA];
-    arr[idxA] = arr[idxB];
-    arr[idxB] = tmp;
-  }
-}
-
-function createSnapshotStore(schema, capacity) {
-  const snap = {};
-  for (const [field, Ctor] of Object.entries(schema)) {
-    snap[field] = new Ctor(capacity);
-  }
-  return snap;
-}
-
-function growSnapshotStore(snap, schema, newCapacity) {
-  for (const [field, Ctor] of Object.entries(schema)) {
-    const old = snap[field];
-    snap[field] = new Ctor(newCapacity);
-    if (Ctor === Array) {
-      for (let i = 0; i < old.length; i++) snap[field][i] = old[i];
-    } else {
-      snap[field].set(old);
-    }
-  }
-}
-
-export function createEntityManager() {
-  let nextId = 1;
-  const allEntityIds = new Set();
-
-  // Change tracking (opt-in via enableTracking)
-  let trackFilter = 0;   // bitmask — only track archetypes matching this
-  let createdSet = null;  // Set<EntityId>
-  let destroyedSet = null; // Set<EntityId>
-
-  // Double-buffered snapshots: tracked archetypes get back-buffer arrays
-  // Game systems write to front (normal SoA arrays), flushSnapshots copies front→back
-  const trackedArchetypes = [];  // archetypes that match trackFilter
-
-  // Component bit registry (symbol → bit index 0..31)
-  const componentBitIndex = new Map();
-  let nextBitIndex = 0;
-
-  function getBit(type) {
-    const sym = toSym(type);
-    let bit = componentBitIndex.get(sym);
-    if (bit === undefined) {
-      bit = nextBitIndex++;
-      componentBitIndex.set(sym, bit);
-    }
-    return bit;
-  }
-
-  function computeMask(types) {
-    let mask = 0;
-    for (const t of types) {
-      mask |= (1 << getBit(t));
-    }
-    return mask;
-  }
-
-  // Archetype storage
-  const archetypes = new Map();         // bitmask → Archetype
-  const entityArchetype = new Map();    // entityId → Archetype
-
-  // Query cache
-  let queryCacheVersion = 0;
-  const queryCache = new Map();         // queryKey → { version, archetypes[] }
-
-  function getOrCreateArchetype(types) {
-    const key = computeMask(types);
-    let arch = archetypes.get(key);
-    if (!arch) {
-      const tracked = trackFilter !== 0 && (key & trackFilter) !== 0;
-      arch = {
-        key,
-        types: new Set(types),
-        entityIds: [],
-        components: new Map(),
-        snapshots: tracked ? new Map() : null,
-        snapshotEntityIds: tracked ? [] : null,
-        snapshotCount: 0,
-        entityToIndex: new Map(),
-        count: 0,
-        capacity: INITIAL_CAPACITY
-      };
-      for (const t of types) {
-        const schema = componentSchemas.get(t);
-        const store = schema ? createSoAStore(schema, INITIAL_CAPACITY) : null;
-        arch.components.set(t, store);
-        if (tracked && store) {
-          arch.snapshots.set(t, createSnapshotStore(schema, INITIAL_CAPACITY));
-        }
-      }
-      archetypes.set(key, arch);
-      if (tracked) trackedArchetypes.push(arch);
-      queryCacheVersion++;
-    }
-    return arch;
-  }
-
-  function ensureCapacity(arch) {
-    if (arch.count < arch.capacity) return;
-    const newCap = arch.capacity * 2;
-    arch.capacity = newCap;
-    for (const [type, store] of arch.components) {
-      if (store) {
-        growSoAStore(store, newCap);
-        if (arch.snapshots) {
-          const snap = arch.snapshots.get(type);
-          if (snap) growSnapshotStore(snap, store._schema, newCap);
-        }
-      }
-    }
-  }
-
-  function addToArchetype(arch, entityId, componentMap) {
-    ensureCapacity(arch);
-    const idx = arch.count;
-    arch.entityIds[idx] = entityId;
-    for (const t of arch.types) {
-      const store = arch.components.get(t);
-      if (store) soaWrite(store, idx, componentMap[t]);
-    }
-    arch.entityToIndex.set(entityId, idx);
-    arch.count++;
-    entityArchetype.set(entityId, arch);
-  }
-
-  function removeFromArchetype(arch, entityId) {
-    const idx = arch.entityToIndex.get(entityId);
-    const lastIdx = arch.count - 1;
-
-    if (idx !== lastIdx) {
-      const lastEntity = arch.entityIds[lastIdx];
-      arch.entityIds[idx] = lastEntity;
-      for (const [type, store] of arch.components) {
-        if (store) soaSwap(store, idx, lastIdx);
-      }
-      arch.entityToIndex.set(lastEntity, idx);
-    }
-
-    arch.entityIds.length = lastIdx;
-    arch.entityToIndex.delete(entityId);
-    arch.count--;
-    entityArchetype.delete(entityId);
-  }
-
-  function readComponentData(arch, type, idx) {
-    const store = arch.components.get(type);
-    if (!store) return undefined;
-    return soaRead(store, idx);
-  }
-
-  function getMatchingArchetypes(types, excludeTypes) {
-    const includeMask = computeMask(types);
-    const excludeMask = excludeTypes && excludeTypes.length > 0 ? computeMask(excludeTypes) : 0;
-    const queryKey = `${includeMask}:${excludeMask}`;
-
-    const cached = queryCache.get(queryKey);
-    if (cached && cached.version === queryCacheVersion) {
-      return cached.archetypes;
-    }
-
-    const matching = [];
-    for (const arch of archetypes.values()) {
-      if ((arch.key & includeMask) === includeMask &&
-          (arch.key & excludeMask) === 0) {
-        matching.push(arch);
-      }
-    }
-
-    queryCache.set(queryKey, { version: queryCacheVersion, archetypes: matching });
-    return matching;
-  }
-
-  return {
-    createEntity() {
-      const id = nextId++;
-      allEntityIds.add(id);
-      return id;
-    },
-
-    destroyEntity(id) {
-      const arch = entityArchetype.get(id);
-      if (arch) {
-        if (destroyedSet && (arch.key & trackFilter)) destroyedSet.add(id);
-        removeFromArchetype(arch, id);
-      }
-      allEntityIds.delete(id);
-    },
-
-    addComponent(entityId, comp, data) {
-      const type = toSym(comp);
-      const arch = entityArchetype.get(entityId);
-
-      if (!arch) {
-        const newArch = getOrCreateArchetype([type]);
-        addToArchetype(newArch, entityId, { [type]: data });
-        return;
-      }
-
-      if (arch.types.has(type)) {
-        const store = arch.components.get(type);
-        if (store) {
-          const idx = arch.entityToIndex.get(entityId);
-          soaWrite(store, idx, data);
-        }
-        return;
-      }
-
-      const newTypes = [...arch.types, type];
-      const newArch = getOrCreateArchetype(newTypes);
-
-      const idx = arch.entityToIndex.get(entityId);
-      const map = { [type]: data };
-      for (const t of arch.types) {
-        map[t] = readComponentData(arch, t, idx);
-      }
-
-      removeFromArchetype(arch, entityId);
-      addToArchetype(newArch, entityId, map);
-    },
-
-    removeComponent(entityId, comp) {
-      const type = toSym(comp);
-      const arch = entityArchetype.get(entityId);
-      if (!arch || !arch.types.has(type)) return;
-
-      // If entity is leaving a tracked archetype, treat as destroyed
-      if (destroyedSet && (arch.key & trackFilter)) destroyedSet.add(entityId);
-
-      if (arch.types.size === 1) {
-        removeFromArchetype(arch, entityId);
-        return;
-      }
-
-      const newTypes = [];
-      for (const t of arch.types) {
-        if (t !== type) newTypes.push(t);
-      }
-      const newArch = getOrCreateArchetype(newTypes);
-
-      const idx = arch.entityToIndex.get(entityId);
-      const map = {};
-      for (const t of newTypes) {
-        map[t] = readComponentData(arch, t, idx);
-      }
-
-      removeFromArchetype(arch, entityId);
-      addToArchetype(newArch, entityId, map);
-    },
-
-    getComponent(entityId, comp) {
-      const type = toSym(comp);
-      const arch = entityArchetype.get(entityId);
-      if (!arch) return undefined;
-      const idx = arch.entityToIndex.get(entityId);
-      if (idx === undefined) return undefined;
-      return readComponentData(arch, type, idx);
-    },
-
-    get(entityId, fieldRef) {
-      const arch = entityArchetype.get(entityId);
-      if (!arch) return undefined;
-      const store = arch.components.get(fieldRef._sym);
-      if (!store) return undefined;
-      const idx = arch.entityToIndex.get(entityId);
-      return store[fieldRef._field][idx];
-    },
-
-    set(entityId, fieldRef, value) {
-      const arch = entityArchetype.get(entityId);
-      if (!arch) return;
-      const store = arch.components.get(fieldRef._sym);
-      if (!store) return;
-      const idx = arch.entityToIndex.get(entityId);
-      store[fieldRef._field][idx] = value;
-    },
-
-    hasComponent(entityId, comp) {
-      const type = toSym(comp);
-      const arch = entityArchetype.get(entityId);
-      return arch ? arch.types.has(type) : false;
-    },
-
-    query(includeTypes, excludeTypes) {
-      const matching = getMatchingArchetypes(includeTypes, excludeTypes);
-      const result = [];
-      for (let a = 0; a < matching.length; a++) {
-        const arch = matching[a];
-        const ids = arch.entityIds;
-        for (let i = 0; i < arch.count; i++) {
-          result.push(ids[i]);
-        }
-      }
-      return result;
-    },
-
-    getAllEntities() {
-      return [...allEntityIds];
-    },
-
-    createEntityWith(...args) {
-      const id = nextId++;
-      allEntityIds.add(id);
-
-      const types = [];
-      const map = {};
-      for (let i = 0; i < args.length; i += 2) {
-        const sym = toSym(args[i]);
-        types.push(sym);
-        map[sym] = args[i + 1];
-      }
-      const arch = getOrCreateArchetype(types);
-      addToArchetype(arch, id, map);
-
-      if (createdSet && (arch.key & trackFilter)) createdSet.add(id);
-      return id;
-    },
-
-    count(includeTypes, excludeTypes) {
-      const matching = getMatchingArchetypes(includeTypes, excludeTypes);
-      let total = 0;
-      for (let a = 0; a < matching.length; a++) {
-        total += matching[a].count;
-      }
-      return total;
-    },
-
-    forEach(includeTypes, callback, excludeTypes) {
-      const matching = getMatchingArchetypes(includeTypes, excludeTypes);
-      for (let a = 0; a < matching.length; a++) {
-        const arch = matching[a];
-        if (arch.count === 0) continue;
-        const snaps = arch.snapshots;
-        const view = {
-          id: arch.key,
-          entityIds: arch.entityIds,
-          count: arch.count,
-          snapshotEntityIds: arch.snapshotEntityIds,
-          snapshotCount: arch.snapshotCount,
-          field(ref) {
-            const sym = ref._sym || ref;
-            const store = arch.components.get(sym);
-            if (!store) return undefined;
-            return store[ref._field];
-          },
-          snapshot(ref) {
-            if (!snaps) return undefined;
-            const sym = ref._sym || ref;
-            const snap = snaps.get(sym);
-            if (!snap) return undefined;
-            return snap[ref._field];
-          }
-        };
-        callback(view);
-      }
-    },
-
-    enableTracking(filterComponent) {
-      trackFilter = 1 << getBit(filterComponent);
-      createdSet = new Set();
-      destroyedSet = new Set();
-      // Retroactively add snapshots to existing matching archetypes
-      for (const arch of archetypes.values()) {
-        if ((arch.key & trackFilter) !== 0 && !arch.snapshots) {
-          arch.snapshots = new Map();
-          arch.snapshotEntityIds = [];
-          arch.snapshotCount = 0;
-          for (const [t, store] of arch.components) {
-            if (store) {
-              arch.snapshots.set(t, createSnapshotStore(store._schema, arch.capacity));
-            }
-          }
-          trackedArchetypes.push(arch);
-        }
-      }
-    },
-
-    flushChanges() {
-      const result = { created: createdSet, destroyed: destroyedSet };
-      createdSet = new Set();
-      destroyedSet = new Set();
-      return result;
-    },
-
-    flushSnapshots() {
-      for (let a = 0; a < trackedArchetypes.length; a++) {
-        const arch = trackedArchetypes[a];
-        const count = arch.count;
-        // Copy entityIds
-        const eids = arch.entityIds;
-        const snapEids = arch.snapshotEntityIds;
-        for (let i = 0; i < count; i++) snapEids[i] = eids[i];
-        arch.snapshotCount = count;
-        // Copy all field arrays via .set() (one memcpy per field)
-        for (const [type, store] of arch.components) {
-          if (!store) continue;
-          const snap = arch.snapshots.get(type);
-          if (!snap) continue;
-          for (const field in store._schema) {
-            const src = store[field];
-            const dst = snap[field];
-            if (src.set) {
-              // TypedArray — use .set() for memcpy, only copy active region
-              dst.set(src.subarray(0, count));
-            } else {
-              // Regular Array (string fields)
-              for (let i = 0; i < count; i++) dst[i] = src[i];
-            }
-          }
-        }
-      }
-    },
-
-    serialize(symbolToName, stripComponents = [], skipEntitiesWith = [], { serializers } = {}) {
-      const stripSymbols = new Set(stripComponents.map(toSym));
-      const skipSymbols = new Set(skipEntitiesWith.map(toSym));
-      const skipEntityIds = new Set();
-
-      if (skipSymbols.size > 0) {
-        for (const arch of archetypes.values()) {
-          let hasSkip = false;
-          for (const sym of skipSymbols) {
-            if (arch.types.has(sym)) { hasSkip = true; break; }
-          }
-          if (!hasSkip) continue;
-          for (let i = 0; i < arch.count; i++) {
-            skipEntityIds.add(arch.entityIds[i]);
-          }
-        }
-      }
-
-      const serializedComponents = {};
-
-      for (const arch of archetypes.values()) {
-        for (const [sym, store] of arch.components) {
-          if (!store) continue;
-          if (stripSymbols.has(sym) || skipSymbols.has(sym)) continue;
-          const name = symbolToName.get(sym);
-          if (!name) continue;
-
-          if (!serializedComponents[name]) {
-            serializedComponents[name] = {};
-          }
-          const entries = serializedComponents[name];
-
-          const customSerializer = serializers && serializers.get(name);
-
-          for (let i = 0; i < arch.count; i++) {
-            const entityId = arch.entityIds[i];
-            if (skipEntityIds.has(entityId)) continue;
-            const value = soaRead(store, i);
-            entries[entityId] = customSerializer ? customSerializer(value) : value;
-          }
-        }
-      }
-
-      for (const name of Object.keys(serializedComponents)) {
-        if (Object.keys(serializedComponents[name]).length === 0) {
-          delete serializedComponents[name];
-        }
-      }
-
-      const serializedEntities = [];
-      for (const id of allEntityIds) {
-        if (!skipEntityIds.has(id)) serializedEntities.push(id);
-      }
-
-      return {
-        nextId,
-        entities: serializedEntities,
-        components: serializedComponents
-      };
-    },
-
-    deserialize(data, nameToSymbol, { deserializers } = {}) {
-      allEntityIds.clear();
-      archetypes.clear();
-      entityArchetype.clear();
-      queryCache.clear();
-      queryCacheVersion = 0;
-
-      nextId = data.nextId;
-
-      const entityComponents = new Map();
-
-      for (const id of data.entities) {
-        allEntityIds.add(id);
-        entityComponents.set(id, {});
-      }
-
-      for (const [name, store] of Object.entries(data.components)) {
-        const entry = nameToSymbol[name];
-        if (!entry) continue;
-        const sym = toSym(entry);
-
-        const customDeserializer = deserializers && deserializers.get(name);
-
-        for (const [entityIdStr, compData] of Object.entries(store)) {
-          const entityId = Number(entityIdStr);
-          const obj = entityComponents.get(entityId);
-          if (!obj) continue;
-
-          if (customDeserializer) {
-            obj[sym] = customDeserializer(compData);
-          } else {
-            obj[sym] = compData;
-          }
-        }
-      }
-
-      const groupedByKey = new Map();
-      for (const [entityId, compMap] of entityComponents) {
-        const types = Object.getOwnPropertySymbols(compMap);
-        if (types.length === 0) continue;
-
-        const key = computeMask(types);
-        if (!groupedByKey.has(key)) {
-          groupedByKey.set(key, []);
-        }
-        groupedByKey.get(key).push({ entityId, compMap });
-      }
-
-      for (const [key, entries] of groupedByKey) {
-        const types = Object.getOwnPropertySymbols(entries[0].compMap);
-        const arch = getOrCreateArchetype(types);
-
-        for (const { entityId, compMap } of entries) {
-          addToArchetype(arch, entityId, compMap);
-        }
-      }
-    }
-  };
-}

package/src/index.d.ts

@@ -1,118 +0,0 @@
-// === Basis types ===
-export type EntityId = number;
-
-// === Field reference descriptor ===
-export interface FieldRef<V = number> {
-  readonly _sym: symbol;
-  readonly _field: string;
-}
-
-// === Component definition ===
-declare const __phantom: unique symbol;
-export type ComponentDef<T = unknown> = {
-  readonly _sym: symbol;
-  readonly _name: string;
-  readonly [__phantom]?: T;
-} & (T extends Record<string, number | string>
-  ? { readonly [K in keyof T & string]: FieldRef<T[K]> }
-  : {});
-
-/** @deprecated Use ComponentDef<T> instead */
-export type Component<T = unknown> = ComponentDef<T>;
-export type ComponentType = ComponentDef;
-
-// === TypedArray schema ===
-export type TypedArrayType = 'f32' | 'f64' | 'i8' | 'i16' | 'i32' | 'u8' | 'u16' | 'u32' | 'string';
-
-export type Schema = Record<string, TypedArrayType>;
-
-/** Maps a schema type to its runtime value type */
-type FieldToType<T extends TypedArrayType> = T extends 'string' ? string : number;
-
-/** Maps a schema definition to its runtime value type */
-type SchemaToType<S extends Schema> = { [K in keyof S]: FieldToType<S[K]> };
-
-export declare const TYPED: unique symbol;
-
-export declare const componentSchemas: Map<symbol, Record<string, Float32ArrayConstructor | Float64ArrayConstructor | Int8ArrayConstructor | Int16ArrayConstructor | Int32ArrayConstructor | Uint8ArrayConstructor | Uint16ArrayConstructor | Uint32ArrayConstructor | ArrayConstructor>>;
-
-// === TypedArray union ===
-type TypedArray = Float32Array | Float64Array | Int8Array | Int16Array | Int32Array | Uint8Array | Uint16Array | Uint32Array;
-
-// === ArchetypeView (forEach callback) ===
-export interface ArchetypeView {
-  readonly id: number;
-  readonly entityIds: EntityId[];
-  readonly count: number;
-  readonly snapshotEntityIds: EntityId[] | null;
-  readonly snapshotCount: number;
-  field(ref: FieldRef<any>): TypedArray | unknown[] | undefined;
-  snapshot(ref: FieldRef<any>): TypedArray | unknown[] | undefined;
-}
-
-// === Serialize/Deserialize ===
-export interface SerializeOptions {
-  serializers?: Map<string, (data: unknown) => unknown>;
-}
-
-export interface DeserializeOptions {
-  deserializers?: Map<string, (data: unknown) => unknown>;
-}
-
-export interface SerializedData {
-  nextId: number;
-  entities: EntityId[];
-  components: Record<string, Record<string, unknown>>;
-}
-
-// === EntityManager ===
-export interface EntityManager {
-  createEntity(): EntityId;
-  destroyEntity(id: EntityId): void;
-  addComponent<T>(entityId: EntityId, type: ComponentDef<T>, data: T): void;
-  removeComponent(entityId: EntityId, type: ComponentDef): void;
-  getComponent<T>(entityId: EntityId, type: ComponentDef<T>): T | undefined;
-  get<V>(entityId: EntityId, fieldRef: FieldRef<V>): V | undefined;
-  set<V>(entityId: EntityId, fieldRef: FieldRef<V>, value: V): void;
-  hasComponent(entityId: EntityId, type: ComponentDef): boolean;
-  query(include: ComponentDef[], exclude?: ComponentDef[]): EntityId[];
-  getAllEntities(): EntityId[];
-  createEntityWith(...args: unknown[]): EntityId;
-  count(include: ComponentDef[], exclude?: ComponentDef[]): number;
-  forEach(include: ComponentDef[], callback: (view: ArchetypeView) => void, exclude?: ComponentDef[]): void;
-  enableTracking(filterComponent: ComponentDef): void;
-  flushChanges(): { created: Set<EntityId>; destroyed: Set<EntityId> };
-  flushSnapshots(): void;
-  serialize(
-    symbolToName: Map<symbol, string>,
-    stripComponents?: ComponentDef[],
-    skipEntitiesWith?: ComponentDef[],
-    options?: SerializeOptions
-  ): SerializedData;
-  deserialize(
-    data: SerializedData,
-    nameToSymbol: Record<string, ComponentDef>,
-    options?: DeserializeOptions
-  ): void;
-}
-
-// === Profiler ===
-export interface ProfilerEntry {
-  avg: number;
-}
-
-export interface Profiler {
-  readonly enabled: boolean;
-  setEnabled(value: boolean): void;
-  begin(): number;
-  end(name: string, t0: number): void;
-  record(name: string, ms: number): void;
-  getData(): Map<string, ProfilerEntry>;
-}
-
-// === Exports ===
-export function createEntityManager(): EntityManager;
-export function component(name: string): ComponentDef;
-export function component<T extends TypedArrayType, F extends string>(name: string, type: T, fields: F[]): ComponentDef<Record<F, FieldToType<T>>>;
-export function component<S extends Schema>(name: string, schema: S): ComponentDef<SchemaToType<S>>;
-export const profiler: Profiler;