iris-ecs 0.0.1

package/dist/world.d.ts

@@ -0,0 +1,172 @@
+import type { ActionInitializer, Actions } from "./actions.js";
+import type { Archetype } from "./archetype.js";
+import type { Component, EntityId, Relation, Tag } from "./encoding.js";
+import type { EntityMeta } from "./entity.js";
+import type { EventId, EventQueueMeta } from "./event.js";
+import type { FilterMeta } from "./filters.js";
+import type { EventType, ObserverMeta } from "./observer.js";
+import type { QueryMeta } from "./query.js";
+import type { ComponentMeta } from "./registry.js";
+import type { ScheduleId, SystemMeta } from "./scheduler.js";
+/**
+ * World instance.
+ *
+ * Contains entity registry, archetype index, filter registry, query registry,
+ * observer system, system registry, schedule registry, and execution state.
+ */
+export type World = {
+    /**
+     * Entity registry (direct Map-based tracking).
+     */
+    entities: {
+        /**
+         * Entity metadata lookup (entity ID -> metadata).
+         */
+        byId: Map<EntityId, EntityMeta>;
+        /**
+         * Freelist of dead entity raw IDs for recycling.
+         */
+        freeIds: number[];
+        /**
+         * Next raw ID to allocate.
+         */
+        nextId: number;
+        /**
+         * Generation lookup for pair target reconstruction (rawId -> generation).
+         */
+        generations: Map<number, number>;
+    };
+    /**
+     * Component registry
+     */
+    components: {
+        /**
+         * Component metadata lookup (component ID -> metadata).
+         */
+        byId: Map<Tag | Component | Relation, ComponentMeta>;
+    };
+    /**
+     * Archetype registry and transition graph.
+     */
+    archetypes: {
+        /**
+         * Root archetype (empty - no components).
+         */
+        root: Archetype;
+        /**
+         * Archetype lookup by hash key (hash -> archetype).
+         */
+        byId: Map<string, Archetype>;
+    };
+    /**
+     * Filter registry for query caching.
+     */
+    filters: {
+        /**
+         * Filter metadata lookup (filter hash -> metadata).
+         */
+        byId: Map<string, FilterMeta>;
+    };
+    /**
+     * Query registry for metadata caching.
+     */
+    queries: {
+        /**
+         * Query metadata lookup (query hash -> metadata).
+         */
+        byId: Map<string, QueryMeta>;
+    };
+    /**
+     * Observer system for lifecycle events.
+     */
+    observers: {
+        [K in EventType]: ObserverMeta<K>;
+    };
+    /**
+     * System registry.
+     */
+    systems: {
+        /**
+         * System metadata by name.
+         */
+        byId: Map<string, SystemMeta>;
+        /**
+         * Next registration index for stable ordering.
+         */
+        nextIndex: number;
+    };
+    /**
+     * Schedule registry.
+     */
+    schedules: {
+        /**
+         * Built schedules (schedule ID -> sorted system IDs).
+         */
+        byId: Map<ScheduleId, string[]>;
+    };
+    /**
+     * Current execution state.
+     */
+    execution: {
+        /**
+         * Active schedule ID (null if not executing).
+         */
+        scheduleId: ScheduleId | null;
+        /**
+         * Currently executing system ID.
+         */
+        systemId: string | null;
+        /**
+         * Execution tick counter.
+         */
+        tick: number;
+    };
+    /**
+     * Event queue registry.
+     */
+    events: {
+        /**
+         * Event queue metadata lookup (event ID -> queue metadata).
+         */
+        byId: Map<EventId, EventQueueMeta>;
+    };
+    /**
+     * Actions registry for cached world-bound action getters.
+     */
+    actions: {
+        /**
+         * Actions lookup by initializer function.
+         */
+        byInitializer: Map<ActionInitializer<Actions>, Actions>;
+    };
+};
+/**
+ * Creates a new ECS world with empty entity registry and root archetype.
+ *
+ * @returns Initialized world instance ready for use
+ *
+ * @example
+ * ```typescript
+ * const world = createWorld();
+ * const entity = spawnEntity(world);
+ * ```
+ */
+export declare function createWorld(): World;
+/**
+ * Resets world to initial state, clearing all entities and caches.
+ *
+ * Does NOT fire per-entity lifecycle events (entityDestroyed, componentRemoved).
+ * For per-entity cleanup, run a "shutdown" schedule before calling resetWorld().
+ * Fires the "worldReset" observer event after reset completes.
+ *
+ * @param world - World instance to reset
+ *
+ * @example
+ * ```typescript
+ * // Run cleanup systems first, then reset
+ * executeSchedule(world, "shutdown");
+ * resetWorld(world);
+ * ```
+ */
+export declare function resetWorld(world: World): void;
+//# sourceMappingURL=world.d.ts.map

package/dist/world.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../src/world.ts"],"names":[],"mappings":"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"}

package/dist/world.js

