@yagejs/core 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -195,6 +195,13 @@ declare class Entity {
     readonly name: string;
     /** Tags for group queries. */
     readonly tags: Set<string>;
+    /**
+     * 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")`).
+     */
+    readonly key?: string;
     private components;
     private _destroyed;
     private _scene;
@@ -240,13 +247,13 @@ declare class Entity {
      * this.spawnChild("hp", EnemyHealthBar);
      * ```
      */
-    spawnChild(name: string): Entity;
-    spawnChild<E extends Entity>(name: string, Class: new () => E): E;
+    spawnChild(name: string, options?: SpawnOptions): Entity;
+    spawnChild<E extends Entity>(name: string, Class: new () => E, options?: SpawnOptions): E;
     spawnChild<E extends Entity, P>(name: string, Class: new () => E & {
         setup(params: P): void;
-    }, params: P): E;
-    spawnChild<P>(name: string, blueprint: Blueprint<P>, params: P): Entity;
-    spawnChild(name: string, blueprint: Blueprint<void>): Entity;
+    }, params: P, options?: SpawnOptions): E;
+    spawnChild<P>(name: string, blueprint: Blueprint<P>, params: P, options?: SpawnOptions): Entity;
+    spawnChild(name: string, blueprint: Blueprint<void>, options?: SpawnOptions): Entity;
     /** Remove a named child. Returns the detached entity. */
     removeChild(name: string): Entity;
     /** Get a child by name. Throws if not found. */
@@ -290,11 +297,24 @@ declare class Entity {
     afterRestore?(data: unknown, resolve: SnapshotResolver): void;
     /** Check if this entity's class implements a given trait. Acts as a type guard. */
     hasTrait<T>(token: TraitToken<T>): this is this & T;
+    /**
+     * 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(): string;
     /**
      * Internal: set the scene and callbacks. Called by Scene.spawn().
      * @internal
      */
     _setScene(scene: Scene | null, callbacks: EntityCallbacks | null): void;
+    /**
+     * 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: string): void;
 }
 
 /** Filter criteria for entity queries. All fields are AND'd together. */
@@ -311,6 +331,28 @@ interface EntityFilter {
 /** Apply a filter to an iterable of entities. Skips destroyed entities. */
 declare function filterEntities(entities: Iterable<Entity>, filter: EntityFilter): Entity[];
 
+/**
+ * Options accepted by the trailing argument of `Scene.spawn` and
+ * `Entity.spawnChild`.
+ */
+interface SpawnOptions {
+    /**
+     * Stable per-scene identity key. Looked up via `Scene.findByKey` and used
+     * as a stable id in persistent stores (e.g. `defineSet<string>("world.opened")`).
+     *
+     * Identity is opt-in — most entities (bullets, particles, transient enemies)
+     * never need a key. Pass one only for entities whose state should persist
+     * across save/load or cross-scene navigation, or that game code looks up
+     * by name (chests, doors, named NPCs).
+     *
+     * Heads-up: don't name a top-level setup-params field `key`. The 2-arg
+     * `spawn(Class, X)` form looks at `X`'s shape to disambiguate params from
+     * options — an `X` whose only own keys are SpawnOptions fields routes
+     * to options. If your params shape clashes (e.g. `setup(p: { key: number })`),
+     * use the explicit 3-arg form `spawn(Class, params, options)`.
+     */
+    key?: string;
+}
 /**
  * Scenes own entities and define lifecycle hooks.
  * Each scene is a self-contained world with its own entity pool.
@@ -339,6 +381,7 @@ declare abstract class Scene {
     private _entityEventHandlers?;
     private _entityEventObserver?;
     private _scopedServices?;
+    private _identityIndex?;
     /** Access the EngineContext. */
     get context(): EngineContext;
     /** Whether this scene is effectively paused (manual pause or paused by stack). */
@@ -355,16 +398,51 @@ declare abstract class Scene {
      * The actual resolution is deferred until first property access.
      */
     protected service<T extends object>(key: ServiceKey<T>): T;
-    /** Spawn a new entity in this scene. */
-    spawn(name?: string): Entity;
-    spawn<P>(blueprint: Blueprint<P>, params: P): Entity;
-    spawn(blueprint: Blueprint<void>): Entity;
+    /**
+     * Spawn a new entity in this scene.
+     *
+     * Pass `{ key }` in the trailing options to register a stable per-scene
+     * identity key, looked up later via `scene.findByKey`. The key is assigned
+     * before `setup()` runs, so `entity.requireKey()` is safe inside it.
+     *
+     * Runtime routing for the 2-arg class form (`spawn(Class, X)`):
+     *   - If the class doesn't declare `setup` → `X` is options.
+     *   - Else if `X`'s own keys are exactly SpawnOptions fields (`{ key }`) →
+     *     `X` is options. Covers both `setup(params = {})` keyed without
+     *     params and `setup()` (no real params) keyed.
+     *   - Else → `X` is params (forwarded to `setup`).
+     * The 3-arg form is always unambiguous: `spawn(Class, params, options)`.
+     *
+     * Don't name a top-level setup-params field `key` — the shape check would
+     * misroute it. If you must, use the 3-arg form.
+     */
+    spawn(name?: string, options?: SpawnOptions): Entity;
+    /**
+     * Spawn from a blueprint. **Note**: blueprint params must not include a
+     * top-level `key: string` field — the runtime can't disambiguate it from
+     * `SpawnOptions`. If your params do, use the explicit 3-arg form
+     * (`spawn(bp, params, { key })`) so options arrives in the trailing slot.
+     */
+    spawn<P>(blueprint: Blueprint<P>, params: P, options?: SpawnOptions): Entity;
+    spawn(blueprint: Blueprint<void>, options?: SpawnOptions): Entity;
     /** Spawn an entity subclass with setup params. */
     spawn<E extends Entity, P>(Class: new () => E & {
         setup(params: P): void;
-    }, params: P): E;
+    }, params: P, options?: SpawnOptions): E;
     /** Spawn an entity subclass without setup params. */
-    spawn<E extends Entity>(Class: new () => E): E;
+    spawn<E extends Entity>(Class: new () => E, options?: SpawnOptions): E;
+    /**
+     * Look up an entity by its stable identity key, scoped to this scene.
+     * Returns `undefined` for unknown or already-destroyed entities.
+     */
+    findByKey<E extends Entity = Entity>(key: string): E | undefined;
+    /**
+     * 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: Entity, key: string): void;
     /**
      * Add an existing entity to this scene (used by Entity.addChild for auto-scene-membership).
      * @internal
@@ -450,7 +528,9 @@ declare abstract class Scene {
      */
     _flushDestroyQueue(): void;
     /**
-     * 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(): void;
@@ -2364,6 +2444,178 @@ declare function createMockEntity(name?: string): {
 /** Advance the game loop by N frames (manual tick). */
 declare function advanceFrames(engine: Engine, n: number, dtMs?: number): void;
 
+/**
+ * Atom — minimal reactive cell.
+ *
+ * Signal-shaped: `get`, `set`, `subscribe`. Identity-based change detection
+ * (`Object.is`); subscribers are notified only when the value actually changes.
+ */
+interface Atom<T> {
+    get(): T;
+    set(next: T): void;
+    subscribe(listener: (value: T) => void): () => void;
+}
+declare function createAtom<T>(initial: T): Atom<T>;
+
+/**
+ * Store — object-shaped reactive store with shallow merge.
+ *
+ * `get()` returns a `Readonly<T>` whose reference is stable between sets.
+ * `set(partial)` merges keys via spread and notifies only when at least one key
+ * changed (Object.is per key). Mutation through the snapshot bypasses
+ * subscribers — TypeScript's `Readonly<T>` enforces the contract; do not reach
+ * into nested objects to mutate them, use `set` instead.
+ */
+interface Store<T extends object> {
+    get(): Readonly<T>;
+    set(partial: Partial<T>): void;
+    subscribe(listener: () => void): () => void;
+}
+declare function createStore<T extends object>(initial: T): Store<T>;
+
+/**
+ * A codec converts a value between its in-memory representation and a JSON-safe
+ * representation that adapters can stringify. Codecs are pure functions; they
+ * don't read or write storage.
+ */
+interface Codec<T> {
+    encode(value: T): unknown;
+    decode(raw: unknown): T;
+}
+/** Identity codec — pass-through for plain JSON-serializable values. */
+declare function jsonCodec<T>(): Codec<T>;
+/** Set ↔ array. */
+declare function setCodec<K>(): Codec<Set<K>>;
+/** Map ↔ entries array. */
+declare function mapCodec<K, V>(): Codec<Map<K, V>>;
+/** Date ↔ ISO string. */
+declare function dateCodec(): Codec<Date>;
+
+/**
+ * Common persistence shape implemented by every defineX output. The save layer
+ * accepts anything matching this structural type — stores don't depend on the
+ * save layer.
+ */
+interface PersistentLike {
+    readonly id: string;
+    readonly version: number;
+    serialize(): {
+        version: number;
+        data: unknown;
+    };
+    hydrate(payload: {
+        version: number;
+        data: unknown;
+    }): void;
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * Reset every persistent store created by defineStore / defineSet / defineMap /
+ * defineCounter back to its defaults. Test-only.
+ *
+ * @internal
+ */
+declare function _resetAllStoresForTesting(): void;
+/**
+ * Drop every persistent store from the internal registry. Use only when you
+ * intend to redefine stores with the same ids (e.g. between test files that
+ * share a module namespace via Vitest's module cache).
+ *
+ * @internal
+ */
+declare function _clearStoreRegistryForTesting(): void;
+interface DefineStoreOptions<T> {
+    /** Schema version. Defaults to 1. Bump when shape changes; provide `migrate`. */
+    version?: number;
+    /** Factory producing the default value. Called on creation and on `reset()`. */
+    defaults: () => T;
+    /** Codec for `T`. Defaults to identity (jsonCodec). */
+    codec?: Codec<T>;
+    /**
+     * Migrate previously-stored data to the current version. Receives the raw
+     * decoded payload and the version it was written at. Called when
+     * `payload.version < version` during `hydrate`.
+     */
+    migrate?: (old: unknown, fromVersion: number) => T;
+}
+interface PersistentStore<T extends object> extends Store<T>, PersistentLike {
+    reset(): void;
+}
+/** Thrown by `hydrate` when stored data is from a newer version than this build. */
+declare class StoreVersionTooNewError extends Error {
+    readonly storeId: string;
+    readonly storedVersion: number;
+    readonly currentVersion: number;
+    constructor(storeId: string, storedVersion: number, currentVersion: number);
+}
+/** Thrown by `hydrate` when stored data is older than the current version and no `migrate` is configured. */
+declare class StoreMigrationMissingError extends Error {
+    readonly storeId: string;
+    readonly storedVersion: number;
+    readonly currentVersion: number;
+    constructor(storeId: string, storedVersion: number, currentVersion: number);
+}
+declare function defineStore<T extends object>(id: string, opts: DefineStoreOptions<T>): PersistentStore<T>;
+interface PersistentSet<K> extends PersistentLike {
+    has(key: K): boolean;
+    add(key: K): void;
+    remove(key: K): void;
+    clear(): void;
+    size(): number;
+    values(): IterableIterator<K>;
+    reset(): void;
+}
+interface DefineSetOptions<K> {
+    version?: number;
+    defaults?: () => Iterable<K>;
+    /**
+     * Migrate older stored data to the current version. Receives the raw decoded
+     * payload (a `K[]` from setCodec) and the version it was written at. Required
+     * when bumping `version`; otherwise older payloads throw at hydrate.
+     */
+    migrate?: (old: unknown, fromVersion: number) => Set<K>;
+}
+declare function defineSet<K>(id: string, opts?: DefineSetOptions<K>): PersistentSet<K>;
+interface PersistentMap<K, V> extends PersistentLike {
+    has(key: K): boolean;
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    remove(key: K): void;
+    clear(): void;
+    size(): number;
+    entries(): IterableIterator<[K, V]>;
+    reset(): void;
+}
+interface DefineMapOptions<K, V> {
+    version?: number;
+    defaults?: () => Iterable<[K, V]>;
+    /**
+     * Migrate older stored data to the current version. Receives the raw decoded
+     * payload (a `[K, V][]` from mapCodec) and the version it was written at.
+     * Required when bumping `version`; otherwise older payloads throw at hydrate.
+     */
+    migrate?: (old: unknown, fromVersion: number) => Map<K, V>;
+}
+declare function defineMap<K, V>(id: string, opts?: DefineMapOptions<K, V>): PersistentMap<K, V>;
+interface PersistentCounter extends PersistentLike {
+    value(): number;
+    set(n: number): void;
+    increment(by?: number): void;
+    decrement(by?: number): void;
+    reset(): void;
+}
+interface DefineCounterOptions {
+    version?: number;
+    defaults?: () => number;
+    /**
+     * Migrate older stored data to the current version. Receives the raw decoded
+     * payload (a number) and the version it was written at. Required when
+     * bumping `version`; otherwise older payloads throw at hydrate.
+     */
+    migrate?: (old: unknown, fromVersion: number) => number;
+}
+declare function defineCounter(id: string, opts?: DefineCounterOptions): PersistentCounter;
+
 declare const VERSION = "0.0.0";
 
-export { AssetHandle, type AssetLoader, AssetManager, AssetManagerKey, type Blueprint, type CameraSnapshot, Component, type ComponentClass, ComponentFixedUpdateSystem, type ComponentStateSnapshot, ComponentUpdateSystem, type EasingFunction, Engine, type EngineConfig, EngineContext, type EngineEvents, EngineKey, type EngineSnapshot, Entity, type EntityCallbacks, type EntityFilter, type EntitySnapshot, ErrorBoundary, ErrorBoundaryKey, type ErrorSnapshot, EventBus, EventBusKey, type EventLogEntry, type EventMap, EventToken, GameLoop, type GameLoopCallbacks, type GameLoopConfig, GameLoopKey, type InputStateSnapshot, Inspector, InspectorKey, type InspectorTimeController, type Interpolatable, type Keyframe, type KeyframeAnimationDef, KeyframeAnimator, type KeyframeTrackOptions, LoadingScene, type LogEntry, LogLevel, Logger, type LoggerConfig, LoggerKey, MathUtils, Phase, type PhysicsSnapshot, type Plugin, type PointerSnapshot, Process, ProcessComponent, type ProcessOptions, ProcessSlot, type ProcessSlotConfig, ProcessSystem, ProcessSystemKey, QueryCache, QueryCacheKey, QueryResult, RandomKey, type RandomService, type RendererAdapter, RendererAdapterKey, SERIALIZABLE_KEY, Scene, SceneHookRegistry, SceneHookRegistryKey, type SceneHooks, SceneManager, SceneManagerKey, type SceneSnapshot, type SceneTransition, type SceneTransitionContext, type SceneTransitionKind, type SceneTransitionOptions, type ScopedProcessQueue, Sequence, SerializableRegistry, ServiceKey, type ServiceKeyOptions, type ServiceScope, type SmoothDampResult, type SnapshotResolver, System, SystemScheduler, SystemSchedulerKey, type SystemSnapshot, TimerEntity, TraitToken, Transform, type TransformData, Tween, type UINodeSnapshot, type UITreeSnapshot, VERSION, Vec2, type Vec2Like, type WorldEntitySnapshot, type WorldSceneSnapshot, _resetEntityIdCounter, advanceFrames, createDefaultRandomSeed, createKeyframeTrack, createMockEntity, createMockScene, createRandomService, createTestEngine, defineBlueprint, defineEvent, defineTrait, easeInOutQuad, easeInQuad, easeLinear, easeOutBounce, easeOutQuad, filterEntities, getSerializableType, globalRandom, interpolate, isPointerConsumeContainer, isSerializable, makeEntityScopedQueue, makeGlobalScopedQueue, makeSceneScopedQueue, markPointerConsumeContainer, normalizeSeed, resolveTransition, serializable, trait, unmarkPointerConsumeContainer };
+export { AssetHandle, type AssetLoader, AssetManager, AssetManagerKey, type Atom, type Blueprint, type CameraSnapshot, type Codec, Component, type ComponentClass, ComponentFixedUpdateSystem, type ComponentStateSnapshot, ComponentUpdateSystem, type DefineCounterOptions, type DefineMapOptions, type DefineSetOptions, type DefineStoreOptions, type EasingFunction, Engine, type EngineConfig, EngineContext, type EngineEvents, EngineKey, type EngineSnapshot, Entity, type EntityCallbacks, type EntityFilter, type EntitySnapshot, ErrorBoundary, ErrorBoundaryKey, type ErrorSnapshot, EventBus, EventBusKey, type EventLogEntry, type EventMap, EventToken, GameLoop, type GameLoopCallbacks, type GameLoopConfig, GameLoopKey, type InputStateSnapshot, Inspector, InspectorKey, type InspectorTimeController, type Interpolatable, type Keyframe, type KeyframeAnimationDef, KeyframeAnimator, type KeyframeTrackOptions, LoadingScene, type LogEntry, LogLevel, Logger, type LoggerConfig, LoggerKey, MathUtils, type PersistentCounter, type PersistentLike, type PersistentMap, type PersistentSet, type PersistentStore, Phase, type PhysicsSnapshot, type Plugin, type PointerSnapshot, Process, ProcessComponent, type ProcessOptions, ProcessSlot, type ProcessSlotConfig, ProcessSystem, ProcessSystemKey, QueryCache, QueryCacheKey, QueryResult, RandomKey, type RandomService, type RendererAdapter, RendererAdapterKey, SERIALIZABLE_KEY, Scene, SceneHookRegistry, SceneHookRegistryKey, type SceneHooks, SceneManager, SceneManagerKey, type SceneSnapshot, type SceneTransition, type SceneTransitionContext, type SceneTransitionKind, type SceneTransitionOptions, type ScopedProcessQueue, Sequence, SerializableRegistry, ServiceKey, type ServiceKeyOptions, type ServiceScope, type SmoothDampResult, type SnapshotResolver, type SpawnOptions, type Store, StoreMigrationMissingError, StoreVersionTooNewError, System, SystemScheduler, SystemSchedulerKey, type SystemSnapshot, TimerEntity, TraitToken, Transform, type TransformData, Tween, type UINodeSnapshot, type UITreeSnapshot, VERSION, Vec2, type Vec2Like, type WorldEntitySnapshot, type WorldSceneSnapshot, _clearStoreRegistryForTesting, _resetAllStoresForTesting, _resetEntityIdCounter, advanceFrames, createAtom, createDefaultRandomSeed, createKeyframeTrack, createMockEntity, createMockScene, createRandomService, createStore, createTestEngine, dateCodec, defineBlueprint, defineCounter, defineEvent, defineMap, defineSet, defineStore, defineTrait, easeInOutQuad, easeInQuad, easeLinear, easeOutBounce, easeOutQuad, filterEntities, getSerializableType, globalRandom, interpolate, isPointerConsumeContainer, isSerializable, jsonCodec, makeEntityScopedQueue, makeGlobalScopedQueue, makeSceneScopedQueue, mapCodec, markPointerConsumeContainer, normalizeSeed, resolveTransition, serializable, setCodec, trait, unmarkPointerConsumeContainer };