@threenative/core 0.3.4 → 0.3.5
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/capabilities.json +1505 -79
- package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
- package/dist/{canvas-layer-DDmC_VVF.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
- package/dist/{game-CljaDv4D.d.ts → game-Bj8G1wmD.d.ts} +102 -11
- package/dist/hot.d.ts +4 -4
- package/dist/index.d.ts +712 -118
- package/dist/index.js +12423 -4955
- package/dist/{gpu-readback-CqJEfWNQ.d.ts → model-lod-BDAUYgsS.d.ts} +80 -5
- package/dist/playtest.d.ts +6 -10
- package/dist/playtest.js +47 -24
- package/dist/react-css.d.ts +62 -0
- package/dist/react-css.js +591 -0
- package/dist/react.d.ts +2 -2
- package/dist/{renderer-CfsS2hxi.d.ts → renderer-9yEo9hPa.d.ts} +489 -22
- package/dist/terrain-jobs-worker.d.ts +2 -0
- package/dist/terrain-jobs-worker.js +130 -0
- package/dist/ui-layer.js +59 -8
- package/dist/world.d.ts +766 -73
- package/dist/world.js +9307 -3543
- package/gpl/recipes/export_world.py +18 -1
- package/mcp/blender-server.mjs +7 -4
- package/mcp/blender.mjs +3 -4
- package/mcp/engine-server.mjs +2 -2
- package/mcp/servers.mjs +4 -4
- package/package.json +15 -9
- package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
- package/patches/three@0.185.1.patch +6594 -700
- package/scripts/apply-three-patch.mjs +62 -4
- package/src/animation-blend.ts +264 -0
- package/src/animation-composition.ts +362 -0
- package/src/animation-layers.ts +260 -0
- package/src/animation-root-motion.ts +283 -0
- package/src/animation.ts +896 -0
- package/src/assets.ts +1303 -0
- package/src/atmosphere/index.ts +335 -0
- package/src/atmosphere/luts.ts +298 -0
- package/src/atmosphere/params.ts +323 -0
- package/src/audio.ts +912 -0
- package/src/billboard.ts +124 -0
- package/src/bone-lengths.ts +157 -0
- package/src/camera-shake.ts +116 -0
- package/src/canvas-layer.ts +47 -0
- package/src/clip-audit.ts +401 -0
- package/src/clustered-batch.ts +492 -0
- package/src/clustered-mesh.ts +638 -0
- package/src/compute-driven.ts +176 -0
- package/src/compute-timing.ts +318 -0
- package/src/config.ts +593 -0
- package/src/debug.ts +82 -0
- package/src/engine-render-hook.ts +25 -0
- package/src/entities.ts +79 -0
- package/src/entity-snapshot.ts +53 -0
- package/src/flight.ts +683 -0
- package/src/fluid-field.ts +748 -0
- package/src/fluid-particles.ts +1253 -0
- package/src/frame-budget.ts +1368 -0
- package/src/game.ts +2390 -0
- package/src/geometry-capture.ts +1098 -0
- package/src/gpu-class.ts +160 -0
- package/src/gpu-frame-observation.ts +424 -0
- package/src/gpu-readback.ts +143 -0
- package/src/gpu-scene-bvh.ts +464 -0
- package/src/grounding.ts +100 -0
- package/src/hot.ts +161 -0
- package/src/import-meta.d.ts +13 -0
- package/src/index.ts +1536 -0
- package/src/input.ts +690 -0
- package/src/instanced-batch-lod.ts +283 -0
- package/src/instanced-batch.ts +274 -0
- package/src/interpolation.ts +129 -0
- package/src/launch-diagnostics.ts +161 -0
- package/src/loop.ts +564 -0
- package/src/matrix-world.ts +245 -0
- package/src/merge-parts.ts +812 -0
- package/src/model-lod.ts +1315 -0
- package/src/net-protocol.ts +333 -0
- package/src/net-session.ts +477 -0
- package/src/net.ts +80 -0
- package/src/ocean/fft.ts +72 -0
- package/src/ocean/spectral.ts +728 -0
- package/src/particle-significance.ts +102 -0
- package/src/particles.ts +648 -0
- package/src/path-follow.ts +175 -0
- package/src/picking.ts +250 -0
- package/src/pipeline-census.ts +1566 -0
- package/src/platform.ts +210 -0
- package/src/playtest.ts +839 -0
- package/src/pointer-events.ts +411 -0
- package/src/pose-measure.ts +435 -0
- package/src/profiling/FrameCounters.ts +231 -0
- package/src/profiling/Spans.ts +548 -0
- package/src/profiling/opacity-convention.ts +21 -0
- package/src/profiling/render-list-validate.ts +175 -0
- package/src/profiling/render-trap-audit.ts +84 -0
- package/src/profiling/scene-warning.ts +190 -0
- package/src/profiling/span-probes.ts +191 -0
- package/src/profiling/unlit-foliage-warning.ts +149 -0
- package/src/projection-apply.ts +1529 -0
- package/src/projection-marker.ts +142 -0
- package/src/projection-plan.ts +1258 -0
- package/src/projection-skinned.ts +419 -0
- package/src/projection-stability.ts +409 -0
- package/src/projection-uniform.ts +328 -0
- package/src/random.ts +41 -0
- package/src/react-css.ts +604 -0
- package/src/react-glyphs.ts +114 -0
- package/src/react-host.ts +576 -0
- package/src/react-layout.ts +265 -0
- package/src/react.ts +60 -0
- package/src/render/alpha-antialiasing.ts +159 -0
- package/src/render/batched-velocity.ts +126 -0
- package/src/render/chain.ts +1021 -0
- package/src/render/daylight.ts +189 -0
- package/src/render/depth-pyramid.ts +596 -0
- package/src/render/foliage-alpha.ts +166 -0
- package/src/render/material-key.ts +60 -0
- package/src/render/mesh-pool.ts +144 -0
- package/src/render/probe-volume.ts +1668 -0
- package/src/render/resolution-subrect.ts +253 -0
- package/src/render/velocity.ts +442 -0
- package/src/render/virtual-shadow-pages.ts +827 -0
- package/src/render/virtual-shadow-partial.ts +174 -0
- package/src/render/virtual-shadow.ts +3330 -0
- package/src/render/world-impostor-surface.ts +722 -0
- package/src/render/world-impostor.ts +558 -0
- package/src/render-camera-cull.ts +441 -0
- package/src/render-pass-budget.ts +501 -0
- package/src/renderProjection.ts +758 -0
- package/src/renderer-config.ts +127 -0
- package/src/renderer.ts +1847 -0
- package/src/replay-protocol.ts +85 -0
- package/src/replay.ts +205 -0
- package/src/resolution-scaler.ts +819 -0
- package/src/rig-preparation.ts +271 -0
- package/src/ripple-field.ts +432 -0
- package/src/scale.ts +109 -0
- package/src/scene.ts +239 -0
- package/src/schedule.ts +155 -0
- package/src/skeletal-mesh.ts +61 -0
- package/src/skeleton.ts +100 -0
- package/src/snow-field.ts +744 -0
- package/src/softbody-topology.ts +269 -0
- package/src/softbody.ts +516 -0
- package/src/sprite-animator.ts +222 -0
- package/src/startup-readiness.ts +386 -0
- package/src/state.ts +66 -0
- package/src/static-transform.ts +274 -0
- package/src/storage-buffer.ts +253 -0
- package/src/streaming.ts +308 -0
- package/src/target-fps.ts +92 -0
- package/src/terrain-jobs-worker.ts +17 -0
- package/src/terrain-jobs.ts +353 -0
- package/src/textures.ts +39 -0
- package/src/tracers.ts +237 -0
- package/src/ui-bridge.ts +368 -0
- package/src/ui-hit-regions.ts +380 -0
- package/src/ui-layer.ts +83 -0
- package/src/ui-state.ts +220 -0
- package/src/version.ts +2 -0
- package/src/viewport.ts +253 -0
- package/src/warmup.ts +1357 -0
- package/src/water-surface.ts +384 -0
- package/src/wave-field.ts +524 -0
- package/src/world-capabilities.ts +131 -0
- package/src/world-cell-proxy.ts +392 -0
- package/src/world-cells.ts +10564 -0
- package/src/world-gpu-scene.ts +3354 -0
- package/src/world-heightmap.ts +82 -0
- package/src/world-package.ts +469 -0
- package/src/world-passes.ts +582 -0
- package/src/world-region.ts +17 -0
- package/src/world-terrain-splat.ts +564 -0
- package/src/world-tiles.ts +3826 -0
- package/src/world-topology.ts +370 -0
- package/src/world-validate.ts +48 -0
- package/src/world.ts +805 -0
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Why a launch stopped, said where the player can read it.
|
|
3
|
+
*
|
|
4
|
+
* A launch has exactly two ways to go wrong quietly, and both were measured on a real game:
|
|
5
|
+
* progress stops moving (a decode that never returns, an asset that never settles) and the GPU
|
|
6
|
+
* device is lost (another process had taken 94% of VRAM). In both the loop keeps iterating, the
|
|
7
|
+
* loading layer keeps painting, and the only account of what happened is a line on stdout — which
|
|
8
|
+
* a player does not have, and which a bug report therefore never carries.
|
|
9
|
+
*
|
|
10
|
+
* So the failure is reported as text, once, through `onLaunchFailure` — and core stops there. Core
|
|
11
|
+
* cannot draw it: on the native host `document` is a Three.js compatibility stub whose
|
|
12
|
+
* `appendChild` is a no-op, so an overlay written here would be invisible on exactly the target
|
|
13
|
+
* that needs it. The page owns the presentation (and the copy-to-clipboard button players are
|
|
14
|
+
* asked for when they report a launch that hung); this owns the noticing and the wording.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* What failed. `stalled` is "no progress for a while"; `device-lost` is the GPU going away;
|
|
19
|
+
* `scene-load-failed` is a scene's `load()` rejecting and `start-failed` is `start()` rejecting,
|
|
20
|
+
* each of which otherwise reads as a stall.
|
|
21
|
+
*/
|
|
22
|
+
export type LaunchFailureKind = "stalled" | "device-lost" | "scene-load-failed" | "start-failed";
|
|
23
|
+
|
|
24
|
+
const MARKERS: Readonly<Record<LaunchFailureKind, string>> = {
|
|
25
|
+
stalled: "TN_STARTUP_STALLED",
|
|
26
|
+
"device-lost": "TN_DEVICE_LOST",
|
|
27
|
+
"scene-load-failed": "TN_SCENE_LOAD_FAILED",
|
|
28
|
+
"start-failed": "TN_START_FAILED",
|
|
29
|
+
};
|
|
30
|
+
|
|
31
|
+
export interface ILaunchFailure {
|
|
32
|
+
readonly kind: LaunchFailureKind;
|
|
33
|
+
/** One human sentence, already naming the numbers — this is what the Copy button copies. */
|
|
34
|
+
readonly message: string;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
const listeners = new Set<(failure: ILaunchFailure) => void>();
|
|
38
|
+
/** One report per kind: a stalled launch keeps stalling, and a wall of identical panels helps no one. */
|
|
39
|
+
const reported = new Set<LaunchFailureKind>();
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Called for every launch failure the engine notices, with the message to show the player.
|
|
43
|
+
*
|
|
44
|
+
* @situation show the player why the game stopped loading instead of leaving the loading screen up
|
|
45
|
+
* @situation report a stalled launch or a lost GPU device in the game's own UI
|
|
46
|
+
* @example const off = onLaunchFailure((failure) => shell.loading({ failure: failure.message }));
|
|
47
|
+
*/
|
|
48
|
+
export function onLaunchFailure(listener: (failure: ILaunchFailure) => void): () => void {
|
|
49
|
+
listeners.add(listener);
|
|
50
|
+
return () => listeners.delete(listener);
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** Forget what has been reported. Tests and a restarting host need a clean slate. */
|
|
54
|
+
export function resetLaunchFailures(): void {
|
|
55
|
+
reported.clear();
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
export function reportLaunchFailure(failure: ILaunchFailure): void {
|
|
59
|
+
if (reported.has(failure.kind)) return;
|
|
60
|
+
// A launch that failed to start or load stops making progress too; that stall is not news.
|
|
61
|
+
if (
|
|
62
|
+
failure.kind === "stalled" &&
|
|
63
|
+
(reported.has("scene-load-failed") || reported.has("start-failed"))
|
|
64
|
+
)
|
|
65
|
+
return;
|
|
66
|
+
reported.add(failure.kind);
|
|
67
|
+
console.error(`${MARKERS[failure.kind]}: ${failure.message}`);
|
|
68
|
+
for (const listener of listeners) listener(failure);
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
export interface IStallWatchOptions {
|
|
72
|
+
/** 0..1, monotonic — `ctx.startup.progress`. */
|
|
73
|
+
readonly progress: () => number;
|
|
74
|
+
/** Monotonic completed work units, independent of the displayed percentage. Never elapsed time. */
|
|
75
|
+
readonly workProgress?: () => number;
|
|
76
|
+
/** What is still loading, so the report names it rather than saying "something". */
|
|
77
|
+
readonly pending: () => readonly string[];
|
|
78
|
+
/** How long progress may stand still before this is a failure. */
|
|
79
|
+
readonly stallMs: number;
|
|
80
|
+
readonly now?: () => number;
|
|
81
|
+
readonly setInterval?: (callback: () => void, ms: number) => unknown;
|
|
82
|
+
readonly clearInterval?: (handle: unknown) => void;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* Reports when startup progress stops moving. Returns the stop function; call it at readiness.
|
|
87
|
+
*
|
|
88
|
+
* Polled rather than driven by frames on purpose: the failure this catches is precisely a launch
|
|
89
|
+
* whose frames have become rare, and a frame-driven check would go quiet with them. It still needs
|
|
90
|
+
* the loop to yield — a JavaScript callback that never returns cannot be observed from JavaScript,
|
|
91
|
+
* and that one is the host's `TN_SLOW_PHASE` to report.
|
|
92
|
+
*/
|
|
93
|
+
export function watchStartupStall(options: IStallWatchOptions): () => void {
|
|
94
|
+
const now = options.now ?? (() => Date.now());
|
|
95
|
+
const start = options.setInterval ?? ((callback, ms) => setInterval(callback, ms));
|
|
96
|
+
const stop = options.clearInterval ?? ((handle) => clearInterval(handle as never));
|
|
97
|
+
if (!(options.stallMs > 0)) {
|
|
98
|
+
throw new Error(`TN_STARTUP_STALL_MS_INVALID: stallMs must be > 0, got ${options.stallMs}`);
|
|
99
|
+
}
|
|
100
|
+
let lastProgress = options.progress();
|
|
101
|
+
let lastWork = options.workProgress?.() ?? 0;
|
|
102
|
+
let lastMovedAt = now();
|
|
103
|
+
const began = lastMovedAt;
|
|
104
|
+
const handle = start(
|
|
105
|
+
() => {
|
|
106
|
+
const progress = options.progress();
|
|
107
|
+
const work = options.workProgress?.() ?? 0;
|
|
108
|
+
if (progress > lastProgress || (Number.isFinite(work) && work > lastWork)) {
|
|
109
|
+
lastProgress = Math.max(lastProgress, progress);
|
|
110
|
+
if (Number.isFinite(work)) lastWork = Math.max(lastWork, work);
|
|
111
|
+
lastMovedAt = now();
|
|
112
|
+
return;
|
|
113
|
+
}
|
|
114
|
+
const stillMs = now() - lastMovedAt;
|
|
115
|
+
if (stillMs < options.stallMs) return;
|
|
116
|
+
const waiting = options.pending();
|
|
117
|
+
const named =
|
|
118
|
+
waiting.length === 0
|
|
119
|
+
? "nothing — no asset or startup hold is outstanding"
|
|
120
|
+
: waiting.slice(0, 8).join(", ");
|
|
121
|
+
const more = waiting.length > 8 ? ` (+${waiting.length - 8} more)` : "";
|
|
122
|
+
reportLaunchFailure({
|
|
123
|
+
kind: "stalled",
|
|
124
|
+
message:
|
|
125
|
+
`The game stopped loading. No startup work has advanced at ${(progress * 100).toFixed(1)}% for ` +
|
|
126
|
+
`${Math.round(stillMs / 1000)}s, ${Math.round((now() - began) / 1000)}s into the launch.\n` +
|
|
127
|
+
`Still loading: ${named}${more}`,
|
|
128
|
+
});
|
|
129
|
+
stop(handle);
|
|
130
|
+
},
|
|
131
|
+
Math.max(250, Math.min(options.stallMs / 4, 5000)),
|
|
132
|
+
);
|
|
133
|
+
return () => stop(handle);
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/**
|
|
137
|
+
* Reports a lost GPU device. Every backend that can lose one exposes the same `device.lost`
|
|
138
|
+
* promise; a renderer that has no device yet (or never will) is not an error here.
|
|
139
|
+
*/
|
|
140
|
+
export function watchDeviceLoss(
|
|
141
|
+
device: { lost?: Promise<{ reason?: string; message?: string }> } | undefined,
|
|
142
|
+
): void {
|
|
143
|
+
const lost = device?.lost;
|
|
144
|
+
if (lost === undefined) return;
|
|
145
|
+
void lost.then((info) => {
|
|
146
|
+
// `reason: "destroyed"` is the shutdown path: the game asked for it, so it is not a failure.
|
|
147
|
+
if (info?.reason === "destroyed") return;
|
|
148
|
+
// A real loss always says something — WebGPU requires a reason, and Dawn fills in a message.
|
|
149
|
+
// A resolution carrying neither is a host stub settling its own placeholder promise, which the
|
|
150
|
+
// desktop host does at loop start; reporting that would cry wolf on every launch.
|
|
151
|
+
if (info?.reason === undefined && (info?.message === undefined || info.message === "")) return;
|
|
152
|
+
const cause =
|
|
153
|
+
"Nothing can be drawn after this. The usual causes are another process holding the GPU's " +
|
|
154
|
+
"memory, a driver reset, or a single submission that ran long enough to be killed.";
|
|
155
|
+
const named = info?.reason === undefined ? "" : ` (${info.reason})`;
|
|
156
|
+
reportLaunchFailure({
|
|
157
|
+
kind: "device-lost",
|
|
158
|
+
message: `The GPU device was lost${named}: ${info?.message ?? "no reason given"}\n${cause}`,
|
|
159
|
+
});
|
|
160
|
+
});
|
|
161
|
+
}
|