@georgeluo/ecs 0.1.0 → 0.1.2

package/README.md

@@ -1,4 +1,4 @@
-# @simeval/ecs
+# @georgeluo/ecs
 
 Reusable ECS core extracted from `workspaces/Describing_Simulation_0/src/core`.
 
@@ -11,15 +11,15 @@ Reusable ECS core extracted from `workspaces/Describing_Simulation_0/src/core`.
 ## Install
 
 ```bash
-npm install @simeval/ecs
+npm install @georgeluo/ecs
 ```
 
 ```bash
-pnpm add @simeval/ecs
+pnpm add @georgeluo/ecs
 ```
 
 ```bash
-yarn add @simeval/ecs
+yarn add @georgeluo/ecs
 ```
 
 For this monorepo before publish, use a local file dependency:
@@ -27,7 +27,7 @@ For this monorepo before publish, use a local file dependency:
 ```json
 {
   "dependencies": {
-    "@simeval/ecs": "file:../../packages/ecs"
+    "@georgeluo/ecs": "file:../../packages/ecs"
   }
 }
 ```
@@ -48,10 +48,84 @@ import {
   type Frame,
   type Acknowledgement,
   type System,
-} from '@simeval/ecs';
+} from '@georgeluo/ecs';
 ```
 
-## Inject systems into EvaluationPlayer
+## Quick Start (SimulationPlayer)
+
+```ts
+import {
+  EntityManager,
+  ComponentManager,
+  SystemManager,
+  SimulationPlayer,
+  Bus,
+  FrameFilter,
+  TimeSystem,
+  type Frame,
+  type Acknowledgement,
+} from '@georgeluo/ecs';
+
+const entities = new EntityManager();
+const components = new ComponentManager();
+const systems = new SystemManager(entities, components);
+const inbound = new Bus<unknown>();
+const outbound = new Bus<Frame | Acknowledgement>();
+const player = new SimulationPlayer(systems, inbound, outbound, new FrameFilter());
+
+const systemId = player.injectSystem({ system: new TimeSystem() });
+outbound.subscribe((message) => {
+  console.log('outbound:', message);
+});
+
+player.start();
+setTimeout(() => player.pause(), 200);
+setTimeout(() => player.stop(), 500);
+setTimeout(() => player.ejectSystem({ systemId }), 800);
+```
+
+## Control Simulation via Inbound Bus
+
+```ts
+import { SimulationMessageType } from '@georgeluo/ecs';
+
+inbound.publish({ type: SimulationMessageType.START, payload: { messageId: 'm-1' } });
+inbound.publish({ type: SimulationMessageType.PAUSE, payload: { messageId: 'm-2' } });
+inbound.publish({ type: SimulationMessageType.STOP, payload: { messageId: 'm-3' } });
+```
+
+## Custom Component + System
+
+```ts
+import { System, type SystemContext, type ComponentType } from '@georgeluo/ecs';
+
+const TemperatureComponent: ComponentType<{ value: number }> = {
+  id: 'temperature',
+  validate: (payload) => Number.isFinite(payload?.value),
+};
+
+class TemperatureSystem extends System {
+  private entity: number | null = null;
+
+  initialize(context: SystemContext): void {
+    this.entity = context.entityManager.create();
+    context.componentManager.addComponent(this.entity, TemperatureComponent, { value: 72 });
+  }
+
+  update(context: SystemContext): void {
+    if (this.entity === null) {
+      return;
+    }
+    const current = context.componentManager.getComponent(this.entity, TemperatureComponent);
+    const nextValue = (current?.payload.value ?? 72) + 0.25;
+    context.componentManager.addComponent(this.entity, TemperatureComponent, { value: nextValue });
+  }
+}
+
+player.injectSystem({ system: new TemperatureSystem() });
+```
+
+## EvaluationPlayer: Inject Systems
 
 ```ts
 const entities = new EntityManager();
@@ -65,7 +139,7 @@ const systemId = player.injectSystem({ system: myEvaluationSystem });
 player.ejectSystem({ systemId });
 ```
 
-## Inject frames into EvaluationPlayer
+## EvaluationPlayer: Inject Frames
 
 ```ts
 inbound.publish({
@@ -85,3 +159,14 @@ player.injectFrame({
   frame: { tick: 1, entities: {} },
 });
 ```
+
+## API Surface
+
+- Managers:
+  - `EntityManager`, `ComponentManager`, `SystemManager`
+- Players:
+  - `Player`, `IOPlayer`, `SimulationPlayer`, `EvaluationPlayer`
+- Base model:
+  - `System`, `SystemContext`, `ComponentType`, `Frame`, `Acknowledgement`
+- Messaging:
+  - `Bus`, `FrameFilter`, `SimulationMessageType`, `EvaluationMessageType`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@georgeluo/ecs",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Reusable ECS engine and simulation players for SimEval.",
   "keywords": [
     "ecs",
@@ -11,7 +11,7 @@
   "license": "ISC",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/GeorgeLuo/simtest0.git",
+    "url": "https://github.com/GeorgeLuo/simtest0.git",
     "directory": "packages/ecs"
   },
   "bugs": {