@forgeax/engine-ecs 0.0.0-dev.8d955ade1c79

package/src/relationship-index.ts

@@ -0,0 +1,175 @@
+import {
+  type Component,
+  type ComponentSchema,
+  defineComponent,
+  type FieldsInput,
+} from './component';
+import type { EntityHandle } from './entity-handle';
+
+declare const relationshipTargetBrand: unique symbol;
+
+/** A relationship target is a read projection, never a structural-write token. */
+export type RelationshipTargetComponent<C extends Component = Component> = C & {
+  readonly [relationshipTargetBrand]: true;
+};
+
+/** The two immutable roles produced by one relationship declaration. */
+export interface RelationshipDefinition {
+  readonly source: Component<string, ComponentSchema>;
+  readonly target: RelationshipTargetComponent<Component<string, ComponentSchema>>;
+}
+
+export interface RelationshipOptions {
+  readonly sourceName: string;
+  readonly sourceField: string;
+  readonly targetName: string;
+  readonly targetField: string;
+  readonly exclusive?: boolean;
+  readonly linkedSpawn?: boolean;
+  /** Allow a source to point at its own holder (e.g. self-animated entities). */
+  readonly allowSelf?: boolean;
+}
+
+export type RelationshipRole =
+  | {
+      readonly kind: 'source';
+      readonly target: Component<string, ComponentSchema>;
+      readonly sourceField: string;
+      readonly targetField: string;
+      readonly exclusive: boolean;
+      readonly linkedSpawn: boolean;
+      readonly allowSelf: boolean;
+    }
+  | {
+      readonly kind: 'target';
+      readonly source: Component<string, ComponentSchema>;
+      readonly sourceField: string;
+      readonly targetField: string;
+    };
+
+const roles = new WeakMap<Component, RelationshipRole>();
+
+/**
+ * Declare both sides of a relationship in one closed operation. The source is
+ * the only writable relationship component; its target is a materialized,
+ * engine-maintained reverse list.
+ */
+export function defineRelationship<
+  const S extends string,
+  const SF extends string,
+  const T extends string,
+  const TF extends string,
+>(
+  options: RelationshipOptions & {
+    readonly sourceName: S;
+    readonly sourceField: SF;
+    readonly targetName: T;
+    readonly targetField: TF;
+  },
+): {
+  readonly source: Component<S, { [K in SF]: 'entity' }>;
+  readonly target: RelationshipTargetComponent<Component<T, { [K in TF]: 'array<entity>' }>>;
+} {
+  const targetFields: FieldsInput = {
+    [options.targetField]: { type: 'array<entity>', transient: true },
+  };
+  const target = defineComponent(options.targetName, targetFields);
+  const sourceFields: FieldsInput = { [options.sourceField]: { type: 'entity' } };
+  const source = defineComponent(options.sourceName, sourceFields);
+
+  roles.set(source, {
+    kind: 'source',
+    target,
+    sourceField: options.sourceField,
+    targetField: options.targetField,
+    exclusive: options.exclusive ?? true,
+    linkedSpawn: options.linkedSpawn ?? false,
+    allowSelf: options.allowSelf ?? false,
+  });
+  roles.set(target, {
+    kind: 'target',
+    source,
+    sourceField: options.sourceField,
+    targetField: options.targetField,
+  });
+  return { source: source as never, target: target as never };
+}
+
+export function relationshipRole(component: Component): RelationshipRole | undefined {
+  return roles.get(component);
+}
+
+/** Return the materialized target token owned by a source relationship. */
+export function relationshipMirror(component: Component): Component | undefined {
+  const role = roles.get(component);
+  return role?.kind === 'source' ? role.target : undefined;
+}
+
+/** Return the source token owned by a materialized relationship target. */
+export function relationshipSource(component: Component): Component | undefined {
+  const role = roles.get(component);
+  return role?.kind === 'target' ? role.source : undefined;
+}
+
+export function isRelationshipTarget(component: Component): boolean {
+  return roles.get(component)?.kind === 'target';
+}
+
+/**
+ * Backpointer index for the materialized reverse lists stored by World.
+ * The target component array is the one authoritative read list; this index
+ * stores only source-to-target locations for O(1) swap-remove bookkeeping.
+ */
+export class RelationshipIndex {
+  private readonly slots = new Map<number, { target: number; slot: number }>();
+  private epochValue = 0;
+
+  get epoch(): number {
+    return this.epochValue;
+  }
+
+  attach(source: EntityHandle, target: EntityHandle, slot: number): number {
+    this.slots.set(source as number, { target: target as number, slot });
+    this.epochValue++;
+    return slot;
+  }
+
+  detach(source: EntityHandle): boolean {
+    if (!this.slots.delete(source as number)) return false;
+    this.epochValue++;
+    return true;
+  }
+
+  reparent(source: EntityHandle, target: EntityHandle, slot: number): number {
+    return this.attach(source, target, slot);
+  }
+
+  slotOf(source: EntityHandle): number | undefined {
+    return this.slots.get(source as number)?.slot;
+  }
+
+  targetOf(source: EntityHandle): EntityHandle | undefined {
+    return this.slots.get(source as number)?.target as EntityHandle | undefined;
+  }
+
+  /** Bind the source that swap-remove moved into `slot`. */
+  updateSlot(source: EntityHandle, target: EntityHandle, slot: number): void {
+    const location = this.slots.get(source as number);
+    if (location === undefined) return;
+    location.target = target as number;
+    location.slot = slot;
+    this.epochValue++;
+  }
+
+  /** Cold recovery path only: rebuild from R source records. */
+  recover(records: Iterable<readonly [EntityHandle, EntityHandle]>): void {
+    this.slots.clear();
+    const nextSlots = new Map<number, number>();
+    for (const [source, target] of records) {
+      const slot = nextSlots.get(target as number) ?? 0;
+      nextSlots.set(target as number, slot + 1);
+      this.attach(source, target, slot);
+    }
+    this.epochValue++;
+  }
+}

