archetype-ecs 1.0.0

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "archetype-ecs",
+  "version": "1.0.0",
+  "description": "Lightweight archetype-based Entity Component System",
+  "type": "module",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/.bin/jest"
+  },
+  "keywords": ["ecs", "entity", "component", "system", "archetype", "gamedev"],
+  "license": "MIT",
+  "devDependencies": {
+    "jest": "^29.7.0",
+    "@jest/globals": "^29.7.0"
+  }
+}

package/src/Container.js

@@ -0,0 +1,23 @@
+export function createContainer() {
+  const factories = new Map();
+  const instances = new Map();
+
+  return {
+    register(key, factory) {
+      factories.set(key, factory);
+    },
+
+    resolve(key) {
+      if (instances.has(key)) {
+        return instances.get(key);
+      }
+      const factory = factories.get(key);
+      if (!factory) {
+        throw new Error(`No factory registered for key: ${key}`);
+      }
+      const instance = factory(this);
+      instances.set(key, instance);
+      return instance;
+    }
+  };
+}

package/src/EntityManager.js

@@ -0,0 +1,362 @@
+export function createEntityManager() {
+  let nextId = 1;
+  const allEntityIds = new Set();
+
+  // Archetype storage
+  const archetypes = new Map();         // key → 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);
+    let arch = archetypes.get(key);
+    if (!arch) {
+      arch = {
+        key,
+        types: new Set(types),
+        entityIds: [],
+        components: new Map(),
+        entityToIndex: new Map(),
+        count: 0
+      };
+      for (const t of types) {
+        arch.components.set(t, []);
+      }
+      archetypes.set(key, arch);
+      queryCacheVersion++;
+    }
+    return arch;
+  }
+
+  function addToArchetype(arch, entityId, componentMap) {
+    const idx = arch.count;
+    arch.entityIds[idx] = entityId;
+    for (const t of arch.types) {
+      arch.components.get(t)[idx] = componentMap.get(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) {
+      // Swap with last
+      const lastEntity = arch.entityIds[lastIdx];
+      arch.entityIds[idx] = lastEntity;
+      for (const [type, arr] of arch.components) {
+        arr[idx] = arr[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 getMatchingArchetypes(types, excludeTypes) {
+    let queryKey = makeArchetypeKey(types);
+    if (excludeTypes && excludeTypes.length > 0) {
+      queryKey += '!' + makeArchetypeKey(excludeTypes);
+    }
+    const cached = queryCache.get(queryKey);
+    if (cached && cached.version === queryCacheVersion) {
+      return cached.archetypes;
+    }
+
+    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 (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 });
+    return matching;
+  }
+
+  return {
+    createEntity() {
+      const id = nextId++;
+      allEntityIds.add(id);
+      return id;
+    },
+
+    destroyEntity(id) {
+      const arch = entityArchetype.get(id);
+      if (arch) {
+        removeFromArchetype(arch, id);
+      }
+      allEntityIds.delete(id);
+    },
+
+    addComponent(entityId, componentName, data) {
+      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);
+        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;
+        return;
+      }
+
+      // Need to move to a new archetype with the extra type
+      const newTypes = [...arch.types, componentName];
+      const newArch = getOrCreateArchetype(newTypes);
+
+      // Collect component data from old archetype
+      const idx = arch.entityToIndex.get(entityId);
+      const map = new Map();
+      for (const t of arch.types) {
+        map.set(t, arch.components.get(t)[idx]);
+      }
+      map.set(componentName, data);
+
+      removeFromArchetype(arch, entityId);
+      addToArchetype(newArch, entityId, map);
+    },
+
+    removeComponent(entityId, componentName) {
+      const arch = entityArchetype.get(entityId);
+      if (!arch || !arch.types.has(componentName)) 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);
+      }
+      const newArch = getOrCreateArchetype(newTypes);
+
+      const idx = arch.entityToIndex.get(entityId);
+      const map = new Map();
+      for (const t of newTypes) {
+        map.set(t, arch.components.get(t)[idx]);
+      }
+
+      removeFromArchetype(arch, entityId);
+      addToArchetype(newArch, entityId, map);
+    },
+
+    getComponent(entityId, componentName) {
+      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)];
+    },
+
+    hasComponent(entityId, componentName) {
+      const arch = entityArchetype.get(entityId);
+      return arch ? arch.types.has(componentName) : 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(componentMap) {
+      const id = nextId++;
+      allEntityIds.add(id);
+
+      const types = [...componentMap.keys()];
+      const arch = getOrCreateArchetype(types);
+      addToArchetype(arch, id, componentMap);
+
+      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;
+    },
+
+    serialize(symbolToName, stripComponents = [], skipEntitiesWith = [], { serializers } = {}) {
+      const stripSymbols = new Set(stripComponents);
+      const skipSymbols = new Set(skipEntitiesWith);
+      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;
+          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, arr] of arch.components) {
+          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;
+            if (customSerializer) {
+              entries[entityId] = customSerializer(arr[i]);
+            } else {
+              entries[entityId] = structuredClone(arr[i]);
+            }
+          }
+        }
+      }
+
+      // Remove empty component groups
+      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 } = {}) {
+      // Clear all state
+      allEntityIds.clear();
+      archetypes.clear();
+      entityArchetype.clear();
+      queryCache.clear();
+      queryCacheVersion = 0;
+
+      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());
+      }
+
+      for (const [name, store] of Object.entries(data.components)) {
+        const sym = nameToSymbol[name];
+        if (!sym) continue;
+
+        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;
+
+          if (customDeserializer) {
+            map.set(sym, customDeserializer(compData));
+          } else {
+            map.set(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 key = makeArchetypeKey([...compMap.keys()]);
+        if (!groupedByKey.has(key)) {
+          groupedByKey.set(key, []);
+        }
+        groupedByKey.get(key).push({ entityId, compMap });
+      }
+
+      for (const [key, entries] of groupedByKey) {
+        const types = [...entries[0].compMap.keys()];
+        const arch = getOrCreateArchetype(types);
+
+        for (const { entityId, compMap } of entries) {
+          addToArchetype(arch, entityId, compMap);
+        }
+      }
+    }
+  };
+}

