@daneren2005/shared-memory-ecs 1.0.1 → 1.1.0

package/README.md

@@ -9,14 +9,21 @@ fog of war, sub-classed entities, required components, etc).
 
 - **Component** – a plain object with an `index` (its block inside a shared-memory pool) plus getters/
   setters over that memory. Games decide what components exist.
-- **`ComponentDefinition`** – describes a component: its typed array `type`, block `size`, a `load(entity, memory, config)`
-  and an optional `save(component)`.
+- **`ComponentDefinition`** – describes a component: its typed array `type`, block `size`, the config keys
+  that trigger loading (`loadProperties`), a `load(entity, memory, config)` and an optional `save(component)`.
+  A component's data splits into `Config` (defining props supplied up front, e.g. `maxHealth`) and
+  `Serialization` (runtime-derived state, e.g. current `health`); `load` sees `Config & Serialization` while
+  `save` returns only the `Serialization` slice.
 - **`ComponentRegistry<C>`** – the map of all component definitions for a game.
-- **`BaseWorld<C>`** – builds one `MemoryComponent` per registered component and runs systems. It is
-  generic over your component map `C`, so `world.components`, `entity.components`, `setComponent`, etc.
-  are fully typed.
+- **`EntityFactory<C>`** – maps an entity `type` name to a base (template) config. Loading an entity layers
+  the caller's config over its type's template, so shared static data lives in one place and a save only
+  needs the `type` plus the entity's serialization. `BaseWorld#loadEntity` always goes through the factory.
+- **`BaseWorld<C>`** – builds one `MemoryComponent` per registered component (attached to that component's
+  definition as `world.registry[name].memoryComponent`) and runs systems. It is generic over your component
+  map `C`, so `world.registry`, `entity.components`, `setComponent`, etc. are fully typed.
 - **`BaseEntity<C>`** – an `eid`, an optional `id`, and a bag of memory-backed components. It has no
-  direct property accessors and only loads/saves component data.
+  direct property accessors and only loads/saves component data. Every entity has an `entity` component
+  whose `type` (a plain, worker-invisible string) records the factory template it was built from.
 - **Systems** – `System`, `IterableSystem`, `EntitySystem` (main-thread iteration over entities with a
   given set of components) and `ComponentSystem` (runs an update function over raw memory blocks,
   off-thread when Web Workers + `SharedArrayBuffer` are available).