package/src/resource.ts

@@ -0,0 +1,106 @@
+// @forgeax/engine-ecs — Resource store: typed key-value global singletons.
+//
+// Map<string, unknown> backend. insertResource is idempotent (overwrites).
+// getResource throws ResourceNotFoundError if key absent.
+
+import { ResourceNotFoundError } from './errors';
+
+// ────────────────────────────────────────────────────────────────────────────
+// ResourceStore
+// ────────────────────────────────────────────────────────────────────────────
+
+/** Internal resource storage. */
+export interface ResourceEntry {
+  value: unknown;
+  added: number;
+  changed: number;
+}
+
+export interface ResourceStore {
+  readonly entries: Map<string, ResourceEntry>;
+}
+
+/** Create a fresh resource store. */
+export function createResourceStore(): ResourceStore {
+  return { entries: new Map() };
+}
+
+/**
+ * Insert or overwrite a resource (idempotent, E-13).
+ *
+ * @example
+ * ```ts
+ * import { createResourceStore, insertResource, type ResourceStore } from './resource';
+ *
+ * const store: ResourceStore = createResourceStore();
+ * insertResource(store, 'health', 100);
+ * // overwriting is idempotent (no error / no duplicate slot):
+ * insertResource(store, 'health', 95);
+ * ```
+ */
+export function insertResource<T>(store: ResourceStore, key: string, value: T, epoch = 0): void {
+  const current = store.entries.get(key);
+  if (current === undefined) {
+    store.entries.set(key, { value, added: epoch, changed: epoch });
+  } else {
+    current.value = value;
+    current.changed = epoch;
+  }
+}
+
+/**
+ * Get a resource by key.
+ * @throws ResourceNotFoundError if key does not exist (E-14).
+ *
+ * @example
+ * ```ts
+ * import { getResource, insertResource, type ResourceStore } from './resource';
+ *
+ * declare const store: ResourceStore;
+ * insertResource(store, 'health', 100);
+ * const hp = getResource<number>(store, 'health');
+ * // hp === 100; throws ResourceNotFoundError on missing key (charter proposition 4)
+ * ```
+ */
+export function getResource<T>(store: ResourceStore, key: string): T {
+  const entry = store.entries.get(key);
+  if (entry === undefined) {
+    throw new ResourceNotFoundError(key);
+  }
+  return entry.value as T;
+}
+
+/**
+ * Check if a resource exists.
+ *
+ * @example
+ * ```ts
+ * import { hasResource, insertResource, type ResourceStore } from './resource';
+ *
+ * declare const store: ResourceStore;
+ * insertResource(store, 'health', 100);
+ * if (hasResource(store, 'health')) {
+ *   // guarded access avoids ResourceNotFoundError from getResource
+ * }
+ * ```
+ */
+export function hasResource(store: ResourceStore, key: string): boolean {
+  return store.entries.has(key);
+}
+
+/**
+ * Remove a resource by key.
+ *
+ * @example
+ * ```ts
+ * import { hasResource, insertResource, removeResource, type ResourceStore } from './resource';
+ *
+ * declare const store: ResourceStore;
+ * insertResource(store, 'health', 100);
+ * removeResource(store, 'health');
+ * // hasResource(store, 'health') === false; idempotent on missing keys
+ * ```
+ */
+export function removeResource(store: ResourceStore, key: string): boolean {
+  return store.entries.delete(key);
+}

package/src/schedule-token.ts

@@ -0,0 +1,40 @@
+/**
+ * Nominal label for one of the World-owned schedules.
+ *
+ * Worlds expose the built-in tokens below. A token is both a registration
+ * scope and, for FixedUpdate, the intrinsic Update ordering anchor.
+ */
+export interface ScheduleToken {
+  readonly name: string;
+}
+
+export type ScheduleName = 'Update' | 'FixedUpdate';
+
+function createScheduleToken(name: ScheduleName): ScheduleToken {
+  // The Engine Worker loads its runtime and an execution bootstrap as separate
+  // Vite bundles. Keep the two built-in tokens physically shared across those
+  // bundles so a plugin's `Update` reference still addresses the owning World
+  // schedule instead of becoming an accidental cross-scope edge.
+  const registry = globalThis as typeof globalThis & {
+    readonly [key: symbol]: ScheduleToken | undefined;
+  };
+  const key = Symbol.for(`forgeax.ecs.schedule-token.${name}`);
+  const existing = registry[key];
+  if (existing !== undefined) return existing;
+  const token = Object.freeze({ name });
+  Object.defineProperty(registry, key, {
+    configurable: false,
+    enumerable: false,
+    value: token,
+    writable: false,
+  });
+  return token;
+}
+
+/** Variable-rate World schedule. */
+export const Update = createScheduleToken('Update');
+/** Fixed-rate World schedule and the intrinsic Update ordering anchor. */
+export const FixedUpdate = createScheduleToken('FixedUpdate');
+export function isScheduleToken(value: unknown): value is ScheduleToken {
+  return value === Update || value === FixedUpdate;
+}