package/src/EventBus.js

@@ -0,0 +1,29 @@
+export function createEventBus() {
+  const listeners = new Map();
+
+  return {
+    on(event, callback) {
+      if (!listeners.has(event)) {
+        listeners.set(event, []);
+      }
+      listeners.get(event).push(callback);
+    },
+
+    off(event, callback) {
+      const cbs = listeners.get(event);
+      if (cbs) {
+        const idx = cbs.indexOf(callback);
+        if (idx !== -1) cbs.splice(idx, 1);
+      }
+    },
+
+    emit(event, data) {
+      const cbs = listeners.get(event);
+      if (cbs) {
+        for (const cb of cbs) {
+          cb(data);
+        }
+      }
+    }
+  };
+}

package/src/GameLoop.js

@@ -0,0 +1,110 @@
+import { profiler } from './Profiler.js';
+
+export function createGameLoop(systems, renderSteps, { tickRate = 20, maxFrameTime = 250 } = {}) {
+  let running = false;
+  let lastTime = 0;
+  let accumulator = 0;
+  let tickCount = 0;
+  let frameCount = 0;
+  let fpsTime = 0;
+  let fps = 0;
+  let tps = 0;
+  let fpsLimit = 0;
+  let lastRenderTime = 0;
+  let tickDuration = 1000 / tickRate;
+  let rafId = 0;
+
+  function loop(currentTime) {
+    if (!running) return;
+
+    const frameTime = Math.min(currentTime - lastTime, maxFrameTime);
+    lastTime = currentTime;
+    accumulator += frameTime;
+
+    // Fixed timestep simulation
+    while (accumulator >= tickDuration) {
+      if (profiler.enabled) {
+        const tickStart = performance.now();
+        for (const system of systems) {
+          if (system.update) {
+            const t0 = performance.now();
+            system.update(tickDuration);
+            profiler.end(system.name || 'unnamed', t0);
+          }
+        }
+        profiler.end('Tick Total', tickStart);
+      } else {
+        for (const system of systems) {
+          if (system.update) system.update(tickDuration);
+        }
+      }
+      accumulator -= tickDuration;
+      tickCount++;
+    }
+
+    const alpha = accumulator / tickDuration;
+
+    // Render (respecting fps cap)
+    const minRenderInterval = fpsLimit > 0 ? 1000 / fpsLimit : 0;
+    if (minRenderInterval === 0 || currentTime - lastRenderTime >= minRenderInterval) {
+      if (profiler.enabled) {
+        const renderStart = performance.now();
+        for (const step of renderSteps) {
+          const t0 = performance.now();
+          step.fn(alpha, frameTime);
+          profiler.end(step.name, t0);
+        }
+        profiler.end('Render Total', renderStart);
+      } else {
+        for (const step of renderSteps) {
+          step.fn(alpha, frameTime);
+        }
+      }
+      lastRenderTime = currentTime;
+      frameCount++;
+    }
+
+    fpsTime += frameTime;
+    if (fpsTime >= 1000) {
+      fps = frameCount;
+      tps = tickCount;
+      frameCount = 0;
+      tickCount = 0;
+      fpsTime -= 1000;
+    }
+
+    rafId = requestAnimationFrame(loop);
+  }
+
+  return {
+    start() {
+      if (running) return;
+      running = true;
+      lastTime = performance.now();
+      lastRenderTime = 0;
+      rafId = requestAnimationFrame(loop);
+    },
+
+    stop() {
+      running = false;
+      cancelAnimationFrame(rafId);
+    },
+
+    setFpsLimit(limit) {
+      fpsLimit = limit;
+    },
+
+    setTickRate(rate) {
+      tickDuration = 1000 / rate;
+      accumulator = 0;
+    },
+
+    setProfilingEnabled(enabled) {
+      profiler.setEnabled(enabled);
+    },
+
+    getProfileData() { return profiler.getData(); },
+    getFps() { return fps; },
+    getTps() { return tps; }
+  };
+}

