@bendyline/molen-dioramas 0.0.0-stage → 0.0.2
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 +21 -0
- package/README.md +17 -2
- package/dist/client.d.mts +52 -0
- package/dist/client.mjs +215 -0
- package/dist/kernel.d.mts +12 -0
- package/dist/kernel.mjs +73 -0
- package/dist/types-BeCTg5f7.d.mts +50 -0
- package/package.json +72 -3
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
CHANGED
|
@@ -1,3 +1,18 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @bendyline/molen-dioramas
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Bounded scripted set pieces for Molen: a football game, market, fair or other small performance
|
|
4
|
+
that plays when its place is nearby and its host-selected schedule is active.
|
|
5
|
+
|
|
6
|
+
- `/kernel`: `createDiorama` runs an ordinary `molen/scene@3` in a separate deterministic world,
|
|
7
|
+
with local bounds, an entity budget and the figures capability.
|
|
8
|
+
- `/client`: `DioramaDirector` manages proximity, schedules and asynchronous cancellation;
|
|
9
|
+
`createDioramaVisual` attaches an instance to a three.js root; `loadDioramaScene` fetches trusted
|
|
10
|
+
scene JSON and its JavaScript sources on demand.
|
|
11
|
+
|
|
12
|
+
The scripting runtime loads on first activation. Leaving range disposes an instance; returning
|
|
13
|
+
restarts from its seed. Content is separate from this package. The first example is a scripted
|
|
14
|
+
football stadium with players, spectators and a scoreboard.
|
|
15
|
+
|
|
16
|
+
See the [dioramas guide](https://molen.dev/guide/dioramas) for authoring, Earth placement,
|
|
17
|
+
lifecycles and prototype limits. Scripts run with the normal Molen host authority; bounds and
|
|
18
|
+
budgets are authoring guards, not a sandbox.
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import { a as DioramaLoader, c as DioramaStatus, i as DioramaInstance, n as DioramaDefinition, o as DioramaPlacement, r as DioramaFactory, s as DioramaPlayback, t as DioramaBounds } from "./types-BeCTg5f7.mjs";
|
|
2
|
+
import { Vec3 } from "@bendyline/molen-schema";
|
|
3
|
+
import { AssetCache } from "@bendyline/molen-client";
|
|
4
|
+
import * as THREE from "three";
|
|
5
|
+
|
|
6
|
+
//#region src/client/director.d.ts
|
|
7
|
+
interface DioramaDirectorOptions {
|
|
8
|
+
/** Includes loading instances; default 2. */
|
|
9
|
+
maxActive?: number;
|
|
10
|
+
create: DioramaFactory;
|
|
11
|
+
onError?: (error: unknown, id: string) => void;
|
|
12
|
+
}
|
|
13
|
+
/** Proximity/schedule selection and cancellation. No network or kernel is loaded until selected. */
|
|
14
|
+
declare class DioramaDirector {
|
|
15
|
+
private readonly options;
|
|
16
|
+
private readonly entries;
|
|
17
|
+
private readonly pending;
|
|
18
|
+
private readonly maxActive;
|
|
19
|
+
private disposed;
|
|
20
|
+
constructor(options: DioramaDirectorOptions);
|
|
21
|
+
add(placement: DioramaPlacement): void;
|
|
22
|
+
remove(id: string): void;
|
|
23
|
+
list(): readonly string[];
|
|
24
|
+
status(id: string): DioramaStatus | undefined;
|
|
25
|
+
setPosition(id: string, position: Vec3): void;
|
|
26
|
+
/** A failed load/script stays failed until explicitly retried, preventing fetch loops. */
|
|
27
|
+
retry(id: string): void;
|
|
28
|
+
private stop;
|
|
29
|
+
private start;
|
|
30
|
+
/** timeMs is a host clock for eligibility only; scripts advance on their own fixed ticks. */
|
|
31
|
+
update(observer: Vec3, seconds: number, timeMs: number): void;
|
|
32
|
+
whenIdle(): Promise<void>;
|
|
33
|
+
dispose(): void;
|
|
34
|
+
}
|
|
35
|
+
//#endregion
|
|
36
|
+
//#region src/client/visual.d.ts
|
|
37
|
+
interface DioramaVisualOptions {
|
|
38
|
+
/** Attach below the host's floating-origin root. */
|
|
39
|
+
root: THREE.Object3D;
|
|
40
|
+
camera?: THREE.Camera;
|
|
41
|
+
assets?: AssetCache;
|
|
42
|
+
}
|
|
43
|
+
/** Lazy-load the scripting runtime only when a placement is admitted by the director. */
|
|
44
|
+
declare function createDioramaVisual(definition: DioramaDefinition, placement: DioramaPlacement, options: DioramaVisualOptions): Promise<DioramaInstance>;
|
|
45
|
+
/**
|
|
46
|
+
* Fetch a trusted scene and its relative JavaScript sources on demand. TypeScript sources must
|
|
47
|
+
* be erased by the publisher, or bundled with molenScripts() and supplied through a custom loader.
|
|
48
|
+
* No requests happen until the host calls this function. The host owns URL/pack selection.
|
|
49
|
+
*/
|
|
50
|
+
declare function loadDioramaScene(url: URL, bounds: DioramaBounds, signal?: AbortSignal): Promise<DioramaDefinition>;
|
|
51
|
+
//#endregion
|
|
52
|
+
export { type DioramaBounds, type DioramaDefinition, DioramaDirector, type DioramaDirectorOptions, type DioramaFactory, type DioramaInstance, type DioramaLoader, type DioramaPlacement, type DioramaPlayback, type DioramaStatus, type DioramaVisualOptions, createDioramaVisual, loadDioramaScene };
|
package/dist/client.mjs
ADDED
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
import { InterpolationBuffer, SceneMirror, ThreeSceneBackend } from "@bendyline/molen-client";
|
|
2
|
+
import { figureKind } from "@bendyline/molen-figures/client";
|
|
3
|
+
import * as THREE from "three";
|
|
4
|
+
//#region src/client/director.ts
|
|
5
|
+
/** Proximity/schedule selection and cancellation. No network or kernel is loaded until selected. */
|
|
6
|
+
var DioramaDirector = class {
|
|
7
|
+
options;
|
|
8
|
+
entries = /* @__PURE__ */ new Map();
|
|
9
|
+
pending = /* @__PURE__ */ new Set();
|
|
10
|
+
maxActive;
|
|
11
|
+
disposed = false;
|
|
12
|
+
constructor(options) {
|
|
13
|
+
this.options = options;
|
|
14
|
+
this.maxActive = options.maxActive ?? 2;
|
|
15
|
+
if (!Number.isSafeInteger(this.maxActive) || this.maxActive < 0) throw new Error("Diorama maxActive must be a nonnegative integer");
|
|
16
|
+
}
|
|
17
|
+
add(placement) {
|
|
18
|
+
if (this.disposed) throw new Error("Diorama director is disposed");
|
|
19
|
+
if (!placement.id || this.entries.has(placement.id)) throw new Error(`Duplicate or empty diorama id: ${placement.id}`);
|
|
20
|
+
const enter = placement.enterDistance ?? 350;
|
|
21
|
+
const exit = placement.exitDistance ?? enter * 1.2;
|
|
22
|
+
if (!Number.isFinite(enter) || enter < 0 || !Number.isFinite(exit) || exit < enter || placement.position.length !== 3 || placement.position.some((n) => !Number.isFinite(n)) || !Number.isFinite(placement.yaw ?? 0)) throw new Error("Invalid diorama placement distances or pose");
|
|
23
|
+
this.entries.set(placement.id, {
|
|
24
|
+
placement: {
|
|
25
|
+
...placement,
|
|
26
|
+
position: [...placement.position]
|
|
27
|
+
},
|
|
28
|
+
status: "idle"
|
|
29
|
+
});
|
|
30
|
+
}
|
|
31
|
+
remove(id) {
|
|
32
|
+
const entry = this.entries.get(id);
|
|
33
|
+
if (entry) this.stop(entry);
|
|
34
|
+
this.entries.delete(id);
|
|
35
|
+
}
|
|
36
|
+
list() {
|
|
37
|
+
return [...this.entries.keys()];
|
|
38
|
+
}
|
|
39
|
+
status(id) {
|
|
40
|
+
return this.entries.get(id)?.status;
|
|
41
|
+
}
|
|
42
|
+
setPosition(id, position) {
|
|
43
|
+
if (position.length !== 3 || position.some((n) => !Number.isFinite(n))) throw new Error("Invalid diorama position");
|
|
44
|
+
const entry = this.entries.get(id);
|
|
45
|
+
if (!entry || position.every((n, axis) => n === entry.placement.position[axis])) return;
|
|
46
|
+
entry.placement.position = [...position];
|
|
47
|
+
if (entry.instance?.setPosition) entry.instance.setPosition(position);
|
|
48
|
+
else if (entry.instance) this.stop(entry);
|
|
49
|
+
}
|
|
50
|
+
/** A failed load/script stays failed until explicitly retried, preventing fetch loops. */
|
|
51
|
+
retry(id) {
|
|
52
|
+
const entry = this.entries.get(id);
|
|
53
|
+
if (entry?.status === "failed") entry.status = "idle";
|
|
54
|
+
}
|
|
55
|
+
stop(entry) {
|
|
56
|
+
entry.request?.abort();
|
|
57
|
+
entry.request = void 0;
|
|
58
|
+
entry.instance?.dispose();
|
|
59
|
+
entry.instance = void 0;
|
|
60
|
+
if (entry.status !== "failed") entry.status = "idle";
|
|
61
|
+
}
|
|
62
|
+
start(entry) {
|
|
63
|
+
const request = new AbortController();
|
|
64
|
+
entry.request = request;
|
|
65
|
+
entry.status = "loading";
|
|
66
|
+
const pending = Promise.resolve().then(() => {
|
|
67
|
+
request.signal.throwIfAborted();
|
|
68
|
+
return entry.placement.load(request.signal);
|
|
69
|
+
}).then(async (definition) => {
|
|
70
|
+
if (this.disposed || request.signal.aborted || entry.request !== request) return;
|
|
71
|
+
const instance = await this.options.create(definition, entry.placement);
|
|
72
|
+
if (this.disposed || request.signal.aborted || entry.request !== request) {
|
|
73
|
+
instance.dispose();
|
|
74
|
+
return;
|
|
75
|
+
}
|
|
76
|
+
entry.instance = instance;
|
|
77
|
+
instance.setPosition?.(entry.placement.position);
|
|
78
|
+
entry.status = "playing";
|
|
79
|
+
}).catch((error) => {
|
|
80
|
+
if (request.signal.aborted || entry.request !== request) return;
|
|
81
|
+
this.stop(entry);
|
|
82
|
+
entry.status = "failed";
|
|
83
|
+
this.options.onError?.(error, entry.placement.id);
|
|
84
|
+
}).finally(() => {
|
|
85
|
+
this.pending.delete(pending);
|
|
86
|
+
});
|
|
87
|
+
this.pending.add(pending);
|
|
88
|
+
}
|
|
89
|
+
/** timeMs is a host clock for eligibility only; scripts advance on their own fixed ticks. */
|
|
90
|
+
update(observer, seconds, timeMs) {
|
|
91
|
+
if (this.disposed) return;
|
|
92
|
+
if (observer.length !== 3 || observer.some((n) => !Number.isFinite(n)) || !Number.isFinite(timeMs) || !Number.isFinite(seconds) || seconds < 0) throw new Error("Invalid diorama observer, time or elapsed seconds");
|
|
93
|
+
const eligible = [...this.entries.values()].map((entry) => {
|
|
94
|
+
const p = entry.placement;
|
|
95
|
+
const distance = Math.hypot(...p.position.map((n, axis) => n - observer[axis]));
|
|
96
|
+
const radius = entry.status === "playing" || entry.status === "loading" ? p.exitDistance ?? (p.enterDistance ?? 350) * 1.2 : p.enterDistance ?? 350;
|
|
97
|
+
return {
|
|
98
|
+
entry,
|
|
99
|
+
distance,
|
|
100
|
+
eligible: entry.status !== "failed" && distance <= radius && (p.active?.(timeMs) ?? true)
|
|
101
|
+
};
|
|
102
|
+
}).filter((candidate) => candidate.eligible).sort((a, b) => Number(b.entry.status !== "idle") - Number(a.entry.status !== "idle") || a.distance - b.distance);
|
|
103
|
+
const selected = new Set(eligible.slice(0, this.maxActive).map(({ entry }) => entry));
|
|
104
|
+
for (const entry of this.entries.values()) {
|
|
105
|
+
if (!selected.has(entry)) {
|
|
106
|
+
this.stop(entry);
|
|
107
|
+
continue;
|
|
108
|
+
}
|
|
109
|
+
if (entry.status === "idle") this.start(entry);
|
|
110
|
+
if (entry.instance) try {
|
|
111
|
+
entry.instance.update(seconds);
|
|
112
|
+
} catch (error) {
|
|
113
|
+
this.stop(entry);
|
|
114
|
+
entry.status = "failed";
|
|
115
|
+
this.options.onError?.(error, entry.placement.id);
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
async whenIdle() {
|
|
120
|
+
await Promise.all([...this.pending]);
|
|
121
|
+
}
|
|
122
|
+
dispose() {
|
|
123
|
+
this.disposed = true;
|
|
124
|
+
for (const entry of this.entries.values()) this.stop(entry);
|
|
125
|
+
this.entries.clear();
|
|
126
|
+
}
|
|
127
|
+
};
|
|
128
|
+
//#endregion
|
|
129
|
+
//#region src/client/visual.ts
|
|
130
|
+
/** Lazy-load the scripting runtime only when a placement is admitted by the director. */
|
|
131
|
+
async function createDioramaVisual(definition, placement, options) {
|
|
132
|
+
const { createDiorama } = await import("./kernel.mjs");
|
|
133
|
+
const playback = createDiorama(definition);
|
|
134
|
+
const root = new THREE.Group();
|
|
135
|
+
root.name = `diorama:${placement.id}`;
|
|
136
|
+
root.position.fromArray(placement.position);
|
|
137
|
+
root.rotation.y = placement.yaw ?? 0;
|
|
138
|
+
const mirror = new SceneMirror();
|
|
139
|
+
const interpolation = new InterpolationBuffer(playback.tickRate, { delayTicks: 1 });
|
|
140
|
+
let timeMs = 0;
|
|
141
|
+
const backend = new ThreeSceneBackend(root, options.assets);
|
|
142
|
+
backend.registerKind(figureKind());
|
|
143
|
+
backend.bindMirror(mirror);
|
|
144
|
+
const sync = () => {
|
|
145
|
+
interpolation.sampleActive(timeMs, (id, transform) => backend.setTransform(id, transform));
|
|
146
|
+
const renderTick = interpolation.estimateRenderTick(timeMs) ?? playback.tick;
|
|
147
|
+
if (options.camera) backend.updateLiveAnimations(renderTick, playback.tickRate, options.camera);
|
|
148
|
+
else backend.setAnimationTick(renderTick, playback.tickRate);
|
|
149
|
+
backend.prepareFrame();
|
|
150
|
+
};
|
|
151
|
+
const dispose = () => {
|
|
152
|
+
root.removeFromParent();
|
|
153
|
+
backend.dispose();
|
|
154
|
+
playback.dispose();
|
|
155
|
+
};
|
|
156
|
+
try {
|
|
157
|
+
mirror.applyKeyframe(playback.keyframe());
|
|
158
|
+
mirror.reconcile(backend);
|
|
159
|
+
interpolation.push(playback.tick, mirror.transforms(), 0);
|
|
160
|
+
sync();
|
|
161
|
+
await backend.whenReady();
|
|
162
|
+
options.root.add(root);
|
|
163
|
+
} catch (error) {
|
|
164
|
+
dispose();
|
|
165
|
+
throw error;
|
|
166
|
+
}
|
|
167
|
+
return {
|
|
168
|
+
setPosition(position) {
|
|
169
|
+
root.position.fromArray(position);
|
|
170
|
+
},
|
|
171
|
+
update(seconds) {
|
|
172
|
+
const delta = playback.advance(seconds);
|
|
173
|
+
timeMs += Math.min(seconds, .2) * 1e3;
|
|
174
|
+
if (delta) {
|
|
175
|
+
mirror.applyDelta(delta);
|
|
176
|
+
interpolation.pushDelta(delta.tick, mirror.transformChanges(delta), timeMs);
|
|
177
|
+
mirror.reconcile(backend);
|
|
178
|
+
for (const [id, changed] of Object.entries(delta.changed)) if (changed.renderable || changed.light) interpolation.activate(id);
|
|
179
|
+
}
|
|
180
|
+
sync();
|
|
181
|
+
},
|
|
182
|
+
dispose
|
|
183
|
+
};
|
|
184
|
+
}
|
|
185
|
+
/**
|
|
186
|
+
* Fetch a trusted scene and its relative JavaScript sources on demand. TypeScript sources must
|
|
187
|
+
* be erased by the publisher, or bundled with molenScripts() and supplied through a custom loader.
|
|
188
|
+
* No requests happen until the host calls this function. The host owns URL/pack selection.
|
|
189
|
+
*/
|
|
190
|
+
async function loadDioramaScene(url, bounds, signal) {
|
|
191
|
+
const response = await fetch(url, { signal });
|
|
192
|
+
if (!response.ok) throw new Error(`Diorama scene: HTTP ${response.status}`);
|
|
193
|
+
const scene = await response.json();
|
|
194
|
+
const scripts = await Promise.all((scene.scripts ?? []).map(async (script) => {
|
|
195
|
+
if (!script.path) return script;
|
|
196
|
+
const sourceUrl = new URL(script.path, url);
|
|
197
|
+
if (sourceUrl.pathname.endsWith(".ts")) throw new Error("Runtime diorama loads need JavaScript; erase TypeScript at publication or use molenScripts()");
|
|
198
|
+
const loaded = await fetch(sourceUrl, { signal });
|
|
199
|
+
if (!loaded.ok) throw new Error(`Diorama script ${script.id}: HTTP ${loaded.status}`);
|
|
200
|
+
const { path: _path, ...rest } = script;
|
|
201
|
+
return {
|
|
202
|
+
...rest,
|
|
203
|
+
code: await loaded.text()
|
|
204
|
+
};
|
|
205
|
+
}));
|
|
206
|
+
return {
|
|
207
|
+
scene: {
|
|
208
|
+
...scene,
|
|
209
|
+
scripts
|
|
210
|
+
},
|
|
211
|
+
bounds
|
|
212
|
+
};
|
|
213
|
+
}
|
|
214
|
+
//#endregion
|
|
215
|
+
export { DioramaDirector, createDioramaVisual, loadDioramaScene };
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { n as DioramaDefinition, s as DioramaPlayback, t as DioramaBounds } from "./types-BeCTg5f7.mjs";
|
|
2
|
+
|
|
3
|
+
//#region src/kernel.d.ts
|
|
4
|
+
declare function validateDioramaBounds(bounds: DioramaBounds): void;
|
|
5
|
+
/**
|
|
6
|
+
* A diorama is a normal scripted world in local meters. It owns its RNG, entity ids, timers,
|
|
7
|
+
* script state and figures. Discarding one cannot leave systems in the surrounding world.
|
|
8
|
+
* Scripts use the normal trust contract; bounds and budgets are authoring guards, not a sandbox.
|
|
9
|
+
*/
|
|
10
|
+
declare function createDiorama(definition: DioramaDefinition): DioramaPlayback;
|
|
11
|
+
//#endregion
|
|
12
|
+
export { type DioramaBounds, type DioramaDefinition, type DioramaPlayback, createDiorama, validateDioramaBounds };
|
package/dist/kernel.mjs
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
import { figuresScriptApi, installFigures } from "@bendyline/molen-figures/kernel";
|
|
2
|
+
import { Transform, buildWorld, takeDelta, takeKeyframe } from "@bendyline/molen-kernel";
|
|
3
|
+
import { validate } from "@bendyline/molen-schema";
|
|
4
|
+
//#region src/kernel.ts
|
|
5
|
+
function validateDioramaBounds(bounds) {
|
|
6
|
+
if (bounds.min.length !== 3 || bounds.max.length !== 3) throw new Error("Diorama bounds must have three coordinates");
|
|
7
|
+
for (let axis = 0; axis < 3; axis++) {
|
|
8
|
+
const min = bounds.min[axis];
|
|
9
|
+
const max = bounds.max[axis];
|
|
10
|
+
if (min === void 0 || max === void 0 || !Number.isFinite(min) || !Number.isFinite(max) || min >= max) throw new Error("Diorama bounds need finite min < max on every axis");
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* A diorama is a normal scripted world in local meters. It owns its RNG, entity ids, timers,
|
|
15
|
+
* script state and figures. Discarding one cannot leave systems in the surrounding world.
|
|
16
|
+
* Scripts use the normal trust contract; bounds and budgets are authoring guards, not a sandbox.
|
|
17
|
+
*/
|
|
18
|
+
function createDiorama(definition) {
|
|
19
|
+
validateDioramaBounds(definition.bounds);
|
|
20
|
+
const bounds = structuredClone(definition.bounds);
|
|
21
|
+
const budget = definition.maxEntities ?? 512;
|
|
22
|
+
if (!Number.isSafeInteger(budget) || budget < 1) throw new Error("Diorama maxEntities must be a positive integer");
|
|
23
|
+
const checked = validate("scene", definition.scene);
|
|
24
|
+
if (!checked.ok) throw new Error(checked.formatted);
|
|
25
|
+
const scene = checked.value;
|
|
26
|
+
if (scene.physics?.engine === "rapier" || scene.terrain || scene.ambient) throw new Error("Dioramas support scripted/kinematic scenes; terrain, ambient networks and Rapier belong to the host");
|
|
27
|
+
const guard = (world) => {
|
|
28
|
+
if (world.entityCount > budget) throw new Error(`Diorama exceeds its ${budget}-entity budget`);
|
|
29
|
+
for (const [id, transform] of world.query(Transform)) {
|
|
30
|
+
const pos = transform.pos.map((value, axis) => Math.max(bounds.min[axis], Math.min(bounds.max[axis], value)));
|
|
31
|
+
if (pos.some((value, axis) => value !== transform.pos[axis])) world.set(id, Transform, {
|
|
32
|
+
...transform,
|
|
33
|
+
pos
|
|
34
|
+
});
|
|
35
|
+
}
|
|
36
|
+
};
|
|
37
|
+
let world = buildWorld(scene, void 0, { capabilities: [(w) => ({ figures: figuresScriptApi(installFigures(w)) })] });
|
|
38
|
+
guard(world);
|
|
39
|
+
let accumulator = 0;
|
|
40
|
+
let tick = world.tick;
|
|
41
|
+
const tickRate = world.tickRate;
|
|
42
|
+
return {
|
|
43
|
+
get tick() {
|
|
44
|
+
return tick;
|
|
45
|
+
},
|
|
46
|
+
tickRate,
|
|
47
|
+
keyframe() {
|
|
48
|
+
if (!world) throw new Error("Diorama is disposed");
|
|
49
|
+
return takeKeyframe(world);
|
|
50
|
+
},
|
|
51
|
+
advance(seconds) {
|
|
52
|
+
if (!world) return void 0;
|
|
53
|
+
if (!Number.isFinite(seconds) || seconds < 0) throw new Error("Diorama elapsed time must be finite and nonnegative");
|
|
54
|
+
accumulator += Math.min(seconds, .2) * tickRate;
|
|
55
|
+
const steps = Math.floor(accumulator + 1e-9);
|
|
56
|
+
if (steps === 0) return void 0;
|
|
57
|
+
accumulator = Math.max(0, accumulator - steps);
|
|
58
|
+
const baseTick = tick;
|
|
59
|
+
for (let n = 0; n < steps; n++) {
|
|
60
|
+
world.step();
|
|
61
|
+
guard(world);
|
|
62
|
+
}
|
|
63
|
+
tick = world.tick;
|
|
64
|
+
return takeDelta(world, baseTick);
|
|
65
|
+
},
|
|
66
|
+
dispose() {
|
|
67
|
+
world = void 0;
|
|
68
|
+
accumulator = 0;
|
|
69
|
+
}
|
|
70
|
+
};
|
|
71
|
+
}
|
|
72
|
+
//#endregion
|
|
73
|
+
export { createDiorama, validateDioramaBounds };
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { Delta, Keyframe, SceneManifest, Vec3 } from "@bendyline/molen-schema";
|
|
2
|
+
|
|
3
|
+
//#region src/types.d.ts
|
|
4
|
+
/** Local meters, Y up. Bounds constrain entity origins, not mesh extents. */
|
|
5
|
+
interface DioramaBounds {
|
|
6
|
+
min: Vec3;
|
|
7
|
+
max: Vec3;
|
|
8
|
+
}
|
|
9
|
+
/** Ordinary scene data; resolve script paths to code before handing it to playback. */
|
|
10
|
+
interface DioramaDefinition {
|
|
11
|
+
scene: SceneManifest;
|
|
12
|
+
bounds: DioramaBounds;
|
|
13
|
+
/** Per-instance entity budget, including scenery (default 512). */
|
|
14
|
+
maxEntities?: number;
|
|
15
|
+
}
|
|
16
|
+
/** Small synchronous bridge, usable in Node and by the browser visual. */
|
|
17
|
+
interface DioramaPlayback {
|
|
18
|
+
readonly tick: number;
|
|
19
|
+
readonly tickRate: number;
|
|
20
|
+
keyframe(): Keyframe;
|
|
21
|
+
/** Fixed ticks, with at most 0.2 seconds of catch-up per call. */
|
|
22
|
+
advance(seconds: number): Delta | undefined;
|
|
23
|
+
dispose(): void;
|
|
24
|
+
}
|
|
25
|
+
/** A loader is invoked only when a placement is selected for playback. */
|
|
26
|
+
type DioramaLoader = (signal: AbortSignal) => Promise<DioramaDefinition>;
|
|
27
|
+
interface DioramaPlacement {
|
|
28
|
+
id: string;
|
|
29
|
+
load: DioramaLoader;
|
|
30
|
+
position: Vec3;
|
|
31
|
+
/** Rotation about Y, radians. The authored local +Z turns toward +X. */
|
|
32
|
+
yaw?: number;
|
|
33
|
+
/** Meters from the placement origin, including altitude (default 350). */
|
|
34
|
+
enterDistance?: number;
|
|
35
|
+
/** Hysteresis: retain a loaded/loading scene until this distance (default enter * 1.2). */
|
|
36
|
+
exitDistance?: number;
|
|
37
|
+
/** Host clock policy; omitted means always eligible. Never passed into script state. */
|
|
38
|
+
active?: (timeMs: number) => boolean;
|
|
39
|
+
}
|
|
40
|
+
type DioramaStatus = "idle" | "loading" | "playing" | "failed";
|
|
41
|
+
interface DioramaInstance {
|
|
42
|
+
update(seconds: number): void;
|
|
43
|
+
/** Re-anchor scenery without restarting local simulation (e.g. terrain LOD refinement). */
|
|
44
|
+
setPosition?(position: Vec3): void;
|
|
45
|
+
dispose(): void;
|
|
46
|
+
}
|
|
47
|
+
/** Injectable lifecycle boundary; the standard client creates a local world and a Three visual. */
|
|
48
|
+
type DioramaFactory = (definition: DioramaDefinition, placement: DioramaPlacement) => DioramaInstance | Promise<DioramaInstance>;
|
|
49
|
+
//#endregion
|
|
50
|
+
export { DioramaLoader as a, DioramaStatus as c, DioramaInstance as i, DioramaDefinition as n, DioramaPlacement as o, DioramaFactory as r, DioramaPlayback as s, DioramaBounds as t };
|
package/package.json
CHANGED
|
@@ -1,6 +1,75 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bendyline/molen-dioramas",
|
|
3
|
-
"version": "0.0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.0.2",
|
|
4
|
+
"private": false,
|
|
5
|
+
"publishConfig": {
|
|
6
|
+
"access": "public"
|
|
7
|
+
},
|
|
8
|
+
"type": "module",
|
|
9
|
+
"engines": {
|
|
10
|
+
"node": ">=22.13.0"
|
|
11
|
+
},
|
|
12
|
+
"description": "Bounded scripted set pieces: deterministic local scenes and lazy proximity playback",
|
|
13
|
+
"license": "MIT",
|
|
14
|
+
"repository": {
|
|
15
|
+
"type": "git",
|
|
16
|
+
"url": "git+https://github.com/bendyline/molen.git",
|
|
17
|
+
"directory": "packages/dioramas"
|
|
18
|
+
},
|
|
19
|
+
"homepage": "https://github.com/bendyline/molen/tree/main/packages/dioramas",
|
|
20
|
+
"bugs": {
|
|
21
|
+
"url": "https://github.com/bendyline/molen/issues"
|
|
22
|
+
},
|
|
23
|
+
"keywords": [
|
|
24
|
+
"molen",
|
|
25
|
+
"3d",
|
|
26
|
+
"diorama",
|
|
27
|
+
"scripting"
|
|
28
|
+
],
|
|
29
|
+
"exports": {
|
|
30
|
+
"./kernel": {
|
|
31
|
+
"types": "./dist/kernel.d.mts",
|
|
32
|
+
"default": "./dist/kernel.mjs"
|
|
33
|
+
},
|
|
34
|
+
"./client": {
|
|
35
|
+
"types": "./dist/client.d.mts",
|
|
36
|
+
"default": "./dist/client.mjs"
|
|
37
|
+
}
|
|
38
|
+
},
|
|
39
|
+
"files": [
|
|
40
|
+
"dist"
|
|
41
|
+
],
|
|
42
|
+
"dependencies": {
|
|
43
|
+
"@bendyline/molen-figures": "0.0.9",
|
|
44
|
+
"@bendyline/molen-kernel": "0.0.7",
|
|
45
|
+
"@bendyline/molen-schema": "0.0.7"
|
|
46
|
+
},
|
|
47
|
+
"peerDependencies": {
|
|
48
|
+
"three": ">=0.184.0 <0.187.0",
|
|
49
|
+
"@bendyline/molen-client": "0.0.9"
|
|
50
|
+
},
|
|
51
|
+
"peerDependenciesMeta": {
|
|
52
|
+
"@bendyline/molen-client": {
|
|
53
|
+
"optional": true
|
|
54
|
+
},
|
|
55
|
+
"three": {
|
|
56
|
+
"optional": true
|
|
57
|
+
}
|
|
58
|
+
},
|
|
59
|
+
"devDependencies": {
|
|
60
|
+
"@biomejs/biome": "^2.5.0",
|
|
61
|
+
"@types/three": "0.184.0",
|
|
62
|
+
"fast-check": "^3.23.2",
|
|
63
|
+
"three": "0.184.0",
|
|
64
|
+
"tsdown": "^0.22.2",
|
|
65
|
+
"typescript": "^6.0.3",
|
|
66
|
+
"vitest": "^5.0.1",
|
|
67
|
+
"@bendyline/molen-client": "0.0.9"
|
|
68
|
+
},
|
|
69
|
+
"scripts": {
|
|
70
|
+
"build": "tsdown",
|
|
71
|
+
"typecheck": "tsc -p tsconfig.json",
|
|
72
|
+
"lint": "biome check src test && node ../../scripts/check-dmath.mjs src/kernel.ts",
|
|
73
|
+
"test:unit": "vitest run --passWithNoTests"
|
|
74
|
+
}
|
|
6
75
|
}
|