wip: readme and dx

Author: chase-moskal

README.md

@@ -1,3 +1,100 @@
 
-# @benev/marduk
+# MARDUK
+
+**Marduk** is a [BabylonJS](https://www.babylonjs.com/) framework for rendering good web games.
+- 🧵 **Multithreaded** — rendering happens in its own thread
+- 🎳 **Smart architecture** — logic and rendering happen on separate threads
+
+<br/>
+
+## Install Marduk
+
+```sh
+npm install @benev/marduk
+```
+
+<br/>
+
+## Theater
+
+The theater coordinates your rendering thread and displays the results onto a canvas.
+
+The theater is split into two main parts. Each will live in its own separate bundle.
+- *The Frontstage* hosts the visible canvas in the dom. It doesn't import Babylon, and will be lean in filesize.
+- *The Backstage* run inside a web worker, and performs rendering work. It imports Babylon, and will be fat in filesize.
+
+### Theater project setup
+1. Write your `spec.ts` type, which describes your renderable world
+    ```ts
+    export type MySpec = AsFigmentSpec<{
+
+      // Describe all the renderable objects in your world,
+      // in terms of serializable data.
+      hippo: {hungry: boolean}
+    }>
+    ```
+1. Establish your `backstage.ts` module (this will be a web worker)
+    ```ts
+    import {MySpec} from "./spec.js"
+    import {theaterWorker, babylonBackstage} from "@benev/marduk"
+
+    void async function() {
+      await theaterWorker(
+        await babylonBackstage<MySpec>(async stagecraft => ({
+
+          // now we define a renderer for this object
+          hippo: (id, data) => {
+            console.log("spawn", id, data)
+            return {
+              update: data => console.log("update", id, data),
+              dispose: () => console.log("dispose", id, data),
+            }
+          },
+        }))
+      )
+    }()
+    ```
+    - now bundle this module as `backstage.bundle.js` using `rollup`, `esbuild`, `parcel`, `vite`, or whatever
+1. Establish your `frontstage.ts` module (this will be your app's main entrypoint)
+    ```ts
+    import {MySpec} from "./spec.js"
+    import {theaterHost, Frontstage, theaterElement, register} from "@benev/marduk/x/theater/index.js"
+
+    void async function() {
+
+      // relative url to the backstage web worker bundle
+      const workerUrl = new URL("./backstage.bundle.js", import.meta.url)
+
+      // setup the frontstage
+      const frontstage = new Frontstage(
+        await theaterHost<MySpec>({workerUrl})
+      )
+
+      // create the <marduk-theater> web component
+      const MardukTheater = theaterElement(frontstage)
+
+      // register to the dom
+      register({MardukTheater})
+
+      // okay, now you're ready to manipulate your world
+
+      // spawn a hippo
+      await theater.backstage.setFigments([[0, ["hippo", {hungry: false}]]])
+
+      // update the hippo
+      await theater.backstage.setFigments([[0, ["hippo", {hungry: true}]]])
+
+      // delete the hippo
+      await theater.backstage.setFigments([[0, undefined]])
+    }()
+    ```
+    - now bundle this module as `frontstage.bundle.js`
+1. Load the frontstage onto your web page
+    ```html
+    <script type=module src="./frontstage.bundle.js"></script>
+    ```
+1. Place the `<marduk-theater>` element in your html body
+    ```html
+    <marduk-theater></marduk-theater>
+    ```
 

s/demo/theater/front.ts

@@ -11,9 +11,9 @@ export async function demoFrontstage() {
 	})
 
 	// test full lifecycle
-	await theater.thread.work.setFigments([[0, ["hippo", {hungry: false}]]])
-	await theater.thread.work.setFigments([[0, ["hippo", {hungry: true}]]])
-	await theater.thread.work.setFigments([[0, undefined]])
+	await theater.backstage.setFigments([[0, ["hippo", {hungry: false}]]])
+	await theater.backstage.setFigments([[0, ["hippo", {hungry: true}]]])
+	await theater.backstage.setFigments([[0, undefined]])
 
 	return new Frontstage(theater)
 }

s/demo/theater/worker.bundle.ts

@@ -3,18 +3,15 @@ import {DemoFigmentSpec} from "./spec.js"
 import {theaterWorker} from "../../theater/theater-worker.js"
 import {babylonBackstage} from "../../theater/babylon-backstage.js"
 
-const backstage = await babylonBackstage<DemoFigmentSpec>(async stagecraft => {
-	stagecraft.gameloop.start()
-	return {
-		hippo: (id, data) => {
-			console.log("spawn", id, data)
-			return {
-				update: data => console.log("update", id, data),
-				dispose: () => console.log("dispose", id, data),
-			}
-		},
-	}
-})
+const backstage = await babylonBackstage<DemoFigmentSpec>(async stagecraft => ({
+	hippo: (id, data) => {
+		console.log("spawn", id, data)
+		return {
+			update: data => console.log("update", id, data),
+			dispose: () => console.log("dispose", id, data),
+		}
+	},
+}))
 
 theaterWorker(backstage)
 

s/theater/babylon-backstage.ts

@@ -44,6 +44,7 @@ export async function babylonBackstage<Fs extends FigmentSpec>(
 	}
 
 	const spawners = await establish(stagecraft)
+	stagecraft.gameloop.start()
 
 	return {
 		...stagecraft,

s/theater/index.ts

@@ -1,5 +1,9 @@
 
+export {register} from "@benev/slate/x/base/helpers/register.js"
+
 export * from "./parts/types.js"
 export {theaterHost} from "./theater-host.js"
 export {theaterWorker} from "./theater-worker.js"
+export {Frontstage} from "./parts/frontstage.js"
+export {theaterElement} from "./element/element.js"
 

s/theater/parts/types.ts

@@ -1,5 +1,6 @@
 
 import {Sub} from "@e280/stz"
+import {Remote} from "@e280/renraku"
 import {Vec2Array} from "@benev/math"
 import {Spawn} from "../../tools/lifecycler.js"
 import {AsSchematic, Comrade} from "@e280/comrade"
@@ -11,6 +12,7 @@ export type TheaterHostOptions = {
 export type Theater<Fs extends FigmentSpec = any> = {
 	onFrame: Sub<[frame: Frame]>
 	thread: Comrade.Thread<TheaterSchematic<Fs>>
+	backstage: Remote<TheaterSchematic<Fs>["work"]>
 }
 
 export type TheaterSchematic<Fs extends FigmentSpec> = AsSchematic<{