package/src/Profiler.js

@@ -0,0 +1,39 @@
+const EMA_ALPHA = 0.1;
+const data = new Map();
+let enabled = false;
+
+export const profiler = {
+  get enabled() { return enabled; },
+
+  setEnabled(value) {
+    enabled = value;
+    if (!value) data.clear();
+  },
+
+  begin() {
+    return enabled ? performance.now() : 0;
+  },
+
+  end(name, t0) {
+    if (!enabled) return;
+    const ms = performance.now() - t0;
+    const entry = data.get(name);
+    if (entry) {
+      entry.avg += (ms - entry.avg) * EMA_ALPHA;
+    } else {
+      data.set(name, { avg: ms });
+    }
+  },
+
+  record(name, ms) {
+    if (!enabled) return;
+    const entry = data.get(name);
+    if (entry) {
+      entry.avg += (ms - entry.avg) * EMA_ALPHA;
+    } else {
+      data.set(name, { avg: ms });
+    }
+  },
+
+  getData() { return data; }
+};

package/src/index.js

@@ -0,0 +1,5 @@
+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';

package/tests/Container.test.js

@@ -0,0 +1,38 @@
+import { describe, test, expect } from '@jest/globals';
+import { createContainer } from '../src/Container.js';
+
+describe('Container', () => {
+  test('register and resolve returns factory result', () => {
+    const container = createContainer();
+    container.register('greeting', () => 'hello');
+    expect(container.resolve('greeting')).toBe('hello');
+  });
+
+  test('singleton caching — resolves same instance', () => {
+    const container = createContainer();
+    let callCount = 0;
+    container.register('service', () => {
+      callCount++;
+      return { id: callCount };
+    });
+    const a = container.resolve('service');
+    const b = container.resolve('service');
+    expect(a).toBe(b);
+    expect(callCount).toBe(1);
+  });
+
+  test('factory receives container for dependency injection', () => {
+    const container = createContainer();
+    container.register('config', () => ({ port: 3000 }));
+    container.register('server', (c) => {
+      const config = c.resolve('config');
+      return { port: config.port };
+    });
+    expect(container.resolve('server')).toEqual({ port: 3000 });
+  });
+
+  test('throws for unregistered key', () => {
+    const container = createContainer();
+    expect(() => container.resolve('missing')).toThrow('No factory registered for key: missing');
+  });
+});

package/tests/EntityManager.test.js

