@benev/archimedes 0.1.0-4 → 0.1.0-6

package/README.md

@@ -21,7 +21,7 @@ npm install @benev/archimedes
 ## 🧩 ecs — entities, components, systems
 
 ```ts
-import {Entities, asSystems, change, executeSystems} from "@benev/archimedes"
+import {Entities, Change, makeId, makeExecute} from "@benev/archimedes"
 ```
 
 1. ***define components.*** json-friendly data that entities could have.
@@ -31,45 +31,48 @@ import {Entities, asSystems, change, executeSystems} from "@benev/archimedes"
       bleed: number
     }
     ```
-1. ***create entities map.*** fancy caching for speedy-fast lookups.
+1. ***create entities map.*** indexed for speedy-fast lookups.
     ```ts
-    export const entitiesWritable = new Entities<MyComponents>()
-
-    // only let systems touch the readonly variant!
-    export const entities = entitiesWritable.readonly()
+    export const entities = new Entities<MyComponents>()
+    ```
+1. ***readonly entities.*** recommended to use this in your systems.
+    ```ts
+    export const entitiesReadonly = entities.readonly
     ```
-1. ***define systems.*** select entities by components. yields changes.
+1. ***define systems.*** select entities by components. changes are formalized.
     ```ts
-    const systems = asSystems<MyComponents>(
-      function* bleeding() {
-        for (const [id, components] of entities.select("health", "bleed")) {
-          if (components.bleed >= 0) {
+    const systems = (change: Change<MyComponents>) => [
+      function bleeding() {
+        for (const [id, components] of entitiesReadonly.select("health", "bleed")) {
+          if (components.bleed > 0) {
             const health = components.health - components.bleed
-            const bleed = components.bleed - 1
-            yield change.merge(id, {health, bleed})
+            change.merge(id, {health})
           }
         }
       },
 
-      function* death() {
-        for (const [id, components] of entities.select("health")) {
+      function death() {
+        for (const [id, components] of entitiesReadonly.select("health")) {
           if (components.health <= 0)
-            yield change.delete(id)
+            change.delete(id)
         }
       },
-    )
+    ]
     ```
-1. ***create your first entity.***
+1. ***manually insert your first entity.***
     ```ts
     const wizardId = makeId()
-    entitiesWritable.set(wizardId, {health: 100, bleed: 2})
+    entities.set(wizardId, {health: 100, bleed: 2})
 
     console.log(entities.get(wizardId)?.health)
       // 100
     ```
-1. ***execute systems to simulate each tick.***
+1. ***create an execute fn.*** run one tick at a time.
     ```ts
-    executeSystems(entitiesWritable, systems)
+    const execute = makeExecute(entities, systems)
+
+    // simulate one tick
+    execute()
 
     console.log(entities.get(wizardId)?.health)
       // 98
@@ -91,5 +94,3 @@ import {Entities, asSystems, change, executeSystems} from "@benev/archimedes"
 
 *coming soon*
 
-
-

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@benev/archimedes",
-	"version": "0.1.0-4",
+	"version": "0.1.0-6",
 	"description": "game ecs with auto networking",
 	"license": "MIT",
 	"type": "module",
@@ -17,7 +17,7 @@
 	},
 	"dependencies": {
 		"@e280/renraku": "^0.5.7",
-		"@e280/stz": "^0.2.29",
+		"@e280/stz": "^0.2.30",
 		"@msgpack/msgpack": "^3.1.3",
 		"sparrow-rtc": "^0.2.15"
 	},

package/s/ecs/index.ts

@@ -1,8 +1,8 @@
 
-export * from "./parts/apply-change.js"
+export * from "./parts/apply-delta.js"
 export * from "./parts/change.js"
 export * from "./parts/entities.js"
-export * from "./parts/execute-systems.js"
+export * from "./parts/execute.js"
 export * from "./parts/lifecycle.js"
 export * from "./parts/make-id.js"
 export * from "./parts/types.js"

package/s/ecs/parts/apply-delta.ts

@@ -0,0 +1,37 @@
+
+import {Entities} from "./entities.js"
+import {DeltaSet, Delta, Components, DeltaKind, DeltaMerge, DeltaDrop} from "./types.js"
+
+export function applyDelta<C extends Components>(entities: Entities<C>, delta: Delta<C>) {
+	switch (delta[0]) {
+		case DeltaKind.Set: return applySet<C>(entities, <DeltaSet<C>>delta)
+		case DeltaKind.Merge: return applyMerge<C>(entities, <DeltaMerge<C>>delta)
+		case DeltaKind.Drop: return applyDrop<C>(entities, <DeltaDrop<C>>delta)
+		default: throw new Error(`unknown delta kind "${delta[0]}"`)
+	}
+}
+
+function applySet<C extends Components>(entities: Entities<C>, [, id, components]: DeltaSet<C>) {
+	if (components) entities.set(id, components as Partial<C>)
+	else entities.delete(id)
+	return id
+}
+
+function applyMerge<C extends Components>(entities: Entities<C>, [, id, patch]: DeltaMerge<C>) {
+	const components = entities.get(id)
+	if (!components)
+		return id
+	Object.assign(components, patch)
+	entities.set(id, components)
+	return id
+}
+
+function applyDrop<C extends Components>(entities: Entities<C>, [, id, keys]: DeltaDrop<C>) {
+	const components = entities.get(id)
+	if (!components)
+		return id
+	for (const key of keys) delete components[key]
+	entities.set(id, components)
+	return id
+}
+

package/s/ecs/parts/change.ts

@@ -1,27 +1,39 @@
 
 import {makeId} from "./make-id.js"
-import {Components, ChangeSet, ChangeMerge, Id, ChangeKind, ChangeDrop} from "./types.js"
+import {Components, Id, DeltaKind, Delta} from "./types.js"
 
-export const change = {
+export class Change<C extends Components> {
+	constructor(private commit: (delta: Delta<C>) => void) {}
 
 	/** create a new entity with the given components */
-	create: (components: Partial<Components>): ChangeSet<Components> =>
-		[ChangeKind.Set, makeId(), components],
+	create(components: Partial<C>) {
+		const id = makeId()
+		this.commit([DeltaKind.Set, id, components])
+		return id
+	}
 
 	/** overwrite a whole entity to the given components */
-	set: (id: Id, components: Partial<Components>): ChangeSet<Components> =>
-		[ChangeKind.Set, id, components],
+	set(id: Id, components: Partial<C>) {
+		this.commit([DeltaKind.Set, id, components])
+		return id
+	}
 
 	/** remove the entity */
-	delete: (id: Id): ChangeSet<Components> =>
-		[ChangeKind.Set, id],
+	delete(id: Id) {
+		this.commit([DeltaKind.Set, id])
+		return id
+	}
 
 	/** update or add the given components onto the entity */
-	merge: (id: Id, components: Partial<Components>): ChangeMerge<Components> =>
-		[ChangeKind.Merge, id, components],
+	merge(id: Id, components: Partial<C>) {
+		this.commit([DeltaKind.Merge, id, components])
+		return id
+	}
 
 	/** delete specific components off the entity */
-	drop: <C extends Components>(id: Id, ...keys: (keyof C)[]): ChangeDrop<C> =>
-		[ChangeKind.Drop, id, keys],
+	drop(id: Id, ...keys: (keyof C)[]) {
+		this.commit([DeltaKind.Drop, id, keys])
+		return id
+	}
 }
 

package/s/ecs/parts/entities.ts

@@ -41,7 +41,7 @@ export class Entities<C extends Components> extends GMap<Id, Partial<C>> {
 			yield* this.#makeCache(componentKeys)
 	}
 
-	readonly() {
+	get readonly() {
 		return this as EntitiesReadonly<C>
 	}
 

package/s/ecs/parts/execute.ts

@@ -0,0 +1,29 @@
+
+import {Change} from "./change.js"
+import {Entities} from "./entities.js"
+import {applyDelta} from "./apply-delta.js"
+import {Delta, Components, Systems} from "./types.js"
+
+export function makeExecute<C extends Components>(
+		entities: Entities<C>,
+		systems: Systems<C>,
+	) {
+
+	let deltas: Delta<C>[] = []
+
+	const change = new Change<C>(delta => {
+		applyDelta(entities, delta)
+		deltas.push(delta)
+	})
+
+	const fns = systems(change)
+
+	return () => {
+		for (const fn of fns)
+			fn()
+		const ret = deltas
+		deltas = []
+		return ret
+	}
+}
+

package/s/ecs/parts/lifecycle.ts

@@ -10,21 +10,22 @@ export function lifecycle<C extends Components, K extends keyof C>(
 	) {
 
 	const alive = new GMap<Id, LifecycleCallbacks<C, K>>()
-	const sel = () => entities.select(...componentKeys)
 
-	return function*() {
-		const current = new Map(sel())
+	return () => {
 
+		// add fresh entities
+		for (const [id, components] of entities.select(...componentKeys)) {
+			const callbacks = alive.guarantee(id, () => enter(id, components))
+			callbacks.tick(id, components)
+		}
+
+		// delete stale entities
+		const currentIds = new Set([...entities.select(...componentKeys)].map(([id]) => id))
 		for (const [id, callbacks] of alive) {
-			if (current.has(id)) continue
+			if (currentIds.has(id)) continue
 			alive.delete(id)
 			callbacks.exit(id)
 		}
-
-		for (const [id, components] of current) {
-			const callbacks = alive.guarantee(id, () => enter(id, components))
-			callbacks.tick(id, components)
-		}
 	}
 }
 

package/s/ecs/parts/types.ts

@@ -1,18 +1,19 @@
 
+import {Change} from "./change.js"
+
 export type Id = string
 export type Components = Record<string, unknown>
 export type AsComponents<C extends Components> = C
 export type Select<C extends Components, K extends keyof C> = Pick<C, K> & Partial<C>
-export type System<C extends Components> = () => Generator<Change<C>>
 
-export const asSystem = <C extends Components>(system: System<C>) => system
-export const asSystems = <C extends Components>(...systems: System<C>[]) => systems
+export enum DeltaKind {Set, Merge, Drop}
+export type DeltaSet<C extends Components> = [kind: DeltaKind.Set, id: Id, components?: Partial<C>]
+export type DeltaMerge<C extends Components> = [kind: DeltaKind.Merge, id: Id, patch: Partial<C>]
+export type DeltaDrop<C extends Components> = [kind: DeltaKind.Drop, id: Id, keys: (keyof C)[]]
+export type Delta<C extends Components> = DeltaSet<C> | DeltaMerge<C> | DeltaDrop<C>
 
-export enum ChangeKind {Set, Merge, Drop}
-export type ChangeSet<C extends Components> = [kind: ChangeKind.Set, id: Id, components?: Partial<C>]
-export type ChangeMerge<C extends Components> = [kind: ChangeKind.Merge, id: Id, patch: Partial<C>]
-export type ChangeDrop<C extends Components> = [kind: ChangeKind.Drop, id: Id, keys: (keyof C)[]]
-export type Change<C extends Components> = ChangeSet<C> | ChangeMerge<C> | ChangeDrop<C>
+export type Systems<C extends Components> = (change: Change<C>) => (() => void)[]
+export const asSystems = <C extends Components>(systems: Systems<C>) => systems
 
 export type LifecycleCallbacks<C extends Components, K extends keyof C> = {
 	tick: (id: Id, components: Select<C, K>) => void

package/s/ecs/test/setup-example.ts

@@ -1,49 +1,54 @@
 
-import {change} from "../parts/change.js"
+import {Change} from "../parts/change.js"
 import {asSystems} from "../parts/types.js"
 import {Entities} from "../parts/entities.js"
+import {makeExecute} from "../parts/execute.js"
+import {applyDelta} from "../parts/apply-delta.js"
+
+export type ExampleComponents = {
+	health: number
+	bleed: number
+	mana: number
+	manaRegen: number
+}
 
 export function setupExample() {
-	type MyComponents = {
-		health: number
-		bleed: number
-		mana: number
-		manaRegen: number
-	}
-
-	const writableEntities = new Entities<MyComponents>()
-	const entities = writableEntities.readonly()
-
-	const systems = asSystems<MyComponents>(
-		function* manaRegen() {
-			for (const [id, components] of entities.select("mana", "manaRegen")) {
+	const entities = new Entities<ExampleComponents>()
+	const rentities = entities.readonly
+
+	const systems = asSystems<ExampleComponents>(change => [
+		function manaRegen() {
+			for (const [id, components] of rentities.select("mana", "manaRegen")) {
 				if (components.manaRegen !== 0) {
 					const mana = components.mana + components.manaRegen
-					yield change.merge(id, {mana})
+					change.merge(id, {mana})
 				}
 			}
 		},
 
-		function* bleeding() {
-			for (const [id, components] of entities.select("health", "bleed")) {
+		function bleeding() {
+			for (const [id, components] of rentities.select("health", "bleed")) {
 				if (components.bleed >= 0) {
 					const health = components.health - components.bleed
 					const bleed = components.bleed - 1
-					yield change.merge(id, {health, bleed})
+					change.merge(id, {health, bleed})
 				}
 				if (components.bleed <= 0)
-					yield change.drop(id, "bleed")
+					change.drop(id, "bleed")
 			}
 		},
 
-		function* death() {
-			for (const [id, components] of entities.select("health")) {
+		function death() {
+			for (const [id, components] of rentities.select("health")) {
 				if (components.health <= 0)
-					yield change.delete(id)
+					change.delete(id)
 			}
 		},
-	)
+	])
+
+	const change = new Change<ExampleComponents>(delta => applyDelta(entities, delta))
+	const execute = makeExecute(entities, systems)
 
-	return {entities: writableEntities, systems}
+	return {systems, entities, change, execute}
 }
 

package/s/ecs/test/setup-lifecycle-counts.ts

@@ -6,10 +6,15 @@ export function setupLifecycleCounts() {
 		enters: 0,
 		ticks: 0,
 		exits: 0,
-		expect: (enters: number, ticks: number, exits: number) => {
-			expect(counts.enters).is(enters)
-			expect(counts.ticks).is(ticks)
-			expect(counts.exits).is(exits)
+		expect: (e: {enters: number, ticks: number, exits: number}) => {
+			expect(counts.enters, `enters, expected ${e.enters}, got ${counts.enters}`)
+				.is(e.enters)
+
+			expect(counts.ticks, `ticks, expected ${e.ticks}, got ${counts.ticks}`)
+				.is(e.ticks)
+
+			expect(counts.exits, `exits, expected ${e.exits}, got ${counts.exits}`)
+				.is(e.exits)
 		},
 	}
 	return counts

package/s/ecs/test.ts

@@ -1,126 +1,179 @@
 
 import {suite, test, expect} from "@e280/science"
-import {change} from "./parts/change.js"
+import {asSystems} from "./parts/types.js"
 import {lifecycle} from "./parts/lifecycle.js"
-import {applyChange} from "./parts/apply-change.js"
-import {setupExample} from "./test/setup-example.js"
-import {executeSystems} from "./parts/execute-systems.js"
+import {makeExecute} from "./parts/execute.js"
 import {setupLifecycleCounts} from "./test/setup-lifecycle-counts.js"
+import {ExampleComponents, setupExample} from "./test/setup-example.js"
 
 export default suite({
 	"create an entity": test(async() => {
-		const {entities} = setupExample()
+		const {entities, change} = setupExample()
 		expect(entities.size).is(0)
-		applyChange(entities, change.create({health: 100}))
+		change.create({health: 100})
 		expect(entities.size).is(1)
 	}),
 
 	"delete an entity": test(async() => {
-		const {entities} = setupExample()
-		const id = applyChange(entities, change.create({health: 100}))
+		const {entities, change} = setupExample()
+		const id = change.create({health: 100})
 		expect(entities.size).is(1)
-		applyChange(entities, change.delete(id))
+		change.delete(id)
 		expect(entities.size).is(0)
 	}),
 
 	"merge components into entity": test(async() => {
-		const {entities} = setupExample()
-		const id = applyChange(entities, change.create({health: 100, mana: 100}))
+		const {entities, change} = setupExample()
+		const id = change.create({health: 100, mana: 100})
 		expect(entities.require(id).health).is(100)
-		applyChange(entities, change.merge(id, {health: 99}))
+		change.merge(id, {health: 99})
 		expect(entities.require(id).health).is(99)
 		expect(entities.require(id).mana).is(100)
 	}),
 
+	"ignore merge after delete": test(async() => {
+		const {entities, change} = setupExample()
+		const id = change.create({health: 100, mana: 100})
+		expect(entities.get(id)).ok()
+		change.delete(id)
+		expect(entities.get(id)).not.ok()
+		change.merge(id, {health: 99})
+		expect(entities.get(id)).not.ok()
+	}),
+
+	"ignore drop after delete": test(async() => {
+		const {entities, change} = setupExample()
+		const id = change.create({health: 100, mana: 100})
+		expect(entities.get(id)).ok()
+		change.delete(id)
+		expect(entities.get(id)).not.ok()
+		change.drop(id, "health")
+		expect(entities.get(id)).not.ok()
+	}),
+
 	"select an entity": test(async() => {
-		const {entities} = setupExample()
-		applyChange(entities, change.create({health: 100}))
+		const {entities, change} = setupExample()
+		change.create({health: 100})
 		expect([...entities.select("health")].length).is(1)
 	}),
 
 	"drop components from entity": test(async() => {
-		const {entities} = setupExample()
-		const id = applyChange(entities, change.create({health: 100, mana: 100}))
+		const {entities, change} = setupExample()
+		const id = change.create({health: 100, mana: 100})
 		expect([...entities.select("health", "mana")].length).is(1)
-		applyChange(entities, change.drop(id, "mana"))
+		change.drop(id, "mana")
 		expect("mana" in entities.require(id)).is(false)
 		expect([...entities.select("health", "mana")].length).is(0)
 	}),
 
 	"select two entities": test(async() => {
-		const {entities} = setupExample()
-		applyChange(entities, change.create({health: 100}))
-		applyChange(entities, change.create({health: 100}))
+		const {entities, change} = setupExample()
+		change.create({health: 100})
+		change.create({health: 100})
 		expect([...entities.select("health")].length).is(2)
 	}),
 
 	"select with no component keys selects all": test(async() => {
-		const {entities} = setupExample()
-		applyChange(entities, change.create({health: 100}))
-		applyChange(entities, change.create({health: 100}))
+		const {entities, change} = setupExample()
+		change.create({health: 100})
+		change.create({health: 100})
 		expect([...entities.select()].length).is(2)
 	}),
 
 	"select doesn't include non-match": test(async() => {
-		const {entities} = setupExample()
-		applyChange(entities, change.create({health: 100}))
+		const {entities, change} = setupExample()
+		change.create({health: 100})
 		expect([...entities.select("mana")].length).is(0)
 	}),
 
 	"select includes entities with extra components": test(async() => {
-		const {entities} = setupExample()
-		applyChange(entities, change.create({health: 100, mana: 100}))
+		const {entities, change} = setupExample()
+		change.create({health: 100, mana: 100})
 		expect([...entities.select("health")].length).is(1)
 	}),
 
 	"wizard regens mana": test(async() => {
-		const {entities, systems} = setupExample()
-		const creating = change.create({health: 100, mana: 50, manaRegen: 1})
-		const wizardId = creating[1]
-		applyChange(entities, creating)
-		const changes = executeSystems(entities, systems)
+		const {entities, change, execute} = setupExample()
+		const wizardId = change.create({health: 100, mana: 50, manaRegen: 1})
+		const changes = execute()
 		expect(changes.length).is(1)
 		expect(entities.require(wizardId).mana).is(51)
 	}),
 
 	"death by bleeding": test(async() => {
-		const {entities, systems} = setupExample()
-		const creating = change.create({health: 3, bleed: 2})
-		const wizardId = creating[1]
-		applyChange(entities, creating)
+		const {entities, change, execute} = setupExample()
+		const wizardId = change.create({health: 3, bleed: 2})
 		expect(entities.require(wizardId).health).is(3)
-		executeSystems(entities, systems)
+		execute()
 		expect(entities.require(wizardId).health).is(1)
-		executeSystems(entities, systems)
+		execute()
 		expect(entities.has(wizardId)).is(false)
 	}),
 
 	"lifecycles": test(async() => {
-		const {entities} = setupExample()
+		const {entities, change} = setupExample()
 		const counts = setupLifecycleCounts()
-		const system = lifecycle(entities.readonly(), ["health"], () => {
-			counts.enters++
-			return {
-				tick: () => void counts.ticks++,
-				exit: () => void counts.exits++,
-			}
-		})
-		counts.expect(0, 0, 0)
-
-		const creating = change.create({health: 100, mana: 50})
-		const wizardId = creating[1]
-		applyChange(entities, creating)
-		executeSystems(entities, [system])
-		counts.expect(1, 1, 0)
-
-		applyChange(entities, change.merge(wizardId, {health: 100, mana: 100}))
-		executeSystems(entities, [system])
-		counts.expect(1, 2, 0)
-
-		applyChange(entities, change.delete(wizardId))
-		executeSystems(entities, [system])
-		counts.expect(1, 2, 1)
+		const systems = asSystems<ExampleComponents>(() => [
+			lifecycle(entities.readonly, ["health"], () => {
+				counts.enters++
+				return {
+					tick: () => void counts.ticks++,
+					exit: () => void counts.exits++,
+				}
+			}),
+		])
+		const execute = makeExecute(entities, systems)
+		counts.expect({enters: 0, ticks: 0, exits: 0})
+
+		const wizardId = change.create({health: 100, mana: 50})
+		execute()
+		counts.expect({enters: 1, ticks: 1, exits: 0})
+
+		change.merge(wizardId, {health: 100, mana: 100})
+		execute()
+		counts.expect({enters: 1, ticks: 2, exits: 0})
+
+		change.delete(wizardId)
+		execute()
+		counts.expect({enters: 1, ticks: 2, exits: 1})
 		expect(entities.size).is(0)
 	}),
+
+	"lifecycle can commit changes": test(async() => {
+		const {entities, change} = setupExample()
+		const systems = asSystems<ExampleComponents>(change => [
+			lifecycle(entities.readonly, ["health"], () => {
+				change.create({mana: 50})
+				return {
+					tick: () => {},
+					exit: () => {},
+				}
+			}),
+		])
+		const execute = makeExecute(entities, systems)
+		change.create({health: 100})
+		execute()
+		expect([...entities.select("mana")].length).is(1)
+	}),
+
+	"lifecycle self-deletion immediate cleanup": test(async() => {
+		const {entities, change} = setupExample()
+		let ranExit = 0
+		const systems = asSystems<ExampleComponents>(change => [
+			lifecycle(entities.readonly, ["health"], (id) => {
+				return {
+					tick: () => change.delete(id),
+					exit: () => { ranExit++ },
+				}
+			}),
+		])
+		const execute = makeExecute(entities, systems)
+		change.create({health: 100})
+		expect([...entities.select("health")].length).is(1)
+		expect(ranExit).is(0)
+		execute()
+		expect(ranExit).is(1)
+		expect([...entities.select("health")].length).is(0)
+	}),
 })
 

package/x/ecs/index.d.ts

@@ -1,7 +1,7 @@
-export * from "./parts/apply-change.js";
+export * from "./parts/apply-delta.js";
 export * from "./parts/change.js";
 export * from "./parts/entities.js";
-export * from "./parts/execute-systems.js";
+export * from "./parts/execute.js";
 export * from "./parts/lifecycle.js";
 export * from "./parts/make-id.js";
 export * from "./parts/types.js";

package/x/ecs/index.js

@@ -1,7 +1,7 @@
-export * from "./parts/apply-change.js";
+export * from "./parts/apply-delta.js";
 export * from "./parts/change.js";
 export * from "./parts/entities.js";
-export * from "./parts/execute-systems.js";
+export * from "./parts/execute.js";
 export * from "./parts/lifecycle.js";
 export * from "./parts/make-id.js";
 export * from "./parts/types.js";