Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

21.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    Physics3DModule.ts
 * @brief   The 3D physics wasm module's surface, and how it is loaded.
 */

import { defineResource } from '../ecs/resource';
import type { Entity } from '../types';

/** What the module exports. Kept in step with Physics3DModuleEntry.cpp by
 *  {@link assertPhysics3DContract} — a TypeScript interface is gone at run time,
 *  and a module built before the JS that drives it installs happily and then
 *  throws once per frame for the length of the session. */
export interface Physics3DWasmModule {
    _physics3d_init(gx: number, gy: number, gz: number, maxBodies: number): void;
    _physics3d_shutdown(): void;
    _physics3d_isReady(): number;
    _physics3d_step(dt: number, collisionSteps: number): void;
    _physics3d_optimize(): void;
    _physics3d_setLayerMask(layer: number, mask: number): void;
    /** Each value <= 0 keeps the backend's own default; after init, before bodies. */
    _physics3d_setSolver(velocityIterations: number, positionIterations: number, allowSleep: number,
                         bounceThreshold: number): void;

    _physics3d_addBox(entity: number, hx: number, hy: number, hz: number,
                      px: number, py: number, pz: number,
                      qx: number, qy: number, qz: number, qw: number,
                      motion: number, gravityScale: number, linearDamping: number,
                      angularDamping: number, fixedRotation: number, layer: number,
                      continuous: number, friction: number, restitution: number,
                      isSensor: number, cx: number, cy: number, cz: number): number;
    _physics3d_addSphere(entity: number, radius: number,
                         px: number, py: number, pz: number,
                         qx: number, qy: number, qz: number, qw: number,
                         motion: number, gravityScale: number, linearDamping: number,
                         angularDamping: number, fixedRotation: number, layer: number,
                         continuous: number, friction: number, restitution: number,
                         isSensor: number, cx: number, cy: number, cz: number): number;
    _physics3d_addCapsule(entity: number, radius: number, halfHeight: number,
                          px: number, py: number, pz: number,
                          qx: number, qy: number, qz: number, qw: number,
                          motion: number, gravityScale: number, linearDamping: number,
                          angularDamping: number, fixedRotation: number, layer: number,
                          continuous: number, friction: number, restitution: number,
                          isSensor: number, cx: number, cy: number, cz: number): number;
    _physics3d_addMeshBody(entity: number, vertexPtr: number, vertexCount: number,
                           indexPtr: number, indexCount: number,
                           px: number, py: number, pz: number,
                           qx: number, qy: number, qz: number, qw: number,
                           layer: number, friction: number, restitution: number): number;
    _physics3d_addConvexBody(entity: number, vertexPtr: number, vertexCount: number,
                             px: number, py: number, pz: number,
                             qx: number, qy: number, qz: number, qw: number,
                             motion: number, gravityScale: number, linearDamping: number,
                             angularDamping: number, fixedRotation: number, layer: number,
                             continuous: number, friction: number, restitution: number,
                             isSensor: number): number;
    _physics3d_removeBody(bodyId: number): void;
    /** Optional for older binaries. Required by CompoundCollider3D, never silently approximated. */
    _physics3d_addCompound?(entity: number, parts: number, count: number,
        px: number, py: number, pz: number, qx: number, qy: number, qz: number, qw: number,
        motion: number, gravityScale: number, linearDamping: number, angularDamping: number,
        fixedRotation: number, layer: number, continuous: number, friction: number,
        restitution: number, isSensor: number, mass: number): number;

    _malloc(bytes: number): number;
    _free(ptr: number): void;
    _physics3d_setTransform(bodyId: number, px: number, py: number, pz: number,
                            qx: number, qy: number, qz: number, qw: number): void;
    _physics3d_setLinearVelocity(bodyId: number, vx: number, vy: number, vz: number): void;
    _physics3d_getBodyState(bodyId: number): number;
    /** Writes (mass, wx, wy, wz) to the query buffer; 0 when the body is gone or does not move. */
    _physics3d_getBodyDynamics?(bodyId: number): number;
    /** A force in newtons at a world point, over the next step. */
    _physics3d_addForce?(bodyId: number, fx: number, fy: number, fz: number, px: number, py: number, pz: number): void;
    /** A torque in newton metres, over the next step. */
    _physics3d_addTorque?(bodyId: number, tx: number, ty: number, tz: number): void;

