@bendyline/molen-client 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Bendyline LLC
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/NOTICE.md ADDED
@@ -0,0 +1,11 @@
1
+ # Sky data and mathematical references
2
+
3
+ This package contains no star data. The clear-sky renderer draws stars from a catalog the app
4
+ supplies, usually the `molen.sky` content pack, which is extracted from Hoffleit and Warren's
5
+ Bright Star Catalogue (CDS V/50) and carries that attribution in its own NOTICE.
6
+
7
+ Sun and Moon orbital formula reference: Paul Schlyter, **How to compute planetary positions**,
8
+ https://www.stjarnhimlen.se/comp/ppcomp.html. Molen implements the formulas independently.
9
+
10
+ Regression position fixtures were generated with Don Cross's MIT-licensed **Astronomy Engine**,
11
+ https://github.com/cosinekitty/astronomy. Astronomy Engine is not bundled or required at runtime.
package/README.md ADDED
@@ -0,0 +1,95 @@
1
+ # @bendyline/molen-client
2
+
3
+ The browser half of Molen: a three.js renderer that syncs itself from a kernel's keyframes and
4
+ deltas over a Worker message port, interpolates between ticks, and turns a scene's camera and
5
+ input blocks into a running experience.
6
+
7
+ Part of [Molen](https://molen.dev), an AI-legible 3D experience engine: a deterministic headless
8
+ kernel, a three.js client, and a dev loop an agent can drive end to end.
9
+
10
+ ## Install
11
+
12
+ ```sh
13
+ npm i @bendyline/molen-client three
14
+ npm i -D @types/three # TypeScript projects
15
+ ```
16
+
17
+ ESM only; the runtime target is the browser, and Node >= 22.13 is what the toolchain around it
18
+ expects. three.js is a **peer dependency** (`>=0.184.0 <0.187.0`, developed against 0.184.0), so
19
+ your app and the engine share one copy and `instanceof` checks hold across them. `@types/three` is
20
+ an optional peer in the same range. The client still re-exports three as `THREE` for convenience.
21
+ The `./vite` subpath is a build-time plugin and the one Node-only entry point.
22
+
23
+ ## Use
24
+
25
+ The page owns the canvas; a Worker owns the simulation. `mountExperience` is the one call that
26
+ joins them:
27
+
28
+ ```ts
29
+ import { mountExperience } from '@bendyline/molen-client';
30
+ import { validate } from '@bendyline/molen-schema';
31
+
32
+ const parsed = validate('scene', await (await fetch('/scene.json')).json());
33
+ if (!parsed.ok) throw new Error(parsed.formatted);
34
+
35
+ const { client, dispose } = await mountExperience({
36
+ link: new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' }),
37
+ scene: parsed.value,
38
+ canvas: document.getElementById('view') as HTMLCanvasElement,
39
+ clearColor: '#11131a',
40
+ });
41
+
42
+ client.command('move', { x: 1, z: 0 });
43
+ client.onEvent('collision', (event, tick) => console.log(event.type, tick));
44
+ client.onError((error) => console.error(error.source, error.message));
45
+ ```
46
+
47
+ It creates the client, applies the scene's `camera` block (fixed / free-fly / top-down-ortho /
48
+ follow), wires the `input` block's bindings and emit rules to `client.command`, keeps the
49
+ renderer sized to the canvas, and returns `{ client, input, dispose }`. The Worker side is
50
+ `buildWorld` + `KernelHost` from `@bendyline/molen-kernel` on the same manifest.
51
+
52
+ Wire `onError` in every experience: it is the only signal for the two failures the simulation
53
+ cannot report about itself — a Worker that died (`source: 'link'`) and an exception escaping the
54
+ render frame (`source: 'frame'`).
55
+
56
+ The mount is asynchronous because it picks a graphics backend. `backend` defaults to `'auto'`:
57
+ WebGPU when the browser has it, the Three.js WebGL renderer otherwise, with
58
+ `client.renderer.backend` reporting which one initialized. Pass `backend: 'webgl'` to skip the
59
+ probe — a pinned backend is what makes a captured frame reproducible.
60
+
61
+ ## What's in it
62
+
63
+ | Entry point | For |
64
+ |---|---|
65
+ | `.` | `mountExperience`, `createClient`, `createSnapshotViewer` (render one keyframe), `createViewer` (no kernel) — all four asynchronous, each taking `backend` — plus `createClientCore` (renderer-free, synchronous), `Renderer`, `ThreeSceneBackend`, `SceneMirror`, `MaterialResolver`, `AssetCache`, `InputMap`, `InterpolationBuffer`, `AdaptiveQualityController`, and a `THREE` re-export |
66
+ | `./camera-track` | `molen/cameratrack@1`: `registerCameraTrackSchema` + `evaluateCameraTrack` for scripted camera moves |
67
+ | `./vite` | `molenScripts()` — a Vite plugin that type-strips `*.ts?raw` scene scripts so the browser never sees TypeScript |
68
+ | `./vehicles` | `createVehicleVisual`, `createParkedVehicleBatch`, `vehicleCameraPose` — car visuals and cockpit/chase views, the render half of `@bendyline/molen-kernel/vehicles` |
69
+ | `./aircraft` | `createAircraftVisual`, `aircraftCameraPose` — animated airframe and instrumented cockpit, the render half of `@bendyline/molen-kernel/aircraft` |
70
+
71
+ Renderables are data, not three.js objects: primitives and glTF assets described by a
72
+ `renderable` component, with materials resolved from `palette:`, `matgraph:` and `pixelgrid:`
73
+ refs at load time. Models and textures come from wherever the app keeps them: an `assets.index`
74
+ of URLs, or any `assets.provider` such as a content pack's (`@bendyline/molen-pack`). Earth skies
75
+ draw stars from a catalog the app supplies (`stars`, or `renderer.setStarCatalog`), usually
76
+ `decodeStarCatalog` of the `molen.sky` pack; this package ships no star data. When you do need the real object, `client.getObject(id)` hands it over (and
77
+ un-batches the entity so your edits stay visible); `client.backend` and `client.renderer` are the
78
+ wider escape hatches.
79
+
80
+ ## Status
81
+
82
+ 0.x. The wrapper surface (`mountExperience`, `client.*`) is the stable part; everything reached
83
+ through `backend`, `renderer` or `getObject` is explicitly unstable — you own whatever you mutate.
84
+ The supported three.js range moves with engine releases, and the engine is developed against
85
+ 0.184.0, so treat 0.184 idioms as authoritative over older ones. WebGPU support is newer than the WebGL path; `backend: 'auto'` reaches for it and falls
86
+ back, and `backend: 'webgl'` opts out.
87
+
88
+ ## Docs
89
+
90
+ - [Mounting an experience in a browser page](https://molen.dev/guide/browser-mount) — worker, scene, page
91
+ - [The three.js surface](https://molen.dev/guide/three-surface) — what the client wraps, and the escape hatch
92
+ - [WebGPU and WebGL](https://molen.dev/guide/rendering-backends) — backend selection and material compatibility
93
+ - [API reference](https://molen.dev/api/client/index)
94
+
95
+ MIT © Bendyline LLC
@@ -0,0 +1,23 @@
1
+ import { n as ModelSignals } from "./model-signals-DVlLyP-w.mjs";
2
+ import { a as VehicleCameraPose, i as VehicleCameraOptions, n as VehicleInteriorVisual } from "./vehicle-interior-0o-8QV_-.mjs";
3
+ import { AircraftInputData, AircraftSpec, AircraftStateData } from "@bendyline/molen-schema";
4
+ import * as THREE from "three";
5
+
6
+ //#region src/aircraft.d.ts
7
+ interface AircraftVisual {
8
+ object: THREE.Object3D;
9
+ interior?: VehicleInteriorVisual;
10
+ update(state: AircraftStateData, input: AircraftInputData, altitude: number, signals?: ModelSignals): void;
11
+ dispose(): void;
12
+ }
13
+ /** Takes ownership of a loaded library GLB. The named nodes remain editable in a DCC. */
14
+ declare function createAircraftVisual(model: THREE.Object3D, spec: AircraftSpec): AircraftVisual;
15
+ interface AircraftCameraPose extends VehicleCameraPose {
16
+ rotation: [number, number, number, number];
17
+ }
18
+ declare function aircraftCameraPose(transform: {
19
+ pos: [number, number, number];
20
+ rot: [number, number, number, number];
21
+ }, spec: AircraftSpec, options: VehicleCameraOptions): AircraftCameraPose;
22
+ //#endregion
23
+ export { AircraftCameraPose, AircraftVisual, aircraftCameraPose, createAircraftVisual };
@@ -0,0 +1,99 @@
1
+ import { t as createVehicleInteriorVisual } from "./vehicle-interior-DZT0HmWC.mjs";
2
+ import * as THREE from "three";
3
+ //#region src/aircraft.ts
4
+ /** Takes ownership of a loaded library GLB. The named nodes remain editable in a DCC. */
5
+ function createAircraftVisual(model, spec) {
6
+ const interior = spec.visual.interior === void 0 ? void 0 : createVehicleInteriorVisual(model, spec.visual.interior);
7
+ const moving = /* @__PURE__ */ new Map();
8
+ model.traverse((o) => {
9
+ o.userData.vehicleGeometry = true;
10
+ if (o instanceof THREE.Mesh) {
11
+ o.castShadow = !o.name.includes("canopy") && !o.name.includes("bubble");
12
+ o.receiveShadow = true;
13
+ }
14
+ const list = moving.get(o.name) ?? [];
15
+ list.push(o);
16
+ moving.set(o.name, list);
17
+ });
18
+ const turn = (name, axis, angle) => {
19
+ for (const node of moving.get(name) ?? []) node.rotation[axis] = angle;
20
+ };
21
+ return {
22
+ object: model,
23
+ interior,
24
+ update(state, input, altitude, signals) {
25
+ for (const binding of spec.visual.rotors) {
26
+ const engine = binding.engine === void 0 ? void 0 : state.engines?.[binding.engine];
27
+ turn(binding.node, binding.axis, (engine?.rotorAngle ?? state.rotorAngle) * binding.multiplier);
28
+ }
29
+ for (const name of spec.visual.gearNodes) for (const node of moving.get(name) ?? []) node.visible = input.gear;
30
+ for (const binding of spec.visual.flaps) turn(binding.node, binding.axis, input.flaps ? binding.multiplier : 0);
31
+ for (const binding of spec.visual.ailerons) turn(binding.node, binding.axis, input.roll * binding.multiplier);
32
+ if (interior === void 0 && spec.visual.controlStick !== void 0) {
33
+ turn(spec.visual.controlStick.node, spec.visual.controlStick.pitchAxis, input.pitch * .22);
34
+ turn(spec.visual.controlStick.node, spec.visual.controlStick.rollAxis, input.roll * .22);
35
+ }
36
+ if (interior === void 0 && spec.visual.collective !== void 0) turn(spec.visual.collective.node, spec.visual.collective.axis, input.power * spec.visual.collective.multiplier);
37
+ interior?.update({
38
+ airspeed: state.airspeed,
39
+ altitude,
40
+ altitudeAGL: state.altitudeAGL,
41
+ heading: state.yaw,
42
+ verticalSpeed: state.verticalSpeed,
43
+ rpm: state.rpm,
44
+ pitch: state.pitch,
45
+ roll: state.roll,
46
+ power: input.power,
47
+ pitchInput: input.pitch,
48
+ rollInput: input.roll,
49
+ yawInput: input.yaw,
50
+ gear: Number(input.gear),
51
+ flaps: Number(input.flaps),
52
+ engine: Number(input.engine),
53
+ ...signals
54
+ });
55
+ },
56
+ dispose() {
57
+ const geometries = /* @__PURE__ */ new Set(), materials = /* @__PURE__ */ new Set();
58
+ model.traverse((o) => {
59
+ if (o instanceof THREE.Mesh) {
60
+ geometries.add(o.geometry);
61
+ for (const m of Array.isArray(o.material) ? o.material : [o.material]) materials.add(m);
62
+ }
63
+ });
64
+ for (const g of geometries) g.dispose();
65
+ for (const m of materials) m.dispose();
66
+ model.removeFromParent();
67
+ }
68
+ };
69
+ }
70
+ function aircraftCameraPose(transform, spec, options) {
71
+ const q = new THREE.Quaternion().fromArray(transform.rot);
72
+ const origin = new THREE.Vector3().fromArray(transform.pos);
73
+ const look = new THREE.Quaternion().setFromEuler(new THREE.Euler(-(options.lookPitch ?? 0), -(options.lookYaw ?? 0), 0, "YXZ"));
74
+ const direction = new THREE.Vector3(0, 0, 1).applyQuaternion(look).applyQuaternion(q);
75
+ let position = new THREE.Vector3().fromArray(spec.pilotEye).applyQuaternion(q).add(origin);
76
+ let target = position.clone().add(direction);
77
+ let up = new THREE.Vector3(0, 1, 0).applyQuaternion(q);
78
+ if (options.view === "chase") {
79
+ target = origin.clone().add(new THREE.Vector3(0, 1.5, 0));
80
+ position = target.clone().addScaledVector(direction, -spec.length * 1.5).add(new THREE.Vector3(0, 4.5, 0));
81
+ const hit = options.obstructionDistance?.(target.toArray(), position.toArray());
82
+ if (hit !== void 0 && hit < target.distanceTo(position)) {
83
+ const offset = position.clone().sub(target).normalize();
84
+ position.copy(target).addScaledVector(offset, Math.max(.3, hit - .3));
85
+ }
86
+ up = new THREE.Vector3(0, 1, 0);
87
+ }
88
+ const forward = target.clone().sub(position).normalize();
89
+ const rotation = new THREE.Quaternion().setFromRotationMatrix(new THREE.Matrix4().lookAt(position, target, up));
90
+ return {
91
+ position: position.toArray(),
92
+ lookAt: target.toArray(),
93
+ rotation: rotation.toArray(),
94
+ yaw: Math.atan2(forward.z, forward.x),
95
+ pitch: Math.asin(forward.y)
96
+ };
97
+ }
98
+ //#endregion
99
+ export { aircraftCameraPose, createAircraftVisual };
@@ -0,0 +1,20 @@
1
+ import { n as CameraPose } from "./renderer-B3pd4N-J.mjs";
2
+
3
+ //#region src/camera-track.d.ts
4
+ interface CameraTrackKeyframe {
5
+ tick: number;
6
+ position: [number, number, number];
7
+ lookAt: [number, number, number];
8
+ }
9
+ interface CameraTrackDoc {
10
+ format: "molen/cameratrack@1";
11
+ easing: "linear" | "smooth";
12
+ loop: boolean;
13
+ keyframes: CameraTrackKeyframe[];
14
+ }
15
+ /** Register the camera-track schema into the shared registry (idempotent). */
16
+ declare function registerCameraTrackSchema(): void;
17
+ /** Interpolated camera pose at a given tick along a (validated) track. */
18
+ declare function evaluateCameraTrack(doc: CameraTrackDoc, tick: number): CameraPose;
19
+ //#endregion
20
+ export { CameraTrackDoc, CameraTrackKeyframe, evaluateCameraTrack, registerCameraTrackSchema };
@@ -0,0 +1,102 @@
1
+ import { t as lerp3 } from "./math-ev_jEkRe.mjs";
2
+ import { registerSchema } from "@bendyline/molen-schema";
3
+ import { z } from "zod";
4
+ //#region src/camera-track.ts
5
+ const trackSchema = z.strictObject({
6
+ format: z.literal("molen/cameratrack@1").describe("Format envelope; always 'molen/cameratrack@1'."),
7
+ easing: z.enum(["linear", "smooth"]).describe("Interpolation between keyframes: linear or smooth (smoothstep; default).").default("smooth"),
8
+ loop: z.boolean().describe("Wrap the tick back to the first keyframe after the last one (default false).").default(false),
9
+ keyframes: z.array(z.strictObject({
10
+ tick: z.number().nonnegative().describe("Tick at which this pose is reached (scene tickRate)."),
11
+ position: z.tuple([
12
+ z.number(),
13
+ z.number(),
14
+ z.number()
15
+ ]).describe("Camera position [x, y, z] in meters (Y-up)."),
16
+ lookAt: z.tuple([
17
+ z.number(),
18
+ z.number(),
19
+ z.number()
20
+ ]).describe("Point [x, y, z] in meters the camera looks at.")
21
+ })).min(1).describe("Camera poses over ticks (at least one; sorted by tick when evaluated).")
22
+ });
23
+ let registered = false;
24
+ /** Register the camera-track schema into the shared registry (idempotent). */
25
+ function registerCameraTrackSchema() {
26
+ if (registered) return;
27
+ registered = true;
28
+ registerSchema("cameratrack", trackSchema, {
29
+ id: "molen/cameratrack@1",
30
+ title: "Camera track",
31
+ description: "Keyframed camera poses over ticks for scripted playback (machinima).",
32
+ examples: [{
33
+ format: "molen/cameratrack@1",
34
+ easing: "smooth",
35
+ keyframes: [{
36
+ tick: 0,
37
+ position: [
38
+ 0,
39
+ 20,
40
+ 40
41
+ ],
42
+ lookAt: [
43
+ 0,
44
+ 0,
45
+ 0
46
+ ]
47
+ }, {
48
+ tick: 120,
49
+ position: [
50
+ 40,
51
+ 20,
52
+ 0
53
+ ],
54
+ lookAt: [
55
+ 0,
56
+ 0,
57
+ 0
58
+ ]
59
+ }]
60
+ }],
61
+ docsRef: "schemas/cameratrack.md"
62
+ });
63
+ }
64
+ function smoothstep(t) {
65
+ return t * t * (3 - 2 * t);
66
+ }
67
+ /** Interpolated camera pose at a given tick along a (validated) track. */
68
+ function evaluateCameraTrack(doc, tick) {
69
+ const kfs = [...doc.keyframes].sort((a, b) => a.tick - b.tick);
70
+ const first = kfs[0];
71
+ const last = kfs[kfs.length - 1];
72
+ const span = last.tick - first.tick;
73
+ let t = tick;
74
+ if (doc.loop && span > 0) t = first.tick + ((tick - first.tick) % span + span) % span;
75
+ if (t <= first.tick) return {
76
+ position: first.position,
77
+ lookAt: first.lookAt
78
+ };
79
+ if (t >= last.tick) return {
80
+ position: last.position,
81
+ lookAt: last.lookAt
82
+ };
83
+ let a = first;
84
+ let b = last;
85
+ for (let i = 0; i < kfs.length - 1; i++) {
86
+ const lo = kfs[i];
87
+ const hi = kfs[i + 1];
88
+ if (t >= lo.tick && t <= hi.tick) {
89
+ a = lo;
90
+ b = hi;
91
+ break;
92
+ }
93
+ }
94
+ let f = b.tick > a.tick ? (t - a.tick) / (b.tick - a.tick) : 0;
95
+ if (doc.easing === "smooth") f = smoothstep(f);
96
+ return {
97
+ position: lerp3(a.position, b.position, f),
98
+ lookAt: lerp3(a.lookAt, b.lookAt, f)
99
+ };
100
+ }
101
+ //#endregion
102
+ export { evaluateCameraTrack, registerCameraTrackSchema };