@yagejs/core 0.5.0 → 0.6.0

package/dist/index.cjs

@@ -110,6 +110,8 @@ __export(index_exports, {
   Sequence: () => Sequence,
   SerializableRegistry: () => SerializableRegistry,
   ServiceKey: () => ServiceKey,
+  StoreMigrationMissingError: () => StoreMigrationMissingError,
+  StoreVersionTooNewError: () => StoreVersionTooNewError,
   System: () => System,
   SystemScheduler: () => SystemScheduler,
   SystemSchedulerKey: () => SystemSchedulerKey,
@@ -119,16 +121,25 @@ __export(index_exports, {
   Tween: () => Tween,
   VERSION: () => VERSION,
   Vec2: () => Vec2,
+  _clearStoreRegistryForTesting: () => _clearStoreRegistryForTesting,
+  _resetAllStoresForTesting: () => _resetAllStoresForTesting,
   _resetEntityIdCounter: () => _resetEntityIdCounter,
   advanceFrames: () => advanceFrames,
+  createAtom: () => createAtom,
   createDefaultRandomSeed: () => createDefaultRandomSeed,
   createKeyframeTrack: () => createKeyframeTrack,
   createMockEntity: () => createMockEntity,
   createMockScene: () => createMockScene,
   createRandomService: () => createRandomService,
+  createStore: () => createStore,
   createTestEngine: () => createTestEngine,
+  dateCodec: () => dateCodec,
   defineBlueprint: () => defineBlueprint,
+  defineCounter: () => defineCounter,
   defineEvent: () => defineEvent,
+  defineMap: () => defineMap,
+  defineSet: () => defineSet,
+  defineStore: () => defineStore,
   defineTrait: () => defineTrait,
   easeInOutQuad: () => easeInOutQuad,
   easeInQuad: () => easeInQuad,
@@ -141,13 +152,16 @@ __export(index_exports, {
   interpolate: () => interpolate,
   isPointerConsumeContainer: () => isPointerConsumeContainer,
   isSerializable: () => isSerializable,
+  jsonCodec: () => jsonCodec,
   makeEntityScopedQueue: () => makeEntityScopedQueue,
   makeGlobalScopedQueue: () => makeGlobalScopedQueue,
   makeSceneScopedQueue: () => makeSceneScopedQueue,
+  mapCodec: () => mapCodec,
   markPointerConsumeContainer: () => markPointerConsumeContainer,
   normalizeSeed: () => normalizeSeed,
   resolveTransition: () => resolveTransition,
   serializable: () => serializable,
+  setCodec: () => setCodec,
   trait: () => trait,
   unmarkPointerConsumeContainer: () => unmarkPointerConsumeContainer
 });
@@ -1243,6 +1257,13 @@ var Entity = class {
   name;
   /** Tags for group queries. */
   tags;
+  /**
+   * Stable identity key, scene-scoped. Set at spawn-time when
+   * `options.key` is passed to `scene.spawn` / `entity.spawnChild`;
+   * `undefined` otherwise. Used with `scene.findByKey` and as a stable
+   * id in persistent stores (e.g. `defineSet<string>("world.opened")`).
+   */
+  key;
   components = /* @__PURE__ */ new Map();
   _destroyed = false;
   _scene = null;
@@ -1313,17 +1334,21 @@ var Entity = class {
       this._scene._addExistingEntity(child);
     }
   }
-  spawnChild(name, classOrBlueprint, params) {
+  spawnChild(name, classOrBlueprintOrOptions, paramsOrOptions, maybeOptions) {
     const scene = this.scene;
     if (this._children?.has(name)) {
       throw new Error(
         `Entity "${this.name}" already has a child named "${name}".`
       );
     }
-    const child = classOrBlueprint === void 0 ? scene.spawn(name) : scene.spawn(
-      classOrBlueprint,
-      params
-    );
+    let child;
+    if (classOrBlueprintOrOptions === void 0) {
+      child = scene.spawn(name);
+    } else if (typeof classOrBlueprintOrOptions === "object" && !("build" in classOrBlueprintOrOptions)) {
+      child = scene.spawn(name, classOrBlueprintOrOptions);
+    } else {
+      child = scene.spawn(classOrBlueprintOrOptions, paramsOrOptions, maybeOptions);
+    }
     this.addChild(name, child);
     return child;
   }
@@ -1466,6 +1491,19 @@ var Entity = class {
     }
     return false;
   }
+  /**
+   * Return the stable key, or throw if this entity was spawned without one.
+   * Use inside component `setup()` when the component depends on identity
+   * (e.g. reading from a `defineSet` keyed by entity id).
+   */
+  requireKey() {
+    if (this.key === void 0) {
+      throw new Error(
+        `Entity "${this.name}" (id=${this.id}) has no stable key. Pass { key: "..." } to scene.spawn(...) or entity.spawnChild(...).`
+      );
+    }
+    return this.key;
+  }
   /**
    * Internal: set the scene and callbacks. Called by Scene.spawn().
    * @internal
@@ -1474,6 +1512,20 @@ var Entity = class {
     this._scene = scene;
     this.callbacks = callbacks;
   }
+  /**
+   * Internal: assign the stable identity key. Called by `Scene._registerKey`
+   * during spawn. Throws if the entity already has a key — keys are
+   * immutable for an entity's lifetime.
+   * @internal
+   */
+  _setKey(key) {
+    if (this.key !== void 0) {
+      throw new Error(
+        `Entity "${this.name}" already has key "${this.key}".`
+      );
+    }
+    this.key = key;
+  }
 };
 
 // src/QueryCache.ts
@@ -2656,6 +2708,17 @@ function decodeBase64(base64) {
 __name(decodeBase64, "decodeBase64");
 
 // src/Scene.ts
+var _SPAWN_OPTION_KEYS = /* @__PURE__ */ new Set(["key"]);
+function _looksLikeSpawnOptions(v) {
+  if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
+  const keys = Object.keys(v);
+  if (keys.length === 0) return false;
+  for (const k of keys) {
+    if (!_SPAWN_OPTION_KEYS.has(k)) return false;
+  }
+  return true;
+}
+__name(_looksLikeSpawnOptions, "_looksLikeSpawnOptions");
 var Scene = class {
   static {
     __name(this, "Scene");
@@ -2681,6 +2744,7 @@ var Scene = class {
   _entityEventHandlers;
   _entityEventObserver;
   _scopedServices;
+  _identityIndex;
   /** Access the EngineContext. */
   get context() {
     return this._context;
@@ -2729,10 +2793,26 @@ var Scene = class {
       }, "set")
     });
   }
-  spawn(nameOrBlueprintOrClass, params) {
+  spawn(nameOrBlueprintOrClass, paramsOrOptions, maybeOptions) {
     if (typeof nameOrBlueprintOrClass === "function") {
-      const entity2 = new nameOrBlueprintOrClass();
+      const Ctor = nameOrBlueprintOrClass;
+      const hasSetup = typeof Ctor.prototype.setup === "function";
+      let params;
+      let options2;
+      if (maybeOptions !== void 0) {
+        params = paramsOrOptions;
+        options2 = maybeOptions;
+      } else if (paramsOrOptions === void 0) {
+      } else if (!hasSetup) {
+        options2 = paramsOrOptions;
+      } else if (_looksLikeSpawnOptions(paramsOrOptions)) {
+        options2 = paramsOrOptions;
+      } else {
+        params = paramsOrOptions;
+      }
+      const entity2 = new Ctor();
       entity2._setScene(this, this.entityCallbacks);
+      if (options2?.key !== void 0) this._registerKey(entity2, options2.key);
       this.entities.add(entity2);
       this.bus?.emit("entity:created", { entity: entity2 });
       entity2.setup?.(params);
@@ -2740,15 +2820,59 @@ var Scene = class {
     }
     const isBlueprint = typeof nameOrBlueprintOrClass === "object" && nameOrBlueprintOrClass !== null && "build" in nameOrBlueprintOrClass;
     const name = isBlueprint ? nameOrBlueprintOrClass.name : nameOrBlueprintOrClass;
+    let blueprintParams;
+    let options;
+    if (isBlueprint) {
+      if (maybeOptions !== void 0) {
+        blueprintParams = paramsOrOptions;
+        options = maybeOptions;
+      } else if (paramsOrOptions !== void 0 && _looksLikeSpawnOptions(paramsOrOptions)) {
+        options = paramsOrOptions;
+      } else {
+        blueprintParams = paramsOrOptions;
+      }
+    } else {
+      options = paramsOrOptions;
+    }
     const entity = new Entity(name);
     entity._setScene(this, this.entityCallbacks);
+    if (options?.key !== void 0) this._registerKey(entity, options.key);
     this.entities.add(entity);
     this.bus?.emit("entity:created", { entity });
     if (isBlueprint) {
-      nameOrBlueprintOrClass.build(entity, params);
+      nameOrBlueprintOrClass.build(
+        entity,
+        blueprintParams
+      );
     }
     return entity;
   }
+  /**
+   * Look up an entity by its stable identity key, scoped to this scene.
+   * Returns `undefined` for unknown or already-destroyed entities.
+   */
+  findByKey(key) {
+    const entity = this._identityIndex?.get(key);
+    if (!entity || entity.isDestroyed) return void 0;
+    return entity;
+  }
+  /**
+   * Internal: register a key on a freshly spawned entity. Throws on
+   * duplicate so callers (Scene.spawn) can abort before adding to
+   * `this.entities` or emitting `entity:created`.
+   * @internal
+   */
+  _registerKey(entity, key) {
+    this._identityIndex ??= /* @__PURE__ */ new Map();
+    const existing = this._identityIndex.get(key);
+    if (existing && !existing.isDestroyed) {
+      throw new Error(
+        `Scene "${this.name}" already has an entity with key "${key}". Destroy it before spawning a duplicate.`
+      );
+    }
+    entity._setKey(key);
+    this._identityIndex.set(key, entity);
+  }
   /**
    * Add an existing entity to this scene (used by Entity.addChild for auto-scene-membership).
    * @internal
@@ -2899,12 +3023,17 @@ var Scene = class {
       entity._performDestroy();
       this.queryCache?.onEntityDestroyed(entity);
       this.entities.delete(entity);
+      if (entity.key !== void 0 && this._identityIndex?.get(entity.key) === entity) {
+        this._identityIndex.delete(entity.key);
+      }
       this.bus?.emit("entity:destroyed", { entity });
     }
     this.destroyQueue.length = 0;
   }
   /**
-   * Destroy all entities — used during scene exit.
+   * Destroy all entities — used during scene exit. Clears the identity
+   * index in bulk; per-entity key removal in `_flushDestroyQueue` is the
+   * in-game path.
    * @internal
    */
   _destroyAllEntities() {
@@ -2915,6 +3044,7 @@ var Scene = class {
     this.entities.clear();
     this.destroyQueue.length = 0;
     this._entityEventHandlers?.clear();
+    this._identityIndex?.clear();
   }
 };
 
@@ -4578,6 +4708,387 @@ function advanceFrames(engine, n, dtMs = 1e3 / 60) {
 }
 __name(advanceFrames, "advanceFrames");
 
+// src/state/Atom.ts
+function createAtom(initial) {
+  let value = initial;
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    get() {
+      return value;
+    },
+    set(next) {
+      if (Object.is(value, next)) return;
+      value = next;
+      for (const fn of listeners) fn(value);
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    }
+  };
+}
+__name(createAtom, "createAtom");
+
+// src/state/Store.ts
+function createStore(initial) {
+  let snapshot = { ...initial };
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    get() {
+      return snapshot;
+    },
+    set(partial) {
+      let changed = false;
+      for (const key of Object.keys(partial)) {
+        if (!Object.is(snapshot[key], partial[key])) {
+          changed = true;
+          break;
+        }
+      }
+      if (!changed) return;
+      snapshot = { ...snapshot, ...partial };
+      for (const fn of listeners) fn();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    }
+  };
+}
+__name(createStore, "createStore");
+
+// src/state/codecs.ts
+function jsonCodec() {
+  return {
+    encode: /* @__PURE__ */ __name((value) => value, "encode"),
+    decode: /* @__PURE__ */ __name((raw) => raw, "decode")
+  };
+}
+__name(jsonCodec, "jsonCodec");
+function setCodec() {
+  return {
+    encode: /* @__PURE__ */ __name((value) => Array.from(value), "encode"),
+    decode: /* @__PURE__ */ __name((raw) => {
+      if (!Array.isArray(raw)) {
+        throw new Error("setCodec.decode: expected an array");
+      }
+      return new Set(raw);
+    }, "decode")
+  };
+}
+__name(setCodec, "setCodec");
+function mapCodec() {
+  return {
+    encode: /* @__PURE__ */ __name((value) => Array.from(value.entries()), "encode"),
+    decode: /* @__PURE__ */ __name((raw) => {
+      if (!Array.isArray(raw)) {
+        throw new Error("mapCodec.decode: expected an array of entries");
+      }
+      return new Map(raw);
+    }, "decode")
+  };
+}
+__name(mapCodec, "mapCodec");
+function dateCodec() {
+  return {
+    encode: /* @__PURE__ */ __name((value) => value.toISOString(), "encode"),
+    decode: /* @__PURE__ */ __name((raw) => {
+      if (typeof raw !== "string") {
+        throw new Error("dateCodec.decode: expected an ISO string");
+      }
+      const d = new Date(raw);
+      if (Number.isNaN(d.getTime())) {
+        throw new Error(`dateCodec.decode: invalid ISO string ${JSON.stringify(raw)}`);
+      }
+      return d;
+    }, "decode")
+  };
+}
+__name(dateCodec, "dateCodec");
+
+// src/state/persistent.ts
+var registry3 = /* @__PURE__ */ new Map();
+function register(entry) {
+  registry3.set(entry.id, entry);
+}
+__name(register, "register");
+function _resetAllStoresForTesting() {
+  for (const entry of registry3.values()) entry.reset();
+}
+__name(_resetAllStoresForTesting, "_resetAllStoresForTesting");
+function _clearStoreRegistryForTesting() {
+  registry3.clear();
+}
+__name(_clearStoreRegistryForTesting, "_clearStoreRegistryForTesting");
+var StoreVersionTooNewError = class extends Error {
+  static {
+    __name(this, "StoreVersionTooNewError");
+  }
+  storeId;
+  storedVersion;
+  currentVersion;
+  constructor(storeId, storedVersion, currentVersion) {
+    super(
+      `Store "${storeId}" was saved at version ${storedVersion}, but this build is at version ${currentVersion}. Cannot downgrade.`
+    );
+    this.name = "StoreVersionTooNewError";
+    this.storeId = storeId;
+    this.storedVersion = storedVersion;
+    this.currentVersion = currentVersion;
+  }
+};
+var StoreMigrationMissingError = class extends Error {
+  static {
+    __name(this, "StoreMigrationMissingError");
+  }
+  storeId;
+  storedVersion;
+  currentVersion;
+  constructor(storeId, storedVersion, currentVersion) {
+    super(
+      `Store "${storeId}" needs migration from version ${storedVersion} to ${currentVersion}, but no migrate() was provided.`
+    );
+    this.name = "StoreMigrationMissingError";
+    this.storeId = storeId;
+    this.storedVersion = storedVersion;
+    this.currentVersion = currentVersion;
+  }
+};
+function defineStore(id, opts) {
+  const version = opts.version ?? 1;
+  const codec = opts.codec ?? jsonCodec();
+  const defaults = opts.defaults;
+  const inner = createStore(defaults());
+  const replaceAll = /* @__PURE__ */ __name((next) => {
+    inner.set({ ...next });
+  }, "replaceAll");
+  const store = {
+    id,
+    version,
+    get: inner.get,
+    set: inner.set,
+    subscribe: inner.subscribe,
+    reset() {
+      replaceAll(defaults());
+    },
+    serialize() {
+      return { version, data: codec.encode(inner.get()) };
+    },
+    hydrate(payload) {
+      if (payload.version > version) {
+        throw new StoreVersionTooNewError(id, payload.version, version);
+      }
+      let next;
+      if (payload.version < version) {
+        if (!opts.migrate) {
+          throw new StoreMigrationMissingError(id, payload.version, version);
+        }
+        next = opts.migrate(payload.data, payload.version);
+      } else {
+        next = codec.decode(payload.data);
+      }
+      replaceAll(next);
+    }
+  };
+  register({ id, reset: /* @__PURE__ */ __name(() => store.reset(), "reset") });
+  return store;
+}
+__name(defineStore, "defineStore");
+function defineSet(id, opts) {
+  const version = opts?.version ?? 1;
+  const defaults = /* @__PURE__ */ __name(() => new Set(opts?.defaults?.() ?? []), "defaults");
+  const codec = setCodec();
+  const atom = createAtom(defaults());
+  const replace = /* @__PURE__ */ __name((next) => {
+    atom.set(next);
+  }, "replace");
+  const store = {
+    id,
+    version,
+    has(key) {
+      return atom.get().has(key);
+    },
+    add(key) {
+      const current = atom.get();
+      if (current.has(key)) return;
+      const next = new Set(current);
+      next.add(key);
+      replace(next);
+    },
+    remove(key) {
+      const current = atom.get();
+      if (!current.has(key)) return;
+      const next = new Set(current);
+      next.delete(key);
+      replace(next);
+    },
+    clear() {
+      if (atom.get().size === 0) return;
+      replace(/* @__PURE__ */ new Set());
+    },
+    size() {
+      return atom.get().size;
+    },
+    values() {
+      return atom.get().values();
+    },
+    subscribe(listener) {
+      return atom.subscribe(() => listener());
+    },
+    reset() {
+      replace(defaults());
+    },
+    serialize() {
+      return { version, data: codec.encode(atom.get()) };
+    },
+    hydrate(payload) {
+      if (payload.version > version) {
+        throw new StoreVersionTooNewError(id, payload.version, version);
+      }
+      if (payload.version < version) {
+        if (!opts?.migrate) {
+          throw new StoreMigrationMissingError(id, payload.version, version);
+        }
+        replace(opts.migrate(payload.data, payload.version));
+        return;
+      }
+      replace(codec.decode(payload.data));
+    }
+  };
+  register({ id, reset: /* @__PURE__ */ __name(() => store.reset(), "reset") });
+  return store;
+}
+__name(defineSet, "defineSet");
+function defineMap(id, opts) {
+  const version = opts?.version ?? 1;
+  const defaults = /* @__PURE__ */ __name(() => new Map(opts?.defaults?.() ?? []), "defaults");
+  const codec = mapCodec();
+  const atom = createAtom(defaults());
+  const replace = /* @__PURE__ */ __name((next) => {
+    atom.set(next);
+  }, "replace");
+  const store = {
+    id,
+    version,
+    has(key) {
+      return atom.get().has(key);
+    },
+    get(key) {
+      return atom.get().get(key);
+    },
+    set(key, value) {
+      const current = atom.get();
+      if (current.has(key) && Object.is(current.get(key), value)) return;
+      const next = new Map(current);
+      next.set(key, value);
+      replace(next);
+    },
+    remove(key) {
+      const current = atom.get();
+      if (!current.has(key)) return;
+      const next = new Map(current);
+      next.delete(key);
+      replace(next);
+    },
+    clear() {
+      if (atom.get().size === 0) return;
+      replace(/* @__PURE__ */ new Map());
+    },
+    size() {
+      return atom.get().size;
+    },
+    entries() {
+      return atom.get().entries();
+    },
+    subscribe(listener) {
+      return atom.subscribe(() => listener());
+    },
+    reset() {
+      replace(defaults());
+    },
+    serialize() {
+      return { version, data: codec.encode(atom.get()) };
+    },
+    hydrate(payload) {
+      if (payload.version > version) {
+        throw new StoreVersionTooNewError(id, payload.version, version);
+      }
+      if (payload.version < version) {
+        if (!opts?.migrate) {
+          throw new StoreMigrationMissingError(id, payload.version, version);
+        }
+        replace(opts.migrate(payload.data, payload.version));
+        return;
+      }
+      replace(codec.decode(payload.data));
+    }
+  };
+  register({ id, reset: /* @__PURE__ */ __name(() => store.reset(), "reset") });
+  return store;
+}
+__name(defineMap, "defineMap");
+function defineCounter(id, opts) {
+  const version = opts?.version ?? 1;
+  const defaults = /* @__PURE__ */ __name(() => opts?.defaults?.() ?? 0, "defaults");
+  const atom = createAtom(defaults());
+  const store = {
+    id,
+    version,
+    value() {
+      return atom.get();
+    },
+    set(n) {
+      atom.set(n);
+    },
+    increment(by = 1) {
+      atom.set(atom.get() + by);
+    },
+    decrement(by = 1) {
+      atom.set(atom.get() - by);
+    },
+    subscribe(listener) {
+      return atom.subscribe(() => listener());
+    },
+    reset() {
+      atom.set(defaults());
+    },
+    serialize() {
+      return { version, data: atom.get() };
+    },
+    hydrate(payload) {
+      if (payload.version > version) {
+        throw new StoreVersionTooNewError(id, payload.version, version);
+      }
+      if (payload.version < version) {
+        if (!opts?.migrate) {
+          throw new StoreMigrationMissingError(id, payload.version, version);
+        }
+        const migrated = opts.migrate(payload.data, payload.version);
+        if (typeof migrated !== "number") {
+          throw new Error(
+            `defineCounter "${id}".hydrate: migrate returned non-number ${typeof migrated}`
+          );
+        }
+        atom.set(migrated);
+        return;
+      }
+      if (typeof payload.data !== "number") {
+        throw new Error(
+          `defineCounter "${id}".hydrate: expected number, got ${typeof payload.data}`
+        );
+      }
+      atom.set(payload.data);
+    }
+  };
+  register({ id, reset: /* @__PURE__ */ __name(() => store.reset(), "reset") });
+  return store;
+}
+__name(defineCounter, "defineCounter");
+
 // src/index.ts
 var VERSION = "0.0.0";
 // Annotate the CommonJS export names for ESM import in node:
@@ -4627,6 +5138,8 @@ var VERSION = "0.0.0";
   Sequence,
   SerializableRegistry,
   ServiceKey,
+  StoreMigrationMissingError,
+  StoreVersionTooNewError,
   System,
   SystemScheduler,
   SystemSchedulerKey,
@@ -4636,16 +5149,25 @@ var VERSION = "0.0.0";
   Tween,
   VERSION,
   Vec2,
+  _clearStoreRegistryForTesting,
+  _resetAllStoresForTesting,
   _resetEntityIdCounter,
   advanceFrames,
+  createAtom,
   createDefaultRandomSeed,
   createKeyframeTrack,
   createMockEntity,
   createMockScene,
   createRandomService,
+  createStore,
   createTestEngine,
+  dateCodec,
   defineBlueprint,
+  defineCounter,
   defineEvent,
+  defineMap,
+  defineSet,
+  defineStore,
   defineTrait,
   easeInOutQuad,
   easeInQuad,
@@ -4658,13 +5180,16 @@ var VERSION = "0.0.0";
   interpolate,
   isPointerConsumeContainer,
   isSerializable,
+  jsonCodec,
   makeEntityScopedQueue,
   makeGlobalScopedQueue,
   makeSceneScopedQueue,
+  mapCodec,
   markPointerConsumeContainer,
   normalizeSeed,
   resolveTransition,
   serializable,
+  setCodec,
   trait,
   unmarkPointerConsumeContainer
 });