@benev/archimedes 0.1.0-1

package/LICENSE

@@ -0,0 +1,23 @@
+
+MIT License
+
+Copyright (c) 2026 Chase Moskal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,19 @@
+
+![](https://i.imgur.com/JNCvW1J.png)
+
+# 🏛️ archimedes netlogic engine
+
+> [***"do not disturb my circles!"***](https://en.wikipedia.org/wiki/noli_turbare_circulos_meos!)
+>     — *archimedes, c. 212 bc*
+
+## rollforward netcode for web games
+
+🔮 **automatic networking**  
+you just code your game naively as though it's singleplayer, archimedes handles the multiplayer.
+
+🌎 **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

@@ -0,0 +1,44 @@
+{
+	"name": "@benev/archimedes",
+	"version": "0.1.0-1",
+	"description": "game ecs with auto networking",
+	"license": "MIT",
+	"type": "module",
+	"main": "x/index.js",
+	"files": [
+		"x",
+		"s"
+	],
+	"scripts": {
+		"build": "octo-s '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",
+		"@msgpack/msgpack": "^3.1.3",
+		"sparrow-rtc": "^0.2.15"
+	},
+	"devDependencies": {
+		"@e280/octo": "^0.1.0",
+		"@e280/science": "^0.1.9",
+		"npm-run-all": "^4.1.5",
+		"typescript": "^6.0.2"
+	},
+	"author": "Chase Moskal <chasemoskal@gmail.com>",
+	"keywords": [
+		"networking",
+		"rollforward",
+		"web-games"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/benevolent-games/archimedes.git"
+	},
+	"bugs": {
+		"url": "https://github.com/benevolent-games/archimedes/issues"
+	},
+	"homepage": "https://github.com/benevolent-games/archimedes#readme"
+}

package/s/_archive/GLOSSARY.md

@@ -0,0 +1,31 @@
+
+## Archimedes Concepts
+
+### Core concepts
+
+**Simulator**  
+Abstract class that holds a game state and a `simulate` method. Also has a `tailor` method which can extract a subset of the state for a specific author.
+- *Author ID*, clarifies who an input is coming from. Host alwaysg gets authorId `0`, each connected client gets a different number.
+- *Telegram*, stream of information about the changing state of a simulation. Includes dispatches about state, delta, and input.
+- *Schema*, the types that a simulator operates on.
+  - `state`, full representation of the game state.
+  - `delta`, partial game state, reprents an update/patch to be applied to the state.
+  - `input`, data that clients send back to the host, which may influence the simulation.
+
+**Liaison**  
+Symmetric comms channel, which handles ping/pongs, jitter-smoothing, inbox and outbox. Clients and hosts use a liaison.
+
+**Authority**  
+Hosting rig. Wires a simulator up with a liaison, providing a tick method that handles all communications.
+
+**Speculator**  
+Client rig. Bundles up a pastSimulator and a futureSimulator, and coordinates with a liaison to implement roll-forward networking. Clientside should render the state of the futureSimulator, as it represents the clientside prediction.
+
+### Session concepts
+
+**SessionHost**  
+Creates an Authority and coordinates metadata and userland api setup.
+
+**SessionClient**  
+Creates a Speculator and coordinates metadata and userland api setup.
+

package/s/_archive/README.md

@@ -0,0 +1,209 @@
+
+![](https://i.imgur.com/JNCvW1J.png)
+
+# 🏛️ Archimedes
+
+> [***"Do not disturb my circles!"***](https://en.wikipedia.org/wiki/Noli_turbare_circulos_meos!)  
+>     — *Archimedes, c. 212 BC*  
+
+## Tournament-grade rollforward netcode for web games
+
+🔮 **Whole-world rollforward:**  
+Player inputs feel instant, and mispredictions correct themselves. It's all automatic, so you don't even have to think about lag when you're coding your game's logic.
+
+🚚 **Transport-agnostic:**  
+Default to free player-hosted games via [Sparrow RTC](https://github.com/benevolent-games/sparrow), but you can swap in webtransport or websockets if you want.
+
+⛵ **Logic-agnostic:**  
+We don't care if your game has fancy-schmancy ECS architecture, or a humble classical setup, whatever: just subclass `Simulator` and it's smooth sailing.
+
+🛟 **Seamless reconnects:**  
+Users *will* accidentally close their browser tab mid-game. Archimedes helps them pick up where they left off, no harm, no foul.
+
+📦 **Npm package `@benev/archimedes`:**  
+Archimedes isn't finished yet, it's under active development.
+
+<br/>
+
+# 🤯 Eureka
+
+> [***"Eureka! I have found it!"***](https://en.wikipedia.org/wiki/Eureka_%28word%29)  
+> &nbsp; &nbsp; — *Archimedes, sometime before 212 BC*  
+
+## An elegant ECS framework
+
+*Eureka* is an Entity-Component-System framework. It was designed alongside Archimedes, and it's the easiest way to get into Archimedes without making a custom Simulator integration. Eureka can be used without Archimedes, and Archimedes can be used without Eureka — but when they're together, it's *a vibe.*
+
+### Eureka quick setup
+
+- Define your context.
+  ```ts
+  // All your systems will have access to this.
+  export class MyContext {}
+  ```
+- Declare all your components.
+  ```ts
+  // Each component can be any serializable data.
+  export type MyComponents = {
+    health: number
+    bleeding: number
+    mana: number
+    manaRegen: number
+  }
+  ```
+- Setup the Eureka helper.  
+  It has your context and component types baked-in.  
+  ```ts
+  import {setupEureka} from "@benev/archimedes"
+
+  export const eureka = setupEureka<MyContext, MyComponents>()
+  ```
+- Create the world, and declare your systems.  
+  Each system selects entities by their components, and runs behaviors on them.  
+  ```ts
+  // Instance your context.
+  const context = new MyContext()
+
+  // Create the world, providing context and an array of systems.
+  const world = eureka.world(context, [
+
+    // Give the system a friendly name.
+    eureka.system("my health system")
+
+      // We select which components this system operates on.
+      .select("health").andMaybe("bleeding")
+
+      // Behavior logic for this system.
+      .fn((entities, world) => {
+        for (const {id, components} of entities) {
+
+          // process bleeding
+          if (components.bleeding)
+            components.health -= components.bleeding
+
+          // process death
+          if (components.health <= 0)
+            world.delete(id)
+        }
+      }),
+
+    eureka.system("mana regeneration")
+      .select("mana", "manaRegen")
+      .fn((entities, _world) => {
+        for (const {components} of entities)
+          components.mana += components.manaRegen
+      }),
+  ])
+  ```
+  - Systems are executed sequentially, from top to bottom.
+  - You can organize your systems into separate files, of course.
+  - Please notice that I painstakingly designed all of this for immaculate typescript typings. You are welcome 😌
+
+### Running a Eureka world that does stuff
+
+Okay, now it's time to put something into the world and watch something happen.
+
+- Add an entity.
+  ```ts
+	const warrior = world.create({health: 100, bleeding: 1})
+  ```
+- Execute world systems (one simulation tick).
+  ```ts
+  world.execute()
+
+  // we see that the bleeding behavior worked.
+  warrior.components.health // 99
+  ```
+- Alright, that's the basics, go ahead and setup a 60hz tickloop.
+  ```ts
+  setInterval(() => world.execute(), 1000 / 60)
+  ```
+
+### Entity method reference
+
+- `entity.id` — the id number for this entity.
+  ```ts
+  entity.id // 123
+  ```
+- `entity.components` — the components object for this entity.
+  ```ts
+  entity.components.health // 99
+  entity.components.bleeding // 1
+  ```
+  - The components object is a proxy, and setting its properties automatically informs the eureka about the change.
+    ```ts
+    entity.components.bleeding = 0 // change auto-detected
+    entity.components.health += 25 // change auto-detected
+    ```
+  - You can also delete components, and that'll be detected
+    ```ts
+    delete entity.components.bleeding // auto-detected
+    ```
+  - If you want to change a component's shape in terms of components, you can do this:
+    ```ts
+    entity.components.health // unhappy typescript, entity doesn't have health
+
+    // updating the entity
+    const entityWithHealth = world.update(entity.id, {
+      ...entity.components,
+      health: 100,
+    })
+
+    entityWithHealth.components.health // happy typescript, knows it has health
+
+    // note, this is really a typescript ergonomics thing
+    entity === entityWithHealth // true
+    ```
+- `entity.write()` — manually inform eureka that you've made changes inside the entity's components.
+  ```ts
+  entity.components.myObject.health += 1 // change inside object, not auto-detected
+  entity.write() // manually tell eureka about the change
+  ```
+
+### World method reference
+
+Creating and updating entities.
+- `world.create(components)` — a new entity.
+  ```ts
+  const wizard = world.create({health: 100, mana: 50, manaRegen: 1})
+  ```
+- `world.update(id, components)` — create or update an entity.
+  ```ts
+  world.write(wizard.id, {health: 100, mana: 75, manaRegen: 1})
+  ```
+
+Getting entities.
+- `world.get(id)` — get an entity by id, or return undefined if not present.
+  ```ts
+  const entity = world.get(id)
+  ```
+- `world.require(id)` — get an entity by id, or throw an error if not present.
+  ```ts
+  const entity = world.require(id)
+  ```
+- `world.all()` — iterate over all entities
+  ```ts
+  for (const entity of world.all)
+    console.log(entity.id)
+  ```
+
+Removing entities.
+- `world.delete(id)` — remove an entity from the world.
+  ```ts
+  world.delete(id)
+  ```
+- `world.clear()` — remove *everything* from the world.
+  ```ts
+  world.clear()
+  ```
+
+Full-world data operations.
+- `world.data()` — iterate over all entity data.
+  ```ts
+  const data = [...world.data()]
+  ```
+- `world.overwrite(data)` — create or update all entities with the provided data.
+  ```ts
+  const entity = world.overwrite(data)
+  ```
+

package/s/_archive/core/authority.ts

@@ -0,0 +1,62 @@
+
+import {Liaison} from "./liaison.js"
+import {Simulator} from "./simulator.js"
+import {Ticker} from "../tools/ticker.js"
+import {IdCounter} from "../tools/id-counter.js"
+import {isInputDispatch} from "./utils/is-input-dispatch.js"
+import {DeltaDispatch, InputDispatch, Schema, StateDispatch, Telegram} from "./types.js"
+
+export class Authority<xSchema extends Schema> {
+	idCounter = new IdCounter()
+	liaisons = new Set<Liaison<Telegram<xSchema>>>()
+	authorId = this.idCounter.next()
+	currentTick = 0
+
+	constructor(public simulator: Simulator<xSchema>) {}
+
+	tick() {
+		const tick = ++this.currentTick
+		const inputDispatches = this.#collectInputDispatches()
+		const delta = this.simulator.simulate([tick, inputDispatches])
+		const deltaDispatch: DeltaDispatch<xSchema> = ["delta", delta]
+
+		const broadcast: Telegram<xSchema> = [
+			tick,
+			[...inputDispatches, deltaDispatch],
+		]
+
+		for (const liaison of this.liaisons) {
+			const tailored = this.simulator.tailor(liaison.authorId, broadcast)
+			liaison.send(tailored)
+		}
+	}
+
+	makeTicker(hz: number) {
+		return new Ticker(hz, () => this.tick())
+	}
+
+	getStateTelegram(): Telegram<xSchema> {
+		const dispatch: StateDispatch<xSchema> = ["state", this.simulator.state]
+		return [this.authorId, [dispatch]]
+	}
+
+	#collectInputDispatches() {
+		const dispatches: InputDispatch<xSchema>[] = []
+
+		for (const liaison of this.liaisons)
+			liaison.recv()
+				.map(([_, dispatches]) => ["input", [
+
+					// overwrite author id to prevent spoofing
+					liaison.authorId,
+
+					// filter for inputs
+					dispatches.filter(isInputDispatch),
+
+				]] as InputDispatch<xSchema>)
+				.forEach(t => dispatches.push(t))
+
+		return dispatches
+	}
+}
+

package/s/_archive/core/contact/codecs.i.ts

@@ -0,0 +1,3 @@
+
+export * as codecs from "./codecs.js"
+

package/s/_archive/core/contact/codecs.ts

@@ -0,0 +1,14 @@
+
+import * as m from "@msgpack/msgpack"
+import {asCodec} from "./types.js"
+
+export const json = asCodec({
+	encode: <D>(data: D) => new TextEncoder().encode(JSON.stringify(data)),
+	decode: <D>(code: Uint8Array) => JSON.parse(new TextDecoder().decode(code)) as D,
+})
+
+export const msgpack = asCodec({
+	encode: <D>(data: D) => m.encode(data),
+	decode: <D>(code: Uint8Array) => m.decode(code) as D,
+})
+

package/s/_archive/core/contact/contact.test.ts

@@ -0,0 +1,32 @@
+
+import {coalesce} from "@e280/stz"
+import {Science, test, expect, spy} from "@e280/science"
+
+import {Contact} from "./contact.js"
+import {wiring} from "./wiring.i.js"
+
+export default Science.suite({
+	"binary exchange": test(async() => {
+		const alice = new Contact<string, number>()
+		const bob = new Contact<Uint8Array>()
+		const charlie = new Contact<Uint8Array>()
+		const debbie = new Contact<number, string>()
+
+		const stop = coalesce(
+			wiring.relayBinary(alice, bob),
+			wiring.relayBinary(debbie, charlie),
+			wiring.exchange(bob, charlie),
+		)
+
+		const debbieRecv = spy((_: number) => {})
+		debbie.recv.on(debbieRecv)
+		expect(debbieRecv.spy.calls.length).is(0)
+
+		alice.send(123, true)
+		expect(debbieRecv.spy.calls.length).is(1)
+		expect(debbieRecv.spy.calls.at(0)!.args[0]).is(123)
+
+		stop()
+	}),
+})
+

package/s/_archive/core/contact/contact.ts

@@ -0,0 +1,63 @@
+
+import {pub} from "@e280/stz"
+import {StdCable} from "sparrow-rtc"
+
+import {json} from "./codecs.js"
+import {ContactInput, Codec} from "./types.js"
+import {exchange, mirror, relayCable} from "./wiring.js"
+
+export class Contact<I = any, O = I> {
+	send = pub<[output: O, reliable: boolean]>()
+	recv = pub<[input: I, reliable: boolean]>()
+
+	/** clear all send and recv listeners */
+	dispose() {
+		this.send.clear()
+		this.recv.clear()
+	}
+
+	/** create a new contact that is an exchange partner (see wiring.exchange) */
+	exchange() {
+		const bob = new Contact<O, I>()
+		const detach = exchange(this, bob)
+		return [bob, detach] as [typeof bob, typeof detach]
+	}
+
+	/** create a new contact that is a mirror (see wiring.mirror) */
+	mirror() {
+		const bob = new Contact<I, O>()
+		const detach = mirror(this, bob)
+		return [bob, detach] as [typeof bob, typeof detach]
+	}
+
+	/** create a new contact that is a relay (see wiring.relay) */
+	relay() {
+		const bob = new Contact<I, O>()
+		const detach = mirror(this, bob)
+		return [bob, detach] as [typeof bob, typeof detach]
+	}
+
+	/** attach an rtc cable to this contact as a relay */
+	relayCable(cable: StdCable, codec: Codec = json) {
+		return relayCable(this, cable, codec)
+	}
+
+	/** roll multiple sub-contacts into a single mega-contact */
+	static multiplex<Sc extends {[key: string]: Contact}>(subcontacts: Sc) {
+		type Submessages = {[K in keyof Sc]: [K, ContactInput<Sc[K]>]}
+		type Submessage = Submessages[keyof Sc]
+		const megacontact = new Contact<Submessage>()
+
+		for (const [key, subcontact] of Object.entries(subcontacts))
+			subcontact.send.on((x, reliable) => megacontact.send([key, x], reliable))
+
+		megacontact.recv.on(([key, data], reliable) => {
+			const subcontact = subcontacts[key as any]
+			if (!subcontact) throw new Error(`unknown subcontact "${key as any}"`)
+			subcontact.recv(data as any, reliable)
+		})
+
+		return megacontact
+	}
+}
+

package/s/_archive/core/contact/types.ts

@@ -0,0 +1,24 @@
+
+import {Contact} from "./contact.js"
+
+/** infer a contact's input data type */
+export type ContactInput<C extends Contact> = (
+	C extends Contact<infer I>
+		? I
+		: never
+)
+
+/** infer a contact's output data type */
+export type ContactOutput<C extends Contact> = (
+	C extends Contact<any, infer O>
+		? O
+		: never
+)
+
+export type Codec = {
+	encode: <Data>(data: Data) => Uint8Array
+	decode: <Data>(code: Uint8Array) => Data
+}
+
+export const asCodec = (t: Codec) => t
+

package/s/_archive/core/contact/wiring.i.ts

@@ -0,0 +1,3 @@
+
+export * as wiring from "./wiring.js"
+