@plasius/gpu-physics 0.1.18 → 0.1.19

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/CHANGELOG.md CHANGED
@@ -20,6 +20,32 @@
20
20
  - **Security**
21
21
  - (placeholder)
22
22
 
23
+ ## [0.1.19] - 2026-11-15
24
+
25
+ - **Added**
26
+ - Portable sphere/AABB intersection and continuous swept queries, bounded deterministic kinematic steps, and a React-free collision entry for browser/server game hosts.
27
+
28
+ - **Changed**
29
+ - Refreshed compatible @plasius/* lockfile resolutions to the latest published releases.
30
+ - Bound npm publication to the exact prepared `main` commit after successful push-triggered CI.
31
+ - (placeholder)
32
+
33
+ - **Fixed**
34
+ - Restored trusted branch CI to approved self-hosted Linux/X64 capacity, with
35
+ explicit event/repository/ref guards and regression coverage denying PRs,
36
+ forks and tags; documented bounded, credential-free runner execution.
37
+ - Updated the audit-blocking brace-expansion override from 5.0.9 to 5.0.12.
38
+ - Added exact-commit CI dispatch and disabled package-manager cache finalization in both hosted validation jobs.
39
+ - (placeholder)
40
+
41
+ - **Security**
42
+ - Pin patched development glob, minimatch and brace-expansion resolutions; validate finite collision inputs, bounded paths and integrated state.
43
+ - Removed the npm write-token path, added a fail-closed npm 11.5.1-or-newer OIDC guard, and denied fork PR code access to reviewed CI.
44
+ - Pinned patched transitive npm dependencies to clear the current audit baseline.
45
+ - Moved reviewed CI to explicit GitHub-hosted runners while retaining the same-repository pull-request guard.
46
+ - Added fail-closed source and npm-package admission for the administrative contributor registry and pinned the CI/CD runtime to Node.js 24.18.0 LTS.
47
+ - (placeholder)
48
+
23
49
  ## [0.1.18] - 2026-07-10
24
50
 
25
51
  - **Added**
@@ -269,3 +295,4 @@
269
295
  [0.1.16]: https://github.com/Plasius-LTD/gpu-physics/releases/tag/v0.1.16
270
296
  [0.1.17]: https://github.com/Plasius-LTD/gpu-physics/releases/tag/v0.1.17
271
297
  [0.1.18]: https://github.com/Plasius-LTD/gpu-physics/releases/tag/v0.1.18
298
+ [0.1.19]: https://github.com/Plasius-LTD/gpu-physics/releases/tag/v0.1.19
package/README.md CHANGED
@@ -10,6 +10,47 @@
10
10
 
11
11
  Framework-ready physics bridge package for Plasius GPU migration paths.
12
12
 
13
+ ## Portable collision queries
14
+
15
+ Use `@plasius/gpu-physics/collision` for pure CPU geometry in Node or a browser,
16
+ without importing React or a renderer. The same exports are available from the
17
+ root and browser entries. ESM and CommonJS are supported.
18
+
19
+ ```js
20
+ import { sweepSphereAabb, integrateKinematic } from '@plasius/gpu-physics/collision';
21
+
22
+ const contact = sweepSphereAabb(
23
+ { center: [-10, 0, 0], radius: 1 },
24
+ [20, 0, 0],
25
+ { min: [-1, -1, -1], max: [1, 1, 1] },
26
+ );
27
+ // contact.time === 0.4; contact.position is [-2, 0, 0].
28
+ const next = integrateKinematic(
29
+ { position: [0, 0, 0], velocity: [2, 0, 0] },
30
+ [0, -9.81, 0],
31
+ 1 / 60,
32
+ );
33
+ ```
34
+
35
+ `intersectSpheres`, `intersectSphereAabb` and `intersectAabbs` return a contact
36
+ or `null`. `sweepSphere`, `sweepSphereAabb` and `sweepAabb` return the first
37
+ contact over a displacement against a stationary target: `time` in [0,1],
38
+ moving-centre `position`, stationary-surface `point`, outward `normal`,
39
+ `penetration` and `startsInContact`. Touching includes endpoints and time zero.
40
+ Normals point from the target toward the moving shape. Interior box ties select
41
+ X/Y/Z in order, lower face first; coincident spheres select positive X.
42
+
43
+ `collisionLimits` documents finite input bounds and the 1e-8 contact tolerance.
44
+ Coordinates, displacement and radii are at most 1,000,000 units in magnitude;
45
+ radii are nonnegative and box minima must not exceed maxima. Path endpoints must
46
+ stay in coordinate bounds. Velocity is at most 100,000 units/s, acceleration
47
+ 1,000,000 units/s² and integration steps 0–0.25 seconds. Invalid input or an
48
+ out-of-bounds integrated state throws. Inputs are not mutated. Hosts choose a
49
+ fixed step and own contact response, world scheduling and authority.
50
+
51
+ See [collision design](docs/design/arcade-collisions.md) and
52
+ [ADR-0008](docs/adrs/adr-0008-portable-spatial-collision-queries.md).
53
+
13
54
  The package targets Node.js 24 and currently consumes the stable
14
55
  `@plasius/gpu-shared` 1.x runtime line (`^1.0.12`). Development tooling is
15
56
  validated against TypeScript 7 and the current ESLint 10 release.
@@ -188,3 +229,25 @@ npm run pack:check
188
229
  ## License
189
230
 
190
231
  Apache-2.0
232
+
233
+ <!-- BEGIN PLASIUS RELEASE INTEGRITY -->
234
+ ## Release integrity
235
+
236
+ CI keeps the administrative contributor registry outside Git and npm package
237
+ artifacts using exact, case-normalised path checks. CI runs trusted repository
238
+ branch pushes (including `main`) and manual branch
239
+ validation on `Public CI - Quarantined` with literal `[self-hosted, Linux, X64]`
240
+ labels. Both jobs reject pull requests, fork repositories and tags; there is no
241
+ caller-controlled runner selector. Package-manager caching and checkout credential
242
+ persistence are disabled. Per-ref concurrency and bounded job timeouts constrain
243
+ runner use. A feature branch must have an approved immutable-source admission in
244
+ the runner group before it can execute; never widen the group or use hosted CI
245
+ as a fallback. See [ADR-0007](docs/adrs/adr-0007-trusted-push-self-hosted-ci.md).
246
+ Mandatory coverage and artifact admission do not depend on the remote
247
+ `platform.public-artifact-integrity.enabled` distribution flag. Disabling that
248
+ flag stops staged distribution, not integrity validation.
249
+ Publication uses the GitHub-hosted `production` job with Node 24 and a pinned
250
+ npm 11.6.2 client. It is token-free and proceeds only while the prepared SHA
251
+ is the exact `main` head after successful push-triggered CI. Do not dispatch CD
252
+ until the npm trusted-publisher binding is verified.
253
+ <!-- END PLASIUS RELEASE INTEGRITY -->
package/dist/browser.cjs CHANGED
@@ -19,18 +19,236 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
19
19
  // src/browser.js
20
20
  var browser_exports = {};
21
21
  __export(browser_exports, {
22
+ collisionLimits: () => collisionLimits,
22
23
  createPhysicsSimulationPlan: () => createPhysicsSimulationPlan,
23
24
  createPhysicsWorldSnapshot: () => createPhysicsWorldSnapshot,
24
25
  defaultPhysicsWorkerProfile: () => defaultPhysicsWorkerProfile,
25
26
  getPhysicsWorkerManifest: () => getPhysicsWorkerManifest,
27
+ integrateKinematic: () => integrateKinematic,
28
+ intersectAabbs: () => intersectAabbs,
29
+ intersectSphereAabb: () => intersectSphereAabb,
30
+ intersectSpheres: () => intersectSpheres,
26
31
  physicsDebugOwner: () => physicsDebugOwner,
27
32
  physicsSimulationPlans: () => physicsSimulationPlans,
28
33
  physicsSimulationStageOrder: () => physicsSimulationStageOrder,
29
34
  physicsWorkerManifests: () => physicsWorkerManifests,
30
35
  physicsWorkerProfileNames: () => physicsWorkerProfileNames,
31
- physicsWorkerQueueClasses: () => physicsWorkerQueueClasses
36
+ physicsWorkerQueueClasses: () => physicsWorkerQueueClasses,
37
+ sweepAabb: () => sweepAabb,
38
+ sweepSphere: () => sweepSphere,
39
+ sweepSphereAabb: () => sweepSphereAabb
32
40
  });
33
41
  module.exports = __toCommonJS(browser_exports);
42
+
43
+ // src/collision.js
44
+ var collisionLimits = Object.freeze({
45
+ maxCoordinate: 1e6,
46
+ maxVelocity: 1e5,
47
+ maxAcceleration: 1e6,
48
+ maxStepSeconds: 0.25,
49
+ contactTolerance: 1e-8
50
+ });
51
+ var EPSILON = collisionLimits.contactTolerance;
52
+ function number(value, limit, label, minimum = -limit) {
53
+ if (typeof value !== "number" || !Number.isFinite(value) || value < minimum || value > limit) {
54
+ throw new RangeError(`${label} must be finite and within [${minimum}, ${limit}].`);
55
+ }
56
+ return value;
57
+ }
58
+ function vector(value, limit, label) {
59
+ if (!Array.isArray(value) || value.length !== 3) throw new TypeError(`${label} must be a three-component array.`);
60
+ for (let i = 0; i < 3; i++) number(value[i], limit, `${label}[${i}]`);
61
+ return value;
62
+ }
63
+ function record(value, label) {
64
+ if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${label} must be a shape or state object.`);
65
+ }
66
+ function sphere(value) {
67
+ record(value, "sphere");
68
+ vector(value.center, collisionLimits.maxCoordinate, "sphere.center");
69
+ number(value.radius, collisionLimits.maxCoordinate, "sphere.radius", 0);
70
+ }
71
+ function box(value) {
72
+ record(value, "box");
73
+ vector(value.min, collisionLimits.maxCoordinate, "box.min");
74
+ vector(value.max, collisionLimits.maxCoordinate, "box.max");
75
+ if (value.min.some((x, i) => x > value.max[i])) throw new RangeError("box.min must not exceed box.max.");
76
+ }
77
+ var clamp = (value, min, max) => Math.max(min, Math.min(max, value));
78
+ var at = (start, displacement, time) => start.map((x, i) => x + displacement[i] * time);
79
+ var dot = (a, b) => a.reduce((sum, x, i) => sum + x * b[i], 0);
80
+ var centerOf = (value) => value.min.map((x, i) => (x + value.max[i]) / 2);
81
+ function path(start, displacement) {
82
+ vector(displacement, collisionLimits.maxCoordinate, "displacement");
83
+ vector(at(start, displacement, 1), collisionLimits.maxCoordinate, "path endpoint");
84
+ }
85
+ function spheresContact(a, b) {
86
+ const offset = a.center.map((x, i) => x - b.center[i]);
87
+ const distance = Math.sqrt(dot(offset, offset));
88
+ const radius = a.radius + b.radius;
89
+ if (distance > radius + EPSILON) return null;
90
+ const normal = distance > 0 ? offset.map((x) => x / distance) : [1, 0, 0];
91
+ return { normal, point: b.center.map((x, i) => x + normal[i] * b.radius), penetration: Math.max(0, radius - distance) };
92
+ }
93
+ function sphereBoxContact(a, b) {
94
+ const point = a.center.map((x, i) => clamp(x, b.min[i], b.max[i]));
95
+ const offset = a.center.map((x, i) => x - point[i]);
96
+ const distance = Math.sqrt(dot(offset, offset));
97
+ if (distance > a.radius + EPSILON) return null;
98
+ if (distance > 0) return { point, normal: offset.map((x) => x / distance), penetration: Math.max(0, a.radius - distance) };
99
+ let depth = Infinity, axis = 0, direction = -1;
100
+ for (let i = 0; i < 3; i++) {
101
+ const lower = a.center[i] - b.min[i], upper = b.max[i] - a.center[i];
102
+ if (lower < depth) {
103
+ depth = lower;
104
+ axis = i;
105
+ direction = -1;
106
+ }
107
+ if (upper < depth) {
108
+ depth = upper;
109
+ axis = i;
110
+ direction = 1;
111
+ }
112
+ }
113
+ const normal = [0, 0, 0];
114
+ normal[axis] = direction;
115
+ point[axis] = direction < 0 ? b.min[axis] : b.max[axis];
116
+ return { point, normal, penetration: a.radius + depth };
117
+ }
118
+ function boxesContact(a, b) {
119
+ if (a.min.some((x, i) => x > b.max[i] + EPSILON || a.max[i] < b.min[i] - EPSILON)) return null;
120
+ let depth = Infinity, axis = 0, direction = -1;
121
+ for (let i = 0; i < 3; i++) {
122
+ const lower = a.max[i] - b.min[i], upper = b.max[i] - a.min[i];
123
+ if (lower < depth) {
124
+ depth = lower;
125
+ axis = i;
126
+ direction = -1;
127
+ }
128
+ if (upper < depth) {
129
+ depth = upper;
130
+ axis = i;
131
+ direction = 1;
132
+ }
133
+ }
134
+ const normal = [0, 0, 0];
135
+ normal[axis] = direction;
136
+ const point = centerOf(a).map((x, i) => clamp(x, b.min[i], b.max[i]));
137
+ point[axis] = direction < 0 ? b.min[axis] : b.max[axis];
138
+ return { normal, point, penetration: Math.max(0, depth) };
139
+ }
140
+ function intersectSpheres(a, b) {
141
+ sphere(a);
142
+ sphere(b);
143
+ return spheresContact(a, b);
144
+ }
145
+ function intersectSphereAabb(a, b) {
146
+ sphere(a);
147
+ box(b);
148
+ return sphereBoxContact(a, b);
149
+ }
150
+ function intersectAabbs(a, b) {
151
+ box(a);
152
+ box(b);
153
+ return boxesContact(a, b);
154
+ }
155
+ function firstContact(offset, velocity, radius, maximum) {
156
+ const radiusSquared = radius * radius;
157
+ if (dot(offset, offset) <= radiusSquared) return 0;
158
+ const speedSquared = dot(velocity, velocity);
159
+ if (speedSquared === 0) return null;
160
+ const closestTime = -dot(offset, velocity) / speedSquared;
161
+ if (closestTime < 0) return null;
162
+ const closestOffset = at(offset, velocity, closestTime);
163
+ const distanceSquared = dot(closestOffset, closestOffset);
164
+ const remainder = radiusSquared - distanceSquared;
165
+ const roundoff = Number.EPSILON * 8 * (radiusSquared + distanceSquared);
166
+ if (remainder < -roundoff) return null;
167
+ const time = closestTime - Math.sqrt(Math.max(0, remainder) / speedSquared);
168
+ return time < -1e-12 || time > maximum + 1e-12 ? null : clamp(time, 0, maximum);
169
+ }
170
+ var hit = (contact, time, position, startsInContact) => ({ ...contact, time, position, startsInContact });
171
+ function sweepSphere(moving, displacement, target) {
172
+ sphere(moving);
173
+ sphere(target);
174
+ path(moving.center, displacement);
175
+ const initial = spheresContact(moving, target);
176
+ if (initial) return hit(initial, 0, [...moving.center], true);
177
+ const offset = moving.center.map((x, i) => x - target.center[i]);
178
+ const radius = moving.radius + target.radius;
179
+ const time = firstContact(offset, displacement, radius, 1);
180
+ if (time === null) return null;
181
+ const position = at(moving.center, displacement, time);
182
+ const contact = spheresContact({ center: position, radius: moving.radius }, target);
183
+ return contact ? hit(contact, time, position, false) : null;
184
+ }
185
+ function sweepRoundedBox(moving, displacement, target) {
186
+ const initial = sphereBoxContact(moving, target);
187
+ if (initial) return hit(initial, 0, [...moving.center], true);
188
+ const boundaries = [0, 1];
189
+ for (let axis = 0; axis < 3; axis++) {
190
+ if (displacement[axis] === 0) continue;
191
+ for (const plane of [target.min[axis], target.max[axis]]) {
192
+ const time = (plane - moving.center[axis]) / displacement[axis];
193
+ if (time > 0 && time < 1) boundaries.push(time);
194
+ }
195
+ }
196
+ boundaries.sort((a, b) => a - b);
197
+ for (let segment = 0; segment < boundaries.length - 1; segment++) {
198
+ const start = boundaries[segment], end = boundaries[segment + 1];
199
+ if (end === start) continue;
200
+ const midpoint = at(moving.center, displacement, (start + end) / 2);
201
+ const origin = at(moving.center, displacement, start);
202
+ const offset = [0, 0, 0], velocity = [0, 0, 0];
203
+ for (let axis = 0; axis < 3; axis++) {
204
+ const value = midpoint[axis];
205
+ if (value >= target.min[axis] && value <= target.max[axis]) continue;
206
+ const plane = value < target.min[axis] ? target.min[axis] : target.max[axis];
207
+ offset[axis] = origin[axis] - plane;
208
+ velocity[axis] = displacement[axis];
209
+ }
210
+ const localTime = firstContact(offset, velocity, moving.radius, end - start);
211
+ if (localTime === null) continue;
212
+ const time = start + localTime, position = at(moving.center, displacement, time);
213
+ const contact = sphereBoxContact({ center: position, radius: moving.radius }, target);
214
+ if (contact) return hit(contact, time, position, false);
215
+ }
216
+ return null;
217
+ }
218
+ function sweepSphereAabb(moving, displacement, target) {
219
+ sphere(moving);
220
+ box(target);
221
+ path(moving.center, displacement);
222
+ return sweepRoundedBox(moving, displacement, target);
223
+ }
224
+ function sweepAabb(moving, displacement, target) {
225
+ box(moving);
226
+ box(target);
227
+ path(moving.min, displacement);
228
+ path(moving.max, displacement);
229
+ const center = centerOf(moving), initial = boxesContact(moving, target);
230
+ if (initial) return hit(initial, 0, center, true);
231
+ const half = moving.min.map((x, i) => (moving.max[i] - x) / 2);
232
+ const expanded = { min: target.min.map((x, i) => x - half[i]), max: target.max.map((x, i) => x + half[i]) };
233
+ const result = sweepRoundedBox({ center, radius: 0 }, displacement, expanded);
234
+ if (!result) return null;
235
+ result.point = result.position.map((x, i) => clamp(x - result.normal[i] * half[i], target.min[i], target.max[i]));
236
+ return result;
237
+ }
238
+ function integrateKinematic(state, acceleration, deltaSeconds) {
239
+ record(state, "state");
240
+ vector(state.position, collisionLimits.maxCoordinate, "position");
241
+ vector(state.velocity, collisionLimits.maxVelocity, "velocity");
242
+ vector(acceleration, collisionLimits.maxAcceleration, "acceleration");
243
+ number(deltaSeconds, collisionLimits.maxStepSeconds, "deltaSeconds", 0);
244
+ const velocity = at(state.velocity, acceleration, deltaSeconds);
245
+ const position = at(state.position, velocity, deltaSeconds);
246
+ vector(velocity, collisionLimits.maxVelocity, "next velocity");
247
+ vector(position, collisionLimits.maxCoordinate, "next position");
248
+ return { position, velocity };
249
+ }
250
+
251
+ // src/browser.js
34
252
  var physicsDebugOwner = "physics";
35
253
  var physicsWorkerQueueClasses = Object.freeze({
36
254
  simulation: "simulation",
@@ -1200,15 +1418,23 @@ function createPhysicsWorldSnapshot(input) {
1200
1418
  }
1201
1419
  // Annotate the CommonJS export names for ESM import in node:
1202
1420
  0 && (module.exports = {
1421
+ collisionLimits,
1203
1422
  createPhysicsSimulationPlan,
1204
1423
  createPhysicsWorldSnapshot,
1205
1424
  defaultPhysicsWorkerProfile,
1206
1425
  getPhysicsWorkerManifest,
1426
+ integrateKinematic,
1427
+ intersectAabbs,
1428
+ intersectSphereAabb,
1429
+ intersectSpheres,
1207
1430
  physicsDebugOwner,
1208
1431
  physicsSimulationPlans,
1209
1432
  physicsSimulationStageOrder,
1210
1433
  physicsWorkerManifests,
1211
1434
  physicsWorkerProfileNames,
1212
- physicsWorkerQueueClasses
1435
+ physicsWorkerQueueClasses,
1436
+ sweepAabb,
1437
+ sweepSphere,
1438
+ sweepSphereAabb
1213
1439
  });
1214
1440
  //# sourceMappingURL=browser.cjs.map