@benev/archimedes 0.1.0-3 → 0.1.0-4

package/README.md

@@ -1,19 +1,95 @@
 
-![](https://i.imgur.com/JNCvW1J.png)
+![](https://i.imgur.com/DYcrs49.png)
 
-# 🏛️ archimedes netlogic engine
+# 🌀 archimedes, netlogic for multiplayer web games
 
-> [***"do not disturb my circles!"***](https://en.wikipedia.org/wiki/noli_turbare_circulos_meos!)
+> [***"do not disturb my circles!"***](https://en.wikipedia.org/wiki/noli_turbare_circulos_meos!)  
 >     — *archimedes, c. 212 bc*
 
-## rollforward netcode for web games
+```bash
+npm install @benev/archimedes
+```
 
-🔮 **automatic networking**  
-you just code your game naively as though it's singleplayer, archimedes handles the multiplayer.
+- 🧩 [**#ecs,**](#ecs) entities, components, systems.
+- 🔮 [**#sim,**](#sim) code like it's single-player, archimedes makes it multiplayer.
+- 🌎 [**#net,**](#net) whole-world rollforward, everything is clientside predicted for insta-feels.
+
+
+
+<br/><a id="ecs"></a>
+
+## 🧩 ecs — entities, components, systems
+
+```ts
+import {Entities, asSystems, change, executeSystems} from "@benev/archimedes"
+```
+
+1. ***define components.*** json-friendly data that entities could have.
+    ```ts
+    export type MyComponents = {
+      health: number
+      bleed: number
+    }
+    ```
+1. ***create entities map.*** fancy caching for speedy-fast lookups.
+    ```ts
+    export const entitiesWritable = new Entities<MyComponents>()
+
+    // only let systems touch the readonly variant!
+    export const entities = entitiesWritable.readonly()
+    ```
+1. ***define systems.*** select entities by components. yields changes.
+    ```ts
+    const systems = asSystems<MyComponents>(
+      function* bleeding() {
+        for (const [id, components] of entities.select("health", "bleed")) {
+          if (components.bleed >= 0) {
+            const health = components.health - components.bleed
+            const bleed = components.bleed - 1
+            yield change.merge(id, {health, bleed})
+          }
+        }
+      },
+
+      function* death() {
+        for (const [id, components] of entities.select("health")) {
+          if (components.health <= 0)
+            yield change.delete(id)
+        }
+      },
+    )
+    ```
+1. ***create your first entity.***
+    ```ts
+    const wizardId = makeId()
+    entitiesWritable.set(wizardId, {health: 100, bleed: 2})
+
+    console.log(entities.get(wizardId)?.health)
+      // 100
+    ```
+1. ***execute systems to simulate each tick.***
+    ```ts
+    executeSystems(entitiesWritable, systems)
+
+    console.log(entities.get(wizardId)?.health)
+      // 98
+    ```
+
+
+
+<br/><a id="sim"></a>
+
+## 🔮 sim — networkable simulation architecture
+
+*coming soon*
+
+
+
+<br/><a id="net"></a>
+
+## 🌎 net — connect and run multiplayer games
+
+*coming soon*
 
-🌎 **whole-world rollforward**  
-clientside prediction applies to the whole simulation. all effects of player inputs feel instant.
 
-🧩 **ecs architecture**  
-program your simulation with entities, components, and systems.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@benev/archimedes",
-	"version": "0.1.0-3",
+	"version": "0.1.0-4",
 	"description": "game ecs with auto networking",
 	"license": "MIT",
 	"type": "module",
@@ -10,20 +10,20 @@
 		"s"
 	],
 	"scripts": {
-		"build": "octo-s 'rm -rf x' 'mkdir x' 'tsc'",
+		"build": "rm -rf x && mkdir x && tsc",
 		"dev": "octo 'node --watch x/test.js' 'tsc -w'",
 		"test": "node x/test.js",
 		"count": "find s -path '*/_archive' -prune -o -name '*.ts' -exec wc -l {} +"
 	},
 	"dependencies": {
 		"@e280/renraku": "^0.5.7",
-		"@e280/stz": "^0.2.27",
+		"@e280/stz": "^0.2.29",
 		"@msgpack/msgpack": "^3.1.3",
 		"sparrow-rtc": "^0.2.15"
 	},
 	"devDependencies": {
 		"@e280/octo": "^0.1.0",
-		"@e280/science": "^0.1.9",
+		"@e280/science": "^0.1.10",
 		"npm-run-all": "^4.1.5",
 		"typescript": "^6.0.2"
 	},

package/s/ecs/index.ts

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

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

@@ -0,0 +1,33 @@
+
+import {Entities} from "./entities.js"
+import {ChangeSet, Change, Components, ChangeKind, ChangeMerge, ChangeDrop} from "./types.js"
+
+export function applyChange<C extends Components>(entities: Entities<C>, change: Change<C>) {
+	switch (change[0]) {
+		case ChangeKind.Set: return applySet<C>(entities, <ChangeSet<C>>change)
+		case ChangeKind.Merge: return applyMerge<C>(entities, <ChangeMerge<C>>change)
+		case ChangeKind.Drop: return applyDrop<C>(entities, <ChangeDrop<C>>change)
+		default: throw new Error(`unknown change kind "${change[0]}"`)
+	}
+}
+
+function applySet<C extends Components>(entities: Entities<C>, [, id, components]: ChangeSet<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]: ChangeMerge<C>) {
+	const components = entities.guarantee(id, () => ({}))
+	Object.assign(components, patch)
+	entities.set(id, components)
+	return id
+}
+
+function applyDrop<C extends Components>(entities: Entities<C>, [, id, keys]: ChangeDrop<C>) {
+	const components = entities.guarantee(id, () => ({}))
+	for (const key of keys) delete components[key]
+	entities.set(id, components)
+	return id
+}
+

package/s/ecs/parts/change.ts

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

package/s/ecs/parts/entities.ts

@@ -0,0 +1,98 @@
+
+import {GMap} from "@e280/stz"
+import {Components, Id, Select} from "./types.js"
+
+export class Entities<C extends Components> extends GMap<Id, Partial<C>> {
+	#index = new GMap<Set<keyof C>, GMap<Id, Partial<C>>>()
+
+	set(id: Id, components: Partial<C>) {
+		super.set(id, components)
+		for (const [set, entities] of this.#index) {
+			if (componentsSatisfySet(components, set))
+				entities.set(id, components)
+			else
+				entities.delete(id)
+		}
+		return this
+	}
+
+	delete(id: Id) {
+		const didDelete = super.delete(id)
+		if (!didDelete)
+			return false
+
+		for (const entities of this.#index.values())
+			entities.delete(id)
+
+		return true
+	}
+
+	clear() {
+		super.clear()
+		for (const entities of this.#index.values())
+			entities.clear()
+	}
+
+	*select<K extends keyof C>(...componentKeys: K[]): Iterable<[Id, Select<C, K>]> {
+		const cached = this.#getCache(componentKeys)
+		if (cached)
+			yield* cached
+		else
+			yield* this.#makeCache(componentKeys)
+	}
+
+	readonly() {
+		return this as EntitiesReadonly<C>
+	}
+
+	#getCache<K extends keyof C>(componentKeys: K[]) {
+		for (const set of this.#index.keys()) {
+			if (setHasSameValuesAsArray(set, componentKeys))
+				return this.#index.require(set) as GMap<Id, Select<C, K>>
+		}
+	}
+
+	*#makeCache<K extends keyof C>(componentKeys: K[]) {
+		const set = new Set(componentKeys)
+		const entities = new GMap<Id, Partial<C>>()
+		this.#index.set(set, entities)
+
+		for (const entity of this) {
+			const [id, components] = entity
+
+			if (componentsSatisfyKeys(components, componentKeys)) {
+				entities.set(id, components)
+				yield entity as [Id, Select<C, K>]
+			}
+		}
+	}
+}
+
+export type EntitiesReadonly<C extends Components> = Pick<Entities<Readonly<C>>, (
+	| "has"
+	| "get"
+	| "require"
+	| "keys"
+	| "values"
+	| "entries"
+	| "select"
+	| typeof Symbol.iterator
+)>
+
+function componentsSatisfySet(components: Components, set: Set<PropertyKey>) {
+	for (const key of set)
+		if (!(key in components))
+			return false
+	return true
+}
+
+function setHasSameValuesAsArray(set: Set<unknown>, keys: unknown[]) {
+	if (set.size !== keys.length)
+		return false
+	return keys.every(key => set.has(key))
+}
+
+function componentsSatisfyKeys(components: object, keys: PropertyKey[]) {
+	return keys.every(key => key in components)
+}
+

package/s/ecs/parts/execute-systems.ts

@@ -0,0 +1,18 @@
+
+import {Entities} from "./entities.js"
+import {applyChange} from "./apply-change.js"
+import {Change, Components, System} from "./types.js"
+
+export function executeSystems<C extends Components>(entities: Entities<C>, systems: System<C>[]) {
+	const changes: Change<C>[] = []
+
+	for (const system of systems) {
+		for (const change of system()) {
+			applyChange(entities, change)
+			changes.push(change)
+		}
+	}
+
+	return changes
+}
+

package/s/ecs/parts/lifecycle.ts

@@ -0,0 +1,30 @@
+
+import {GMap} from "@e280/stz"
+import {EntitiesReadonly} from "./entities.js"
+import {Components, Id, LifecycleCallbacks, LifecycleEnter} from "./types.js"
+
+export function lifecycle<C extends Components, K extends keyof C>(
+		entities: EntitiesReadonly<C>,
+		componentKeys: K[],
+		enter: LifecycleEnter<C, K>
+	) {
+
+	const alive = new GMap<Id, LifecycleCallbacks<C, K>>()
+	const sel = () => entities.select(...componentKeys)
+
+	return function*() {
+		const current = new Map(sel())
+
+		for (const [id, callbacks] of alive) {
+			if (current.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

@@ -0,0 +1,25 @@
+
+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 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 LifecycleCallbacks<C extends Components, K extends keyof C> = {
+	tick: (id: Id, components: Select<C, K>) => void
+	exit: (id: Id) => void
+}
+
+export type LifecycleEnter<C extends Components, K extends keyof C> = (
+	(id: Id, components: Select<C, K>) => LifecycleCallbacks<C, K>
+)
+

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

@@ -0,0 +1,49 @@
+
+import {change} from "../parts/change.js"
+import {asSystems} from "../parts/types.js"
+import {Entities} from "../parts/entities.js"
+
+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")) {
+				if (components.manaRegen !== 0) {
+					const mana = components.mana + components.manaRegen
+					yield change.merge(id, {mana})
+				}
+			}
+		},
+
+		function* bleeding() {
+			for (const [id, components] of entities.select("health", "bleed")) {
+				if (components.bleed >= 0) {
+					const health = components.health - components.bleed
+					const bleed = components.bleed - 1
+					yield change.merge(id, {health, bleed})
+				}
+				if (components.bleed <= 0)
+					yield change.drop(id, "bleed")
+			}
+		},
+
+		function* death() {
+			for (const [id, components] of entities.select("health")) {
+				if (components.health <= 0)
+					yield change.delete(id)
+			}
+		},
+	)
+
+	return {entities: writableEntities, systems}
+}
+

package/s/ecs/test.ts

@@ -1,96 +1,104 @@
 
 import {suite, test, expect} from "@e280/science"
-import {create, del, update} from "./parts/changers.js"
-import {setupExampleWorld} from "./test/setup-example-world.js"
+import {change} from "./parts/change.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 {setupLifecycleCounts} from "./test/setup-lifecycle-counts.js"
 
 export default suite({
 	"create an entity": test(async() => {
-		const {world} = setupExampleWorld()
-		expect(world.entities.size).is(0)
-		world.apply(create({health: 100}))
-		expect(world.entities.size).is(1)
+		const {entities} = setupExample()
+		expect(entities.size).is(0)
+		applyChange(entities, change.create({health: 100}))
+		expect(entities.size).is(1)
 	}),
 
 	"delete an entity": test(async() => {
-		const {world} = setupExampleWorld()
-		const id = world.apply(create({health: 100}))
-		expect(world.entities.size).is(1)
-		world.apply(del(id))
-		expect(world.entities.size).is(0)
+		const {entities} = setupExample()
+		const id = applyChange(entities, change.create({health: 100}))
+		expect(entities.size).is(1)
+		applyChange(entities, change.delete(id))
+		expect(entities.size).is(0)
 	}),
 
-	"partial updates": test(async() => {
-		const {world} = setupExampleWorld()
-		const id = world.apply(create({health: 100, mana: 100}))
-		expect(world.require(id).health).is(100)
-		world.apply(update(id, {health: 99}))
-		expect(world.require(id).health).is(99)
-		expect(world.require(id).mana).is(100)
+	"merge components into entity": test(async() => {
+		const {entities} = setupExample()
+		const id = applyChange(entities, change.create({health: 100, mana: 100}))
+		expect(entities.require(id).health).is(100)
+		applyChange(entities, change.merge(id, {health: 99}))
+		expect(entities.require(id).health).is(99)
+		expect(entities.require(id).mana).is(100)
 	}),
 
 	"select an entity": test(async() => {
-		const {world} = setupExampleWorld()
-		world.apply(create({health: 100}))
-		expect([...world.select("health")].length).is(1)
+		const {entities} = setupExample()
+		applyChange(entities, change.create({health: 100}))
+		expect([...entities.select("health")].length).is(1)
 	}),
 
-	"select an entity after shape change": test(async() => {
-		const {world} = setupExampleWorld()
-		const id = world.apply(create({health: 100, mana: 100}))
-		expect([...world.select("health", "mana")].length).is(1)
-		world.apply(update(id, {health: 99, mana: null}))
-		expect([...world.select("health", "mana")].length).is(0)
+	"drop components from entity": test(async() => {
+		const {entities} = setupExample()
+		const id = applyChange(entities, change.create({health: 100, mana: 100}))
+		expect([...entities.select("health", "mana")].length).is(1)
+		applyChange(entities, 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 {world} = setupExampleWorld()
-		world.apply(create({health: 100}))
-		world.apply(create({health: 100}))
-		expect([...world.select("health")].length).is(2)
+		const {entities} = setupExample()
+		applyChange(entities, change.create({health: 100}))
+		applyChange(entities, change.create({health: 100}))
+		expect([...entities.select("health")].length).is(2)
 	}),
 
 	"select with no component keys selects all": test(async() => {
-		const {world} = setupExampleWorld()
-		world.apply(create({health: 100}))
-		world.apply(create({health: 100}))
-		expect([...world.select()].length).is(2)
+		const {entities} = setupExample()
+		applyChange(entities, change.create({health: 100}))
+		applyChange(entities, change.create({health: 100}))
+		expect([...entities.select()].length).is(2)
 	}),
 
 	"select doesn't include non-match": test(async() => {
-		const {world} = setupExampleWorld()
-		world.apply(create({health: 100}))
-		expect([...world.select("mana")].length).is(0)
+		const {entities} = setupExample()
+		applyChange(entities, change.create({health: 100}))
+		expect([...entities.select("mana")].length).is(0)
 	}),
 
 	"select includes entities with extra components": test(async() => {
-		const {world} = setupExampleWorld()
-		world.apply(create({health: 100, mana: 100}))
-		expect([...world.select("health")].length).is(1)
+		const {entities} = setupExample()
+		applyChange(entities, change.create({health: 100, mana: 100}))
+		expect([...entities.select("health")].length).is(1)
 	}),
 
 	"wizard regens mana": test(async() => {
-		const {world, systems} = setupExampleWorld()
-		const wizardId = world.apply(create({health: 100, mana: 50, manaRegen: 1}))
-		const changes = world.execute(systems)
+		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)
 		expect(changes.length).is(1)
-		expect(world.require(wizardId).mana).is(51)
+		expect(entities.require(wizardId).mana).is(51)
 	}),
 
 	"death by bleeding": test(async() => {
-		const {world, systems} = setupExampleWorld()
-		const wizardId = world.apply(create({health: 2, bleed: 1}))
-		expect(world.require(wizardId).health).is(2)
-		world.execute(systems)
-		expect(world.require(wizardId).health).is(1)
-		world.execute(systems)
-		expect(world.entities.has(wizardId)).is(false)
+		const {entities, systems} = setupExample()
+		const creating = change.create({health: 3, bleed: 2})
+		const wizardId = creating[1]
+		applyChange(entities, creating)
+		expect(entities.require(wizardId).health).is(3)
+		executeSystems(entities, systems)
+		expect(entities.require(wizardId).health).is(1)
+		executeSystems(entities, systems)
+		expect(entities.has(wizardId)).is(false)
 	}),
 
 	"lifecycles": test(async() => {
-		const {world} = setupExampleWorld()
+		const {entities} = setupExample()
 		const counts = setupLifecycleCounts()
-		const system = world.lifecycle(["health"], () => {
+		const system = lifecycle(entities.readonly(), ["health"], () => {
 			counts.enters++
 			return {
 				tick: () => void counts.ticks++,
@@ -99,18 +107,20 @@ export default suite({
 		})
 		counts.expect(0, 0, 0)
 
-		const wizardId = world.apply(create({health: 100, mana: 50}))
-		world.execute([system])
+		const creating = change.create({health: 100, mana: 50})
+		const wizardId = creating[1]
+		applyChange(entities, creating)
+		executeSystems(entities, [system])
 		counts.expect(1, 1, 0)
 
-		world.apply(update(wizardId, {health: 100, mana: 100}))
-		world.execute([system])
+		applyChange(entities, change.merge(wizardId, {health: 100, mana: 100}))
+		executeSystems(entities, [system])
 		counts.expect(1, 2, 0)
 
-		world.apply(del(wizardId))
-		world.execute([system])
+		applyChange(entities, change.delete(wizardId))
+		executeSystems(entities, [system])
 		counts.expect(1, 2, 1)
-		expect(world.entities.size).is(0)
+		expect(entities.size).is(0)
 	}),
 })
 

package/x/ecs/index.d.ts

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

package/x/ecs/index.js

@@ -1,6 +1,8 @@
-export * from "./parts/changers.js";
-export * as change from "./parts/changers.js";
+export * from "./parts/apply-change.js";
+export * from "./parts/change.js";
+export * from "./parts/entities.js";
+export * from "./parts/execute-systems.js";
+export * from "./parts/lifecycle.js";
 export * from "./parts/make-id.js";
-export * from "./parts/world.js";
-export * from "./types.js";
+export * from "./parts/types.js";
 //# sourceMappingURL=index.js.map

package/x/ecs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../s/ecs/index.ts"],"names":[],"mappings":"AACA,cAAc,qBAAqB,CAAA;AACnC,OAAO,KAAK,MAAM,MAAM,qBAAqB,CAAA;AAC7C,cAAc,oBAAoB,CAAA;AAClC,cAAc,kBAAkB,CAAA;AAEhC,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../s/ecs/index.ts"],"names":[],"mappings":"AACA,cAAc,yBAAyB,CAAA;AACvC,cAAc,mBAAmB,CAAA;AACjC,cAAc,qBAAqB,CAAA;AACnC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,kBAAkB,CAAA"}

package/x/ecs/parts/apply-change.d.ts

@@ -0,0 +1,3 @@
+import { Entities } from "./entities.js";
+import { Change, Components } from "./types.js";
+export declare function applyChange<C extends Components>(entities: Entities<C>, change: Change<C>): string;