@@ -0,0 +1,127 @@
+import { createArchetype, registerArchetype } from "./archetype.js";
+import { initNameSystem } from "./name.js";
+import { fireObserverEvent, unregisterObserverCallback } from "./observer.js";
+import { COMPONENT_REGISTRY } from "./registry.js";
+import { initRemovalSystem } from "./removal.js";
+/**
+ * Creates a new ECS world with empty entity registry and root archetype.
+ *
+ * @returns Initialized world instance ready for use
+ *
+ * @example
+ * ```typescript
+ * const world = createWorld();
+ * const entity = spawnEntity(world);
+ * ```
+ */
+export function createWorld() {
+    const root = createArchetype([], new Map());
+    const world = {
+        entities: {
+            byId: new Map(),
+            freeIds: [],
+            nextId: 1,
+            generations: new Map(),
+        },
+        components: {
+            byId: COMPONENT_REGISTRY.byId,
+        },
+        archetypes: {
+            root,
+            byId: new Map(),
+        },
+        filters: {
+            byId: new Map(),
+        },
+        queries: {
+            byId: new Map(),
+        },
+        systems: {
+            byId: new Map(),
+            nextIndex: 0,
+        },
+        schedules: {
+            byId: new Map(),
+        },
+        execution: {
+            scheduleId: null,
+            systemId: null,
+            tick: 1,
+        },
+        events: {
+            byId: new Map(),
+        },
+        actions: {
+            byInitializer: new Map(),
+        },
+        observers: {
+            archetypeCreated: { callbacks: [] },
+            archetypeDestroyed: { callbacks: [] },
+            filterCreated: { callbacks: [] },
+            filterDestroyed: { callbacks: [] },
+            entityCreated: { callbacks: [] },
+            entityDestroyed: { callbacks: [] },
+            componentAdded: { callbacks: [] },
+            componentRemoved: { callbacks: [] },
+            componentChanged: { callbacks: [] },
+            worldReset: { callbacks: [] },
+        },
+    };
+    registerArchetype(world, root);
+    initNameSystem(world);
+    initRemovalSystem(world);
+    return world;
+}
+/**
+ * Resets world to initial state, clearing all entities and caches.
+ *
+ * Does NOT fire per-entity lifecycle events (entityDestroyed, componentRemoved).
+ * For per-entity cleanup, run a "shutdown" schedule before calling resetWorld().
+ * Fires the "worldReset" observer event after reset completes.
+ *
+ * @param world - World instance to reset
+ *
+ * @example
+ * ```typescript
+ * // Run cleanup systems first, then reset
+ * executeSchedule(world, "shutdown");
+ * resetWorld(world);
+ * ```
+ */
+export function resetWorld(world) {
+    // 1. Clear filters (unregister observer callbacks)
+    for (const filter of world.filters.byId.values()) {
+        unregisterObserverCallback(world, "archetypeCreated", filter.onArchetypeCreate);
+        unregisterObserverCallback(world, "archetypeDestroyed", filter.onArchetypeDelete);
+    }
+    world.filters.byId.clear();
+    // 2. Clear queries (unregister observer callbacks)
+    for (const query of world.queries.byId.values()) {
+        unregisterObserverCallback(world, "filterDestroyed", query.onFilterDestroy);
+    }
+    world.queries.byId.clear();
+    // 3. Clear archetypes (break circular refs via edges)
+    for (const archetype of world.archetypes.byId.values()) {
+        archetype.edges.clear();
+    }
+    world.archetypes.byId.clear();
+    // 4. Reinitialize entity registry
+    world.entities.byId.clear();
+    world.entities.freeIds.length = 0;
+    world.entities.nextId = 1;
+    world.entities.generations.clear();
+    // 5. Create new root archetype
+    const newRoot = createArchetype([], new Map());
+    world.archetypes.root = newRoot;
+    registerArchetype(world, newRoot);
+    // 6. Reset execution state
+    world.execution.tick = 1;
+    world.execution.scheduleId = null;
+    world.execution.systemId = null;
+    // 7. Clear caches
+    world.events.byId.clear();
+    world.actions.byInitializer.clear();
+    // 8. Fire worldReset event (subsystems handle their own reset via this observer)
+    fireObserverEvent(world, "worldReset", world);
+}
+//# sourceMappingURL=world.js.map

package/dist/world.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.js","sourceRoot":"","sources":["../src/world.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "iris-ecs",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "High-performance TypeScript Entity Component System",
+  "author": "Yury Tomilin (https://github.com/r04423)",
+  "homepage": "https://github.com/r04423/iris#readme",
+  "bugs": "https://github.com/r04423/iris/issues",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "ecs",
+    "entity-component-system",
+    "game",
+    "typescript"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/r04423/iris.git",
+    "directory": "packages/ecs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "c8": "^10.1.3",
+    "tsx": "^4.19.4",
+    "typescript": "^5.9.0-beta"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "tsx --test 'src/**/*.test.ts'",
+    "test:coverage": "c8 tsx --test 'src/**/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  }
+}