@@ -0,0 +1,224 @@
+import { describe, test, expect, beforeEach } from '@jest/globals';
+import { createEntityManager } from '../src/EntityManager.js';
+
+describe('EntityManager', () => {
+  let em;
+  const Position = Symbol('Position');
+  const Velocity = Symbol('Velocity');
+  const Health = Symbol('Health');
+
+  beforeEach(() => {
+    em = createEntityManager();
+  });
+
+  describe('createEntity / destroyEntity', () => {
+    test('creates entities with incrementing ids', () => {
+      const a = em.createEntity();
+      const b = em.createEntity();
+      expect(b).toBe(a + 1);
+    });
+
+    test('destroyEntity removes entity', () => {
+      const id = em.createEntity();
+      em.addComponent(id, Position, { x: 0, y: 0 });
+      em.destroyEntity(id);
+      expect(em.getAllEntities()).toEqual([]);
+      expect(em.getComponent(id, Position)).toBeUndefined();
+    });
+  });
+
+  describe('addComponent / getComponent / hasComponent', () => {
+    test('adds and retrieves a component', () => {
+      const id = em.createEntity();
+      em.addComponent(id, Position, { x: 1, y: 2 });
+      expect(em.getComponent(id, Position)).toEqual({ x: 1, y: 2 });
+      expect(em.hasComponent(id, Position)).toBe(true);
+    });
+
+    test('returns undefined for missing component', () => {
+      const id = em.createEntity();
+      expect(em.getComponent(id, Position)).toBeUndefined();
+      expect(em.hasComponent(id, Position)).toBe(false);
+    });
+
+    test('overwrites component data on duplicate add', () => {
+      const id = em.createEntity();
+      em.addComponent(id, Position, { x: 1, y: 2 });
+      em.addComponent(id, Position, { x: 10, y: 20 });
+      expect(em.getComponent(id, Position)).toEqual({ x: 10, y: 20 });
+    });
+
+    test('adds multiple component types', () => {
+      const id = em.createEntity();
+      em.addComponent(id, Position, { x: 0, y: 0 });
+      em.addComponent(id, Velocity, { vx: 1, vy: 1 });
+      expect(em.getComponent(id, Position)).toEqual({ x: 0, y: 0 });
+      expect(em.getComponent(id, Velocity)).toEqual({ vx: 1, vy: 1 });
+    });
+  });
+
+  describe('removeComponent', () => {
+    test('removes a component', () => {
+      const id = em.createEntity();
+      em.addComponent(id, Position, { x: 1, y: 2 });
+      em.addComponent(id, Velocity, { vx: 1, vy: 1 });
+      em.removeComponent(id, Position);
+      expect(em.hasComponent(id, Position)).toBe(false);
+      expect(em.hasComponent(id, Velocity)).toBe(true);
+    });
+
+    test('removing last component leaves entity alive but without archetype', () => {
+      const id = em.createEntity();
+      em.addComponent(id, Position, { x: 1, y: 2 });
+      em.removeComponent(id, Position);
+      expect(em.getAllEntities()).toContain(id);
+      expect(em.hasComponent(id, Position)).toBe(false);
+    });
+
+    test('removing non-existent component is a no-op', () => {
+      const id = em.createEntity();
+      em.removeComponent(id, Position); // no-op
+      expect(em.getAllEntities()).toContain(id);
+    });
+  });
+
+  describe('query', () => {
+    test('returns entities matching component types', () => {
+      const a = em.createEntity();
+      em.addComponent(a, Position, { x: 0, y: 0 });
+      em.addComponent(a, Velocity, { vx: 1, vy: 1 });
+
+      const b = em.createEntity();
+      em.addComponent(b, Position, { x: 5, y: 5 });
+
+      const result = em.query([Position, Velocity]);
+      expect(result).toContain(a);
+      expect(result).not.toContain(b);
+    });
+
+    test('exclude types filters out entities', () => {
+      const a = em.createEntity();
+      em.addComponent(a, Position, { x: 0, y: 0 });
+
+      const b = em.createEntity();
+      em.addComponent(b, Position, { x: 1, y: 1 });
+      em.addComponent(b, Health, { hp: 100 });
+
+      const result = em.query([Position], [Health]);
+      expect(result).toContain(a);
+      expect(result).not.toContain(b);
+    });
+  });
+
+  describe('createEntityWith', () => {
+    test('creates entity with multiple components at once', () => {
+      const map = new Map();
+      map.set(Position, { x: 3, y: 4 });
+      map.set(Velocity, { vx: 1, vy: 0 });
+
+      const id = em.createEntityWith(map);
+      expect(em.getComponent(id, Position)).toEqual({ x: 3, y: 4 });
+      expect(em.getComponent(id, Velocity)).toEqual({ vx: 1, vy: 0 });
+    });
+  });
+
+  describe('count', () => {
+    test('counts entities matching query', () => {
+      const a = em.createEntity();
+      em.addComponent(a, Position, { x: 0, y: 0 });
+
+      const b = em.createEntity();
+      em.addComponent(b, Position, { x: 1, y: 1 });
+      em.addComponent(b, Velocity, { vx: 1, vy: 0 });
+
+      expect(em.count([Position])).toBe(2);
+      expect(em.count([Position, Velocity])).toBe(1);
+    });
+  });
+
+  describe('serialize / deserialize', () => {
+    const symbolToName = new Map([
+      [Position, 'Position'],
+      [Velocity, 'Velocity'],
+      [Health, 'Health']
+    ]);
+    const nameToSymbol = {
+      Position, Velocity, Health
+    };
+
+    test('round-trips entities and components', () => {
+      const a = em.createEntity();
+      em.addComponent(a, Position, { x: 1, y: 2 });
+      em.addComponent(a, Velocity, { vx: 3, vy: 4 });
+
+      const b = em.createEntity();
+      em.addComponent(b, Position, { x: 5, y: 6 });
+
+      const data = em.serialize(symbolToName);
+      em.deserialize(data, nameToSymbol);
+
+      expect(em.getAllEntities().sort()).toEqual([a, b].sort());
+      expect(em.getComponent(a, Position)).toEqual({ x: 1, y: 2 });
+      expect(em.getComponent(a, Velocity)).toEqual({ vx: 3, vy: 4 });
+      expect(em.getComponent(b, Position)).toEqual({ x: 5, y: 6 });
+    });
+
+    test('strip components excludes component data but keeps entity', () => {
+      const a = em.createEntity();
+      em.addComponent(a, Position, { x: 1, y: 2 });
+      em.addComponent(a, Velocity, { vx: 3, vy: 4 });
+
+      const data = em.serialize(symbolToName, [Velocity]);
+      expect(data.components['Velocity']).toBeUndefined();
+      expect(data.components['Position']).toBeDefined();
+    });
+
+    test('skip entities with component excludes entire entity', () => {
+      const a = em.createEntity();
+      em.addComponent(a, Position, { x: 1, y: 2 });
+
+      const b = em.createEntity();
+      em.addComponent(b, Position, { x: 5, y: 6 });
+      em.addComponent(b, Health, { hp: 100 });
+
+      const data = em.serialize(symbolToName, [], [Health]);
+      expect(data.entities).toContain(a);
+      expect(data.entities).not.toContain(b);
+    });
+
+    test('custom serializers are used when provided', () => {
+      const a = em.createEntity();
+      em.addComponent(a, Position, { x: 1, y: 2, _internal: 'secret' });
+
+      const serializers = new Map([
+        ['Position', (data) => ({ x: data.x, y: data.y })]
+      ]);
+
+      const result = em.serialize(symbolToName, [], [], { serializers });
+      expect(result.components['Position'][a]).toEqual({ x: 1, y: 2 });
+      expect(result.components['Position'][a]._internal).toBeUndefined();
+    });
+
+    test('custom deserializers are used when provided', () => {
+      const a = em.createEntity();
+      em.addComponent(a, Position, { x: 1, y: 2 });
+
+      const data = em.serialize(symbolToName);
+
+      const deserializers = new Map([
+        ['Position', (compData) => ({ ...compData, restored: true })]
+      ]);
+
+      em.deserialize(data, nameToSymbol, { deserializers });
+      expect(em.getComponent(a, Position)).toEqual({ x: 1, y: 2, restored: true });
+    });
+
+    test('deserialize clears previous state', () => {
+      const a = em.createEntity();
+      em.addComponent(a, Position, { x: 1, y: 2 });
+
+      em.deserialize({ nextId: 1, entities: [], components: {} }, nameToSymbol);
+      expect(em.getAllEntities()).toEqual([]);
+    });
+  });
+});

