pelican-engine 0.0.0-stage → 0.3.1
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/AGENTS.md +147 -0
- package/LICENSE +22 -0
- package/README.md +129 -2
- package/distribution.json +197 -0
- package/docs/AI-WORKFLOW.md +517 -0
- package/docs/ARCHITECTURE.md +268 -0
- package/docs/CAPABILITIES.md +264 -0
- package/docs/DECISIONS.md +107 -0
- package/docs/M3-USAGE.md +192 -0
- package/docs/PELICAN-MIGRATION.md +38 -0
- package/docs/RENDER-BACKENDS.md +50 -0
- package/docs/ROADMAP.md +239 -0
- package/docs/THIRD-PARTY-NOTICES.md +151 -0
- package/docs/api/REFERENCE.md +1435 -0
- package/docs/api/index.json +1139 -0
- package/docs/npm/DISTRIBUTION.md +130 -0
- package/docs/npm/GAME-AUTHOR.md +147 -0
- package/engine.manifest.json +15 -0
- package/lib/assets/audio.js +67 -0
- package/lib/assets/errors.js +36 -0
- package/lib/assets/glb.js +277 -0
- package/lib/assets/index.js +53 -0
- package/lib/assets/jpeg.js +199 -0
- package/lib/assets/model.js +558 -0
- package/lib/assets/optimize.js +95 -0
- package/lib/assets/texture.js +187 -0
- package/lib/compiler/distribution.js +17 -0
- package/lib/compiler/extract.js +425 -0
- package/lib/compiler/graph.js +366 -0
- package/lib/compiler/index.js +574 -0
- package/lib/compiler/normalize.js +1194 -0
- package/lib/compiler/source-map.js +25 -0
- package/lib/compiler/types.js +2 -0
- package/lib/compiler/version.js +93 -0
- package/lib/experiments/simulation/index.js +2 -0
- package/lib/experiments/simulation/math.js +41 -0
- package/lib/experiments/simulation/probe.js +215 -0
- package/lib/experiments/simulation/scenes.js +192 -0
- package/lib/experiments/simulation/solver.js +346 -0
- package/lib/experiments/simulation/types.js +1 -0
- package/lib/experiments/world/adapters.js +30 -0
- package/lib/experiments/world/geometry.js +180 -0
- package/lib/experiments/world/index.js +2 -0
- package/lib/experiments/world/probe.js +288 -0
- package/lib/experiments/world/types.js +1 -0
- package/lib/experiments/world/world.js +599 -0
- package/lib/navigation/index.js +157 -0
- package/lib/physics/index.js +909 -0
- package/lib/protocol/index.js +92 -0
- package/lib/renderer/acceleration.js +609 -0
- package/lib/renderer/browser.js +2015 -0
- package/lib/renderer/bsdf.js +260 -0
- package/lib/renderer/checkpoint.js +88 -0
- package/lib/renderer/compute-executor.js +1034 -0
- package/lib/renderer/compute-texture-assets.js +49 -0
- package/lib/renderer/compute-view-contract.js +1 -0
- package/lib/renderer/denoiser.js +361 -0
- package/lib/renderer/dielectric.js +360 -0
- package/lib/renderer/embedded-image-pixels.js +368 -0
- package/lib/renderer/emissive-lights.js +67 -0
- package/lib/renderer/environment-importance.js +55 -0
- package/lib/renderer/environment.js +346 -0
- package/lib/renderer/gameplay.js +464 -0
- package/lib/renderer/geometry.js +103 -0
- package/lib/renderer/graph-expressions.js +485 -0
- package/lib/renderer/graph-tsl.js +141 -0
- package/lib/renderer/graph.js +214 -0
- package/lib/renderer/managed-texture-sampling.js +29 -0
- package/lib/renderer/material-graphs.js +297 -0
- package/lib/renderer/medium.js +348 -0
- package/lib/renderer/models.js +1053 -0
- package/lib/renderer/motion-shader.js +40 -0
- package/lib/renderer/path-shader.js +196 -0
- package/lib/renderer/pathtrace.js +324 -0
- package/lib/renderer/postprocess-contract.js +1 -0
- package/lib/renderer/postprocess.js +494 -0
- package/lib/renderer/render-buffers.js +132 -0
- package/lib/renderer/render-textures.js +155 -0
- package/lib/renderer/startup.js +50 -0
- package/lib/renderer/surface-capture.js +199 -0
- package/lib/renderer/surface-gpu.js +270 -0
- package/lib/renderer/surface-motion.js +84 -0
- package/lib/renderer/surface-ray-shader.js +91 -0
- package/lib/renderer/surface-shader.js +88 -0
- package/lib/renderer/surface-tracer.js +1720 -0
- package/lib/renderer/surface.js +1425 -0
- package/lib/renderer/temporal-filter.js +512 -0
- package/lib/renderer/texture-pixels.js +207 -0
- package/lib/renderer/traversal-nodes.js +54 -0
- package/lib/renderer/ui.js +446 -0
- package/lib/renderer/vertex-bounds.js +127 -0
- package/lib/renderer/vertex-contract.js +1 -0
- package/lib/renderer/vertex-graphs.js +197 -0
- package/lib/renderer/volume-shader.js +50 -0
- package/lib/runtime/compute-contract.js +1 -0
- package/lib/runtime/compute-service.js +674 -0
- package/lib/runtime/contracts.js +1 -0
- package/lib/runtime/error.js +37 -0
- package/lib/runtime/events.js +189 -0
- package/lib/runtime/game-services.js +772 -0
- package/lib/runtime/host.js +839 -0
- package/lib/runtime/material-parameters.js +145 -0
- package/lib/runtime/plugins.js +1 -0
- package/lib/runtime/postprocess-contract.js +1 -0
- package/lib/runtime/postprocess.js +189 -0
- package/lib/runtime/prefabs.js +13 -0
- package/lib/runtime/random.js +88 -0
- package/lib/runtime/render-buffer-contract.js +1 -0
- package/lib/runtime/render-buffers.js +243 -0
- package/lib/runtime/render-capabilities.js +17 -0
- package/lib/runtime/render-settings.js +249 -0
- package/lib/runtime/render-texture-contract.js +1 -0
- package/lib/runtime/render-textures.js +271 -0
- package/lib/runtime/resources.js +648 -0
- package/lib/runtime/scheduler.js +765 -0
- package/lib/runtime/storage.js +169 -0
- package/lib/runtime/world.js +594 -0
- package/lib/schema/index.js +24 -0
- package/lib/sdk/graph-values.js +16 -0
- package/lib/sdk/index.d.ts +800 -0
- package/lib/sdk/index.js +82 -0
- package/lib/tools/api-index.js +113 -0
- package/lib/tools/browser-session.js +89 -0
- package/lib/tools/cli.js +513 -0
- package/lib/tools/compress-dist.js +59 -0
- package/lib/tools/control-client.js +153 -0
- package/lib/tools/control-server.js +633 -0
- package/lib/tools/diagnostic-code.js +3 -0
- package/lib/tools/doctor.js +496 -0
- package/lib/tools/npm/browser-cli.js +6 -0
- package/lib/tools/npm/entry.js +40 -0
- package/lib/tools/npm/layout.js +195 -0
- package/lib/tools/setup.js +153 -0
- package/licenses/@dimforge/rapier2d-compat/LICENSE +201 -0
- package/licenses/@dimforge/rapier3d-compat/LICENSE +201 -0
- package/licenses/@gltf-transform/core/LICENSE.md +21 -0
- package/licenses/@gltf-transform/extensions/LICENSE.md +21 -0
- package/licenses/@gltf-transform/functions/LICENSE.md +21 -0
- package/licenses/@img/colour/LICENSE.md +82 -0
- package/licenses/@img/sharp-win32-x64/LICENSE +191 -0
- package/licenses/@oxc-project/types/LICENSE +22 -0
- package/licenses/@rolldown/pluginutils/LICENSE +21 -0
- package/licenses/@tweenjs/tween.js/LICENSE +23 -0
- package/licenses/@types/ndarray/LICENSE +21 -0
- package/licenses/@types/node/LICENSE +21 -0
- package/licenses/@types/stats.js/LICENSE +21 -0
- package/licenses/@types/three/@dimforge/rapier3d-compat/LICENSE +201 -0
- package/licenses/@types/three/LICENSE +21 -0
- package/licenses/@types/webxr/LICENSE +21 -0
- package/licenses/@webgpu/types/LICENSE +26 -0
- package/licenses/THIRD-PARTY-NOTICES.md +139 -0
- package/licenses/cwise-compiler/LICENSE +22 -0
- package/licenses/detect-libc/LICENSE +201 -0
- package/licenses/esbuild/LICENSE.md +21 -0
- package/licenses/fast-png/LICENSE +21 -0
- package/licenses/fdir/LICENSE +7 -0
- package/licenses/fflate/LICENSE +21 -0
- package/licenses/iobuffer/LICENSE +22 -0
- package/licenses/iota-array/LICENSE +22 -0
- package/licenses/is-buffer/LICENSE +21 -0
- package/licenses/ktx-parse/LICENSE +21 -0
- package/licenses/lightningcss/LICENSE +373 -0
- package/licenses/lightningcss-win32-x64-msvc/LICENSE +373 -0
- package/licenses/meshoptimizer/LICENSE.md +21 -0
- package/licenses/nanoid/LICENSE +20 -0
- package/licenses/ndarray/LICENSE +22 -0
- package/licenses/ndarray-lanczos/LICENSE +21 -0
- package/licenses/ndarray-ops/LICENSE +22 -0
- package/licenses/ndarray-pixels/LICENSE +21 -0
- package/licenses/ngraph.path/LICENSE +21 -0
- package/licenses/picocolors/LICENSE +15 -0
- package/licenses/picomatch/LICENSE +21 -0
- package/licenses/playwright/LICENSE +202 -0
- package/licenses/playwright/NOTICE +5 -0
- package/licenses/playwright-core/LICENSE +202 -0
- package/licenses/playwright-core/NOTICE +5 -0
- package/licenses/postcss/LICENSE +20 -0
- package/licenses/prettier/LICENSE +7 -0
- package/licenses/property-graph/LICENSE +21 -0
- package/licenses/rolldown/LICENSE +25 -0
- package/licenses/semver/LICENSE +15 -0
- package/licenses/sharp/LICENSE +191 -0
- package/licenses/source-map-js/LICENSE +28 -0
- package/licenses/three/LICENSE +21 -0
- package/licenses/tinyglobby/LICENSE +21 -0
- package/licenses/tsx/LICENSE +21 -0
- package/licenses/typescript/LICENSE.txt +55 -0
- package/licenses/undici-types/LICENSE +21 -0
- package/licenses/uniq/LICENSE +22 -0
- package/licenses/vite/LICENSE.md +2084 -0
- package/package.json +49 -4
- package/web/index.html +34 -0
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import path from "node:path";
|
|
2
|
+
/** Stable source-map names even when Windows engine and game live on different drives. */
|
|
3
|
+
export function mapSourcePath(source, projectRoot, sdkPath, paths = path, sourceRoot = "") {
|
|
4
|
+
if (source.includes("pelican:m0-game-entry") ||
|
|
5
|
+
source.includes("pelican:game-entry"))
|
|
6
|
+
return "pelican-generated-entry";
|
|
7
|
+
const absolute = paths.resolve(paths.isAbsolute(source)
|
|
8
|
+
? source
|
|
9
|
+
: paths.resolve(projectRoot, "dist", sourceRoot, source));
|
|
10
|
+
const sdk = paths.resolve(sdkPath);
|
|
11
|
+
const same = paths === path.win32 || (paths === path && process.platform === "win32")
|
|
12
|
+
? absolute.toLowerCase() === sdk.toLowerCase()
|
|
13
|
+
: absolute === sdk;
|
|
14
|
+
if (same)
|
|
15
|
+
return "pelican-sdk/index.ts";
|
|
16
|
+
const sdkRelative = paths.relative(paths.dirname(sdk), absolute);
|
|
17
|
+
if (sdkRelative &&
|
|
18
|
+
!sdkRelative.startsWith("..") &&
|
|
19
|
+
!paths.isAbsolute(sdkRelative))
|
|
20
|
+
return "pelican-sdk/" + sdkRelative.replaceAll("\\", "/");
|
|
21
|
+
const relative = paths.relative(projectRoot, absolute);
|
|
22
|
+
if (paths.isAbsolute(relative))
|
|
23
|
+
throw new Error("TC_SOURCE_MAP_EXTERNAL: Cannot map a non-SDK source on another drive.");
|
|
24
|
+
return relative.replaceAll("\\", "/");
|
|
25
|
+
}
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
import path from "node:path";
|
|
2
|
+
import ts from "typescript";
|
|
3
|
+
/** Absolute cross-drive Windows paths are retained; relative paths use the project root. */
|
|
4
|
+
export function resolveEnginePath(projectRoot, enginePath, paths = path) {
|
|
5
|
+
return paths.resolve(projectRoot, enginePath);
|
|
6
|
+
}
|
|
7
|
+
/** Inspect the version declaration without importing/executing the selected SDK. */
|
|
8
|
+
export function readSDKVersion(text) {
|
|
9
|
+
const source = ts.createSourceFile("sdk.ts", text, ts.ScriptTarget.Latest, true);
|
|
10
|
+
for (const statement of source.statements) {
|
|
11
|
+
if (!ts.isVariableStatement(statement))
|
|
12
|
+
continue;
|
|
13
|
+
for (const declaration of statement.declarationList.declarations) {
|
|
14
|
+
if (ts.isIdentifier(declaration.name) &&
|
|
15
|
+
declaration.name.text === "SDK_VERSION") {
|
|
16
|
+
let value = declaration.initializer;
|
|
17
|
+
while (value &&
|
|
18
|
+
(ts.isAsExpression(value) ||
|
|
19
|
+
ts.isSatisfiesExpression(value) ||
|
|
20
|
+
ts.isParenthesizedExpression(value)))
|
|
21
|
+
value = value.expression;
|
|
22
|
+
if (value && ts.isStringLiteral(value))
|
|
23
|
+
return value.text;
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
return undefined;
|
|
28
|
+
}
|
|
29
|
+
/** A lock is exact, including prerelease identifiers; semver ranges are not locks. */
|
|
30
|
+
export function validateManifest(value, sdkVersion) {
|
|
31
|
+
const diagnostics = [];
|
|
32
|
+
const fail = (message) => diagnostics.push({
|
|
33
|
+
code: "TC_PROJECT_CONFIG",
|
|
34
|
+
severity: "error",
|
|
35
|
+
message,
|
|
36
|
+
suggestion: "Use entry, engineVersion and engine.{version,path} strings in pelican.project.json.",
|
|
37
|
+
});
|
|
38
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) {
|
|
39
|
+
fail("Project manifest must be an object.");
|
|
40
|
+
return { diagnostics };
|
|
41
|
+
}
|
|
42
|
+
const manifest = value;
|
|
43
|
+
for (const key of ["entry", "engineVersion"])
|
|
44
|
+
if (manifest[key] !== undefined &&
|
|
45
|
+
(typeof manifest[key] !== "string" || !manifest[key].trim()))
|
|
46
|
+
fail(key + " must be a non-empty string.");
|
|
47
|
+
if (manifest.engine !== undefined) {
|
|
48
|
+
if (!manifest.engine ||
|
|
49
|
+
typeof manifest.engine !== "object" ||
|
|
50
|
+
Array.isArray(manifest.engine))
|
|
51
|
+
fail("engine must be an object.");
|
|
52
|
+
else
|
|
53
|
+
for (const key of ["version", "path"])
|
|
54
|
+
if (manifest.engine[key] !== undefined &&
|
|
55
|
+
(typeof manifest.engine[key] !== "string" ||
|
|
56
|
+
!manifest.engine[key].trim()))
|
|
57
|
+
fail("engine." + key + " must be a non-empty string.");
|
|
58
|
+
}
|
|
59
|
+
if (diagnostics.length)
|
|
60
|
+
return { diagnostics };
|
|
61
|
+
for (const [key, version] of [
|
|
62
|
+
["engineVersion", manifest.engineVersion],
|
|
63
|
+
["engine.version", manifest.engine?.version],
|
|
64
|
+
]) {
|
|
65
|
+
if (version !== undefined && version !== sdkVersion)
|
|
66
|
+
diagnostics.push({
|
|
67
|
+
code: "TC_ENGINE_VERSION_MISMATCH",
|
|
68
|
+
severity: "error",
|
|
69
|
+
message: key +
|
|
70
|
+
" locks " +
|
|
71
|
+
version +
|
|
72
|
+
" but the selected SDK is " +
|
|
73
|
+
sdkVersion +
|
|
74
|
+
".",
|
|
75
|
+
suggestion: "Migrate the project to the public API of " +
|
|
76
|
+
sdkVersion +
|
|
77
|
+
", then explicitly update " +
|
|
78
|
+
key +
|
|
79
|
+
". M0 0.0.1 projects require migration; no implicit upgrade is performed.",
|
|
80
|
+
});
|
|
81
|
+
}
|
|
82
|
+
if (manifest.engineVersion === undefined &&
|
|
83
|
+
manifest.engine?.version === undefined)
|
|
84
|
+
diagnostics.push({
|
|
85
|
+
code: "TC_ENGINE_VERSION_UNLOCKED",
|
|
86
|
+
severity: "warning",
|
|
87
|
+
message: "Legacy project has no engine version lock.",
|
|
88
|
+
suggestion: "Add engineVersion: " +
|
|
89
|
+
JSON.stringify(sdkVersion) +
|
|
90
|
+
" to pelican.project.json for reproducible builds.",
|
|
91
|
+
});
|
|
92
|
+
return { manifest, diagnostics };
|
|
93
|
+
}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
export const add = (a, b) => [
|
|
2
|
+
a[0] + b[0],
|
|
3
|
+
a[1] + b[1],
|
|
4
|
+
a[2] + b[2],
|
|
5
|
+
];
|
|
6
|
+
export const sub = (a, b) => [
|
|
7
|
+
a[0] - b[0],
|
|
8
|
+
a[1] - b[1],
|
|
9
|
+
a[2] - b[2],
|
|
10
|
+
];
|
|
11
|
+
export const mul = (a, s) => [a[0] * s, a[1] * s, a[2] * s];
|
|
12
|
+
export const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
|
|
13
|
+
export const cross = (a, b) => [
|
|
14
|
+
a[1] * b[2] - a[2] * b[1],
|
|
15
|
+
a[2] * b[0] - a[0] * b[2],
|
|
16
|
+
a[0] * b[1] - a[1] * b[0],
|
|
17
|
+
];
|
|
18
|
+
export const length = (a) => Math.hypot(...a);
|
|
19
|
+
export function accumulate(a, b, scale = 1) {
|
|
20
|
+
for (let k = 0; k < 3; k++)
|
|
21
|
+
a[k] += b[k] * scale;
|
|
22
|
+
}
|
|
23
|
+
export const volume = (a, b, c, d) => dot(sub(b, a), cross(sub(c, a), sub(d, a))) / 6;
|
|
24
|
+
export function seededRandom(seed) {
|
|
25
|
+
let state = seed >>> 0;
|
|
26
|
+
return () => {
|
|
27
|
+
state = (state + 0x6d2b79f5) >>> 0;
|
|
28
|
+
let t = Math.imul(state ^ (state >>> 15), 1 | state);
|
|
29
|
+
t ^= t + Math.imul(t ^ (t >>> 7), 61 | t);
|
|
30
|
+
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
|
|
31
|
+
};
|
|
32
|
+
}
|
|
33
|
+
export function copy(value) {
|
|
34
|
+
return JSON.parse(JSON.stringify(value));
|
|
35
|
+
}
|
|
36
|
+
export function fail(code, message) {
|
|
37
|
+
throw new Error(`${code}: ${message}`);
|
|
38
|
+
}
|
|
39
|
+
export const isVec3 = (v) => Array.isArray(v) &&
|
|
40
|
+
v.length === 3 &&
|
|
41
|
+
v.every((x) => typeof x === "number" && Number.isFinite(x));
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
import { createSimulation } from "./solver.js";
|
|
2
|
+
import { KINDS } from "./scenes.js";
|
|
3
|
+
import { length, sub } from "./math.js";
|
|
4
|
+
function positionDifference(a, b) {
|
|
5
|
+
const body = Math.max(0, ...a.bodies.map((p, i) => length(sub(p.position, b.bodies[i].position))));
|
|
6
|
+
const differences = a.particles.map((p, i) => length(sub(p.position, b.particles[i].position)));
|
|
7
|
+
return {
|
|
8
|
+
body,
|
|
9
|
+
particles: Math.sqrt(differences.reduce((s, x) => s + x * x, 0) / differences.length),
|
|
10
|
+
max: Math.max(body, ...differences),
|
|
11
|
+
};
|
|
12
|
+
}
|
|
13
|
+
/** Numeric diff includes velocities, counters, configuration, rest lengths and every coordinate. */
|
|
14
|
+
export function maxSnapshotDifference(a, b) {
|
|
15
|
+
if (typeof a === "number" && typeof b === "number")
|
|
16
|
+
return Math.abs(a - b);
|
|
17
|
+
if (a === b)
|
|
18
|
+
return 0;
|
|
19
|
+
if (!a || !b || typeof a !== "object" || typeof b !== "object")
|
|
20
|
+
return Infinity;
|
|
21
|
+
const ak = Object.keys(a), bk = Object.keys(b);
|
|
22
|
+
if (ak.length !== bk.length || ak.some((key) => !Object.hasOwn(b, key)))
|
|
23
|
+
return Infinity;
|
|
24
|
+
return Math.max(0, ...ak.map((key) => maxSnapshotDifference(a[key], b[key])));
|
|
25
|
+
}
|
|
26
|
+
const bytes = (x) => new TextEncoder().encode(JSON.stringify(x)).byteLength;
|
|
27
|
+
export function runSimulationProbe(options = {}) {
|
|
28
|
+
const seed = options.seed ?? 12345, steps = options.steps ?? 120, cycles = options.lifecycleCycles ?? 8;
|
|
29
|
+
const kinds = options.kinds ?? [...KINDS];
|
|
30
|
+
if (!Number.isInteger(steps) || steps < 60 || steps > 3600)
|
|
31
|
+
throw new Error("SIM_PROBE_OPTIONS: steps must be in [60,3600].");
|
|
32
|
+
if (!Number.isInteger(cycles) || cycles < 1 || cycles > 100)
|
|
33
|
+
throw new Error("SIM_PROBE_OPTIONS: lifecycleCycles must be in [1,100].");
|
|
34
|
+
if (!kinds.length ||
|
|
35
|
+
new Set(kinds).size !== kinds.length ||
|
|
36
|
+
kinds.some((k) => !KINDS.includes(k)))
|
|
37
|
+
throw new Error("SIM_PROBE_OPTIONS: kinds must be a nonempty unique list of valid kinds.");
|
|
38
|
+
const cases = kinds.map((kind) => probeCase(kind, seed, steps, cycles));
|
|
39
|
+
return {
|
|
40
|
+
prototype: "pelican-m0-cpu-interaction",
|
|
41
|
+
version: 1,
|
|
42
|
+
passed: cases.every((c) => c.passed),
|
|
43
|
+
seed,
|
|
44
|
+
fixedDt: 1 / 60,
|
|
45
|
+
steps,
|
|
46
|
+
cases,
|
|
47
|
+
limitations: [
|
|
48
|
+
"Small CPU-only reference experiments; no GPU / WebGPU performance or production physics claim.",
|
|
49
|
+
"One dynamic translational sphere per scene; no angular dynamics, friction, rigid mesh contacts or CCD.",
|
|
50
|
+
"Rope / cloth / tetrahedral softbody couple only to that sphere and static axis-aligned walls, not to each other.",
|
|
51
|
+
"No cloth self-collision, tearing, plasticity, arbitrary solid surface collision or rigid-body library integration.",
|
|
52
|
+
"WCSPH has O(n²) neighbors, compressive pressure / viscosity, no surface tension or boundary-density correction; particle sphere contact is not hydrodynamically accurate buoyancy.",
|
|
53
|
+
"Fixed walls and rope / cloth anchors exchange momentum with the environment; damping dissipates energy.",
|
|
54
|
+
"Owned-array lifecycle checks demonstrate explicit release only, not absence of process / GPU memory leaks.",
|
|
55
|
+
"Snapshot replay is checked on the same JS runtime; no cross-browser or cross-architecture bitwise determinism guarantee.",
|
|
56
|
+
"Render data is renderer-independent; dynamic BVH / actual WebGPU and ray-tracing synchronization is a separate integration test.",
|
|
57
|
+
],
|
|
58
|
+
};
|
|
59
|
+
}
|
|
60
|
+
function probeCase(kind, seed, steps, cycles) {
|
|
61
|
+
const started = performance.now();
|
|
62
|
+
const sim = createSimulation(kind, { seed }), noContact = createSimulation(kind, { seed, contacts: false }), oneWay = createSimulation(kind, { seed, twoWayCoupling: false });
|
|
63
|
+
const initial = sim.getRenderState(), initialSnapshot = sim.snapshot();
|
|
64
|
+
let peakBodyDistanceFromNoContact = 0, peakBodyDistanceFromOneWay = 0, peakParticleRmsFromNoContact = 0, peakParticleRmsFromOneWay = 0;
|
|
65
|
+
const stability = {
|
|
66
|
+
samples: 0,
|
|
67
|
+
allFinite: true,
|
|
68
|
+
maxDistanceRelativeError: 0,
|
|
69
|
+
maxVolumeRelativeError: 0,
|
|
70
|
+
minSignedVolumeRatio: null,
|
|
71
|
+
maxSpeed: 0,
|
|
72
|
+
maxFluidPressure: 0,
|
|
73
|
+
};
|
|
74
|
+
const midpoint = Math.floor(steps / 2);
|
|
75
|
+
let checkpoint, checkpointRender, captureWallMs = 0;
|
|
76
|
+
try {
|
|
77
|
+
for (let frame = 1; frame <= steps; frame++) {
|
|
78
|
+
const inspection = sim.step(), nc = noContact.step(), ow = oneWay.step();
|
|
79
|
+
const render = sim.getRenderState();
|
|
80
|
+
const d0 = positionDifference(render, noContact.getRenderState()), d1 = positionDifference(render, oneWay.getRenderState());
|
|
81
|
+
peakBodyDistanceFromNoContact = Math.max(peakBodyDistanceFromNoContact, d0.body);
|
|
82
|
+
peakBodyDistanceFromOneWay = Math.max(peakBodyDistanceFromOneWay, d1.body);
|
|
83
|
+
peakParticleRmsFromNoContact = Math.max(peakParticleRmsFromNoContact, d0.particles);
|
|
84
|
+
peakParticleRmsFromOneWay = Math.max(peakParticleRmsFromOneWay, d1.particles);
|
|
85
|
+
stability.samples++;
|
|
86
|
+
stability.allFinite &&= inspection.finite && nc.finite && ow.finite;
|
|
87
|
+
stability.maxDistanceRelativeError = Math.max(stability.maxDistanceRelativeError, inspection.maxDistanceRelativeError, nc.maxDistanceRelativeError, ow.maxDistanceRelativeError);
|
|
88
|
+
stability.maxVolumeRelativeError = Math.max(stability.maxVolumeRelativeError, inspection.maxVolumeRelativeError, nc.maxVolumeRelativeError, ow.maxVolumeRelativeError);
|
|
89
|
+
if (inspection.minSignedVolumeRatio !== null)
|
|
90
|
+
stability.minSignedVolumeRatio = Math.min(stability.minSignedVolumeRatio ?? Infinity, inspection.minSignedVolumeRatio, nc.minSignedVolumeRatio, ow.minSignedVolumeRatio);
|
|
91
|
+
stability.maxSpeed = Math.max(stability.maxSpeed, inspection.maxSpeed, nc.maxSpeed, ow.maxSpeed);
|
|
92
|
+
stability.maxFluidPressure = Math.max(stability.maxFluidPressure, inspection.fluid?.maxPressure ?? 0, nc.fluid?.maxPressure ?? 0, ow.fluid?.maxPressure ?? 0);
|
|
93
|
+
if (frame === midpoint) {
|
|
94
|
+
const start = performance.now();
|
|
95
|
+
checkpoint = sim.snapshot();
|
|
96
|
+
captureWallMs = performance.now() - start;
|
|
97
|
+
checkpointRender = sim.getRenderState();
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
const final = sim.inspect(), nc = noContact.inspect(), ow = oneWay.inspect(), finalSnapshot = sim.snapshot(), finalRender = sim.getRenderState();
|
|
101
|
+
const restoreStart = performance.now();
|
|
102
|
+
sim.restore(JSON.parse(JSON.stringify(checkpoint)));
|
|
103
|
+
const restoreWallMs = performance.now() - restoreStart;
|
|
104
|
+
const maxRestoreDifference = maxSnapshotDifference(checkpoint, sim.snapshot());
|
|
105
|
+
const renderRestoredExactly = JSON.stringify(checkpointRender) === JSON.stringify(sim.getRenderState());
|
|
106
|
+
sim.step(steps - midpoint);
|
|
107
|
+
const maxReplayDifference = maxSnapshotDifference(finalSnapshot, sim.snapshot());
|
|
108
|
+
const renderReplayedExactly = JSON.stringify(finalRender) === JSON.stringify(sim.getRenderState());
|
|
109
|
+
let releasedEveryCycle = true;
|
|
110
|
+
let ownedCountsAfterDispose = {
|
|
111
|
+
bodies: 0,
|
|
112
|
+
particles: 0,
|
|
113
|
+
constraints: 0,
|
|
114
|
+
triangles: 0,
|
|
115
|
+
};
|
|
116
|
+
for (let cycle = 0; cycle < cycles; cycle++) {
|
|
117
|
+
const temporary = createSimulation(kind, { seed });
|
|
118
|
+
temporary.restore(checkpoint);
|
|
119
|
+
temporary.step(2);
|
|
120
|
+
temporary.dispose();
|
|
121
|
+
temporary.dispose();
|
|
122
|
+
const inspection = temporary.inspect();
|
|
123
|
+
ownedCountsAfterDispose = inspection.resources;
|
|
124
|
+
releasedEveryCycle &&=
|
|
125
|
+
inspection.disposed &&
|
|
126
|
+
Object.values(inspection.resources).every((x) => x === 0);
|
|
127
|
+
}
|
|
128
|
+
const topologyUnchanged = JSON.stringify({ l: initial.links, t: initial.triangles }) ===
|
|
129
|
+
JSON.stringify({ l: finalRender.links, t: finalRender.triangles });
|
|
130
|
+
const checks = {
|
|
131
|
+
finite: stability.allFinite,
|
|
132
|
+
contactOccurred: final.contacts.contactCount > 0,
|
|
133
|
+
noContactControlClean: nc.contacts.contactCount === 0 &&
|
|
134
|
+
nc.contacts.absoluteReactionImpulse === 0,
|
|
135
|
+
oneWayControlHasContactWithoutReaction: ow.contacts.contactCount > 0 &&
|
|
136
|
+
ow.contacts.absoluteReactionImpulse === 0,
|
|
137
|
+
measuredReaction: final.contacts.absoluteReactionImpulse > 1e-5,
|
|
138
|
+
bodyResponds: peakBodyDistanceFromNoContact > 1e-4 &&
|
|
139
|
+
peakBodyDistanceFromOneWay > 1e-4,
|
|
140
|
+
particlesRespond: peakParticleRmsFromNoContact > 1e-4 && peakParticleRmsFromOneWay > 1e-5,
|
|
141
|
+
distanceStable: stability.maxDistanceRelativeError < 0.1,
|
|
142
|
+
volumeStable: stability.maxVolumeRelativeError < 0.1 &&
|
|
143
|
+
(stability.minSignedVolumeRatio === null ||
|
|
144
|
+
stability.minSignedVolumeRatio > 0),
|
|
145
|
+
boundedSpeed: stability.maxSpeed < 20,
|
|
146
|
+
fluidPressureActive: kind !== "fluid" || stability.maxFluidPressure > 0,
|
|
147
|
+
restored: maxRestoreDifference === 0 && renderRestoredExactly,
|
|
148
|
+
replayed: maxReplayDifference === 0 && renderReplayedExactly,
|
|
149
|
+
geometryUpdated: positionDifference(initial, finalRender).max > 1e-4 &&
|
|
150
|
+
topologyUnchanged,
|
|
151
|
+
released: releasedEveryCycle,
|
|
152
|
+
};
|
|
153
|
+
return {
|
|
154
|
+
kind,
|
|
155
|
+
passed: Object.values(checks).every(Boolean),
|
|
156
|
+
checks,
|
|
157
|
+
load: {
|
|
158
|
+
bodies: initial.bodies.length,
|
|
159
|
+
particles: initial.particles.length,
|
|
160
|
+
distanceConstraints: initialSnapshot.distances.length,
|
|
161
|
+
volumeConstraints: initialSnapshot.volumes.length,
|
|
162
|
+
triangles: initial.triangles.length,
|
|
163
|
+
},
|
|
164
|
+
controls: {
|
|
165
|
+
noContact: {
|
|
166
|
+
contactCount: nc.contacts.contactCount,
|
|
167
|
+
absoluteReactionImpulse: nc.contacts.absoluteReactionImpulse,
|
|
168
|
+
finalBodyPosition: nc.bodies[0].position,
|
|
169
|
+
},
|
|
170
|
+
oneWay: {
|
|
171
|
+
contactCount: ow.contacts.contactCount,
|
|
172
|
+
absoluteReactionImpulse: ow.contacts.absoluteReactionImpulse,
|
|
173
|
+
finalBodyPosition: ow.bodies[0].position,
|
|
174
|
+
},
|
|
175
|
+
peakBodyDistanceFromNoContact,
|
|
176
|
+
peakBodyDistanceFromOneWay,
|
|
177
|
+
peakParticleRmsFromNoContact,
|
|
178
|
+
peakParticleRmsFromOneWay,
|
|
179
|
+
},
|
|
180
|
+
stability,
|
|
181
|
+
snapshot: {
|
|
182
|
+
bytes: bytes(checkpoint),
|
|
183
|
+
captureWallMs,
|
|
184
|
+
restoreWallMs,
|
|
185
|
+
capturedTick: midpoint,
|
|
186
|
+
replayedSteps: steps - midpoint,
|
|
187
|
+
maxRestoreDifference,
|
|
188
|
+
maxReplayDifference,
|
|
189
|
+
renderRestoredExactly,
|
|
190
|
+
renderReplayedExactly,
|
|
191
|
+
},
|
|
192
|
+
geometry: {
|
|
193
|
+
initialBytes: bytes(initial),
|
|
194
|
+
finalBytes: bytes(finalRender),
|
|
195
|
+
maxPositionChange: positionDifference(initial, finalRender).max,
|
|
196
|
+
topologyUnchanged,
|
|
197
|
+
},
|
|
198
|
+
timing: {
|
|
199
|
+
coupledSolverWallMs: final.timing.solverWallMs,
|
|
200
|
+
noContactSolverWallMs: nc.timing.solverWallMs,
|
|
201
|
+
oneWaySolverWallMs: ow.timing.solverWallMs,
|
|
202
|
+
meanCoupledStepMs: final.timing.meanStepMs,
|
|
203
|
+
maxCoupledStepMs: final.timing.maxStepMs,
|
|
204
|
+
probeWallMs: performance.now() - started,
|
|
205
|
+
},
|
|
206
|
+
lifecycle: { cycles, releasedEveryCycle, ownedCountsAfterDispose },
|
|
207
|
+
final,
|
|
208
|
+
};
|
|
209
|
+
}
|
|
210
|
+
finally {
|
|
211
|
+
sim.dispose();
|
|
212
|
+
noContact.dispose();
|
|
213
|
+
oneWay.dispose();
|
|
214
|
+
}
|
|
215
|
+
}
|
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
import { copy, fail, isVec3, length, seededRandom, sub, volume, } from "./math.js";
|
|
2
|
+
export const KINDS = ["rope", "cloth", "softbody", "fluid"];
|
|
3
|
+
export function resolveOptions(kind, options = {}) {
|
|
4
|
+
if (!KINDS.includes(kind))
|
|
5
|
+
fail("SIM_KIND", `Unknown simulation kind: ${kind}`);
|
|
6
|
+
const result = {
|
|
7
|
+
seed: options.seed ?? 12345,
|
|
8
|
+
fixedDt: options.fixedDt ?? 1 / 60,
|
|
9
|
+
substeps: options.substeps ?? 6,
|
|
10
|
+
iterations: options.iterations ?? 8,
|
|
11
|
+
twoWayCoupling: options.twoWayCoupling ?? true,
|
|
12
|
+
contacts: options.contacts ?? true,
|
|
13
|
+
gravity: copy(options.gravity ?? [0, -2, 0]),
|
|
14
|
+
bodyPosition: copy(options.bodyPosition ??
|
|
15
|
+
(kind === "cloth" ? [0.08, 0.15, -0.72] : [-0.78, 0.15, 0])),
|
|
16
|
+
bodyVelocity: copy(options.bodyVelocity ?? (kind === "cloth" ? [0, 0, 1.6] : [1.6, 0, 0])),
|
|
17
|
+
};
|
|
18
|
+
if (!Number.isSafeInteger(result.seed) ||
|
|
19
|
+
result.seed < 0 ||
|
|
20
|
+
result.seed > 0xffffffff)
|
|
21
|
+
fail("SIM_OPTIONS", "seed must be an unsigned 32-bit integer.");
|
|
22
|
+
if (!Number.isFinite(result.fixedDt) ||
|
|
23
|
+
result.fixedDt < 1 / 1000 ||
|
|
24
|
+
result.fixedDt > 1 / 30)
|
|
25
|
+
fail("SIM_OPTIONS", "fixedDt must be between 1/1000 and 1/30 seconds.");
|
|
26
|
+
for (const key of ["substeps", "iterations"]) {
|
|
27
|
+
if (!Number.isInteger(result[key]) || result[key] < 1 || result[key] > 32)
|
|
28
|
+
fail("SIM_OPTIONS", `${key} must be an integer in [1,32].`);
|
|
29
|
+
}
|
|
30
|
+
if (typeof result.contacts !== "boolean" ||
|
|
31
|
+
typeof result.twoWayCoupling !== "boolean")
|
|
32
|
+
fail("SIM_OPTIONS", "Contact options must be boolean.");
|
|
33
|
+
for (const key of ["gravity", "bodyPosition", "bodyVelocity"]) {
|
|
34
|
+
if (!isVec3(result[key]) || result[key].some((x) => Math.abs(x) > 100))
|
|
35
|
+
fail("SIM_OPTIONS", `${key} must contain three finite values in [-100,100].`);
|
|
36
|
+
}
|
|
37
|
+
return result;
|
|
38
|
+
}
|
|
39
|
+
export function makeScene(kind, options) {
|
|
40
|
+
const s = {
|
|
41
|
+
format: "pelican-m0-simulation",
|
|
42
|
+
version: 1,
|
|
43
|
+
kind,
|
|
44
|
+
options: copy(options),
|
|
45
|
+
tick: 0,
|
|
46
|
+
bodies: [
|
|
47
|
+
{
|
|
48
|
+
id: "body:0",
|
|
49
|
+
position: copy(options.bodyPosition),
|
|
50
|
+
velocity: copy(options.bodyVelocity),
|
|
51
|
+
inverseMass: 1 / 0.35,
|
|
52
|
+
radius: 0.25,
|
|
53
|
+
},
|
|
54
|
+
],
|
|
55
|
+
particles: [],
|
|
56
|
+
distances: [],
|
|
57
|
+
volumes: [],
|
|
58
|
+
triangles: [],
|
|
59
|
+
counters: {
|
|
60
|
+
contactCount: 0,
|
|
61
|
+
reactionImpulse: [0, 0, 0],
|
|
62
|
+
absoluteReactionImpulse: 0,
|
|
63
|
+
maxContactCorrection: 0,
|
|
64
|
+
maxObservedSpeed: 0,
|
|
65
|
+
},
|
|
66
|
+
};
|
|
67
|
+
const rng = seededRandom(options.seed);
|
|
68
|
+
const particle = (position, pinned = false, radius = 0.045, mass = 0.025) => {
|
|
69
|
+
const index = s.particles.length;
|
|
70
|
+
// Seeded small perturbation breaks symmetry; no random forces / prescribed trajectories.
|
|
71
|
+
const p = position.map((x) => x + (pinned ? 0 : (rng() - 0.5) * 0.001));
|
|
72
|
+
s.particles.push({
|
|
73
|
+
id: `particle:${index}`,
|
|
74
|
+
position: p,
|
|
75
|
+
velocity: [0, 0, 0],
|
|
76
|
+
radius,
|
|
77
|
+
inverseMass: pinned ? 0 : 1 / mass,
|
|
78
|
+
});
|
|
79
|
+
return index;
|
|
80
|
+
};
|
|
81
|
+
const edges = new Set();
|
|
82
|
+
const link = (a, b, compliance = 1e-7) => {
|
|
83
|
+
const key = `${Math.min(a, b)}:${Math.max(a, b)}`;
|
|
84
|
+
if (edges.has(key))
|
|
85
|
+
return;
|
|
86
|
+
edges.add(key);
|
|
87
|
+
s.distances.push({
|
|
88
|
+
a,
|
|
89
|
+
b,
|
|
90
|
+
restLength: length(sub(s.particles[a].position, s.particles[b].position)),
|
|
91
|
+
compliance,
|
|
92
|
+
});
|
|
93
|
+
};
|
|
94
|
+
if (kind === "rope") {
|
|
95
|
+
for (let i = 0; i < 15; i++)
|
|
96
|
+
particle([0, 1.15 - i * 0.12, 0], i === 0, 0.055, 0.04);
|
|
97
|
+
for (let i = 0; i < 14; i++)
|
|
98
|
+
link(i, i + 1);
|
|
99
|
+
for (let i = 0; i < 13; i++)
|
|
100
|
+
link(i, i + 2, 2e-4);
|
|
101
|
+
}
|
|
102
|
+
else if (kind === "cloth") {
|
|
103
|
+
const n = 7;
|
|
104
|
+
for (let y = 0; y < n; y++)
|
|
105
|
+
for (let x = 0; x < n; x++)
|
|
106
|
+
particle([-0.6 + x * 0.2, 1 - y * 0.2, 0], y === 0 && (x === 0 || x === n - 1), 0.045, 0.015);
|
|
107
|
+
for (let y = 0; y < n; y++)
|
|
108
|
+
for (let x = 0; x < n; x++) {
|
|
109
|
+
const i = y * n + x;
|
|
110
|
+
if (x + 1 < n)
|
|
111
|
+
link(i, i + 1);
|
|
112
|
+
if (y + 1 < n)
|
|
113
|
+
link(i, i + n);
|
|
114
|
+
if (x + 1 < n && y + 1 < n) {
|
|
115
|
+
link(i, i + n + 1);
|
|
116
|
+
link(i + 1, i + n);
|
|
117
|
+
s.triangles.push([i, i + n, i + 1], [i + 1, i + n, i + n + 1]);
|
|
118
|
+
}
|
|
119
|
+
if (x + 2 < n)
|
|
120
|
+
link(i, i + 2, 5e-5);
|
|
121
|
+
if (y + 2 < n)
|
|
122
|
+
link(i, i + 2 * n, 5e-5);
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
else if (kind === "softbody") {
|
|
126
|
+
const index = (x, y, z) => z * 9 + y * 3 + x;
|
|
127
|
+
for (let z = 0; z < 3; z++)
|
|
128
|
+
for (let y = 0; y < 3; y++)
|
|
129
|
+
for (let x = 0; x < 3; x++)
|
|
130
|
+
particle([(x - 1) * 0.24, 0.2 + (y - 1) * 0.24, (z - 1) * 0.24], false, 0.085, 0.025);
|
|
131
|
+
const faces = new Map();
|
|
132
|
+
for (let z = 0; z < 2; z++)
|
|
133
|
+
for (let y = 0; y < 2; y++)
|
|
134
|
+
for (let x = 0; x < 2; x++) {
|
|
135
|
+
const v = [
|
|
136
|
+
index(x, y, z),
|
|
137
|
+
index(x + 1, y, z),
|
|
138
|
+
index(x, y + 1, z),
|
|
139
|
+
index(x + 1, y + 1, z),
|
|
140
|
+
index(x, y, z + 1),
|
|
141
|
+
index(x + 1, y, z + 1),
|
|
142
|
+
index(x, y + 1, z + 1),
|
|
143
|
+
index(x + 1, y + 1, z + 1),
|
|
144
|
+
];
|
|
145
|
+
for (const local of [
|
|
146
|
+
[0, 1, 3, 7],
|
|
147
|
+
[0, 3, 2, 7],
|
|
148
|
+
[0, 2, 6, 7],
|
|
149
|
+
[0, 6, 4, 7],
|
|
150
|
+
[0, 4, 5, 7],
|
|
151
|
+
[0, 5, 1, 7],
|
|
152
|
+
]) {
|
|
153
|
+
const t = local.map((i) => v[i]);
|
|
154
|
+
if (volume(...t.map((i) => s.particles[i].position)) < 0)
|
|
155
|
+
[t[1], t[2]] = [t[2], t[1]];
|
|
156
|
+
s.volumes.push({
|
|
157
|
+
indices: t,
|
|
158
|
+
restVolume: volume(...t.map((i) => s.particles[i].position)),
|
|
159
|
+
compliance: 1e-10,
|
|
160
|
+
});
|
|
161
|
+
for (let a = 0; a < 4; a++)
|
|
162
|
+
for (let b = a + 1; b < 4; b++)
|
|
163
|
+
link(t[a], t[b], 2e-6);
|
|
164
|
+
// Outward winding for a positively oriented tetrahedron. Shared interior faces cancel.
|
|
165
|
+
for (const face of [
|
|
166
|
+
[t[1], t[2], t[3]],
|
|
167
|
+
[t[0], t[3], t[2]],
|
|
168
|
+
[t[0], t[1], t[3]],
|
|
169
|
+
[t[0], t[2], t[1]],
|
|
170
|
+
]) {
|
|
171
|
+
const key = [...face].sort((a, b) => a - b).join(":");
|
|
172
|
+
if (faces.has(key))
|
|
173
|
+
faces.delete(key);
|
|
174
|
+
else
|
|
175
|
+
faces.set(key, face);
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
s.triangles = [...faces.values()];
|
|
180
|
+
}
|
|
181
|
+
else {
|
|
182
|
+
// 64 SPH particles: mass = restDensity * latticeSpacing^3, restDensity = 1.
|
|
183
|
+
for (let z = 0; z < 4; z++)
|
|
184
|
+
for (let y = 0; y < 4; y++)
|
|
185
|
+
for (let x = 0; x < 4; x++)
|
|
186
|
+
particle([(x - 1.5) * 0.16, 0.22 + (y - 1.5) * 0.16, (z - 1.5) * 0.16], false, 0.055, 0.16 ** 3);
|
|
187
|
+
}
|
|
188
|
+
return s;
|
|
189
|
+
}
|
|
190
|
+
export function allPoints(s) {
|
|
191
|
+
return [...s.bodies, ...s.particles];
|
|
192
|
+
}
|