@bendyline/molen-ambient 0.0.3

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/README.md ADDED
@@ -0,0 +1,102 @@
1
+ # @bendyline/molen-ambient
2
+
3
+ Background life for Molen: NPC cars, pedestrians, trains and aircraft that move on a transport
4
+ network built from roads, railways and paths, spawned around an observer and removed behind it.
5
+
6
+ Part of [Molen](https://molen.dev), an AI-legible 3D experience engine: a deterministic headless
7
+ kernel, a three.js client, and a dev loop an agent can drive end to end.
8
+
9
+ ## Install
10
+
11
+ ```sh
12
+ npm i @bendyline/molen-ambient
13
+ ```
14
+
15
+ Node >= 22.13, ESM only. There is deliberately **no `.` export**: import
16
+ `@bendyline/molen-ambient/kernel` or `@bendyline/molen-ambient/client`. The client half needs the
17
+ optional peers `three` (`>=0.184.0 <0.187.0`) and `@bendyline/molen-client`; the kernel half
18
+ needs neither, and runs in a Worker and in Node.
19
+
20
+ ## Use
21
+
22
+ A scene opts in with an `ambient` block. The `molen` CLI installs the capability for any scene
23
+ that has one, so `molen validate`, `molen sim run` and `molen shot` work with no extra wiring:
24
+
25
+ ```json
26
+ {
27
+ "format": "molen/scene@3",
28
+ "name": "crossroads",
29
+ "tickRate": 60,
30
+ "ambient": {
31
+ "network": {
32
+ "format": "molen/transport-network@1",
33
+ "ways": [
34
+ { "class": "road", "subclass": "primary", "points": [[-300, 0], [300, 0]], "lanes": 4 },
35
+ { "class": "road", "subclass": "residential", "points": [[0, -300], [0, 300]] }
36
+ ],
37
+ "signals": [{ "at": [0, 0], "kind": "light" }]
38
+ },
39
+ "observer": "camera-rig",
40
+ "density": { "car": 16 }
41
+ },
42
+ "entities": [
43
+ { "id": "camera-rig", "components": { "transform": { "pos": [30, 0, 30], "rot": [0, 0, 0, 1] } } }
44
+ ]
45
+ }
46
+ ```
47
+
48
+ In a browser, the worker adds the capability and the page adds the renderable kind:
49
+
50
+ ```ts
51
+ // worker.ts
52
+ import { ambientCapability } from '@bendyline/molen-ambient/kernel';
53
+ import { startKernelWorker } from '@bendyline/molen-kernel';
54
+
55
+ startKernelWorker({ scene, capabilities: [ambientCapability()] });
56
+
57
+ // main.ts
58
+ import { ambientVehicleKind } from '@bendyline/molen-ambient/client';
59
+ import { mountExperience } from '@bendyline/molen-client';
60
+
61
+ await mountExperience({ link: worker, scene, canvas, kinds: [ambientVehicleKind()] });
62
+ ```
63
+
64
+ A host that steps its own world installs the kernel directly and feeds it map tiles or documents:
65
+
66
+ ```ts
67
+ import { createAmbientRenderer } from '@bendyline/molen-ambient/client';
68
+ import { installAmbient } from '@bendyline/molen-ambient/kernel';
69
+
70
+ const ambient = installAmbient(world, { classes: ['car', 'pedestrian', 'train'] });
71
+ ambient.addDocument(network);
72
+ ambient.setObserver({ pos: [0, 1.7, 0], forward: [0, 1] });
73
+ const renderer = createAmbientRenderer({ world, parent: scene });
74
+ // each frame: world.step(); renderer.update(cameraPosition, dt);
75
+ ```
76
+
77
+ `@bendyline/molen-earth` runs it on the streamed map by default (`mountEarthView({ ambient })`).
78
+
79
+ ## What's in it
80
+
81
+ | Entry point | For |
82
+ | --- | --- |
83
+ | `./kernel` | The `molen/transport-network@1` format, the lane graph (planar junctions, lanes, connectors, conflicts, signals, tile stitching), the observer-driven spawner, car following, pedestrians, train consists and aircraft corridors, the `ambientAgent` / `ambientObserver` / `ambientRole` components, `ambientCapability` for scenes, and `molen.ambient.*` for scripts. |
84
+ | `./client` | `createAmbientRenderer` for main-thread worlds (instanced proxies, pooled full models near the camera, procedural pedestrian figures, aircraft), and the `ambient-vehicle` renderable kind (`ambientVehicleKind()`) for Worker hosts. |
85
+
86
+ Agent state lives in hashed components; the network, occupancy and signal phases are derived, so
87
+ traffic replays and restores like the rest of the world.
88
+
89
+ ## Status
90
+
91
+ 0.x, versioned independently of the other `@bendyline/molen-*` packages. The
92
+ `molen/transport-network@1` format is versioned and beta. Known limits: map data carries no turn
93
+ restrictions or speed limits, aircraft fly straight corridors, and pedestrians follow their lane
94
+ without stepping around each other.
95
+
96
+ ## Docs
97
+
98
+ - [Ambient life: traffic, pedestrians, trains and aircraft](https://molen.dev/guide/ambient-life)
99
+ - [Earth view](https://molen.dev/guide/earth-view)
100
+ - [Transport network format](https://molen.dev/schemas/transport-network)
101
+
102
+ MIT © Bendyline LLC
@@ -0,0 +1,170 @@
1
+ import { World } from "@bendyline/molen-kernel/world";
2
+ import { AircraftSpec, VehicleData } from "@bendyline/molen-schema";
3
+ import * as THREE from "three";
4
+ import { FigureData } from "@bendyline/molen-figures/client";
5
+ import { RenderableKind } from "@bendyline/molen-client";
6
+
7
+ //#region src/client/aircraft.d.ts
8
+ interface AmbientAircraftModels {
9
+ load(type: string): Promise<THREE.Object3D | undefined>;
10
+ /** The aircraft spec (rotor and gear bindings) of a type, if it is an aircraft type. */
11
+ aircraft(type: string): AircraftSpec | undefined;
12
+ }
13
+ //#endregion
14
+ //#region src/client/proxies.d.ts
15
+ type ProxyShape = "car" | "bus" | "rail" | "aircraft";
16
+ interface ProxyDimensions {
17
+ length: number;
18
+ width: number;
19
+ height: number;
20
+ }
21
+ /** The shape to draw for an agent kind and its dimensions. */
22
+ declare function proxyShapeFor(kind: string, length: number): ProxyShape;
23
+ /** Default body height for a proxy when the type gives none. */
24
+ declare function proxyHeight(shape: ProxyShape, length: number, width: number, type: string): number;
25
+ /** Cached geometry for a shape at given dimensions (rounded to 10 cm). Never dispose it. */
26
+ declare function proxyGeometry(shape: ProxyShape, dims: ProxyDimensions): THREE.BufferGeometry;
27
+ //#endregion
28
+ //#region src/client/batches.d.ts
29
+ interface ProxyInstance {
30
+ shape: ProxyShape;
31
+ dims: ProxyDimensions;
32
+ pos: readonly [number, number, number];
33
+ rot: readonly [number, number, number, number];
34
+ scale: number;
35
+ color: THREE.Color;
36
+ }
37
+ declare class ProxyBatches {
38
+ private readonly prepare?;
39
+ private readonly initialCapacity;
40
+ readonly group: THREE.Group;
41
+ private readonly batches;
42
+ private readonly anchor;
43
+ private readonly matrix;
44
+ private readonly position;
45
+ private readonly quaternion;
46
+ private readonly scale;
47
+ constructor(prepare?: ((object: THREE.Object3D) => void) | undefined, initialCapacity?: number);
48
+ /** Start a frame: keep the anchor within a few hundred metres of the camera. */
49
+ begin(camera: readonly [number, number, number]): void;
50
+ add(instance: ProxyInstance): void;
51
+ /** Finish a frame: upload what changed and cull empty batches from drawing. */
52
+ end(): number;
53
+ private grow;
54
+ /** Number of instanced meshes (draw calls when all are populated). */
55
+ get meshCount(): number;
56
+ dispose(): void;
57
+ }
58
+ //#endregion
59
+ //#region src/client/detail.d.ts
60
+ /** Where full vehicle models come from (absent: every car stays a proxy). */
61
+ interface AmbientVehicleModels {
62
+ /** A fresh model instance for a type, or undefined when the type has no model. */
63
+ load(type: string): Promise<THREE.Object3D | undefined>;
64
+ /** The vehicle data (wheel nodes, paint material, spec) of a type, if it is a vehicle type. */
65
+ vehicle(type: string): VehicleData | undefined;
66
+ }
67
+ interface DetailCandidate {
68
+ id: string;
69
+ type: string;
70
+ color: string;
71
+ distance: number;
72
+ }
73
+ //#endregion
74
+ //#region src/client/figures.d.ts
75
+ interface WalkerView {
76
+ id: string;
77
+ figure: FigureData;
78
+ pos: readonly [number, number, number];
79
+ rot: readonly [number, number, number, number];
80
+ speed: number;
81
+ since: number;
82
+ hidden: boolean;
83
+ }
84
+ interface FigureBudget {
85
+ /** Skinned (animated) figures at most. */
86
+ skinned: number;
87
+ /** Figures beyond this radius (m) are not drawn. */
88
+ radius: number;
89
+ /** Pose evaluations per frame (nearest first, the rest round-robin). */
90
+ posesPerFrame: number;
91
+ }
92
+ declare class AmbientFigures {
93
+ private readonly prepare?;
94
+ readonly group: THREE.Group;
95
+ private readonly cache;
96
+ private readonly material;
97
+ private readonly active;
98
+ private readonly pool;
99
+ private readonly descriptors;
100
+ private budget;
101
+ private cursor;
102
+ private frame;
103
+ constructor(prepare?: ((object: THREE.Object3D) => void) | undefined);
104
+ setBudget(budget: Partial<FigureBudget>): void;
105
+ get count(): number;
106
+ private tierFor;
107
+ private acquire;
108
+ private pooled;
109
+ private releaseMesh;
110
+ /** Update every walker for this frame. */
111
+ update(walkers: readonly WalkerView[], camera: readonly [number, number, number], tick: number, tickRate: number): void;
112
+ private pose;
113
+ dispose(): void;
114
+ }
115
+ //#endregion
116
+ //#region src/client/kind.d.ts
117
+ interface AmbientVehicleKindOptions {
118
+ /** Body heights by type id (default: from the shape). */
119
+ heights?: Readonly<Record<string, number>>;
120
+ }
121
+ /** The `ambient-vehicle` renderable kind (proxy meshes) for Worker-hosted scenes. */
122
+ declare function ambientVehicleKind(options?: AmbientVehicleKindOptions): RenderableKind;
123
+ //#endregion
124
+ //#region src/client/renderer.d.ts
125
+ interface AmbientRenderBudget {
126
+ /** Cars drawn with their full model at most. */
127
+ detailedCars: number;
128
+ /** Animated (skinned) pedestrians at most. */
129
+ skinnedFigures: number;
130
+ /** Pedestrians beyond this distance (m) are not drawn. */
131
+ figureRadius: number;
132
+ /** Pedestrian pose evaluations per frame. */
133
+ posesPerFrame: number;
134
+ }
135
+ interface AmbientRendererOptions {
136
+ world: World;
137
+ /** Parent in absolute world coordinates (e.g. the terrain stream object). */
138
+ parent: THREE.Object3D;
139
+ /** Shader warm-up for new objects (e.g. `renderer.prepareObject`). */
140
+ prepare?: (object: THREE.Object3D) => Promise<void> | void;
141
+ /** Full vehicle models for nearby cars (absent: proxies only). */
142
+ vehicles?: AmbientVehicleModels;
143
+ /** Aircraft models (absent: proxies only). */
144
+ aircraft?: AmbientAircraftModels;
145
+ /** Body heights by type id, for proxies (the kernel stores length and width only). */
146
+ heights?: Readonly<Record<string, number>>;
147
+ budget?: Partial<AmbientRenderBudget>;
148
+ }
149
+ interface AmbientRenderStats {
150
+ cars: number;
151
+ pedestrians: number;
152
+ trains: number;
153
+ aircraft: number;
154
+ proxies: number;
155
+ detailedCars: number;
156
+ figures: number;
157
+ drawBatches: number;
158
+ }
159
+ interface AmbientRenderer {
160
+ readonly object: THREE.Group;
161
+ /** Draw the current world state; `camera` is the absolute camera position. */
162
+ update(camera: readonly [number, number, number], dt: number): void;
163
+ setBudget(budget: Partial<AmbientRenderBudget>): void;
164
+ setVisible(visible: boolean): void;
165
+ stats(): AmbientRenderStats;
166
+ dispose(): void;
167
+ }
168
+ declare function createAmbientRenderer(options: AmbientRendererOptions): AmbientRenderer;
169
+ //#endregion
170
+ export { type AmbientAircraftModels, AmbientFigures, type AmbientRenderBudget, type AmbientRenderStats, type AmbientRenderer, type AmbientRendererOptions, type AmbientVehicleKindOptions, type AmbientVehicleModels, type DetailCandidate, type FigureBudget, ProxyBatches, type ProxyDimensions, type ProxyInstance, type ProxyShape, type WalkerView, ambientVehicleKind, createAmbientRenderer, proxyGeometry, proxyHeight, proxyShapeFor };