    _physics3d_addCharacter(entity: number, radius: number, halfHeight: number,
                            px: number, py: number, pz: number,
                            maxSlope: number, mass: number, layer: number,
                            pushForce: number): number;
    _physics3d_removeCharacter(characterId: number): void;
    _physics3d_moveCharacter(characterId: number, vx: number, vy: number, vz: number,
                             dt: number, stepUp: number, stepDown: number): void;
    _physics3d_setCharacterPosition(characterId: number, px: number, py: number,
                                    pz: number): void;

    /** `_physics3d_raycast` with flags: bit 0 also meets characters. */
    _physics3d_raycastWith(ox: number, oy: number, oz: number, dx: number, dy: number, dz: number,
                           layerMask: number, flags: number): number;
    _physics3d_raycast(ox: number, oy: number, oz: number,
                       dx: number, dy: number, dz: number, layerMask: number): number;
    _physics3d_sphereCast(px: number, py: number, pz: number, radius: number,
                          dx: number, dy: number, dz: number, layerMask: number): number;
    _physics3d_overlapSphere(px: number, py: number, pz: number, radius: number,
                             layerMask: number): number;
    _physics3d_overlapBox(px: number, py: number, pz: number,
                          hx: number, hy: number, hz: number, layerMask: number): number;

    _physics3d_addSwingTwistJoint(entity: number, bodyA: number, bodyB: number,
        px: number, py: number, pz: number, ax: number, ay: number, az: number,
        nx: number, ny: number, nz: number, normalHalf: number, planeHalf: number,
        twistMin: number, twistMax: number, collideConnected: number): number;
    _physics3d_addSixDOFJoint(entity: number, bodyA: number, bodyB: number,
        px: number, py: number, pz: number, ax: number, ay: number, az: number,
        nx: number, ny: number, nz: number, translationMotion: number, rotationMotion: number,
        lx: number, ly: number, lz: number, hx: number, hy: number, hz: number,
        rx: number, ry: number, rz: number, sx: number, sy: number, sz: number,
        collideConnected: number): number;
    _physics3d_setAdvancedJointMotor(entity: number, enable: number,
        vx: number, vy: number, vz: number, wx: number, wy: number, wz: number,
        maxForce: number, maxTorque: number): void;
    _physics3d_addPointJoint(entity: number, bodyA: number, bodyB: number,
                             px: number, py: number, pz: number,
                             collideConnected: number): number;
    _physics3d_addHingeJoint(entity: number, bodyA: number, bodyB: number,
                             px: number, py: number, pz: number,
                             ax: number, ay: number, az: number,
                             enableLimit: number, lower: number, upper: number,
                             enableMotor: number, motorSpeed: number, maxTorque: number,
                             collideConnected: number): number;
    _physics3d_addSliderJoint(entity: number, bodyA: number, bodyB: number,
                              px: number, py: number, pz: number,
                              ax: number, ay: number, az: number,
                              enableLimit: number, lower: number, upper: number,
                              enableMotor: number, motorSpeed: number, maxForce: number,
                              collideConnected: number): number;
    _physics3d_addDistanceJoint(entity: number, bodyA: number, bodyB: number,
                                ax: number, ay: number, az: number,
                                bx: number, by: number, bz: number,
                                minLength: number, maxLength: number,
                                frequency: number, damping: number,
                                collideConnected: number): number;
    _physics3d_addFixedJoint(entity: number, bodyA: number, bodyB: number,
                             collideConnected: number): number;
    _physics3d_removeJoint(entity: number, bodyA: number, bodyB: number): void;
    _physics3d_setJointMotor(entity: number, enable: number, speed: number): void;
    /** Optional for older binaries: (force N, torque N m) the joint held with over the last step, to the query buffer. */
    _physics3d_jointForce?(entity: number): number;
    /** Optional for older binaries: every body on a line, (entity, entry, exit, point, normal) each, nearest first. */
    _physics3d_raycastAll?(ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, layerMask: number, maxHits: number): number;
    /** Optional for older binaries: what characters ran into this step, ten floats a meeting. */
    _physics3d_characterHits?(): number;
    _physics3d_characterHitsBytes?(): number;
    /** Optional for older binaries: a live hinge's or slider's range, its motor's limit, a distance joint's shape. */
    _physics3d_setJointLimits?(entity: number, enable: number, lower: number, upper: number): void;
    _physics3d_setJointMotorLimit?(entity: number, limit: number): void;
    _physics3d_setDistanceJoint?(entity: number, minLength: number, maxLength: number, frequency: number, damping: number): void;
    _physics3d_jointValue(entity: number): number;

