@yali-engine/physics 0.0.0-stage → 0.4.0

package/dist/physics.js

@@ -0,0 +1,132 @@
+import { requireFeature, YaliError } from '@yali-engine/core';
+const RAY_IN = 8;
+const RAY_OUT = 5;
+/**
+ * The physics world of an app (the `physics` resource): ray casts, collision assets, settings
+ * and stats. Bodies and colliders are entities (`physics.RigidBody`, `physics.Collider`); this is
+ * everything else.
+ *
+ * @example
+ * const physics = app.resource<Physics>('physics');
+ * const hit = physics.raycast([0, 10, 0], [0, -1, 0], 100);
+ * if (hit) console.log(hit.entity, hit.distance);
+ */
+export class Physics {
+    world;
+    #x;
+    #rays = new Float64Array(0);
+    constructor(world, fixedDelta, settings = {}) {
+        requireFeature(world.core, 'physics');
+        this.world = world;
+        this.#x = world.core.exports;
+        this.#fixedDelta = fixedDelta;
+        this.configure(settings);
+    }
+    #fixedDelta;
+    /** What debug draw shows; both off by default. The plugin hands the lines to `render.debug`. */
+    debug = { colliders: false, contacts: false, maxSegments: 200_000 };
+    #origin = [0, 0, 0];
+    #lines = { f32: new Float32Array(0), u32: new Uint32Array(0), first: 0, count: 0, origin: this.#origin };
+    /**
+     * This step's debug segments (what `debug` asks for), or null when it asks for nothing. The
+     * views point into the core's memory: read them before the next step. Allocation-free.
+     */
+    debugLines() {
+        const flags = (this.debug.colliders ? 1 : 0) | (this.debug.contacts ? 2 : 0);
+        if (flags === 0)
+            return null;
+        const ptr = this.world.scratch(40);
+        this.world.check(this.#x.yali_physics_debug(this.world.handle, flags, this.debug.maxSegments, ptr));
+        const heap = this.world.core.heap;
+        const f = heap.f64;
+        const at = ptr >>> 3;
+        const l = this.#lines;
+        l.f32 = heap.f32;
+        l.u32 = heap.u32;
+        l.first = f[at] / 16;
+        l.count = f[at + 1];
+        this.#origin[0] = f[at + 2];
+        this.#origin[1] = f[at + 3];
+        this.#origin[2] = f[at + 4];
+        return l;
+    }
+    /** Gravity and substeps (the fixed step is the app's). */
+    configure(s) {
+        const g = s.gravity ?? [0, -9.81, 0];
+        this.world.check(this.#x.yali_physics_settings(this.world.handle, this.#fixedDelta, g[0], g[1], g[2], s.substeps ?? 4));
+    }
+    /** The first collider the ray hits within `maxDistance` (layers in `mask`), or null. */
+    raycast(origin, dir, maxDistance = 1e6, mask = 0xffffffff) {
+        const out = this.raycasts([[origin, dir, maxDistance, mask]]);
+        return out[0];
+    }
+    /** Many rays in one call into the core (each `[origin, dir, maxDistance, mask]`). */
+    raycasts(rays) {
+        const n = rays.length;
+        const bytes = n * (RAY_IN + RAY_OUT) * 8;
+        const ptr = this.world.scratch(bytes);
+        const heap = this.world.core.heap;
+        const input = ptr >>> 3;
+        const output = input + n * RAY_IN;
+        for (let i = 0; i < n; i++) {
+            const [o, d, max, mask] = rays[i];
+            heap.f64.set([o[0], o[1], o[2], d[0], d[1], d[2], max, mask >>> 0], input + i * RAY_IN);
+        }
+        this.world.check(this.#x.yali_physics_ray_casts(this.world.handle, ptr, n, ptr + n * RAY_IN * 8));
+        const f = this.world.core.heap.f64;
+        const hits = [];
+        for (let i = 0; i < n; i++) {
+            const at = output + i * RAY_OUT;
+            hits.push(f[at] < 0 ? null : { entity: f[at], distance: f[at + 1], normal: [f[at + 2], f[at + 3], f[at + 4]] });
+        }
+        return hits;
+    }
+    /** Adds a convex hull of `points` (x, y, z triples, local frame); returns its asset index. */
+    addHull(points) {
+        if (points.length < 12 || points.length % 3 !== 0) {
+            throw new YaliError('PHYSICS_INVALID', `A hull needs at least 4 points as x, y, z triples; got ${points.length} numbers.`, 'Pass a Float32Array of 3n numbers, n ≥ 4.');
+        }
+        const ptr = this.world.scratch(points.byteLength);
+        this.world.core.heap.f32.set(points, ptr >>> 2);
+        return this.world.check(this.#x.yali_physics_add_hull(this.world.handle, ptr, points.length / 3));
+    }
+    /** Adds a static triangle mesh; returns its asset index. */
+    addMesh(vertices, indices, doubleSided = false) {
+        const ptr = this.world.scratch(vertices.byteLength + indices.byteLength);
+        const heap = this.world.core.heap;
+        heap.f32.set(vertices, ptr >>> 2);
+        heap.u32.set(indices, (ptr + vertices.byteLength) >>> 2);
+        return this.world.check(this.#x.yali_physics_add_mesh(this.world.handle, ptr, vertices.length / 3, ptr + vertices.byteLength, indices.length, doubleSided ? 1 : 0));
+    }
+    /** Adds a heightfield (`rows × cols` heights, row-major); returns its asset index. */
+    addHeightfield(rows, cols, heights, cell, heightScale = 1) {
+        const ptr = this.world.scratch(heights.byteLength);
+        this.world.core.heap.f32.set(heights, ptr >>> 2);
+        return this.world.check(this.#x.yali_physics_add_heightfield(this.world.handle, rows, cols, ptr, cell[0], heightScale, cell[1]));
+    }
+    /**
+     * Saves the physics state (ADR-0091: bodies, contacts with their warm-start impulses, joints,
+     * sleep); returns its id. Restoring it continues bit for bit. The ECS world's own state is the
+     * caller's to save (rollback, replay, undo).
+     */
+    snapshot() {
+        return this.world.check(this.#x.yali_physics_snapshot(this.world.handle));
+    }
+    /** Back to snapshot `id`, between frames; every body's Transform and velocity is written back. */
+    restore(id) {
+        this.world.check(this.#x.yali_physics_restore(this.world.handle, id));
+    }
+    /** Frees snapshot `id`. */
+    dropSnapshot(id) {
+        this.world.check(this.#x.yali_physics_snapshot_free(this.world.handle, id));
+    }
+    /** The last step's counts. */
+    stats() {
+        const ptr = this.world.scratch(24);
+        this.world.check(this.#x.yali_physics_stats(this.world.handle, ptr));
+        const u = this.world.core.heap.u32;
+        const i = ptr >>> 2;
+        return { bodies: u[i], awake: u[i + 1], pairs: u[i + 2], contacts: u[i + 3], colors: u[i + 4], threads: u[i + 5] };
+    }
+}
+//# sourceMappingURL=physics.js.map

package/dist/physics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"physics.js","sourceRoot":"","sources":["../src/physics.ts"],"names":[],"mappings":"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"}

package/dist/plugin.d.ts

@@ -0,0 +1,22 @@
+import type { YaliPlugin } from '@yali-engine/core';
+import { type PhysicsDebug, type PhysicsSettings } from './physics.ts';
+/** `physicsPlugin`'s options: the physics settings, and debug draw to start with. */
+export interface PhysicsPluginOptions extends PhysicsSettings {
+    /** Debug draw from the start (`true`: colliders); change it any time on `Physics.debug`. */
+    readonly debug?: boolean | Partial<PhysicsDebug>;
+}
+/**
+ * `@yali-engine/physics` as a plugin (ADR-0082): Kanduka, compiled into the core module's `physics`
+ * variant, steps every fixed step after the transform snapshot. Provides the `physics` resource
+ * (`Physics`: ray casts, collision assets, stats) and the `physicsComponents` resource
+ * (`RigidBody`, `Collider`). Fails at startup, with the fix, when the loaded core has no physics.
+ * Registers the tools `physics.stats`, `physics.raycast` and `physics.debug`, and four counters.
+ * With debug draw on (`debug`, or `Physics.debug` at run time) and `@yali-engine/render` present, every
+ * collider's wireframe (and, if asked, each contact) is drawn over the scene (ADR-0087).
+ *
+ * @example
+ * const app = App.create({ core, plugins: [transformsPlugin(), physicsPlugin({ gravity: [0, -9.81, 0] }), game] });
+ * // in game's build:
+ * const { RigidBody, Collider } = b.app.resource<PhysicsComponents>('physicsComponents');
+ */
+export declare function physicsPlugin(settings?: PhysicsPluginOptions): YaliPlugin;

package/dist/plugin.js

@@ -0,0 +1,102 @@
+import { registerPhysics } from "./components.js";
+import { Physics } from "./physics.js";
+/**
+ * `@yali-engine/physics` as a plugin (ADR-0082): Kanduka, compiled into the core module's `physics`
+ * variant, steps every fixed step after the transform snapshot. Provides the `physics` resource
+ * (`Physics`: ray casts, collision assets, stats) and the `physicsComponents` resource
+ * (`RigidBody`, `Collider`). Fails at startup, with the fix, when the loaded core has no physics.
+ * Registers the tools `physics.stats`, `physics.raycast` and `physics.debug`, and four counters.
+ * With debug draw on (`debug`, or `Physics.debug` at run time) and `@yali-engine/render` present, every
+ * collider's wireframe (and, if asked, each contact) is drawn over the scene (ADR-0087).
+ *
+ * @example
+ * const app = App.create({ core, plugins: [transformsPlugin(), physicsPlugin({ gravity: [0, -9.81, 0] }), game] });
+ * // in game's build:
+ * const { RigidBody, Collider } = b.app.resource<PhysicsComponents>('physicsComponents');
+ */
+export function physicsPlugin(settings = {}) {
+    return {
+        name: '@yali-engine/physics',
+        version: '0.4.0',
+        dependencies: [{ name: '@yali-engine/transforms', range: '^0.4.0', optional: true }],
+        build(b) {
+            const world = b.app.world;
+            const physics = new Physics(world, b.app.time.fixedDelta, settings);
+            const components = registerPhysics(world);
+            b.provide('physics', physics);
+            b.provide('physicsComponents', components);
+            if (settings.debug)
+                Object.assign(physics.debug, settings.debug === true ? { colliders: true } : settings.debug);
+            // Extract: after the camera moved (PostUpdate), so `render.debug` places lines for this frame.
+            let sink;
+            b.system({
+                name: 'physics.debugDraw',
+                stage: 'Extract',
+                run: () => {
+                    if (!physics.debug.colliders && !physics.debug.contacts)
+                        return;
+                    if (sink === undefined) {
+                        try {
+                            sink = b.app.resource('render').debug ?? null;
+                        }
+                        catch {
+                            sink = null; // no renderer (headless): nothing to draw into
+                        }
+                    }
+                    const lines = sink && physics.debugLines();
+                    if (lines)
+                        sink.add(lines.f32, lines.u32, lines.first, lines.count, lines.origin);
+                },
+            });
+            let last = physics.stats();
+            b.system({ name: 'physics.stats', stage: 'EndFrame', run: () => (last = physics.stats()) });
+            b.counter('physics.bodies', () => last.bodies);
+            b.counter('physics.awake', () => last.awake);
+            b.counter('physics.pairs', () => last.pairs);
+            b.counter('physics.contacts', () => last.contacts);
+            b.tool({
+                name: 'physics.stats',
+                description: 'Physics counts from the last step: bodies, awake bodies, pairs, contact constraints.',
+                input: { type: 'object', properties: {} },
+                run: () => physics.stats(),
+            });
+            b.tool({
+                name: 'physics.debug',
+                description: 'Turns physics debug draw on or off (collider wireframes, contact points); returns what is drawn.',
+                input: {
+                    type: 'object',
+                    properties: {
+                        colliders: { type: 'boolean', description: 'Collider wireframes.' },
+                        contacts: { type: 'boolean', description: 'Contact points and normals.' },
+                    },
+                },
+                run: (args) => {
+                    if (typeof args.colliders === 'boolean')
+                        physics.debug.colliders = args.colliders;
+                    if (typeof args.contacts === 'boolean')
+                        physics.debug.contacts = args.contacts;
+                    return { ...physics.debug };
+                },
+            });
+            b.tool({
+                name: 'physics.raycast',
+                description: 'Casts a ray into the physics world; returns the entity hit, the distance and the normal, or null.',
+                input: {
+                    type: 'object',
+                    properties: {
+                        origin: { type: 'array', description: 'World position [x, y, z].' },
+                        direction: { type: 'array', description: 'Direction [x, y, z] (normalized for you).' },
+                        maxDistance: { type: 'number', description: 'Default 1e6.' },
+                    },
+                    required: ['origin', 'direction'],
+                },
+                run: (args) => {
+                    const o = args.origin;
+                    const d = args.direction;
+                    return physics.raycast([o[0], o[1], o[2]], [d[0], d[1], d[2]], args.maxDistance ?? 1e6);
+                },
+            });
+        },
+    };
+}
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@yali-engine/physics",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.0",
+  "description": "Yali physics: Kanduka (Yali's own Soft Step solver) as ECS components, ray casts and collision assets. Needs the core's physics variant (ADR-0082, ADR-0084).",
+  "license": "MIT OR Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./gpu": {
+      "types": "./dist/gpu.d.ts",
+      "default": "./dist/gpu.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@webgpu/types": "^0.1.60",
+    "@yali-engine/core": "0.4.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --experimental-strip-types --no-warnings --test \"test/*.test.ts\""
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.