@@ -35,10 +42,15 @@ interface HealthComponent {
 const HEALTH_INDEX = 0;
 const HEALTH_MAX_INDEX = 1;
 
-const healthDefinition: ComponentDefinition<HealthComponent, Int32Array> = {
+// `maxHealth` is the defining Config prop; `health` is optional, runtime-derived Serialization.  `load`
+// and `save` both see the combined `{ maxHealth: number, health?: number }`.
+const healthDefinition: ComponentDefinition<HealthComponent, Int32Array, { maxHealth: number }, { health?: number }> = {
 	type: Int32Array,
 	size: 2,
-	load(entity, memoryComponent, config: { health?: number, maxHealth: number }) {
+	// Configs are flat and shared: this component loads whenever `maxHealth` is present, then reads what it
+	// needs off the same config object.  Only Config props may appear here.
+	loadProperties: ['maxHealth'],
+	load(entity, memoryComponent, config) {
 		const index = memoryComponent.create([config.health ?? config.maxHealth, config.maxHealth]);
 		const memory = memoryComponent.getBlock(index);
 
@@ -50,7 +62,8 @@ const healthDefinition: ComponentDefinition<HealthComponent, Int32Array> = {
 		};
 	},
 	save(component) {
-		return { maxHealth: component.maxHealth, health: component.health };
+		// save returns only Serialization; maxHealth is Config and comes back from the template on reload.
+		return { health: component.health };
 	}
 };
 
@@ -69,19 +82,54 @@ import { BaseWorld } from '@daneren2005/shared-memory-ecs';
 
 const world = new BaseWorld<Components>(registry);
 
-const entity = world.loadEntity({ health: { maxHealth: 100 } });
+const entity = world.loadEntity({ maxHealth: 100 });
 entity.components.health!.health -= 10;
 
-console.log(entity.save()); // { health: { maxHealth: 100, health: 90 } }
+console.log(entity.save()); // { health: 90 }
+```
+
+### Entity types via the factory
+
+Register per-type base configs, then load entities by `type`.  The template supplies the defining config, so
+only the `type` and runtime serialization need to be saved:
+
+```ts
+import { BaseWorld, EntityFactory } from '@daneren2005/shared-memory-ecs';
+
+const factory = new EntityFactory<Components>({
+	goblin: { maxHealth: 20 },
+});
+const world = new BaseWorld<Components>(registry, { factory });
+
+const goblin = world.loadEntity({ type: 'goblin', health: 10 });
+console.log(goblin.components.health!.maxHealth); // 20 (from the template)
+console.log(goblin.save()); // { type: 'goblin', health: 10 } - no templated maxHealth
+
+// A save re-expands back through the factory:
+world.loadEntity(goblin.save());
 ```
 
 ## ComponentSystem workers
 
 `ComponentSystem` needs a `getWorker()` that returns a real `Worker`, and an `updateFunction`. Your
-worker entry file calls `createComponentWorker(updateFunction)`. When Web Workers or
+worker entry file calls `createComponentWorker(self, updateFunction)`. When Web Workers or
 `SharedArrayBuffer` are unavailable it transparently falls back to running the same update function on
 the main thread. Attach any extra per-run data (the equivalent of the old faction/fog-of-war fields)
-by overriding `addDataToWorld(world)`.
+by overriding `addDataToWorld(world)`. Declare its shape with the `W` type parameter (an interface
+extending `ComponentSystemWorld`) so both `addDataToWorld` and the `updateFunction` see it typed:
+
+```ts
+interface DamageWorld extends ComponentSystemWorld {
+	damage: number
+}
+
+const damageUpdate: EntityUpdateFunction<Components, { health: Int32Array }, DamageWorld> =
+	(world, entityId, components) => { components.health[0] -= world.damage; };
+
+class DamageSystem extends ComponentSystem<Components, { health: Int32Array }, DamageWorld> {
+	addDataToWorld(world: DamageWorld) { world.damage = 5; }
+}
+```
 
 ## Building
 

package/dist/actions/create-entity-worker.d.ts

@@ -0,0 +1,2 @@
+import type { ComponentSystemCallbacks, CreateEntityConfig } from '../systems/component-system';
+export default function createEntityWorker(config: CreateEntityConfig, callbacks: ComponentSystemCallbacks): void;

package/dist/actions/kill-entity-worker.d.ts

@@ -0,0 +1,2 @@
+import type { ComponentSystemCallbacks, EntityUpdateComponents } from '../systems/component-system';
+export default function killEntityWorker(entityId: number, components: EntityUpdateComponents, callbacks: ComponentSystemCallbacks): void;

package/dist/actions/kill-entity.d.ts

@@ -0,0 +1,2 @@
+import type BaseEntity from '../entity';
+export default function killEntity(entity: BaseEntity): void;

package/dist/component-definition.d.ts

@@ -0,0 +1,38 @@
+import type { TypedArrayConstructor } from '@daneren2005/shared-memory-objects';
+import type MemoryComponent from './memory-component';
+import type { ComponentTypedArray } from './memory-component';
+import type BaseEntity from './entity';
+import type { EntityComponent, EntityComponentConfig, EntityComponentSerialization } from './entity-component';
+export interface BaseComponent {
+    index: number;
+}
+export type ComponentMap = Record<string, BaseComponent>;
+export interface ComponentDefinition<Component extends BaseComponent, T extends ComponentTypedArray = ComponentTypedArray, Config = any, Serialization = object> {
+    type: TypedArrayConstructor<T>;
+    size: number;
+    loadProperties: Array<keyof Config & string>;
+    loadInFinishLoading?: boolean;
+    load(entity: BaseEntity, memory: MemoryComponent<T>, config: Config & Serialization): Component;
+    save?(component: Component): Serialization;
+}
+export type RegisteredComponentDefinition<Component extends BaseComponent, T extends ComponentTypedArray = ComponentTypedArray, Config = any, Serialization = object> = ComponentDefinition<Component, T, Config, Serialization> & {
+    memoryComponent: MemoryComponent<T>;
+};
+export type ComponentRegistry<C extends ComponentMap> = {
+    [K in keyof C]: ComponentDefinition<C[K]>;
+};
+export type RegisteredComponentRegistry<C extends ComponentMap> = {
+    [K in keyof C]: RegisteredComponentDefinition<C[K]>;
+};
+export type ComponentDefinitionMap = Record<string, ComponentDefinition<BaseComponent>>;
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+type DefinitionConfig<D> = D extends ComponentDefinition<BaseComponent, ComponentTypedArray, infer Config, infer Serialization> ? Config & Serialization : never;
+export type ComponentsOf<R extends ComponentDefinitionMap> = {
+    [K in keyof R]: ReturnType<R[K]['load']>;
+} & {
+    entity: EntityComponent;
+};
+export type EntityConfigOf<R extends ComponentDefinitionMap> = Partial<UnionToIntersection<{
+    [K in keyof R]: DefinitionConfig<R[K]>;
+}[keyof R]> & EntityComponentConfig & EntityComponentSerialization>;
+export {};

package/dist/entity-component.d.ts

@@ -0,0 +1,18 @@
+import type { ComponentDefinition } from './component-definition';
+export interface EntityComponent {
+    index: number;
+    type: string;
+    dead: boolean;
+    isStatic: boolean;
+}
+export interface EntityComponentConfig {
+    type: string;
+    isStatic?: boolean;
+}
+export interface EntityComponentSerialization {
+    type?: string;
+    dead?: boolean;
+}
+export declare const DEAD_INDEX = 0;
+export declare const STATIC_INDEX = 1;
+export declare const entityDefinition: ComponentDefinition<EntityComponent, Uint32Array, EntityComponentConfig, EntityComponentSerialization>;

package/dist/entity-factory.d.ts

@@ -0,0 +1,16 @@
+import BaseEntity from './entity';
+import type BaseWorld from './world';
+import type { ComponentDefinitionMap, ComponentMap } from './component-definition';
+export default class EntityFactory<C extends ComponentMap = ComponentMap, Cfg = any> {
+    world: BaseWorld<ComponentDefinitionMap, C, Cfg>;
+    configs: {
+        [type: string]: Cfg;
+    };
+    constructor(configs?: {
+        [type: string]: Cfg;
+    });
+    register(type: string, config: Cfg): void;
+    getConfig(config: Cfg): Cfg;
+    loadEntity(config: Cfg, created?: boolean): BaseEntity<C, Cfg>;
+    protected createEntity(config: Cfg): BaseEntity<C, Cfg>;
+}

package/dist/entity.d.ts

@@ -0,0 +1,26 @@
+import { EventEmitter } from 'eventemitter3';
+import type BaseWorld from './world';
+import type { ComponentDefinitionMap, ComponentMap } from './component-definition';
+import type { EntityComponent } from './entity-component';
+export default class BaseEntity<C extends ComponentMap = ComponentMap, Cfg = any> extends EventEmitter {
+    static eidCounter: number;
+    readonly eid: number;
+    config?: Cfg;
+    world: BaseWorld<ComponentDefinitionMap, C, Cfg>;
+    components: Partial<C> & {
+        entity: EntityComponent;
+    };
+    constructor(world: BaseWorld<ComponentDefinitionMap, C, Cfg>, config?: Cfg);
+    loadComponent<K extends keyof C>(name: K, config: any, emitAdded?: boolean): C[K];
+    removeComponent<K extends keyof C>(name: K): void;
+    setComponent<K extends keyof C, P extends keyof C[K]>(componentName: K, prop: P, value: C[K][P]): void;
+    /**
+     * NOTE: Does not emit component-property-updated!
+     */
+    setComponentBulk<K extends keyof C>(componentName: K, values: Partial<C[K]>): void;
+    deleteComponent<K extends keyof C>(componentName: K, prop: keyof C[K]): void;
+    deleteAllComponentMemory(): void;
+    load(config: Cfg): void;
+    save(): Cfg;
+    finishLoading(): void;
+}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+export { default as BaseWorld } from './world';
+export type { WorldOptions, WorldConfig } from './world';
+export { default as BaseEntity } from './entity';
+export { default as EntityFactory } from './entity-factory';
+export { entityDefinition, DEAD_INDEX, STATIC_INDEX } from './entity-component';
+export type { EntityComponent, EntityComponentConfig, EntityComponentSerialization, } from './entity-component';
+export { default as killEntity } from './actions/kill-entity';
+export { default as killEntityWorker } from './actions/kill-entity-worker';
+export { default as createEntityWorker } from './actions/create-entity-worker';
+export { default as MemoryComponent } from './memory-component';
+export type { ComponentTypedArray } from './memory-component';
+export type { BaseComponent, ComponentMap, ComponentDefinition, ComponentDefinitionMap, ComponentRegistry, ComponentsOf, EntityConfigOf, RegisteredComponentDefinition, RegisteredComponentRegistry, } from './component-definition';
+export { default as System } from './systems/system';
+export type { SystemConfig } from './systems/system';
+export { default as IterableSystem } from './systems/iterable-system';
+export type { IterableSystemConfig } from './systems/iterable-system';
+export { default as EntitySystem } from './systems/entity-system';
+export type { EntitySystemConfig } from './systems/entity-system';
+export { default as ComponentSystem } from './systems/component-system';
+export type { ComponentSystemConfig, ComponentSystemQuery, ComponentSystemWorld, ComponentSystemCallbacks, CreateEntityConfig, EntityUpdateComponents, EntityQueryComponents, EntityUpdateFunction, EntityUpdatePreRunFunction, EntityRemovedFunction, UpdateEntityConfig, UpdateEntityConfigObject, } from './systems/component-system';
+export { default as WebWorker } from './systems/workers/web-worker';
+export { default as ComponentWebWorker } from './systems/workers/component-web-worker';
+export { default as createComponentWorker } from './systems/workers/create-component-worker';
+export type { default as ComponentWorkerMessage } from './systems/workers/component-worker-message';