archetype-ecs 1.0.0 → 1.2.0

package/src/EntityManager.js

@@ -1,26 +1,87 @@
+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;
+  }
+}
+
 export function createEntityManager() {
   let nextId = 1;
   const allEntityIds = new Set();
 
+  // 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();         // key → Archetype
+  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 makeArchetypeKey(types) {
-    const descs = [];
-    for (const sym of types) {
-      descs.push(sym.description);
-    }
-    descs.sort();
-    return descs.join('|');
-  }
-
   function getOrCreateArchetype(types) {
-    const key = makeArchetypeKey(types);
+    const key = computeMask(types);
     let arch = archetypes.get(key);
     if (!arch) {
       arch = {
@@ -29,10 +90,12 @@ export function createEntityManager() {
         entityIds: [],
         components: new Map(),
         entityToIndex: new Map(),
-        count: 0
+        count: 0,
+        capacity: INITIAL_CAPACITY
       };
       for (const t of types) {
-        arch.components.set(t, []);
+        const schema = componentSchemas.get(t);
+        arch.components.set(t, schema ? createSoAStore(schema, INITIAL_CAPACITY) : null);
       }
       archetypes.set(key, arch);
       queryCacheVersion++;
@@ -40,11 +103,22 @@ export function createEntityManager() {
     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);
+    }
+  }
+
   function addToArchetype(arch, entityId, componentMap) {
+    ensureCapacity(arch);
     const idx = arch.count;
     arch.entityIds[idx] = entityId;
     for (const t of arch.types) {
-      arch.components.get(t)[idx] = componentMap.get(t);
+      const store = arch.components.get(t);
+      if (store) soaWrite(store, idx, componentMap[t]);
     }
     arch.entityToIndex.set(entityId, idx);
     arch.count++;
@@ -56,30 +130,31 @@ export function createEntityManager() {
     const lastIdx = arch.count - 1;
 
     if (idx !== lastIdx) {
-      // Swap with last
       const lastEntity = arch.entityIds[lastIdx];
       arch.entityIds[idx] = lastEntity;
-      for (const [type, arr] of arch.components) {
-        arr[idx] = arr[lastIdx];
+      for (const [type, store] of arch.components) {
+        if (store) soaSwap(store, idx, lastIdx);
       }
       arch.entityToIndex.set(lastEntity, idx);
     }
 
-    // Pop last
     arch.entityIds.length = lastIdx;
-    for (const [type, arr] of arch.components) {
-      arr.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) {
-    let queryKey = makeArchetypeKey(types);
-    if (excludeTypes && excludeTypes.length > 0) {
-      queryKey += '!' + makeArchetypeKey(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;
@@ -87,22 +162,10 @@ export function createEntityManager() {
 
     const matching = [];
     for (const arch of archetypes.values()) {
-      let match = true;
-      for (const t of types) {
-        if (!arch.types.has(t)) {
-          match = false;
-          break;
-        }
+      if ((arch.key & includeMask) === includeMask &&
+          (arch.key & excludeMask) === 0) {
+        matching.push(arch);
       }
-      if (match && excludeTypes) {
-        for (const t of excludeTypes) {
-          if (arch.types.has(t)) {
-            match = false;
-            break;
-          }
-        }
-      }
-      if (match) matching.push(arch);
     }
 
     queryCache.set(queryKey, { version: queryCacheVersion, archetypes: matching });
@@ -124,78 +187,95 @@ export function createEntityManager() {
       allEntityIds.delete(id);
     },
 
-    addComponent(entityId, componentName, data) {
+    addComponent(entityId, comp, data) {
+      const type = toSym(comp);
       const arch = entityArchetype.get(entityId);
 
       if (!arch) {
-        // Entity has no archetype yet — create single-type archetype
-        const newArch = getOrCreateArchetype([componentName]);
-        const map = new Map();
-        map.set(componentName, data);
-        addToArchetype(newArch, entityId, map);
+        const newArch = getOrCreateArchetype([type]);
+        addToArchetype(newArch, entityId, { [type]: data });
         return;
       }
 
-      if (arch.types.has(componentName)) {
-        // Already has this component type — just update data
-        const idx = arch.entityToIndex.get(entityId);
-        arch.components.get(componentName)[idx] = data;
+      if (arch.types.has(type)) {
+        const store = arch.components.get(type);
+        if (store) {
+          const idx = arch.entityToIndex.get(entityId);
+          soaWrite(store, idx, data);
+        }
         return;
       }
 
-      // Need to move to a new archetype with the extra type
-      const newTypes = [...arch.types, componentName];
+      const newTypes = [...arch.types, type];
       const newArch = getOrCreateArchetype(newTypes);
 
-      // Collect component data from old archetype
       const idx = arch.entityToIndex.get(entityId);
-      const map = new Map();
+      const map = { [type]: data };
       for (const t of arch.types) {
-        map.set(t, arch.components.get(t)[idx]);
+        map[t] = readComponentData(arch, t, idx);
       }
-      map.set(componentName, data);
 
       removeFromArchetype(arch, entityId);
       addToArchetype(newArch, entityId, map);
     },
 
-    removeComponent(entityId, componentName) {
+    removeComponent(entityId, comp) {
+      const type = toSym(comp);
       const arch = entityArchetype.get(entityId);
-      if (!arch || !arch.types.has(componentName)) return;
+      if (!arch || !arch.types.has(type)) return;
 
       if (arch.types.size === 1) {
-        // Removing last component — entity has no archetype
         removeFromArchetype(arch, entityId);
         return;
       }
 
       const newTypes = [];
       for (const t of arch.types) {
-        if (t !== componentName) newTypes.push(t);
+        if (t !== type) newTypes.push(t);
       }
       const newArch = getOrCreateArchetype(newTypes);
 
       const idx = arch.entityToIndex.get(entityId);
-      const map = new Map();
+      const map = {};
       for (const t of newTypes) {
-        map.set(t, arch.components.get(t)[idx]);
+        map[t] = readComponentData(arch, t, idx);
       }
 
       removeFromArchetype(arch, entityId);
       addToArchetype(newArch, entityId, map);
     },
 
-    getComponent(entityId, componentName) {
+    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 arr = arch.components.get(componentName);
-      if (!arr) return undefined;
-      return arr[arch.entityToIndex.get(entityId)];
+      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, componentName) {
+    hasComponent(entityId, comp) {
+      const type = toSym(comp);
       const arch = entityArchetype.get(entityId);
-      return arch ? arch.types.has(componentName) : false;
+      return arch ? arch.types.has(type) : false;
     },
 
     query(includeTypes, excludeTypes) {
@@ -215,13 +295,19 @@ export function createEntityManager() {
       return [...allEntityIds];
     },
 
-    createEntityWith(componentMap) {
+    createEntityWith(...args) {
       const id = nextId++;
       allEntityIds.add(id);
 
-      const types = [...componentMap.keys()];
+      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, componentMap);
+      addToArchetype(arch, id, map);
 
       return id;
     },
@@ -235,12 +321,30 @@ export function createEntityManager() {
       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 view = {
+          entityIds: arch.entityIds,
+          count: arch.count,
+          field(ref) {
+            const sym = ref._sym || ref;
+            const store = arch.components.get(sym);
+            if (!store) return undefined;
+            return store[ref._field];
+          }
+        };
+        callback(view);
+      }
+    },
+
     serialize(symbolToName, stripComponents = [], skipEntitiesWith = [], { serializers } = {}) {
-      const stripSymbols = new Set(stripComponents);
-      const skipSymbols = new Set(skipEntitiesWith);
+      const stripSymbols = new Set(stripComponents.map(toSym));
+      const skipSymbols = new Set(skipEntitiesWith.map(toSym));
       const skipEntityIds = new Set();
 
-      // Find entities that have any "skip entity" component — these are fully excluded
       if (skipSymbols.size > 0) {
         for (const arch of archetypes.values()) {
           let hasSkip = false;
@@ -257,7 +361,8 @@ export function createEntityManager() {
       const serializedComponents = {};
 
       for (const arch of archetypes.values()) {
-        for (const [sym, arr] of arch.components) {
+        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;
@@ -272,16 +377,12 @@ export function createEntityManager() {
           for (let i = 0; i < arch.count; i++) {
             const entityId = arch.entityIds[i];
             if (skipEntityIds.has(entityId)) continue;
-            if (customSerializer) {
-              entries[entityId] = customSerializer(arr[i]);
-            } else {
-              entries[entityId] = structuredClone(arr[i]);
-            }
+            const value = soaRead(store, i);
+            entries[entityId] = customSerializer ? customSerializer(value) : value;
           }
         }
       }
 
-      // Remove empty component groups
       for (const name of Object.keys(serializedComponents)) {
         if (Object.keys(serializedComponents[name]).length === 0) {
           delete serializedComponents[name];
@@ -301,7 +402,6 @@ export function createEntityManager() {
     },
 
     deserialize(data, nameToSymbol, { deserializers } = {}) {
-      // Clear all state
       allEntityIds.clear();
       archetypes.clear();
       entityArchetype.clear();
@@ -310,39 +410,39 @@ export function createEntityManager() {
 
       nextId = data.nextId;
 
-      // Build per-entity component maps
       const entityComponents = new Map();
 
       for (const id of data.entities) {
         allEntityIds.add(id);
-        entityComponents.set(id, new Map());
+        entityComponents.set(id, {});
       }
 
       for (const [name, store] of Object.entries(data.components)) {
-        const sym = nameToSymbol[name];
-        if (!sym) continue;
+        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 map = entityComponents.get(entityId);
-          if (!map) continue;
+          const obj = entityComponents.get(entityId);
+          if (!obj) continue;
 
           if (customDeserializer) {
-            map.set(sym, customDeserializer(compData));
+            obj[sym] = customDeserializer(compData);
           } else {
-            map.set(sym, compData);
+            obj[sym] = compData;
           }
         }
       }
 
-      // Group by archetype key and bulk-insert
       const groupedByKey = new Map();
       for (const [entityId, compMap] of entityComponents) {
-        if (compMap.size === 0) continue; // entity with no components
+        const types = Object.getOwnPropertySymbols(compMap);
+        if (types.length === 0) continue;
 
-        const key = makeArchetypeKey([...compMap.keys()]);
+        const key = computeMask(types);
         if (!groupedByKey.has(key)) {
           groupedByKey.set(key, []);
         }
@@ -350,7 +450,7 @@ export function createEntityManager() {
       }
 
       for (const [key, entries] of groupedByKey) {
-        const types = [...entries[0].compMap.keys()];
+        const types = Object.getOwnPropertySymbols(entries[0].compMap);
         const arch = getOrCreateArchetype(types);
 
         for (const { entityId, compMap } of entries) {

package/src/index.d.ts

@@ -0,0 +1,111 @@
+// === 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 entityIds: EntityId[];
+  readonly count: number;
+  field(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;
+  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;

package/src/index.js

@@ -1,5 +1,37 @@
 export { createEntityManager } from './EntityManager.js';
-export { createEventBus } from './EventBus.js';
-export { createContainer } from './Container.js';
-export { createGameLoop } from './GameLoop.js';
 export { profiler } from './Profiler.js';
+export { TYPED, componentSchemas } from './ComponentRegistry.js';
+import { TYPE_MAP, componentSchemas } from './ComponentRegistry.js';
+
+export function component(name, typeOrSchema, fields) {
+  const sym = Symbol(name);
+  const comp = { _sym: sym, _name: name };
+
+  let schema;
+
+  if (typeof typeOrSchema === 'string' && Array.isArray(fields)) {
+    // Short form: component('Position', 'f32', ['x', 'y'])
+    const Ctor = TYPE_MAP[typeOrSchema];
+    if (!Ctor) throw new Error(`Unknown type "${typeOrSchema}"`);
+    schema = {};
+    for (const f of fields) {
+      schema[f] = Ctor;
+      comp[f] = { _sym: sym, _field: f };
+    }
+  } else if (typeOrSchema && typeof typeOrSchema === 'object') {
+    // Schema form: component('Position', { x: 'f32', y: 'f32' })
+    schema = {};
+    for (const [field, type] of Object.entries(typeOrSchema)) {
+      const Ctor = TYPE_MAP[type];
+      if (!Ctor) throw new Error(`Unknown type "${type}" for field "${field}"`);
+      schema[field] = Ctor;
+      comp[field] = { _sym: sym, _field: field };
+    }
+  }
+
+  if (schema) {
+    componentSchemas.set(sym, schema);
+  }
+
+  return comp;
+}