package/tests/EventBus.test.js

@@ -0,0 +1,41 @@
+import { describe, test, expect } from '@jest/globals';
+import { createEventBus } from '../src/EventBus.js';
+
+describe('EventBus', () => {
+  test('on/emit calls listener with data', () => {
+    const bus = createEventBus();
+    const received = [];
+    bus.on('test', (data) => received.push(data));
+    bus.emit('test', { value: 42 });
+    expect(received).toEqual([{ value: 42 }]);
+  });
+
+  test('multiple listeners on same event', () => {
+    const bus = createEventBus();
+    const results = [];
+    bus.on('test', () => results.push('a'));
+    bus.on('test', () => results.push('b'));
+    bus.emit('test');
+    expect(results).toEqual(['a', 'b']);
+  });
+
+  test('off removes listener', () => {
+    const bus = createEventBus();
+    const results = [];
+    const cb = () => results.push('called');
+    bus.on('test', cb);
+    bus.off('test', cb);
+    bus.emit('test');
+    expect(results).toEqual([]);
+  });
+
+  test('emit on non-existent event is a no-op', () => {
+    const bus = createEventBus();
+    expect(() => bus.emit('nonexistent', {})).not.toThrow();
+  });
+
+  test('off on non-existent event is a no-op', () => {
+    const bus = createEventBus();
+    expect(() => bus.off('nonexistent', () => {})).not.toThrow();
+  });
+});