    _physics3d_contactEnters(): number;
    _physics3d_contactEntersBytes(): number;
    /** Optional for older binaries: one closing speed for each contact begun. */
    _physics3d_contactEnterSpeeds?(): number;
    _physics3d_contactEnterSpeedsBytes?(): number;
    /** Optional for older binaries: the mass, in kilograms, each contact begun met with. */
    _physics3d_contactEnterMasses?(): number;
    _physics3d_contactEnterMassesBytes?(): number;
    /** Optional for older binaries: a moving body's mass in kilograms. */
    _physics3d_setMass?(bodyId: number, mass: number): void;
    /** Optional for older binaries: a blow in newton seconds at a world point, or the centre of mass for NaN. */
    _physics3d_addImpulse?(bodyId: number, ix: number, iy: number, iz: number, px: number, py: number, pz: number): void;
    _physics3d_addAngularImpulse?(bodyId: number, ix: number, iy: number, iz: number): void;
    _physics3d_setAngularVelocity?(bodyId: number, wx: number, wy: number, wz: number): void;
    _physics3d_setGravity?(gx: number, gy: number, gz: number): void;
    _physics3d_setAwake?(bodyId: number, awake: number): void;
    _physics3d_isAwake?(bodyId: number): number;
    /** Optional for older binaries: (mass, centre x/y/z in metres, moments about its own axes in kg m^2) to the query buffer. */
    _physics3d_getBodyMassData?(bodyId: number): number;
    /** Optional for older binaries: a turned box or an upright capsule swept, written as a sphere cast is. */
    _physics3d_boxCast?(px: number, py: number, pz: number, hx: number, hy: number, hz: number,
                        qx: number, qy: number, qz: number, qw: number, dx: number, dy: number, dz: number, layerMask: number): number;
    _physics3d_capsuleCast?(px: number, py: number, pz: number, radius: number, halfHeight: number,
                            qx: number, qy: number, qz: number, qw: number, dx: number, dy: number, dz: number, layerMask: number): number;
    _physics3d_contactExits(): number;
    _physics3d_contactExitsBytes(): number;
    _physics3d_sensorEnters(): number;
    _physics3d_sensorEntersBytes(): number;
    _physics3d_sensorExits(): number;
    _physics3d_sensorExitsBytes(): number;

    _physics3d_transforms(): number;
    _physics3d_transformsBytes(): number;
    _physics3d_queryResult(): number;
    _physics3d_queryResultBytes(): number;

    HEAPF32: Float32Array;
    HEAPU32: Uint32Array;
}

export type Physics3DModuleFactory =
    (options?: { wasmBinary?: ArrayBuffer }) => Promise<Physics3DWasmModule>;

/** One readback record: entity, position, rotation. */
export const PHYSICS3D_TRANSFORM_STRIDE = 8;

const REQUIRED_EXPORTS = [
    '_physics3d_init', '_physics3d_shutdown', '_physics3d_isReady', '_physics3d_step', '_physics3d_setSolver',
    '_physics3d_addBox', '_physics3d_addSphere', '_physics3d_addCapsule',
    '_physics3d_removeBody', '_physics3d_setTransform', '_physics3d_raycast', '_physics3d_raycastWith',
    '_physics3d_transforms', '_physics3d_transformsBytes',
    '_physics3d_addCharacter', '_physics3d_moveCharacter', '_physics3d_removeCharacter',
    '_physics3d_setCharacterPosition',
    '_physics3d_sphereCast', '_physics3d_overlapSphere', '_physics3d_overlapBox',
    '_physics3d_contactEnters', '_physics3d_contactEntersBytes',
    '_physics3d_sensorEnters', '_physics3d_sensorEntersBytes',
    '_physics3d_addHingeJoint', '_physics3d_removeJoint',
    '_physics3d_addSwingTwistJoint', '_physics3d_addSixDOFJoint', '_physics3d_setAdvancedJointMotor',
] as const;

