@threenative/core 0.3.4 → 0.3.6
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-Jz4Fdoeb.d.ts} +114 -11
- package/dist/hot.d.ts +4 -4
- package/dist/index.d.ts +712 -118
- package/dist/index.js +12437 -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 +57 -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 +2408 -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 +574 -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 +850 -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
package/src/config.ts
ADDED
|
@@ -0,0 +1,593 @@
|
|
|
1
|
+
export type ThreeNativeOrientation = "landscape" | "portrait" | "sensor";
|
|
2
|
+
|
|
3
|
+
/** Which renderer draws a game's `src/ui/`. @see IThreeNativeConfig.ui */
|
|
4
|
+
export type ThreeNativeUiRenderer = "native" | "native-css" | "web";
|
|
5
|
+
|
|
6
|
+
/** What the native host does with the render loop while the app is off-screen. */
|
|
7
|
+
export type ThreeNativeBackgroundMode = "continue" | "pause";
|
|
8
|
+
|
|
9
|
+
export interface IThreeNativeIconVariants {
|
|
10
|
+
readonly android?: {
|
|
11
|
+
readonly foreground?: string;
|
|
12
|
+
readonly background?: string;
|
|
13
|
+
readonly monochrome?: string;
|
|
14
|
+
};
|
|
15
|
+
readonly ios?: {
|
|
16
|
+
readonly dark?: string;
|
|
17
|
+
readonly tinted?: string;
|
|
18
|
+
};
|
|
19
|
+
readonly web?: {
|
|
20
|
+
readonly favicon?: string;
|
|
21
|
+
readonly maskable?: string;
|
|
22
|
+
readonly monochrome?: string;
|
|
23
|
+
readonly appleTouch?: string;
|
|
24
|
+
};
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export interface IThreeNativeBootSplash {
|
|
28
|
+
readonly backgroundColor?: string;
|
|
29
|
+
readonly image?: string;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** What a clip is for, stated as a bound on where its energy sits, in the inspector's bands. */
|
|
33
|
+
export interface IThreeNativeAudioSpectrum {
|
|
34
|
+
readonly band: "air" | "high" | "low" | "mid" | "sub";
|
|
35
|
+
/** Most of the clip's energy that may sit in the band. */
|
|
36
|
+
readonly maxPercent?: number;
|
|
37
|
+
/** Least of the clip's energy that must sit in the band. */
|
|
38
|
+
readonly minPercent?: number;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** Loop conditioning for a clip that repeats forever; its seam is cross-faded, then asserted. */
|
|
42
|
+
export interface IThreeNativeAudioLoop {
|
|
43
|
+
/** Equal-power cross-fade in milliseconds. `0` keeps the clip's own length and still asserts. */
|
|
44
|
+
readonly crossFadeMs?: number;
|
|
45
|
+
/** How far the splice may move to find a quiet seam, in milliseconds. */
|
|
46
|
+
readonly spliceToleranceMs?: number;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Per-glob audio declarations. Which clips loop, which are positional, and what a clip is for are
|
|
51
|
+
* facts only the game knows, so they are declared and never inferred from a filename.
|
|
52
|
+
*/
|
|
53
|
+
export interface IThreeNativeAudioOverride {
|
|
54
|
+
/** `"none"` ships these bytes as committed; measurement and a declared loop's assertion run. */
|
|
55
|
+
readonly conditioning?: "none";
|
|
56
|
+
/** First matching override wins; matched against the logical path, e.g. `"audio/bed.ogg"`. */
|
|
57
|
+
readonly glob: string;
|
|
58
|
+
readonly loop?: boolean | IThreeNativeAudioLoop;
|
|
59
|
+
readonly normalise?: "ceiling" | "peak";
|
|
60
|
+
/** Peak ceiling in dBFS, between -60 and 0. */
|
|
61
|
+
readonly peakDb?: number;
|
|
62
|
+
/** The clip plays from a place in the world, so it is downmixed to mono. */
|
|
63
|
+
readonly positional?: boolean;
|
|
64
|
+
/** Vorbis VBR quality, -1 to 10. */
|
|
65
|
+
readonly quality?: number;
|
|
66
|
+
/** The largest wrap-to-neighbourhood step ratio a declared loop may ship with, 1 to 5. */
|
|
67
|
+
readonly seamMaxRatio?: number;
|
|
68
|
+
readonly spectrum?: IThreeNativeAudioSpectrum;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Audio conditioning options for the asset compile step; `"none"` ships clips verbatim.
|
|
73
|
+
*
|
|
74
|
+
* `"ceiling"` normalisation only ever attenuates, keeping the game's relative mix; `"peak"` also
|
|
75
|
+
* lifts a quiet clip to the ceiling.
|
|
76
|
+
*/
|
|
77
|
+
export interface IThreeNativeAudioConfig {
|
|
78
|
+
readonly normalise?: "ceiling" | "peak";
|
|
79
|
+
readonly overrides?: readonly IThreeNativeAudioOverride[];
|
|
80
|
+
readonly peakDb?: number;
|
|
81
|
+
readonly quality?: number;
|
|
82
|
+
readonly seamMaxRatio?: number;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** Texture compression options for the asset compile step; `"none"` ships sources verbatim. */
|
|
86
|
+
export interface IThreeNativeTexturesConfig {
|
|
87
|
+
/** Automatic compression floor; omitted fields default to SSIM 0.95 and mean ΔE00 3. */
|
|
88
|
+
readonly floor?: { readonly ssim?: number; readonly meanDeltaE00?: number };
|
|
89
|
+
/** Scalar or glTF slot map (e.g. baseColorTexture/normalTexture). Integer at least 4; caps the longest edge, preserving aspect and 4x4 alignment; never upscales. */
|
|
90
|
+
readonly maxSize?: number | Readonly<Record<string, number>>;
|
|
91
|
+
readonly overrides?: readonly {
|
|
92
|
+
readonly codec: "etc1s" | "none" | "uastc";
|
|
93
|
+
readonly glob: string;
|
|
94
|
+
readonly quality?: number;
|
|
95
|
+
}[];
|
|
96
|
+
/** ETC1S encoder quality 1–255. Ignored for UASTC. */
|
|
97
|
+
readonly quality?: number;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** Model optimization sub-pass switches; absent means every pass runs. */
|
|
101
|
+
export interface IThreeNativeModelPassesConfig {
|
|
102
|
+
readonly dedup?: boolean;
|
|
103
|
+
readonly meshopt?: boolean;
|
|
104
|
+
readonly prune?: boolean;
|
|
105
|
+
readonly quantize?: boolean;
|
|
106
|
+
readonly reorder?: boolean;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** Model optimization options for the asset compile step; `"none"` ships sources verbatim. */
|
|
110
|
+
export interface IThreeNativeModelsConfig {
|
|
111
|
+
/**
|
|
112
|
+
* Lossless scene-graph compaction: flatten empty transform chains, join sibling primitives
|
|
113
|
+
* that share a material, and batch a mesh several nodes reuse as `EXT_mesh_gpu_instancing`.
|
|
114
|
+
*
|
|
115
|
+
* On by default; `false` ships the scene graph as authored. A node matching `protectedPattern`,
|
|
116
|
+
* named in `protectedNames`, targeted by an animation or a skin joint is never merged or
|
|
117
|
+
* instanced, so an exact-name lookup or a bone-driven node survives.
|
|
118
|
+
*/
|
|
119
|
+
readonly compact?:
|
|
120
|
+
| boolean
|
|
121
|
+
| {
|
|
122
|
+
readonly flatten?: boolean;
|
|
123
|
+
readonly instance?: boolean | { readonly min?: number };
|
|
124
|
+
readonly join?: boolean;
|
|
125
|
+
readonly protectedNames?: readonly string[];
|
|
126
|
+
readonly protectedPattern?: string;
|
|
127
|
+
};
|
|
128
|
+
/** Standard glTF TEXCOORD_1 atlas generation for offline static-light assets. */
|
|
129
|
+
readonly lightmap?: {
|
|
130
|
+
readonly atlasSize: number;
|
|
131
|
+
readonly padding: number;
|
|
132
|
+
};
|
|
133
|
+
readonly passes?: IThreeNativeModelPassesConfig;
|
|
134
|
+
readonly quantize?: {
|
|
135
|
+
readonly normalBits?: number;
|
|
136
|
+
readonly positionBits?: number;
|
|
137
|
+
readonly uvBits?: number;
|
|
138
|
+
};
|
|
139
|
+
/**
|
|
140
|
+
* Write each distinct embedded image once under `shared/images/` and reference it from every
|
|
141
|
+
* model that carries it. A marketplace pack whose eight pines all embed the same bark map then
|
|
142
|
+
* ships and encodes it once. Default true; false embeds and re-encodes duplicate images in
|
|
143
|
+
* each model. The served GLB references files beside it.
|
|
144
|
+
*/
|
|
145
|
+
readonly sharedImages?: boolean;
|
|
146
|
+
/**
|
|
147
|
+
* Embedded-texture compression for images carried inside a `.glb`.
|
|
148
|
+
*
|
|
149
|
+
* On by default in the compile step; `"none"` ships every embedded image exactly as
|
|
150
|
+
* authored. `maxSize` caps the longest edge, preserving aspect and snapping to whole 4x4
|
|
151
|
+
* blocks, and never upscales.
|
|
152
|
+
*/
|
|
153
|
+
readonly textures?:
|
|
154
|
+
| "none"
|
|
155
|
+
| {
|
|
156
|
+
readonly floor?: { readonly ssim?: number; readonly meanDeltaE00?: number };
|
|
157
|
+
/** Scalar or glTF slot map; unlisted slots retain the 2048 default. Shared images use the largest cap. */
|
|
158
|
+
readonly maxSize?: number | Readonly<Record<string, number>>;
|
|
159
|
+
readonly quality?: number;
|
|
160
|
+
readonly overrides?: readonly {
|
|
161
|
+
readonly slot: string;
|
|
162
|
+
readonly codec: "etc1s" | "none" | "uastc";
|
|
163
|
+
}[];
|
|
164
|
+
};
|
|
165
|
+
/**
|
|
166
|
+
* Mesh simplification. Absent means none at all, which is the default.
|
|
167
|
+
*
|
|
168
|
+
* `ratio` is the fraction of triangles to keep. `error` is a quality guard rather than a
|
|
169
|
+
* target — the largest a vertex may move as a fraction of the mesh's extent — so a loose
|
|
170
|
+
* ratio with a tight error stops short, and the compile step reports the ratio it actually
|
|
171
|
+
* achieved next to the one that was asked for.
|
|
172
|
+
*/
|
|
173
|
+
readonly simplify?: {
|
|
174
|
+
readonly ratio: number;
|
|
175
|
+
readonly error?: number;
|
|
176
|
+
};
|
|
177
|
+
/**
|
|
178
|
+
* Cluster-DAG bake for virtual geometry, or `"none"` to ship every primitive as authored.
|
|
179
|
+
*
|
|
180
|
+
* Absent means on with defaults: any primitive of 65,536 triangles or more bakes to a cluster
|
|
181
|
+
* DAG the loader turns into a `ClusteredMesh`, and everything below that line compiles
|
|
182
|
+
* byte-identically. The payload costs roughly 3-4x the primitive's compiled bytes, which is
|
|
183
|
+
* what `"none"` and `minSourceTriangles` are for.
|
|
184
|
+
*/
|
|
185
|
+
readonly virtual?:
|
|
186
|
+
| "none"
|
|
187
|
+
| {
|
|
188
|
+
/** Clusters folded together per group, default 4. */
|
|
189
|
+
readonly groupSize?: number;
|
|
190
|
+
/** Upper bound on a cluster's triangles, default 128. */
|
|
191
|
+
readonly maxTriangles?: number;
|
|
192
|
+
/** Lower bound on a cluster's triangles, default 96. */
|
|
193
|
+
readonly minTriangles?: number;
|
|
194
|
+
/** Primitives below this many triangles are left alone, default 65,536. */
|
|
195
|
+
readonly minSourceTriangles?: number;
|
|
196
|
+
/** Fraction of a group's triangles kept per level, default 0.5. */
|
|
197
|
+
readonly simplifyRatio?: number;
|
|
198
|
+
};
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
/** Quality policy for automatic discrete LOD; it picks the projected pixel-error budget. */
|
|
202
|
+
export type ThreeNativeLodPreset = "aggressive" | "balanced" | "quality";
|
|
203
|
+
|
|
204
|
+
/** What the `minTriangles` pre-filter is measured against. */
|
|
205
|
+
export type ThreeNativeLodMinTrianglesScope = "primitive" | "asset";
|
|
206
|
+
|
|
207
|
+
/** Generation knobs shared by every preset. All are ceilings or filters, not promises. */
|
|
208
|
+
export interface IThreeNativeLodGenerationConfig {
|
|
209
|
+
/**
|
|
210
|
+
* Increasing geometric-error targets in normalized mesh-extent units; 1–16 positive finite
|
|
211
|
+
* numbers that strictly increase. Default `[0.002, 0.006, 0.02, 0.06]`. Each is simplified from
|
|
212
|
+
* LOD0 independently and a target that cannot reduce is dropped.
|
|
213
|
+
*/
|
|
214
|
+
readonly errorTargets?: readonly number[];
|
|
215
|
+
/** Levels in the chain **including LOD0**; integer 1–8, default 4. `1` emits nothing derived. */
|
|
216
|
+
readonly maxLevels?: number;
|
|
217
|
+
/**
|
|
218
|
+
* Fraction of its predecessor's triangles a derived level must save to be kept; finite in
|
|
219
|
+
* `[0, 1)`, default `0.2`. This is the benefit gate — a mesh that cannot reach it is skipped
|
|
220
|
+
* with `insufficient-reduction`, which is a normal outcome, not an error.
|
|
221
|
+
*/
|
|
222
|
+
readonly minSaving?: number;
|
|
223
|
+
/**
|
|
224
|
+
* Cheap pre-filter floor in triangles; positive integer, default `128`. It only avoids
|
|
225
|
+
* clearly-pointless work (the simplifier's fixed per-call cost); `minSaving` is the real gate.
|
|
226
|
+
*/
|
|
227
|
+
readonly minTriangles?: number;
|
|
228
|
+
/**
|
|
229
|
+
* What `minTriangles` is measured against; `"primitive"` or `"asset"`, default `"asset"`. The
|
|
230
|
+
* asset scope measures the whole model, so a model split into many small primitives is still
|
|
231
|
+
* eligible on its total.
|
|
232
|
+
*/
|
|
233
|
+
readonly minTrianglesScope?: ThreeNativeLodMinTrianglesScope;
|
|
234
|
+
/**
|
|
235
|
+
* Opt-in far rung that joins a mesh's same-material primitives into one draw per material group.
|
|
236
|
+
* Default `false`: with no option the cook is byte-identical to today. A join never crosses a
|
|
237
|
+
* material, never touches a skinned, morph-target or animated node, and never leaves the mesh's
|
|
238
|
+
* own node, so authored LOD0, node identity, per-node visibility, picking and transforms are
|
|
239
|
+
* untouched; the joined geometry is an additional far rung beside LOD0.
|
|
240
|
+
*/
|
|
241
|
+
readonly join?: boolean;
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
/** Screen-space selection knobs. */
|
|
245
|
+
export interface IThreeNativeLodRuntimeConfig {
|
|
246
|
+
/** Projected geometric-error budget in raster pixels; positive finite. Default by preset. */
|
|
247
|
+
readonly maxPixelError?: number;
|
|
248
|
+
/** Fraction in `[0, 0.5)`, default 0.15, that stabilizes coarsening at a boundary. */
|
|
249
|
+
readonly hysteresis?: number;
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/** A partial override for one asset; nested objects overlay, they never replace. */
|
|
253
|
+
export interface IThreeNativeLodOverride {
|
|
254
|
+
readonly enabled?: boolean;
|
|
255
|
+
readonly generation?: IThreeNativeLodGenerationConfig;
|
|
256
|
+
readonly preset?: ThreeNativeLodPreset;
|
|
257
|
+
readonly runtime?: IThreeNativeLodRuntimeConfig;
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
/**
|
|
261
|
+
* Automatic discrete LOD policy. `{}` resolves to enabled/balanced and any explicit block turns
|
|
262
|
+
* generation on; `false` and `{ enabled: false }` are equivalent absolute kill switches that no
|
|
263
|
+
* per-asset override can re-enable. Overrides are keyed by canonical project-relative source asset
|
|
264
|
+
* (`/` separators).
|
|
265
|
+
*
|
|
266
|
+
* Omission currently bakes nothing: the default-on front door opens only after the qualification
|
|
267
|
+
* phase passes. Until then `assets.lod: {}` is the opt-in that resolves to enabled/balanced.
|
|
268
|
+
*/
|
|
269
|
+
export interface IThreeNativeLodConfig {
|
|
270
|
+
readonly enabled?: boolean;
|
|
271
|
+
readonly generation?: IThreeNativeLodGenerationConfig;
|
|
272
|
+
readonly overrides?: Readonly<Record<string, boolean | IThreeNativeLodOverride>>;
|
|
273
|
+
readonly preset?: ThreeNativeLodPreset;
|
|
274
|
+
readonly runtime?: IThreeNativeLodRuntimeConfig;
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
/** One measured byte ceiling on a produced artifact, and what crossing it does. */
|
|
278
|
+
export interface IThreeNativeArtifactBudgetLimit {
|
|
279
|
+
/** Bytes, exclusive: a build measuring exactly the limit is inside it. */
|
|
280
|
+
readonly limit: number;
|
|
281
|
+
/** `"error"` refuses the build and keeps the previous artifact; `"warn"` prints and publishes. */
|
|
282
|
+
readonly severity: "error" | "warn";
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
/**
|
|
286
|
+
* Runtime ceilings a profile wants every playtest of the artifact it builds to hold.
|
|
287
|
+
*
|
|
288
|
+
* The fields are the playtest harness's own `assert.performance` fields, one name for one meaning:
|
|
289
|
+
* a budget declared here is merged into each scenario's performance assertion, so a budget and a
|
|
290
|
+
* scenario bound the same number instead of two vocabularies for one measurement. Spelled out
|
|
291
|
+
* rather than imported — the harness runs against plain Three.js with no dependency on this
|
|
292
|
+
* package, and core must not invert that. A closed key list validated in both places is the price;
|
|
293
|
+
* `create-threenative/__tests__/build-report.spec.ts` fails if the two lists drift.
|
|
294
|
+
*/
|
|
295
|
+
export interface IThreeNativePerformanceBudget {
|
|
296
|
+
/** Per-pass draw-call ceilings, keyed by pass kind: main, shadow, reflection, nested. */
|
|
297
|
+
readonly maxPassDrawCalls?: Readonly<Partial<Record<ThreeNativeRenderPassKind, number>>>;
|
|
298
|
+
/** Per-pass triangle ceilings, keyed by pass kind: main, shadow, reflection, nested. */
|
|
299
|
+
readonly maxPassTriangles?: Readonly<Partial<Record<ThreeNativeRenderPassKind, number>>>;
|
|
300
|
+
/** Per-phase millisecond ceilings at nearest-rank p95: hostGap, update, render, overlay, residual. */
|
|
301
|
+
readonly maxPhaseMsP95?: Readonly<Partial<Record<ThreeNativeFramePhase, number>>>;
|
|
302
|
+
/** Maximum renderer draw-call count across every pass combined. */
|
|
303
|
+
readonly maxDrawCalls?: number;
|
|
304
|
+
/** Maximum nearest-rank 95th-percentile frame time in milliseconds. */
|
|
305
|
+
readonly maxFrameMsP95?: number;
|
|
306
|
+
/** Maximum renderer triangle count across every pass combined. */
|
|
307
|
+
readonly maxTriangles?: number;
|
|
308
|
+
/** Frame-budget floor: the median presented frame must sustain at least this many frames a second. */
|
|
309
|
+
readonly minFps?: number;
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
/** The engine's frame-budget phases, as a budget spells them. */
|
|
313
|
+
export type ThreeNativeFramePhase = "hostGap" | "overlay" | "render" | "residual" | "update";
|
|
314
|
+
|
|
315
|
+
/** The render-pass kinds a per-pass budget bounds. */
|
|
316
|
+
export type ThreeNativeRenderPassKind = "main" | "shadow" | "reflection" | "nested";
|
|
317
|
+
|
|
318
|
+
export interface IThreeNativeConfig {
|
|
319
|
+
/**
|
|
320
|
+
* The engine that draws the game on web and desktop. Defaults to ThreeNative's own C++ engine
|
|
321
|
+
* (`"threenative"`): compiled to Wasm on web, the V8 engine player on desktop. `"threejs"` is the named
|
|
322
|
+
* override: it keeps upstream Three.js on web and the legacy host on desktop. Android and iOS still run the legacy host.
|
|
323
|
+
*/
|
|
324
|
+
readonly engine?: "threejs" | "threenative";
|
|
325
|
+
readonly app?: {
|
|
326
|
+
readonly id?: string;
|
|
327
|
+
readonly name?: string;
|
|
328
|
+
readonly version?: string;
|
|
329
|
+
readonly build?: number;
|
|
330
|
+
readonly icon?: string;
|
|
331
|
+
readonly icons?: IThreeNativeIconVariants;
|
|
332
|
+
};
|
|
333
|
+
readonly display?: {
|
|
334
|
+
readonly orientation?: ThreeNativeOrientation;
|
|
335
|
+
readonly fullscreen?: boolean;
|
|
336
|
+
readonly keepScreenOn?: boolean;
|
|
337
|
+
/**
|
|
338
|
+
* Maximum native presentation rate in frames per second. Left out, it follows the display's own
|
|
339
|
+
* refresh rate capped at 120 on desktop and web, and stays 60 on mobile where the ceiling is
|
|
340
|
+
* power and heat; the resolved value and its source are reported on every `TN_FRAME_BUDGET`
|
|
341
|
+
* line as `targetFps` and `targetSource`. A number set here wins outright, and `0` removes the
|
|
342
|
+
* software ceiling. Android also submits this value as the surface's preferred frame rate,
|
|
343
|
+
* which the display policy may decline because of hardware, power, or thermal state. Android
|
|
344
|
+
* uses non-blocking presentation above 60 fps so a missed high-refresh interval does not fall
|
|
345
|
+
* to an integer refresh-rate divisor.
|
|
346
|
+
*/
|
|
347
|
+
readonly maxFps?: number;
|
|
348
|
+
/**
|
|
349
|
+
* What the native host does when the player leaves the app — presses the power button,
|
|
350
|
+
* switches away, minimizes the window. `"pause"` (the default) stops running frames and
|
|
351
|
+
* suspends audio until the app comes back; `"continue"` keeps rendering off-screen, which a
|
|
352
|
+
* server-shaped or split-screen game may genuinely want. On Android the operating system
|
|
353
|
+
* stops the app whatever this says, so `"continue"` takes effect on desktop only.
|
|
354
|
+
*
|
|
355
|
+
* Turning the pause off does not turn the reporting off: `TN_LIFECYCLE` markers are emitted
|
|
356
|
+
* either way and name the mode that executed.
|
|
357
|
+
*/
|
|
358
|
+
readonly backgroundMode?: ThreeNativeBackgroundMode;
|
|
359
|
+
};
|
|
360
|
+
readonly window?: {
|
|
361
|
+
readonly title?: string;
|
|
362
|
+
readonly width?: number;
|
|
363
|
+
readonly height?: number;
|
|
364
|
+
/** Start maximized on desktop when `display.fullscreen` is false. */
|
|
365
|
+
readonly maximized?: boolean;
|
|
366
|
+
readonly resizable?: boolean;
|
|
367
|
+
};
|
|
368
|
+
/**
|
|
369
|
+
* Named cook profiles: one authored asset tree, one compiler, a different representation per
|
|
370
|
+
* artifact. `--profile` on `threenative build` wins over `defaults[target]`; with neither, the
|
|
371
|
+
* `assets` block is used exactly as declared. An overlay changes resource-processing options
|
|
372
|
+
* only — the source root, the output root, worker concurrency and exclusions stay in `assets`.
|
|
373
|
+
*/
|
|
374
|
+
readonly buildProfiles?: {
|
|
375
|
+
readonly defaults?: {
|
|
376
|
+
readonly android?: string;
|
|
377
|
+
readonly desktop?: string;
|
|
378
|
+
readonly ios?: string;
|
|
379
|
+
readonly web?: string;
|
|
380
|
+
};
|
|
381
|
+
readonly profiles: Readonly<
|
|
382
|
+
Record<
|
|
383
|
+
string,
|
|
384
|
+
{
|
|
385
|
+
/**
|
|
386
|
+
* Byte ceilings on what this profile actually produced, measured after packaging and
|
|
387
|
+
* checked before the artifact is published. `artifactBytes` is the artifact itself (a
|
|
388
|
+
* file, or the recursive sum of a directory, `.app` bundle or outDir);
|
|
389
|
+
* `packagedAssetBytes` is the sum of the asset files that survived the packaging
|
|
390
|
+
* selector. `"error"` refuses the build and leaves the previous artifact in place;
|
|
391
|
+
* `"warn"` prints and publishes.
|
|
392
|
+
*/
|
|
393
|
+
readonly artifactBudget?: {
|
|
394
|
+
readonly artifactBytes?: IThreeNativeArtifactBudgetLimit;
|
|
395
|
+
readonly packagedAssetBytes?: IThreeNativeArtifactBudgetLimit;
|
|
396
|
+
};
|
|
397
|
+
/**
|
|
398
|
+
* Runtime ceilings this profile's artifact must hold, published into the
|
|
399
|
+
* `<artifact>.build-report.json` a build writes beside it and merged by
|
|
400
|
+
* `threenative-playtest --build-report` into every scenario's `assert.performance`. The
|
|
401
|
+
* build measures none of it — it cannot; the numbers exist only once a runtime drew
|
|
402
|
+
* frames — so a budget never refuses a build and never passes one either.
|
|
403
|
+
*/
|
|
404
|
+
readonly performanceBudget?: IThreeNativePerformanceBudget;
|
|
405
|
+
readonly assets?: Pick<
|
|
406
|
+
NonNullable<IThreeNativeConfig["assets"]>,
|
|
407
|
+
"audio" | "budget" | "lod" | "models" | "targets" | "textures"
|
|
408
|
+
>;
|
|
409
|
+
}
|
|
410
|
+
>
|
|
411
|
+
>;
|
|
412
|
+
};
|
|
413
|
+
readonly assets?: {
|
|
414
|
+
/**
|
|
415
|
+
* Audio conditioning options, or `"none"` to ship every clip exactly as committed. Absent
|
|
416
|
+
* means conditioning runs with defaults. `"none"` still measures and still reports.
|
|
417
|
+
*/
|
|
418
|
+
readonly audio?: "none" | IThreeNativeAudioConfig;
|
|
419
|
+
/**
|
|
420
|
+
* Byte ceilings: uncooked defaults to 64,000,000; total defaults to "none". Mobile
|
|
421
|
+
* targets without decoders are exempt from uncooked. A number sets uncooked; "none"
|
|
422
|
+
* disables both gates. Measurements still print when a gate is disabled.
|
|
423
|
+
*/
|
|
424
|
+
readonly budget?:
|
|
425
|
+
| number
|
|
426
|
+
| "none"
|
|
427
|
+
| {
|
|
428
|
+
readonly uncooked?: number | "none";
|
|
429
|
+
readonly total?: number | "none";
|
|
430
|
+
};
|
|
431
|
+
/** Source-relative globs omitted from builds; excluded bytes are still reported. */
|
|
432
|
+
readonly exclude?: readonly string[];
|
|
433
|
+
/**
|
|
434
|
+
* How many cook workers a bake may run at once; absent means the driver's default,
|
|
435
|
+
* min(4, cores - 1). Not part of any cache key, so changing it re-cooks nothing.
|
|
436
|
+
*/
|
|
437
|
+
readonly concurrency?: number;
|
|
438
|
+
/**
|
|
439
|
+
* Automatic discrete LOD. `assets.lod: {}` opts in with the balanced default; `false` or
|
|
440
|
+
* `{ enabled: false }` is the absolute kill switch, and per-asset overrides key off canonical
|
|
441
|
+
* source asset paths. Omission currently bakes nothing — the default-on front door opens only
|
|
442
|
+
* after the qualification phase passes. See {@link IThreeNativeLodConfig}.
|
|
443
|
+
*/
|
|
444
|
+
readonly lod?: boolean | IThreeNativeLodConfig;
|
|
445
|
+
readonly models?: "none" | IThreeNativeModelsConfig;
|
|
446
|
+
/**
|
|
447
|
+
* Also emit the native cooked package (`<output>/native/assets.tnpk`, TNPK v1) beside the
|
|
448
|
+
* existing outputs, for a native-engine build that loads its assets without a JS `GLTFLoader`.
|
|
449
|
+
* Absent or `false` leaves the output set unchanged.
|
|
450
|
+
*/
|
|
451
|
+
readonly nativePackage?: boolean;
|
|
452
|
+
readonly output?: string;
|
|
453
|
+
readonly source?: string;
|
|
454
|
+
readonly targets?: {
|
|
455
|
+
readonly maxMaterials?: number;
|
|
456
|
+
readonly maxTriangles?: number;
|
|
457
|
+
readonly maxTextureDimension?: number;
|
|
458
|
+
};
|
|
459
|
+
/** Texture compression options, or `"none"` to ship every texture exactly as committed. */
|
|
460
|
+
readonly textures?: "none" | IThreeNativeTexturesConfig;
|
|
461
|
+
};
|
|
462
|
+
readonly bootSplash?: IThreeNativeBootSplash;
|
|
463
|
+
readonly nativeEntry?: string;
|
|
464
|
+
readonly renderer?: {
|
|
465
|
+
readonly preferWebGPU?: boolean;
|
|
466
|
+
/**
|
|
467
|
+
* Portable drawing-buffer scale. CSS and UI layout dimensions are unchanged.
|
|
468
|
+
*
|
|
469
|
+
* `"auto"` — the default a template ships — lets the engine hold the `display.maxFps` budget
|
|
470
|
+
* without the game hand-authoring a resolution constant. A number in `(0, 1]` pins it and
|
|
471
|
+
* turns the loop off. Either way the active scale is reported in every `TN_FRAME_BUDGET`
|
|
472
|
+
* window: turning the convention off does not turn its measurement off.
|
|
473
|
+
*/
|
|
474
|
+
readonly resolutionScale?: number | "auto";
|
|
475
|
+
/** Portable multisampling. Sampling and resolution are one pixel budget, not two. */
|
|
476
|
+
readonly antialias?: boolean;
|
|
477
|
+
/**
|
|
478
|
+
* Portable alpha antialiasing: resolve alpha-tested cutout silhouettes — foliage, fences,
|
|
479
|
+
* hair — through the multisample coverage mask rather than a binary `discard`. On by default,
|
|
480
|
+
* costing no target and no pass; it buys the cutouts the samples `antialias` already pays
|
|
481
|
+
* for. Set false for a deliberately hard-edged look. It does nothing on a single-sampled
|
|
482
|
+
* surface, and says so in `TN_ALPHA_ANTIALIASING` rather than reporting itself applied.
|
|
483
|
+
*/
|
|
484
|
+
readonly alphaAntialiasing?: boolean;
|
|
485
|
+
/**
|
|
486
|
+
* Whether the engine may render an internal mirror of the scene to collapse repeated draws,
|
|
487
|
+
* and how often that mirror proves a batched material still matches its group's shared draw.
|
|
488
|
+
*
|
|
489
|
+
* On by default, which is the shipping behaviour and is what an unset option means. The mirror
|
|
490
|
+
* is opportunistic and correctness-preserving, but it pays a reconciliation cost per frame, so
|
|
491
|
+
* a game that has measured it as a loss — a scene whose draw count falls without its frame time
|
|
492
|
+
* following — can decline it with `false`. An opted-out game builds no mirror and runs no
|
|
493
|
+
* eligibility scan, so the opt-out costs nothing rather than declining each frame; the authored
|
|
494
|
+
* scene is what renders. The `TN_RENDER_PROJECTION` marker still reports it, with its own
|
|
495
|
+
* reason code rather than one of the measured declines.
|
|
496
|
+
*
|
|
497
|
+
* An object instead of `false` names the material check:
|
|
498
|
+
*
|
|
499
|
+
* - `materialChecks: "spread"` — **the default.** A bounded slice of the batched materials is
|
|
500
|
+
* proved per frame instead of all of them, so a frame of 4,096 colour-only materials costs
|
|
501
|
+
* 512 checks rather than 4,096. A material that gains a roughness, a map or a define still
|
|
502
|
+
* leaves its group and is drawn exactly; it is caught up to `materialCheckStaleFrames` frames
|
|
503
|
+
* later, and `TN_RENDER_PROJECTION` reports that bound. A base-colour edit never waits: the
|
|
504
|
+
* per-instance colour is O(1) per member and always exact.
|
|
505
|
+
* - `materialChecks: "everyFrame"` — the named alternative, and the check exactly as it shipped
|
|
506
|
+
* before the sweep existed: every material proved every frame, at about 1.1 µs a material. Use
|
|
507
|
+
* it when a game would rather pay the per-frame cost than accept the bound.
|
|
508
|
+
*
|
|
509
|
+
* Any other value throws at startup rather than falling back to a default nobody asked for.
|
|
510
|
+
*
|
|
511
|
+
* `"js"` names the mirror on a host that would not build one. The native engine player batches
|
|
512
|
+
* the authored scene in its own renderer and reports `hostProjected`, so core builds no mirror and
|
|
513
|
+
* reads no object across the boundary. `"js"` forces the mirror there anyway (for a comparison, or
|
|
514
|
+
* a game that depends on it), and the report states `path: "js"` and `pathOverridden: true`. On
|
|
515
|
+
* three the mirror is the only path, so `"js"` changes nothing.
|
|
516
|
+
*/
|
|
517
|
+
readonly projection?:
|
|
518
|
+
| boolean
|
|
519
|
+
| "js"
|
|
520
|
+
| {
|
|
521
|
+
readonly materialChecks?: "spread" | "everyFrame";
|
|
522
|
+
};
|
|
523
|
+
/**
|
|
524
|
+
* Projected diameter, in raster pixels, below which the engine does not submit an object to
|
|
525
|
+
* the render camera. On by default at a conservative **0.5 px**: an object under half a pixel
|
|
526
|
+
* cannot light a whole pixel of the frame, so only unresolvable geometry is removed. Set a
|
|
527
|
+
* larger number for a tuned cut — a shipped game's ladder chose 2 px — or `false` to leave
|
|
528
|
+
* every object drawn. The measurement still runs with `false`; `TN_PROJECTION` reports how many
|
|
529
|
+
* objects were considered and skipped. Exempt a single object with `alwaysRender` from
|
|
530
|
+
* `@threenative/core`; the player's camera-attached objects and shadow casters are already kept.
|
|
531
|
+
*/
|
|
532
|
+
readonly minimumProjectedPixels?: number | false;
|
|
533
|
+
/**
|
|
534
|
+
* How much of the scene graph the engine walks for world matrices each frame.
|
|
535
|
+
*
|
|
536
|
+
* `"visible"` — the default — does not recurse into a hidden subtree. three's own
|
|
537
|
+
* `updateMatrixWorld` walks every child whatever its `visible` flag, multiplying a world matrix
|
|
538
|
+
* for a full-detail body whose merged stand-in is showing, a hidden LOD level, a parked model —
|
|
539
|
+
* none of which can draw. The engine composes every visible node exactly as three does, and
|
|
540
|
+
* remembers a hidden node it skipped so the first frame that subtree shows again its whole
|
|
541
|
+
* chain is refreshed before anything reads it. A game that reads a **hidden** object's
|
|
542
|
+
* `matrixWorld` directly must not rely on the walk having reached it: use `getWorldPosition`
|
|
543
|
+
* (which updates the chain) or call `updateWorldMatrix(true, false)` first.
|
|
544
|
+
*
|
|
545
|
+
* `"all"` visits every node, exactly as three's own walk does — for a game that reads hidden
|
|
546
|
+
* world matrices without going through `getWorld*` and cannot say so per object. Both modes
|
|
547
|
+
* report the number of nodes walked in the `TN_PROJECTION` window, so the cost of the walk the
|
|
548
|
+
* default removed is measurable rather than asserted.
|
|
549
|
+
*/
|
|
550
|
+
readonly matrixWorld?: "visible" | "all";
|
|
551
|
+
/**
|
|
552
|
+
* Android-only rendering overrides selected by the engine.
|
|
553
|
+
*
|
|
554
|
+
* `antialias` belongs here beside `resolutionScale` because they spend the same budget: a
|
|
555
|
+
* tile-based mobile GPU resolves MSAA in tile memory and prices it quite differently from a
|
|
556
|
+
* desktop one, so a platform that scales resolution down must be able to buy sampling back
|
|
557
|
+
* on that same platform rather than accepting whatever the portable value happened to be.
|
|
558
|
+
*/
|
|
559
|
+
readonly android?: {
|
|
560
|
+
readonly resolutionScale?: number | "auto";
|
|
561
|
+
readonly antialias?: boolean;
|
|
562
|
+
/**
|
|
563
|
+
* `alphaAntialiasing` belongs here for the reason `antialias` does, one step on: a phone
|
|
564
|
+
* that bought sampling back must be able to spend it on cutouts, and one that gave sampling
|
|
565
|
+
* up has nothing to spend.
|
|
566
|
+
*/
|
|
567
|
+
readonly alphaAntialiasing?: boolean;
|
|
568
|
+
};
|
|
569
|
+
};
|
|
570
|
+
readonly ui?: {
|
|
571
|
+
/**
|
|
572
|
+
* Which renderer draws `src/ui/`. Defaults to `"web"`.
|
|
573
|
+
*
|
|
574
|
+
* `"web"` runs the same React DOM, Tailwind, CSS, SVG and fonts on every target, through
|
|
575
|
+
* that platform's own browser-class renderer composited over the game surface. What is
|
|
576
|
+
* guaranteed is source parity — one `src/ui/` — not browser-binary parity, which no design
|
|
577
|
+
* using the platforms' own engines can offer once iOS is in the set.
|
|
578
|
+
*
|
|
579
|
+
* `"native"` maps React to `CanvasLayer` quads with no web view, no CSS and no second
|
|
580
|
+
* process. Choose it for a UI that is part of the rendered frame, or a target with no web
|
|
581
|
+
* view, or zero extra processes — and own the appearance difference, which is the trade
|
|
582
|
+
* being made rather than something to discover in a screenshot.
|
|
583
|
+
*
|
|
584
|
+
* `"native-css"` runs the same React tree in the game's own JS realm — no web view, no second
|
|
585
|
+
* process — with a native CSS engine painting it and the stylesheet coming from the same Vite +
|
|
586
|
+
* Tailwind build the web renderer uses. Desktop only, experimental, and opt-in.
|
|
587
|
+
*
|
|
588
|
+
* Which surface `"web"` lands on is the platform's business and never a game's: no config,
|
|
589
|
+
* type or document names the engine underneath.
|
|
590
|
+
*/
|
|
591
|
+
readonly renderer?: ThreeNativeUiRenderer;
|
|
592
|
+
};
|
|
593
|
+
}
|
package/src/debug.ts
ADDED
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A debug switch a game reads the same way on every platform it ships to.
|
|
3
|
+
*
|
|
4
|
+
* Two questions an agent answers differently in every game, both of which cost a rewrite: how do I
|
|
5
|
+
* turn this on for one run without changing the code, and how does a capture script reach the object
|
|
6
|
+
* it wants to look at. The answers here are one function each, and neither decides how anything
|
|
7
|
+
* looks.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
/** The shared global the engine's dev surfaces and `exposeDebug` both publish under. */
|
|
11
|
+
const HOST_KEY = "__THREENATIVE__";
|
|
12
|
+
|
|
13
|
+
/** `freeCam` → `FREE_CAM`. A name a developer typed becomes a name a shell can set. */
|
|
14
|
+
function envName(name: string): string {
|
|
15
|
+
return `TN_DEBUG_${name.replace(/([a-z0-9])([A-Z])/gu, "$1_$2").toUpperCase()}`;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* `process.env` on a host that installed one, narrowed rather than asserted exactly as
|
|
20
|
+
* `isDevLaunch` does in `game.ts`: it exists on the native runtime and not in a browser bundle.
|
|
21
|
+
*/
|
|
22
|
+
function envValue(name: string): string | undefined {
|
|
23
|
+
const scope: unknown = globalThis;
|
|
24
|
+
if (typeof scope !== "object" || scope === null || !("process" in scope)) return undefined;
|
|
25
|
+
const hostProcess: unknown = scope.process;
|
|
26
|
+
if (typeof hostProcess !== "object" || hostProcess === null || !("env" in hostProcess))
|
|
27
|
+
return undefined;
|
|
28
|
+
const env: unknown = hostProcess.env;
|
|
29
|
+
if (typeof env !== "object" || env === null) return undefined;
|
|
30
|
+
const value: unknown = (env as Record<string, unknown>)[name];
|
|
31
|
+
return typeof value === "string" ? value : undefined;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** Not one of the two spellings of off. */
|
|
35
|
+
function isOn(value: string): boolean {
|
|
36
|
+
return value !== "0" && value !== "false";
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* A debug switch read from the URL, or from the environment on a native launch.
|
|
41
|
+
*
|
|
42
|
+
* @situation read a debug toggle from the URL or an environment variable
|
|
43
|
+
*
|
|
44
|
+
* A browser asks with the query string — `?freeCam`, or `?freeCam=0` to force it off — and a native
|
|
45
|
+
* launch asks with `TN_DEBUG_FREE_CAM`, because a query string is not something a developer sets on
|
|
46
|
+
* a command line. `0` and `false` are off, so a saved URL that used to enable a switch still says
|
|
47
|
+
* "off" rather than quietly turning it back on.
|
|
48
|
+
*/
|
|
49
|
+
export function debugFlag(name: string): boolean {
|
|
50
|
+
// An exported-but-empty variable is off, as `DEV_MODE=` is to the engine's own reader; a bare
|
|
51
|
+
// `?freeCam` is on, because the query string has no other way to say it.
|
|
52
|
+
const env = envValue(envName(name));
|
|
53
|
+
if (env !== undefined && env !== "" && isOn(env)) return true;
|
|
54
|
+
const search: unknown = globalThis.location?.search;
|
|
55
|
+
if (typeof search !== "string") return false;
|
|
56
|
+
const value = new URLSearchParams(search).get(name);
|
|
57
|
+
return value !== null && isOn(value);
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* Publish one game object for a capture script or the console, in development builds only.
|
|
62
|
+
*
|
|
63
|
+
* @situation expose a game object to a capture script or the console in dev builds
|
|
64
|
+
*
|
|
65
|
+
* Playtest reads `__THREENATIVE__` in a dev build and is silent in a production one, so a game that
|
|
66
|
+
* publishes its player, its camera or a scene handle under `.debug` is reachable from the same
|
|
67
|
+
* place a production build is not. Other keys on the shared object are left alone; the dev surfaces
|
|
68
|
+
* the engine installs beside them keep working.
|
|
69
|
+
*/
|
|
70
|
+
export function exposeDebug(name: string, value: unknown): void {
|
|
71
|
+
// Written out here rather than through a helper: the bundler must see the literal `import.meta`
|
|
72
|
+
// access to strip the whole publish from a production build, and an indirection survives into the
|
|
73
|
+
// bundle — where the game is compiled as a script, not a module, and the bundle fails to parse.
|
|
74
|
+
const isDev =
|
|
75
|
+
(import.meta as ImportMeta & { env?: Record<"DEV", boolean | undefined> }).env?.DEV === true;
|
|
76
|
+
if (!isDev) return;
|
|
77
|
+
const tools = (Reflect.get(globalThis, HOST_KEY) ?? {}) as { debug?: Record<string, unknown> };
|
|
78
|
+
const debug = tools.debug ?? {};
|
|
79
|
+
debug[name] = value;
|
|
80
|
+
tools.debug = debug;
|
|
81
|
+
Reflect.set(globalThis, HOST_KEY, tools);
|
|
82
|
+
}
|