@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
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
import type { IWorldExtent, IWorldTerrain } from "./world-package.js";
|
|
2
|
+
|
|
3
|
+
const HEIGHTMAP_MAX = 65_535;
|
|
4
|
+
|
|
5
|
+
function hostIsLittleEndian(): boolean {
|
|
6
|
+
const view = new DataView(new ArrayBuffer(2));
|
|
7
|
+
view.setUint16(0, 1, true);
|
|
8
|
+
return view.getUint8(0) === 1;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Build a game-usable `sampleHeight` from a raw v1 heightmap.
|
|
13
|
+
*
|
|
14
|
+
* The returned function interpolates bilinearly in world units and clamps to the map edges, so it
|
|
15
|
+
* plugs straight into `Heightfield.fromSampler` and `TerrainTiles`. Height is
|
|
16
|
+
* `heightMin + v / 65535 * (heightMax - heightMin)` at vertex `(column, row)`.
|
|
17
|
+
*
|
|
18
|
+
* @situation turn an exported raw heightmap into terrain collision and rendering
|
|
19
|
+
* @situation query ground height from a Blender-authored world package
|
|
20
|
+
* @constraint the sampler reads the game's data; the framework never selects a terrain shape
|
|
21
|
+
* @example const sampleHeight = heightSamplerFromHeightmap(terrain, extent, await loadWorldHeightmap(url));
|
|
22
|
+
*/
|
|
23
|
+
export function heightSamplerFromHeightmap(
|
|
24
|
+
terrain: IWorldTerrain,
|
|
25
|
+
extent: IWorldExtent,
|
|
26
|
+
data: Uint16Array,
|
|
27
|
+
): (x: number, z: number) => number {
|
|
28
|
+
const expected = terrain.columns * terrain.rows;
|
|
29
|
+
if (data.length !== expected)
|
|
30
|
+
throw new Error(
|
|
31
|
+
`World heightmap expected ${String(expected)} samples, received ${String(data.length)}.`,
|
|
32
|
+
);
|
|
33
|
+
const columns = terrain.columns;
|
|
34
|
+
const rows = terrain.rows;
|
|
35
|
+
const range = terrain.heightMax - terrain.heightMin;
|
|
36
|
+
const heightAt = (index: number): number =>
|
|
37
|
+
terrain.heightMin + ((data[index] as number) / HEIGHTMAP_MAX) * range;
|
|
38
|
+
|
|
39
|
+
return (x: number, z: number): number => {
|
|
40
|
+
const column = Math.min(columns - 1, Math.max(0, (x - extent.minX) / terrain.spacing));
|
|
41
|
+
const row = Math.min(rows - 1, Math.max(0, (z - extent.minZ) / terrain.spacing));
|
|
42
|
+
const column0 = Math.floor(column);
|
|
43
|
+
const row0 = Math.floor(row);
|
|
44
|
+
const column1 = Math.min(columns - 1, column0 + 1);
|
|
45
|
+
const row1 = Math.min(rows - 1, row0 + 1);
|
|
46
|
+
const mixX = column - column0;
|
|
47
|
+
const mixZ = row - row0;
|
|
48
|
+
const upperLeft = heightAt(row0 * columns + column0);
|
|
49
|
+
const upperRight = heightAt(row0 * columns + column1);
|
|
50
|
+
const lowerLeft = heightAt(row1 * columns + column0);
|
|
51
|
+
const lowerRight = heightAt(row1 * columns + column1);
|
|
52
|
+
const upper = upperLeft + (upperRight - upperLeft) * mixX;
|
|
53
|
+
const lower = lowerLeft + (lowerRight - lowerLeft) * mixX;
|
|
54
|
+
return upper + (lower - upper) * mixZ;
|
|
55
|
+
};
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Fetch a raw little-endian uint16 heightmap and expose it as samples.
|
|
60
|
+
*
|
|
61
|
+
* @situation load a world package's heightmap once before building terrain
|
|
62
|
+
* @constraint a non-OK response throws; bytes are byte-swapped only on a big-endian host
|
|
63
|
+
* @example const data = await loadWorldHeightmap("/world/terrain/heightmap.u16");
|
|
64
|
+
*/
|
|
65
|
+
export async function loadWorldHeightmap(url: string): Promise<Uint16Array> {
|
|
66
|
+
const response = await fetch(url);
|
|
67
|
+
if (!response.ok)
|
|
68
|
+
throw new Error(
|
|
69
|
+
`World heightmap request failed with status ${String(response.status)} for ${url}.`,
|
|
70
|
+
);
|
|
71
|
+
const buffer = await response.arrayBuffer();
|
|
72
|
+
if (buffer.byteLength % 2 !== 0)
|
|
73
|
+
throw new Error(
|
|
74
|
+
`World heightmap ${url} has an odd byte length of ${String(buffer.byteLength)}.`,
|
|
75
|
+
);
|
|
76
|
+
if (!hostIsLittleEndian()) {
|
|
77
|
+
const view = new DataView(buffer);
|
|
78
|
+
for (let offset = 0; offset < buffer.byteLength; offset += 2)
|
|
79
|
+
view.setUint16(offset, view.getUint16(offset, true), false);
|
|
80
|
+
}
|
|
81
|
+
return new Uint16Array(buffer);
|
|
82
|
+
}
|
|
@@ -0,0 +1,469 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `world.json` package contract: a versioned manifest that names a raw heightmap, stable
|
|
3
|
+
* asset ids, placement runs and the square cells that stream them.
|
|
4
|
+
*
|
|
5
|
+
* Every value is authored by the world exporter and read by the runtime, so the game never
|
|
6
|
+
* hard-codes a cell layout or an asset path. Validation never throws on malformed JSON-shaped
|
|
7
|
+
* input: it collects named errors so an exporter can report every problem in one pass.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
export type WorldPackageErrorCode =
|
|
11
|
+
| "WORLD_VERSION_MISMATCH"
|
|
12
|
+
| "WORLD_UNKNOWN_ASSET"
|
|
13
|
+
| "WORLD_RUN_OUT_OF_RANGE"
|
|
14
|
+
| "WORLD_CELL_OUTSIDE_EXTENT"
|
|
15
|
+
| "WORLD_MALFORMED";
|
|
16
|
+
|
|
17
|
+
export interface IWorldPackageError {
|
|
18
|
+
readonly code: WorldPackageErrorCode;
|
|
19
|
+
readonly message: string;
|
|
20
|
+
/** JSON-shaped path to the offending field, e.g. `cells[2].runs[0].offset`. */
|
|
21
|
+
readonly path: string;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export interface IWorldExtent {
|
|
25
|
+
readonly minX: number;
|
|
26
|
+
readonly minZ: number;
|
|
27
|
+
readonly sizeX: number;
|
|
28
|
+
readonly sizeZ: number;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export interface IWorldTerrain {
|
|
32
|
+
/** Package-relative path to the raw little-endian uint16 heightmap. */
|
|
33
|
+
readonly heightmap: string;
|
|
34
|
+
/** Vertex counts; `columns = sizeX / spacing + 1`, likewise `rows`. */
|
|
35
|
+
readonly columns: number;
|
|
36
|
+
readonly rows: number;
|
|
37
|
+
/** Metres between adjacent heightmap vertices on both axes. */
|
|
38
|
+
readonly spacing: number;
|
|
39
|
+
readonly heightMin: number;
|
|
40
|
+
readonly heightMax: number;
|
|
41
|
+
/** Optional opaque layer-mask paths, passed through to the game's surface untouched. */
|
|
42
|
+
readonly layers?: Readonly<Record<string, string>>;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
export interface IWorldAssetLod {
|
|
46
|
+
readonly glb: string;
|
|
47
|
+
readonly distance: number;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export interface IWorldAssetBounds {
|
|
51
|
+
readonly min: readonly [number, number, number];
|
|
52
|
+
readonly max: readonly [number, number, number];
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
export interface IWorldAsset {
|
|
56
|
+
readonly glb: string;
|
|
57
|
+
readonly lods?: readonly IWorldAssetLod[];
|
|
58
|
+
readonly bounds: IWorldAssetBounds;
|
|
59
|
+
readonly maxDistance?: number;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
export interface IWorldRun {
|
|
63
|
+
readonly asset: string;
|
|
64
|
+
/** Record offset into `placements`; one record is eight float32 values. */
|
|
65
|
+
readonly offset: number;
|
|
66
|
+
readonly count: number;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
export interface IWorldCellProxy {
|
|
70
|
+
readonly glb: string;
|
|
71
|
+
/** Conservative world-space simplification error bound, in metres. */
|
|
72
|
+
readonly error: number;
|
|
73
|
+
readonly triangles: number;
|
|
74
|
+
readonly materialGroups: number;
|
|
75
|
+
/** Older records without scope cover chunks only. */
|
|
76
|
+
readonly scope?: "cell" | "chunks";
|
|
77
|
+
readonly bounds?: IWorldAssetBounds;
|
|
78
|
+
readonly sourceTriangles?: number;
|
|
79
|
+
/** Cook census only: runtime compares the currently active shared batches. */
|
|
80
|
+
readonly sourcePrimitives?: number;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
export interface IWorldCell {
|
|
84
|
+
readonly x: number;
|
|
85
|
+
readonly z: number;
|
|
86
|
+
readonly runs: readonly IWorldRun[];
|
|
87
|
+
readonly chunks?: readonly string[];
|
|
88
|
+
readonly proxy?: IWorldCellProxy;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
export interface IWorldPackage {
|
|
92
|
+
readonly version: 1;
|
|
93
|
+
readonly extent: IWorldExtent;
|
|
94
|
+
readonly cellSize: number;
|
|
95
|
+
readonly terrain: IWorldTerrain;
|
|
96
|
+
readonly assets: Readonly<Record<string, IWorldAsset>>;
|
|
97
|
+
readonly placements: string;
|
|
98
|
+
readonly cells: readonly IWorldCell[];
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
export interface IWorldPackageValidationOptions {
|
|
102
|
+
/** Byte length of the placement buffer the runs index into. */
|
|
103
|
+
readonly placementsByteLength: number;
|
|
104
|
+
/** When known, the heightmap length must be `columns * rows * 2`. */
|
|
105
|
+
readonly heightmapByteLength?: number;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
const WORLD_PACKAGE_VERSION = 1;
|
|
109
|
+
const PLACEMENT_RECORD_BYTES = 32;
|
|
110
|
+
|
|
111
|
+
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
112
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* Validate a `world.json` manifest against the v1 contract.
|
|
117
|
+
*
|
|
118
|
+
* Never throws on garbage input: a non-object manifest is `WORLD_MALFORMED`. Every problem is
|
|
119
|
+
* collected, so an exporter sees the complete list at once.
|
|
120
|
+
*
|
|
121
|
+
* @situation check a Blender-exported world package before the runtime attaches anything
|
|
122
|
+
* @situation report why a world package cannot be streamed
|
|
123
|
+
* @constraint validation only checks structure and ranges; it never fetches the heightmap or GLBs
|
|
124
|
+
* @example const { ok, errors } = validateWorldPackage(json, { placementsByteLength: buffer.byteLength });
|
|
125
|
+
*/
|
|
126
|
+
export function validateWorldPackage(
|
|
127
|
+
manifest: unknown,
|
|
128
|
+
options: IWorldPackageValidationOptions,
|
|
129
|
+
): { ok: boolean; errors: IWorldPackageError[] } {
|
|
130
|
+
const errors: IWorldPackageError[] = [];
|
|
131
|
+
const record = (code: WorldPackageErrorCode, path: string, message: string): void => {
|
|
132
|
+
errors.push({ code, message, path });
|
|
133
|
+
};
|
|
134
|
+
const malformed = (path: string, message: string): void => {
|
|
135
|
+
record("WORLD_MALFORMED", path, message);
|
|
136
|
+
};
|
|
137
|
+
const finite = (value: unknown, path: string): number | undefined => {
|
|
138
|
+
if (typeof value !== "number" || !Number.isFinite(value)) {
|
|
139
|
+
malformed(path, `${path} must be a finite number.`);
|
|
140
|
+
return undefined;
|
|
141
|
+
}
|
|
142
|
+
return value;
|
|
143
|
+
};
|
|
144
|
+
const positive = (value: unknown, path: string): number | undefined => {
|
|
145
|
+
const number = finite(value, path);
|
|
146
|
+
if (number !== undefined && number <= 0) {
|
|
147
|
+
malformed(path, `${path} must be greater than zero.`);
|
|
148
|
+
return undefined;
|
|
149
|
+
}
|
|
150
|
+
return number;
|
|
151
|
+
};
|
|
152
|
+
const positiveInteger = (value: unknown, path: string): number | undefined => {
|
|
153
|
+
if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
|
|
154
|
+
malformed(path, `${path} must be a positive integer.`);
|
|
155
|
+
return undefined;
|
|
156
|
+
}
|
|
157
|
+
return value;
|
|
158
|
+
};
|
|
159
|
+
const integer = (value: unknown, path: string): number | undefined => {
|
|
160
|
+
if (typeof value !== "number" || !Number.isInteger(value)) {
|
|
161
|
+
malformed(path, `${path} must be an integer.`);
|
|
162
|
+
return undefined;
|
|
163
|
+
}
|
|
164
|
+
return value;
|
|
165
|
+
};
|
|
166
|
+
const text = (value: unknown, path: string): string | undefined => {
|
|
167
|
+
if (typeof value !== "string" || value.length === 0) {
|
|
168
|
+
malformed(path, `${path} must be a non-empty string.`);
|
|
169
|
+
return undefined;
|
|
170
|
+
}
|
|
171
|
+
return value;
|
|
172
|
+
};
|
|
173
|
+
|
|
174
|
+
if (!isRecord(manifest)) {
|
|
175
|
+
malformed("", "World package must be a JSON object.");
|
|
176
|
+
return { errors, ok: false };
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
if (typeof manifest.version !== "number") {
|
|
180
|
+
malformed("version", "World package version is required and must be a number.");
|
|
181
|
+
} else if (manifest.version !== WORLD_PACKAGE_VERSION) {
|
|
182
|
+
record(
|
|
183
|
+
"WORLD_VERSION_MISMATCH",
|
|
184
|
+
"version",
|
|
185
|
+
`World package version ${String(manifest.version)} is not supported; expected ${String(WORLD_PACKAGE_VERSION)}.`,
|
|
186
|
+
);
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
let extent: IWorldExtent | undefined;
|
|
190
|
+
if (!isRecord(manifest.extent)) {
|
|
191
|
+
malformed("extent", "World package extent is required and must be an object.");
|
|
192
|
+
} else {
|
|
193
|
+
const minX = finite(manifest.extent.minX, "extent.minX");
|
|
194
|
+
const minZ = finite(manifest.extent.minZ, "extent.minZ");
|
|
195
|
+
const sizeX = positive(manifest.extent.sizeX, "extent.sizeX");
|
|
196
|
+
const sizeZ = positive(manifest.extent.sizeZ, "extent.sizeZ");
|
|
197
|
+
if (minX !== undefined && minZ !== undefined && sizeX !== undefined && sizeZ !== undefined)
|
|
198
|
+
extent = { minX, minZ, sizeX, sizeZ };
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
const cellSize = positive(manifest.cellSize, "cellSize");
|
|
202
|
+
|
|
203
|
+
let terrain: IWorldTerrain | undefined;
|
|
204
|
+
if (!isRecord(manifest.terrain)) {
|
|
205
|
+
malformed("terrain", "World package terrain is required and must be an object.");
|
|
206
|
+
} else {
|
|
207
|
+
const raw = manifest.terrain;
|
|
208
|
+
const heightmap = text(raw.heightmap, "terrain.heightmap");
|
|
209
|
+
const columns = positiveInteger(raw.columns, "terrain.columns");
|
|
210
|
+
const rows = positiveInteger(raw.rows, "terrain.rows");
|
|
211
|
+
const spacing = positive(raw.spacing, "terrain.spacing");
|
|
212
|
+
const heightMin = finite(raw.heightMin, "terrain.heightMin");
|
|
213
|
+
const heightMax = finite(raw.heightMax, "terrain.heightMax");
|
|
214
|
+
let layers: Record<string, string> | undefined;
|
|
215
|
+
if (raw.layers !== undefined) {
|
|
216
|
+
if (!isRecord(raw.layers)) {
|
|
217
|
+
malformed("terrain.layers", "terrain.layers must be an object of string paths.");
|
|
218
|
+
} else {
|
|
219
|
+
layers = {};
|
|
220
|
+
for (const [name, value] of Object.entries(raw.layers)) {
|
|
221
|
+
const path = text(value, `terrain.layers.${name}`);
|
|
222
|
+
if (path !== undefined) layers[name] = path;
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
if (extent !== undefined && columns !== undefined && spacing !== undefined) {
|
|
227
|
+
const expected = extent.sizeX / spacing + 1;
|
|
228
|
+
if (columns !== expected)
|
|
229
|
+
malformed(
|
|
230
|
+
"terrain.columns",
|
|
231
|
+
`terrain.columns ${String(columns)} does not match extent.sizeX / spacing + 1 (${String(expected)}).`,
|
|
232
|
+
);
|
|
233
|
+
}
|
|
234
|
+
if (extent !== undefined && rows !== undefined && spacing !== undefined) {
|
|
235
|
+
const expected = extent.sizeZ / spacing + 1;
|
|
236
|
+
if (rows !== expected)
|
|
237
|
+
malformed(
|
|
238
|
+
"terrain.rows",
|
|
239
|
+
`terrain.rows ${String(rows)} does not match extent.sizeZ / spacing + 1 (${String(expected)}).`,
|
|
240
|
+
);
|
|
241
|
+
}
|
|
242
|
+
if (
|
|
243
|
+
heightmap !== undefined &&
|
|
244
|
+
columns !== undefined &&
|
|
245
|
+
rows !== undefined &&
|
|
246
|
+
spacing !== undefined &&
|
|
247
|
+
heightMin !== undefined &&
|
|
248
|
+
heightMax !== undefined
|
|
249
|
+
)
|
|
250
|
+
terrain = {
|
|
251
|
+
columns,
|
|
252
|
+
heightMax,
|
|
253
|
+
heightMin,
|
|
254
|
+
heightmap,
|
|
255
|
+
rows,
|
|
256
|
+
spacing,
|
|
257
|
+
...(layers === undefined ? {} : { layers }),
|
|
258
|
+
};
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
if (options.heightmapByteLength !== undefined && terrain !== undefined) {
|
|
262
|
+
const expected = terrain.columns * terrain.rows * 2;
|
|
263
|
+
if (options.heightmapByteLength !== expected)
|
|
264
|
+
malformed(
|
|
265
|
+
"terrain.heightmap",
|
|
266
|
+
`heightmapByteLength ${String(options.heightmapByteLength)} does not match columns * rows * 2 (${String(expected)}).`,
|
|
267
|
+
);
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
const assetIds = new Set<string>();
|
|
271
|
+
if (!isRecord(manifest.assets)) {
|
|
272
|
+
malformed("assets", "World package assets is required and must be an object.");
|
|
273
|
+
} else {
|
|
274
|
+
for (const [id, value] of Object.entries(manifest.assets)) {
|
|
275
|
+
assetIds.add(id);
|
|
276
|
+
const path = `assets.${id}`;
|
|
277
|
+
if (!isRecord(value)) {
|
|
278
|
+
malformed(path, `${path} must be an object.`);
|
|
279
|
+
continue;
|
|
280
|
+
}
|
|
281
|
+
text(value.glb, `${path}.glb`);
|
|
282
|
+
if (!isRecord(value.bounds)) {
|
|
283
|
+
malformed(`${path}.bounds`, `${path}.bounds is required and must be an object.`);
|
|
284
|
+
} else {
|
|
285
|
+
for (const key of ["min", "max"] as const) {
|
|
286
|
+
const corner = value.bounds[key];
|
|
287
|
+
if (
|
|
288
|
+
!Array.isArray(corner) ||
|
|
289
|
+
corner.length !== 3 ||
|
|
290
|
+
corner.some((component) => typeof component !== "number" || !Number.isFinite(component))
|
|
291
|
+
)
|
|
292
|
+
malformed(
|
|
293
|
+
`${path}.bounds.${key}`,
|
|
294
|
+
`${path}.bounds.${key} must be three finite numbers.`,
|
|
295
|
+
);
|
|
296
|
+
}
|
|
297
|
+
}
|
|
298
|
+
if (value.lods !== undefined) {
|
|
299
|
+
if (!Array.isArray(value.lods)) {
|
|
300
|
+
malformed(`${path}.lods`, `${path}.lods must be an array.`);
|
|
301
|
+
} else {
|
|
302
|
+
value.lods.forEach((lod, index) => {
|
|
303
|
+
const lodPath = `${path}.lods[${index}]`;
|
|
304
|
+
if (!isRecord(lod)) {
|
|
305
|
+
malformed(lodPath, `${lodPath} must be an object.`);
|
|
306
|
+
return;
|
|
307
|
+
}
|
|
308
|
+
text(lod.glb, `${lodPath}.glb`);
|
|
309
|
+
finite(lod.distance, `${lodPath}.distance`);
|
|
310
|
+
});
|
|
311
|
+
}
|
|
312
|
+
}
|
|
313
|
+
if (value.maxDistance !== undefined) finite(value.maxDistance, `${path}.maxDistance`);
|
|
314
|
+
}
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
text(manifest.placements, "placements");
|
|
318
|
+
|
|
319
|
+
const maximumCellX =
|
|
320
|
+
extent !== undefined && cellSize !== undefined ? Math.ceil(extent.sizeX / cellSize) : undefined;
|
|
321
|
+
const maximumCellZ =
|
|
322
|
+
extent !== undefined && cellSize !== undefined ? Math.ceil(extent.sizeZ / cellSize) : undefined;
|
|
323
|
+
|
|
324
|
+
if (!Array.isArray(manifest.cells)) {
|
|
325
|
+
malformed("cells", "World package cells is required and must be an array.");
|
|
326
|
+
} else {
|
|
327
|
+
manifest.cells.forEach((cell, cellIndex) => {
|
|
328
|
+
const path = `cells[${cellIndex}]`;
|
|
329
|
+
if (!isRecord(cell)) {
|
|
330
|
+
malformed(path, `${path} must be an object.`);
|
|
331
|
+
return;
|
|
332
|
+
}
|
|
333
|
+
const x = integer(cell.x, `${path}.x`);
|
|
334
|
+
const z = integer(cell.z, `${path}.z`);
|
|
335
|
+
if (x !== undefined && (x < 0 || (maximumCellX !== undefined && x >= maximumCellX)))
|
|
336
|
+
record(
|
|
337
|
+
"WORLD_CELL_OUTSIDE_EXTENT",
|
|
338
|
+
`${path}.x`,
|
|
339
|
+
`Cell x ${String(x)} is outside the world extent.`,
|
|
340
|
+
);
|
|
341
|
+
if (z !== undefined && (z < 0 || (maximumCellZ !== undefined && z >= maximumCellZ)))
|
|
342
|
+
record(
|
|
343
|
+
"WORLD_CELL_OUTSIDE_EXTENT",
|
|
344
|
+
`${path}.z`,
|
|
345
|
+
`Cell z ${String(z)} is outside the world extent.`,
|
|
346
|
+
);
|
|
347
|
+
if (cell.chunks !== undefined) {
|
|
348
|
+
if (
|
|
349
|
+
!Array.isArray(cell.chunks) ||
|
|
350
|
+
cell.chunks.some((chunk) => typeof chunk !== "string" || chunk.length === 0)
|
|
351
|
+
)
|
|
352
|
+
malformed(`${path}.chunks`, `${path}.chunks must be an array of non-empty strings.`);
|
|
353
|
+
}
|
|
354
|
+
if (cell.proxy !== undefined) {
|
|
355
|
+
const proxyPath = `${path}.proxy`;
|
|
356
|
+
if (!isRecord(cell.proxy)) malformed(proxyPath, `${proxyPath} must be an object.`);
|
|
357
|
+
else {
|
|
358
|
+
const proxy = cell.proxy;
|
|
359
|
+
text(proxy.glb, `${proxyPath}.glb`);
|
|
360
|
+
const error = finite(proxy.error, `${proxyPath}.error`);
|
|
361
|
+
if (error !== undefined && error < 0)
|
|
362
|
+
malformed(`${proxyPath}.error`, "Proxy error must be non-negative.");
|
|
363
|
+
for (const name of [
|
|
364
|
+
"triangles",
|
|
365
|
+
"materialGroups",
|
|
366
|
+
"sourceTriangles",
|
|
367
|
+
"sourcePrimitives",
|
|
368
|
+
] as const) {
|
|
369
|
+
if (
|
|
370
|
+
proxy[name] === undefined &&
|
|
371
|
+
(name === "sourceTriangles" || name === "sourcePrimitives")
|
|
372
|
+
)
|
|
373
|
+
continue;
|
|
374
|
+
const value = positiveInteger(proxy[name], `${proxyPath}.${name}`);
|
|
375
|
+
if (value !== undefined && !Number.isSafeInteger(value))
|
|
376
|
+
malformed(`${proxyPath}.${name}`, "Proxy counts must be safe integers.");
|
|
377
|
+
}
|
|
378
|
+
if (proxy.scope !== undefined && proxy.scope !== "cell" && proxy.scope !== "chunks")
|
|
379
|
+
malformed(`${proxyPath}.scope`, "Proxy scope must be cell or chunks.");
|
|
380
|
+
if (proxy.bounds !== undefined) {
|
|
381
|
+
if (
|
|
382
|
+
!isRecord(proxy.bounds) ||
|
|
383
|
+
!Array.isArray(proxy.bounds.min) ||
|
|
384
|
+
!Array.isArray(proxy.bounds.max) ||
|
|
385
|
+
proxy.bounds.min.length !== 3 ||
|
|
386
|
+
proxy.bounds.max.length !== 3
|
|
387
|
+
)
|
|
388
|
+
malformed(`${proxyPath}.bounds`, "Proxy bounds must contain min and max triples.");
|
|
389
|
+
else
|
|
390
|
+
for (let axis = 0; axis < 3; axis += 1) {
|
|
391
|
+
const low = finite(proxy.bounds.min[axis], `${proxyPath}.bounds.min[${axis}]`);
|
|
392
|
+
const high = finite(proxy.bounds.max[axis], `${proxyPath}.bounds.max[${axis}]`);
|
|
393
|
+
if (low !== undefined && high !== undefined && low > high)
|
|
394
|
+
malformed(`${proxyPath}.bounds`, "Proxy bounds are inverted.");
|
|
395
|
+
}
|
|
396
|
+
}
|
|
397
|
+
}
|
|
398
|
+
}
|
|
399
|
+
if (!Array.isArray(cell.runs)) {
|
|
400
|
+
malformed(`${path}.runs`, `${path}.runs is required and must be an array.`);
|
|
401
|
+
return;
|
|
402
|
+
}
|
|
403
|
+
cell.runs.forEach((run, runIndex) => {
|
|
404
|
+
const runPath = `${path}.runs[${runIndex}]`;
|
|
405
|
+
if (!isRecord(run)) {
|
|
406
|
+
malformed(runPath, `${runPath} must be an object.`);
|
|
407
|
+
return;
|
|
408
|
+
}
|
|
409
|
+
if (typeof run.asset !== "string" || !assetIds.has(run.asset))
|
|
410
|
+
record(
|
|
411
|
+
"WORLD_UNKNOWN_ASSET",
|
|
412
|
+
`${runPath}.asset`,
|
|
413
|
+
`Run references unknown asset '${String(run.asset)}'.`,
|
|
414
|
+
);
|
|
415
|
+
if (typeof run.offset !== "number") {
|
|
416
|
+
malformed(`${runPath}.offset`, `${runPath}.offset must be a number.`);
|
|
417
|
+
return;
|
|
418
|
+
}
|
|
419
|
+
if (typeof run.count !== "number") {
|
|
420
|
+
malformed(`${runPath}.count`, `${runPath}.count must be a number.`);
|
|
421
|
+
return;
|
|
422
|
+
}
|
|
423
|
+
if (
|
|
424
|
+
!Number.isInteger(run.offset) ||
|
|
425
|
+
!Number.isInteger(run.count) ||
|
|
426
|
+
run.offset < 0 ||
|
|
427
|
+
run.count < 0
|
|
428
|
+
)
|
|
429
|
+
record(
|
|
430
|
+
"WORLD_RUN_OUT_OF_RANGE",
|
|
431
|
+
runPath,
|
|
432
|
+
`${runPath} offset and count must be non-negative integers.`,
|
|
433
|
+
);
|
|
434
|
+
else if ((run.offset + run.count) * PLACEMENT_RECORD_BYTES > options.placementsByteLength)
|
|
435
|
+
record(
|
|
436
|
+
"WORLD_RUN_OUT_OF_RANGE",
|
|
437
|
+
runPath,
|
|
438
|
+
`${runPath} reaches past the ${String(options.placementsByteLength)}-byte placement buffer.`,
|
|
439
|
+
);
|
|
440
|
+
});
|
|
441
|
+
});
|
|
442
|
+
}
|
|
443
|
+
|
|
444
|
+
return { errors, ok: errors.length === 0 };
|
|
445
|
+
}
|
|
446
|
+
|
|
447
|
+
/**
|
|
448
|
+
* Borrow the run's placement records as a live view over the placement buffer.
|
|
449
|
+
*
|
|
450
|
+
* @situation feed one cell's instance transforms into a batch without copying
|
|
451
|
+
* @constraint the returned view aliases the caller's buffer; writing to it mutates the source
|
|
452
|
+
* @example const records = cellPlacements(buffer, { asset: "tree", offset: 0, count: 120 });
|
|
453
|
+
*/
|
|
454
|
+
export function cellPlacements(placements: ArrayBuffer, run: IWorldRun): Float32Array {
|
|
455
|
+
if (
|
|
456
|
+
!Number.isInteger(run.offset) ||
|
|
457
|
+
!Number.isInteger(run.count) ||
|
|
458
|
+
run.offset < 0 ||
|
|
459
|
+
run.count < 0
|
|
460
|
+
)
|
|
461
|
+
throw new RangeError("Placement run offset and count must be non-negative integers.");
|
|
462
|
+
const start = run.offset * PLACEMENT_RECORD_BYTES;
|
|
463
|
+
const length = run.count * PLACEMENT_RECORD_BYTES;
|
|
464
|
+
if (start + length > placements.byteLength)
|
|
465
|
+
throw new RangeError(
|
|
466
|
+
`Placement run [${String(run.offset)}, ${String(run.offset + run.count)}) reaches past the ${String(placements.byteLength)}-byte buffer.`,
|
|
467
|
+
);
|
|
468
|
+
return new Float32Array(placements, start, run.count * (PLACEMENT_RECORD_BYTES / 4));
|
|
469
|
+
}
|