/** Throws naming what is missing, rather than letting the first frame do it. */
export function assertPhysics3DContract(module: unknown): void {
    const bag = module as Record<string, unknown>;
    const missing = REQUIRED_EXPORTS.filter((name) => typeof bag?.[name] !== 'function');
    if (missing.length > 0) {
        throw new Error(`physics3d.wasm is missing ${missing.join(', ')} — it was built `
            + 'from sources older than the code driving it');
    }
}

/** Load the module from `url`, or adopt a factory a host already resolved. */
export async function loadPhysics3DModule(
    url: string, factory?: Physics3DModuleFactory,
): Promise<Physics3DWasmModule> {
    const resolved = factory
        ?? ((await import(/* @vite-ignore */ url)) as { default: Physics3DModuleFactory }).default;
    const module = await resolved();
    assertPhysics3DContract(module);
    return module;
}

// =============================================================================
// Events
// =============================================================================

/** Two bodies met, and where. */
export interface Contact3DEvent {
    entityA: Entity;
    entityB: Entity;
    normalX: number;
    normalY: number;
    normalZ: number;
    pointX: number;
    pointY: number;
    pointZ: number;
    /**
     * How fast A was closing on B where they met, along the normal, in world units a second, read before the solver
     * answered: a ball dropped on a floor from a metre lands at about 4.4 m/s. Undefined from a binary too old to say.
     */
    speed?: number;
    /**
     * The mass they met with, in kilograms: 1 / (1/a + 1/b), where a body that does not move counts as having no
     * inverse mass, so a stone landing on a floor meets it with the stone's own. Infinity where neither moves of itself.
     */
    mass?: number;
    /**
     * How hard: `speed` times `mass`, in kilograms by world units a second, the push it takes to stop the two coming
     * together. A 1 kg stone landing at 10 m/s in a scene of 100 units to the metre is 1000.
     */
    impulse?: number;
}

/** A character ran into something it was not already touching, as a contact between bodies would say it. */
export interface CharacterHit3DEvent {
    character: Entity;
    other: Entity;
    pointX: number;
    pointY: number;
    pointZ: number;
    /** Toward the character. */
    normalX: number;
    normalY: number;
    normalZ: number;
    /** How fast it closed on what it met, world units a second. */
    speed: number;
    /** The mass they met with, kilograms: the character's own against something that does not move. */
    mass: number;
    /** `speed` times `mass`, as a contact's: what a Breakable it ran into is struck with. */
    impulse: number;
}

/** A joint gave way: which, and what it was holding when it did. */
export interface JointBreak3DEvent {
    entity: Entity;
    /** Newtons. */
    force: number;
    /** Newton metres. */
    torque: number;
}

/** A sensor was entered or left. The SENSOR is always named first. */
export interface Sensor3DEvent {
    sensorEntity: Entity;
    visitorEntity: Entity;
}

export interface Physics3DEventsData {
    contactEnters: Contact3DEvent[];
    /** Ends carry only the pair: at that moment the bodies are locked and one may
     *  already be gone, so there is no geometry left to report. */
    contactExits: Array<{ entityA: Entity; entityB: Entity }>;
    sensorEnters: Sensor3DEvent[];
    sensorExits: Sensor3DEvent[];
    /** What characters ran into this step; empty from a binary too old to say. */
    characterHits?: CharacterHit3DEvent[];
    /** Joints that gave way this step. */
    jointBreaks?: JointBreak3DEvent[];
}

/**
 * This step's 3D collision and trigger events. Drained per fixed step, so a
 * system reading it must run inside one — a read from `Update` sees whatever the
 * last step left.
 *
 * @experimental
 */
