@benev/archimedes 0.1.0-3 → 0.1.0-5

package/README.md

@@ -1,19 +1,89 @@
 
-![](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.
 
-🌎 **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.
+
+<br/><a id="ecs"></a>
+
+## 🧩 ecs — entities, components, systems
+
+```ts
+import {Entities, asSystems, makeId, 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.*** indexed for speedy-fast lookups.
+    ```ts
+    export const entities = new Entities<MyComponents>()
+    ```
+1. ***define systems.*** select entities by components. formal changes.
+    ```ts
+    const systems = asSystems<MyComponents>(
+      function bleeding(entities, change) {
+        for (const [id, components] of entities.select("health", "bleed")) {
+          if (components.bleed > 0) {
+            const health = components.health - components.bleed
+            change.merge(id, {health})
+          }
+        }
+      },
+
+      function death(entities, change) {
+        for (const [id, components] of entities.select("health")) {
+          if (components.health <= 0)
+            change.delete(id)
+        }
+      },
+    )
+    ```
+1. ***manually insert your first entity.***
+    ```ts
+    const wizardId = makeId()
+    entities.set(wizardId, {health: 100, bleed: 2})
+
+    console.log(entities.get(wizardId)?.health)
+      // 100
+    ```
+1. ***execute systems to simulate each tick.***
+    ```ts
+    executeSystems(entities, 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*
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@benev/archimedes",
-	"version": "0.1.0-3",
+	"version": "0.1.0-5",
 	"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-delta.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-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

@@ -0,0 +1,39 @@
+
+import {makeId} from "./make-id.js"
+import {Components, Id, DeltaKind, Delta} from "./types.js"
+
+export class Change<C extends Components> {
+	constructor(private commit: (delta: Delta<C>) => void) {}
+
+	/** create a new entity with the given 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<C>) {
+		this.commit([DeltaKind.Set, id, components])
+		return id
+	}
+
+	/** remove the entity */
+	delete(id: Id) {
+		this.commit([DeltaKind.Set, id])
+		return id
+	}
+
+	/** update or add the given components onto the entity */
+	merge(id: Id, components: Partial<C>) {
+		this.commit([DeltaKind.Merge, id, components])
+		return id
+	}
+
+	/** delete specific components off the entity */
+	drop(id: Id, ...keys: (keyof C)[]) {
+		this.commit([DeltaKind.Drop, id, keys])
+		return id
+	}
+}
+

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,21 @@
+
+import {Change} from "./change.js"
+import {Entities} from "./entities.js"
+import {applyDelta} from "./apply-delta.js"
+import {Delta, Components, System} from "./types.js"
+
+export function executeSystems<C extends Components>(entities: Entities<C>, systems: System<C>[]) {
+	const entitiesReadonly = entities.readonly()
+	const deltas: Delta<C>[] = []
+
+	const change = new Change<C>(delta => {
+		applyDelta(entities, delta)
+		deltas.push(delta)
+	})
+
+	for (const system of systems)
+		system(entitiesReadonly, change)
+
+	return deltas
+}
+

package/s/ecs/parts/lifecycle.ts

@@ -0,0 +1,29 @@
+
+import {GMap} from "@e280/stz"
+import {Components, Id, LifecycleCallbacks, LifecycleEnter, System} from "./types.js"
+
+export function lifecycle<C extends Components, K extends keyof C>(
+		componentKeys: K[],
+		enter: LifecycleEnter<C, K>
+	): System<C> {
+
+	const alive = new GMap<Id, LifecycleCallbacks<C, K>>()
+
+	return (entities, commit) => {
+
+		// add fresh entities
+		for (const [id, components] of entities.select(...componentKeys)) {
+			const callbacks = alive.guarantee(id, () => enter(id, components, commit))
+			callbacks.tick(id, components)
+		}
+
+		// delete stale entities
+		const currentIds = new Set([...entities.select(...componentKeys)].map(([id]) => id))
+		for (const [id, callbacks] of alive) {
+			if (currentIds.has(id)) continue
+			alive.delete(id)
+			callbacks.exit(id)
+		}
+	}
+}
+

package/s/ecs/parts/types.ts

@@ -0,0 +1,28 @@
+
+import {Change} from "./change.js"
+import {EntitiesReadonly} from "./entities.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 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 type System<C extends Components> = (entities: EntitiesReadonly<C>, change: Change<C>) => void
+export const asSystem = <C extends Components>(system: System<C>) => system
+export const asSystems = <C extends Components>(...systems: System<C>[]) => systems
+
+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>, change: Change<C>) => LifecycleCallbacks<C, K>
+)
+

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

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