export const Physics3DEvents = defineResource<Physics3DEventsData>({
    contactEnters: [],
    contactExits: [],
    sensorEnters: [],
    sensorExits: [],
}, 'Physics3DEvents');

/**
 * Refill `events` from the module's four buffers. A contact point is made in the world's own
 * units, so `pixelsPerUnit` brings it into the space `Transform` and the queries speak.
 */
export function drainPhysics3DEvents(module: Physics3DWasmModule,
                                     events: Physics3DEventsData,
                                     pixelsPerUnit = 1): void {
    const f32 = module.HEAPF32;
    const read = <T>(ptr: number, bytes: number, stride: number,
                     make: (base: number) => T): T[] => {
        const out: T[] = [];
        const base = ptr >> 2;
        for (let i = 0; i < bytes / 4; i += stride) out.push(make(base + i));
        return out;
    };

    events.contactEnters = read(
        module._physics3d_contactEnters(), module._physics3d_contactEntersBytes(), 8,
        (o) => ({
            entityA: f32[o] as Entity, entityB: f32[o + 1] as Entity,
            normalX: f32[o + 2]!, normalY: f32[o + 3]!, normalZ: f32[o + 4]!,
            pointX: f32[o + 5]! * pixelsPerUnit, pointY: f32[o + 6]! * pixelsPerUnit, pointZ: f32[o + 7]! * pixelsPerUnit,
        }));
    if (module._physics3d_contactEnterSpeeds && module._physics3d_contactEnterSpeedsBytes) {
        const speeds = read(module._physics3d_contactEnterSpeeds(), module._physics3d_contactEnterSpeedsBytes(), 1, (o) => f32[o]!);
        // One for each contact, in its order; a count that does not match is a binary that writes something else.
        if (speeds.length === events.contactEnters.length) events.contactEnters.forEach((c, i) => { c.speed = speeds[i]! * pixelsPerUnit; });
    }
    if (module._physics3d_contactEnterMasses && module._physics3d_contactEnterMassesBytes) {
        const masses = read(module._physics3d_contactEnterMasses(), module._physics3d_contactEnterMassesBytes(), 1, (o) => f32[o]!);
        if (masses.length === events.contactEnters.length) {
            events.contactEnters.forEach((c, i) => {
                c.mass = masses[i]!;
                // Nothing pushes at no speed, however heavy: an unmoving pair is no blow.
                if (c.speed !== undefined) c.impulse = c.speed > 0 ? c.speed * c.mass : 0;
            });
        }
    }
    if (module._physics3d_characterHits && module._physics3d_characterHitsBytes) {
        events.characterHits = read(module._physics3d_characterHits(), module._physics3d_characterHitsBytes(), 10, (o) => {
            const speed = f32[o + 8]! * pixelsPerUnit, mass = f32[o + 9]!;
            return {
                character: f32[o] as Entity, other: f32[o + 1] as Entity,
                pointX: f32[o + 2]! * pixelsPerUnit, pointY: f32[o + 3]! * pixelsPerUnit, pointZ: f32[o + 4]! * pixelsPerUnit,
                normalX: f32[o + 5]!, normalY: f32[o + 6]!, normalZ: f32[o + 7]!,
                speed, mass, impulse: speed > 0 ? speed * mass : 0,
            };
        });
    }
    events.jointBreaks = [];
    events.contactExits = read(
        module._physics3d_contactExits(), module._physics3d_contactExitsBytes(), 2,
        (o) => ({ entityA: f32[o] as Entity, entityB: f32[o + 1] as Entity }));
    events.sensorEnters = read(
        module._physics3d_sensorEnters(), module._physics3d_sensorEntersBytes(), 2,
        (o) => ({ sensorEntity: f32[o] as Entity, visitorEntity: f32[o + 1] as Entity }));
    events.sensorExits = read(
        module._physics3d_sensorExits(), module._physics3d_sensorExitsBytes(), 2,
        (o) => ({ sensorEntity: f32[o] as Entity, visitorEntity: f32[o + 1] as Entity }));
}