@series-inc/rundot-syncplay 5.26.0 → 5.28.0-beta.0

package/dist/physics3d-voxel.js

@@ -1,3 +1,141 @@
+/**
+ * Amanatides & Woo 3D Digital Differential Analyzer (DDA) fast voxel grid raycaster.
+ * Marches through chunk cells in O(distance) directly over the occupancy bitset.
+ */
+export function raycastDeterministicVoxelChunk3D(chunk, query) {
+    const { dimX, dimY, dimZ, cellSize, occupancy } = chunk;
+    if (cellSize <= 0 || occupancy.length !== dimX * dimY * dimZ) {
+        return undefined;
+    }
+    const dirLen = Math.hypot(query.dx, query.dy, query.dz);
+    if (dirLen <= 1e-12) {
+        return undefined;
+    }
+    const dx = query.dx / dirLen;
+    const dy = query.dy / dirLen;
+    const dz = query.dz / dirLen;
+    const maxDistance = query.maxDistance;
+    if (maxDistance < 0) {
+        return undefined;
+    }
+    const ox = query.x / cellSize;
+    const oy = query.y / cellSize;
+    const oz = query.z / cellSize;
+    let tMin = 0;
+    let tMax = maxDistance / cellSize;
+    let enterNormal = { x: 0, y: 0, z: 0 };
+    const axes = [
+        { o: ox, d: dx, min: 0, max: dimX, nx: 1, ny: 0, nz: 0 },
+        { o: oy, d: dy, min: 0, max: dimY, nx: 0, ny: 1, nz: 0 },
+        { o: oz, d: dz, min: 0, max: dimZ, nx: 0, ny: 0, nz: 1 },
+    ];
+    for (const axis of axes) {
+        if (Math.abs(axis.d) < 1e-12) {
+            if (axis.o < axis.min || axis.o > axis.max) {
+                return undefined;
+            }
+        }
+        else {
+            let t1 = (axis.min - axis.o) / axis.d;
+            let t2 = (axis.max - axis.o) / axis.d;
+            let n1 = { x: -axis.nx, y: -axis.ny, z: -axis.nz };
+            if (t1 > t2) {
+                const temp = t1;
+                t1 = t2;
+                t2 = temp;
+                n1 = { x: axis.nx, y: axis.ny, z: axis.nz };
+            }
+            if (t1 > tMin) {
+                tMin = t1;
+                enterNormal = n1;
+            }
+            if (t2 < tMax) {
+                tMax = t2;
+            }
+            if (tMin > tMax) {
+                return undefined;
+            }
+        }
+    }
+    if (ox >= 0 && ox < dimX && oy >= 0 && oy < dimY && oz >= 0 && oz < dimZ) {
+        tMin = 0;
+    }
+    const startX = ox + dx * tMin;
+    const startY = oy + dy * tMin;
+    const startZ = oz + dz * tMin;
+    let currentX = Math.floor(startX);
+    let currentY = Math.floor(startY);
+    let currentZ = Math.floor(startZ);
+    currentX = Math.max(0, Math.min(dimX - 1, currentX));
+    currentY = Math.max(0, Math.min(dimY - 1, currentY));
+    currentZ = Math.max(0, Math.min(dimZ - 1, currentZ));
+    const stepX = dx > 0 ? 1 : dx < 0 ? -1 : 0;
+    const stepY = dy > 0 ? 1 : dy < 0 ? -1 : 0;
+    const stepZ = dz > 0 ? 1 : dz < 0 ? -1 : 0;
+    const tDeltaX = stepX !== 0 ? Math.abs(1 / dx) : Infinity;
+    const tDeltaY = stepY !== 0 ? Math.abs(1 / dy) : Infinity;
+    const tDeltaZ = stepZ !== 0 ? Math.abs(1 / dz) : Infinity;
+    let tMaxX = stepX > 0 ? (currentX + 1 - ox) / dx : stepX < 0 ? (currentX - ox) / dx : Infinity;
+    let tMaxY = stepY > 0 ? (currentY + 1 - oy) / dy : stepY < 0 ? (currentY - oy) / dy : Infinity;
+    let tMaxZ = stepZ > 0 ? (currentZ + 1 - oz) / dz : stepZ < 0 ? (currentZ - oz) / dz : Infinity;
+    let currentNormal = enterNormal;
+    let hitDistanceGrid = tMin;
+    while (currentX >= 0 && currentX < dimX && currentY >= 0 && currentY < dimY && currentZ >= 0 && currentZ < dimZ) {
+        const cellIndex = currentX + dimX * (currentY + dimY * currentZ);
+        if (occupancy[cellIndex] === 1) {
+            const worldDistance = hitDistanceGrid * cellSize;
+            if (worldDistance > maxDistance) {
+                return undefined;
+            }
+            const hitPoint = {
+                x: query.x + dx * worldDistance,
+                y: query.y + dy * worldDistance,
+                z: query.z + dz * worldDistance,
+            };
+            return {
+                hit: true,
+                distance: worldDistance,
+                voxelX: currentX,
+                voxelY: currentY,
+                voxelZ: currentZ,
+                point: hitPoint,
+                normal: currentNormal,
+            };
+        }
+        if (tMaxX < tMaxY) {
+            if (tMaxX < tMaxZ) {
+                hitDistanceGrid = tMaxX;
+                tMaxX += tDeltaX;
+                currentX += stepX;
+                currentNormal = { x: -stepX, y: 0, z: 0 };
+            }
+            else {
+                hitDistanceGrid = tMaxZ;
+                tMaxZ += tDeltaZ;
+                currentZ += stepZ;
+                currentNormal = { x: 0, y: 0, z: -stepZ };
+            }
+        }
+        else {
+            if (tMaxY < tMaxZ) {
+                hitDistanceGrid = tMaxY;
+                tMaxY += tDeltaY;
+                currentY += stepY;
+                currentNormal = { x: 0, y: -stepY, z: 0 };
+            }
+            else {
+                hitDistanceGrid = tMaxZ;
+                tMaxZ += tDeltaZ;
+                currentZ += stepZ;
+                currentNormal = { x: 0, y: 0, z: -stepZ };
+            }
+        }
+        if (hitDistanceGrid > tMax) {
+            break;
+        }
+    }
+    return undefined;
+}
 /**
  * Deterministic greedy box merge: scan z→y→x ascending and grow each unconsumed
  * solid cell into the largest box along +x, then +y, then +z. A solid n³ chunk
@@ -89,3 +227,202 @@ export function cookDeterministicVoxelChunkCollider3D(chunk) {
     }
     return { type: 'compound', children };
 }
+/**
+ * Carves or fills a 3D axis-aligned cell region in a voxel chunk occupancy grid.
+ * Computes interval intersection with chunk dimensions, returning chunk unchanged
+ * if disjoint or no-op.
+ */
+export function carveDeterministicVoxelChunk3D(chunk, region) {
+    const { dimX, dimY, dimZ, cellSize, occupancy } = chunk;
+    const startX = Math.max(0, Math.min(region.minX, region.maxX));
+    const endX = Math.min(dimX - 1, Math.max(region.minX, region.maxX));
+    const startY = Math.max(0, Math.min(region.minY, region.maxY));
+    const endY = Math.min(dimY - 1, Math.max(region.minY, region.maxY));
+    const startZ = Math.max(0, Math.min(region.minZ, region.maxZ));
+    const endZ = Math.min(dimZ - 1, Math.max(region.minZ, region.maxZ));
+    if (startX > endX || startY > endY || startZ > endZ) {
+        return chunk;
+    }
+    const targetVal = region.operation === 'carve' ? 0 : 1;
+    let changed = false;
+    const nextOccupancy = [...occupancy];
+    for (let z = startZ; z <= endZ; z += 1) {
+        for (let y = startY; y <= endY; y += 1) {
+            for (let x = startX; x <= endX; x += 1) {
+                const index = x + dimX * (y + dimY * z);
+                if (nextOccupancy[index] !== targetVal) {
+                    nextOccupancy[index] = targetVal;
+                    changed = true;
+                }
+            }
+        }
+    }
+    if (!changed) {
+        return chunk;
+    }
+    return {
+        dimX,
+        dimY,
+        dimZ,
+        cellSize,
+        occupancy: nextOccupancy,
+    };
+}
+function cookSubregionBoxes(chunk, minX, minY, minZ, maxX, maxY, maxZ) {
+    const { dimX, dimY, dimZ, cellSize, occupancy } = chunk;
+    const solid = (x, y, z) => occupancy[x + dimX * (y + dimY * z)] !== 0;
+    const consumed = new Uint8Array(dimX * dimY * dimZ);
+    const free = (x, y, z) => solid(x, y, z) && consumed[x + dimX * (y + dimY * z)] === 0;
+    const children = [];
+    for (let z = minZ; z <= maxZ; z += 1) {
+        for (let y = minY; y <= maxY; y += 1) {
+            for (let x = minX; x <= maxX; x += 1) {
+                if (!free(x, y, z)) {
+                    continue;
+                }
+                let x1 = x;
+                while (x1 + 1 <= maxX && free(x1 + 1, y, z)) {
+                    x1 += 1;
+                }
+                const rowFree = (yy, zz) => {
+                    for (let xx = x; xx <= x1; xx += 1) {
+                        if (!free(xx, yy, zz)) {
+                            return false;
+                        }
+                    }
+                    return true;
+                };
+                let y1 = y;
+                while (y1 + 1 <= maxY && rowFree(y1 + 1, z)) {
+                    y1 += 1;
+                }
+                const slabFree = (zz) => {
+                    for (let yy = y; yy <= y1; yy += 1) {
+                        if (!rowFree(yy, zz)) {
+                            return false;
+                        }
+                    }
+                    return true;
+                };
+                let z1 = z;
+                while (z1 + 1 <= maxZ && slabFree(z1 + 1)) {
+                    z1 += 1;
+                }
+                for (let zz = z; zz <= z1; zz += 1) {
+                    for (let yy = y; yy <= y1; yy += 1) {
+                        for (let xx = x; xx <= x1; xx += 1) {
+                            consumed[xx + dimX * (yy + dimY * zz)] = 1;
+                        }
+                    }
+                }
+                children.push({
+                    shape: {
+                        type: 'box',
+                        halfX: ((x1 - x + 1) * cellSize) / 2,
+                        halfY: ((y1 - y + 1) * cellSize) / 2,
+                        halfZ: ((z1 - z + 1) * cellSize) / 2,
+                    },
+                    offset: {
+                        x: ((x + x1) / 2) * cellSize,
+                        y: ((y + y1) / 2) * cellSize,
+                        z: ((z + z1) / 2) * cellSize,
+                    },
+                });
+            }
+        }
+    }
+    return children;
+}
+/**
+ * Re-cooks compound collider boxes intersecting a dirty AABB cell region,
+ * iteratively expanding the re-cook volume to cover any intersecting previously-merged
+ * boxes so uncarved solid voxels are never dropped. Preserves disjoint children
+ * without full-chunk re-cooking. Returns undefined if 0 voxels remain across the chunk.
+ */
+export function cookDeterministicVoxelSubregion3D(chunk, existingShape, dirtyRegion) {
+    const { dimX, dimY, dimZ, cellSize } = chunk;
+    let activeMinX = Math.max(0, Math.min(dirtyRegion.minX, dirtyRegion.maxX));
+    let activeMaxX = Math.min(dimX - 1, Math.max(dirtyRegion.minX, dirtyRegion.maxX));
+    let activeMinY = Math.max(0, Math.min(dirtyRegion.minY, dirtyRegion.maxY));
+    let activeMaxY = Math.min(dimY - 1, Math.max(dirtyRegion.minY, dirtyRegion.maxY));
+    let activeMinZ = Math.max(0, Math.min(dirtyRegion.minZ, dirtyRegion.maxZ));
+    let activeMaxZ = Math.min(dimZ - 1, Math.max(dirtyRegion.minZ, dirtyRegion.maxZ));
+    if (activeMinX > activeMaxX || activeMinY > activeMaxY || activeMinZ > activeMaxZ) {
+        return existingShape;
+    }
+    // Iterative fixed-point expansion to absorb all intersecting merged boxes
+    let expanded = true;
+    while (expanded) {
+        expanded = false;
+        for (const child of existingShape.children) {
+            if (child.shape.type !== 'box') {
+                continue;
+            }
+            const boxMinX = Math.round((child.offset.x - child.shape.halfX) / cellSize + 0.5);
+            const boxMaxX = Math.round((child.offset.x + child.shape.halfX) / cellSize - 0.5);
+            const boxMinY = Math.round((child.offset.y - child.shape.halfY) / cellSize + 0.5);
+            const boxMaxY = Math.round((child.offset.y + child.shape.halfY) / cellSize - 0.5);
+            const boxMinZ = Math.round((child.offset.z - child.shape.halfZ) / cellSize + 0.5);
+            const boxMaxZ = Math.round((child.offset.z + child.shape.halfZ) / cellSize - 0.5);
+            const overlaps = boxMinX <= activeMaxX && boxMaxX >= activeMinX
+                && boxMinY <= activeMaxY && boxMaxY >= activeMinY
+                && boxMinZ <= activeMaxZ && boxMaxZ >= activeMinZ;
+            if (overlaps) {
+                if (boxMinX < activeMinX) {
+                    activeMinX = Math.max(0, boxMinX);
+                    expanded = true;
+                }
+                if (boxMaxX > activeMaxX) {
+                    activeMaxX = Math.min(dimX - 1, boxMaxX);
+                    expanded = true;
+                }
+                if (boxMinY < activeMinY) {
+                    activeMinY = Math.max(0, boxMinY);
+                    expanded = true;
+                }
+                if (boxMaxY > activeMaxY) {
+                    activeMaxY = Math.min(dimY - 1, boxMaxY);
+                    expanded = true;
+                }
+                if (boxMinZ < activeMinZ) {
+                    activeMinZ = Math.max(0, boxMinZ);
+                    expanded = true;
+                }
+                if (boxMaxZ > activeMaxZ) {
+                    activeMaxZ = Math.min(dimZ - 1, boxMaxZ);
+                    expanded = true;
+                }
+            }
+        }
+    }
+    // Preserve disjoint children
+    const preservedChildren = [];
+    for (const child of existingShape.children) {
+        if (child.shape.type !== 'box') {
+            preservedChildren.push(child);
+            continue;
+        }
+        const boxMinX = Math.round((child.offset.x - child.shape.halfX) / cellSize + 0.5);
+        const boxMaxX = Math.round((child.offset.x + child.shape.halfX) / cellSize - 0.5);
+        const boxMinY = Math.round((child.offset.y - child.shape.halfY) / cellSize + 0.5);
+        const boxMaxY = Math.round((child.offset.y + child.shape.halfY) / cellSize - 0.5);
+        const boxMinZ = Math.round((child.offset.z - child.shape.halfZ) / cellSize + 0.5);
+        const boxMaxZ = Math.round((child.offset.z + child.shape.halfZ) / cellSize - 0.5);
+        const overlaps = boxMinX <= activeMaxX && boxMaxX >= activeMinX
+            && boxMinY <= activeMaxY && boxMaxY >= activeMinY
+            && boxMinZ <= activeMaxZ && boxMaxZ >= activeMinZ;
+        if (!overlaps) {
+            preservedChildren.push(child);
+        }
+    }
+    // Cook newly carved/filled subregion
+    const subCooked = cookSubregionBoxes(chunk, activeMinX, activeMinY, activeMinZ, activeMaxX, activeMaxY, activeMaxZ);
+    const finalChildren = [...preservedChildren, ...subCooked];
+    if (finalChildren.length === 0) {
+        return undefined;
+    }
+    return {
+        type: 'compound',
+        children: finalChildren,
+    };
+}

package/dist/physics3d.d.ts

@@ -58,6 +58,24 @@ export type DeterministicPhysicsShape3D = DeterministicPhysicsPrimitiveShape3D |
     readonly type: 'compound';
     readonly children: readonly DeterministicPhysicsCompoundChild3D[];
 };
+/**
+ * Creates a centered axis-aligned box shape from full dimensional sizes (sizeX, sizeY, sizeZ).
+ */
+export declare function createBoxShapeFromExtents(sizeX: number, sizeY: number, sizeZ: number): Extract<DeterministicPhysicsShape3D, {
+    readonly type: 'box';
+}>;
+/**
+ * Creates a box shape from min and max bounding coordinates.
+ * Returns a simple box if centered at (0,0,0), or a single-child compound with offset if not centered.
+ */
+export declare function createBoxShapeFromMinMax(min: Point3D, max: Point3D): DeterministicPhysicsShape3D;
+/**
+ * Creates an upright capsule shape anchored at its base (y = 0), matching character controller conventions.
+ * Encapsulates the offset into a single-child compound shape centered at y = halfHeight + radius.
+ */
+export declare function createCapsuleShapeFromBase(radius: number, totalHeight: number): Extract<DeterministicPhysicsShape3D, {
+    readonly type: 'compound';
+}>;
 export declare const deterministicPhysicsCallback3D: {
     readonly collisionEnter: 1;
     readonly collisionStay: 2;
@@ -202,6 +220,28 @@ export interface DeterministicPhysicsDetailedHit3D extends DeterministicPhysicsH
     readonly point: Point3D;
     readonly normal: Point3D;
     readonly penetration: number;
+    readonly childIndex?: number;
+}
+export interface DeterministicKinematicPose3D {
+    readonly id: string;
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+    readonly rx?: number;
+    readonly ry?: number;
+    readonly rz?: number;
+    readonly orientation?: DeterministicPhysicsQuaternion3D;
+    readonly vx?: number;
+    readonly vy?: number;
+    readonly vz?: number;
+    readonly angularVelX?: number;
+    readonly angularVelY?: number;
+    readonly angularVelZ?: number;
+}
+export interface DeterministicKinematicTransformBuffer3D {
+    readonly bodyIds: readonly string[];
+    /** Flat [x, y, z, qx, qy, qz, qw] buffer per body. Length must be bodyIds.length * 7. */
+    readonly transforms: Float64Array | Float32Array | readonly number[];
 }
 export interface DeterministicPhysicsScheduledQuery3D {
     readonly id: string;
@@ -363,6 +403,23 @@ export interface DeterministicPhysicsWorldEdit3D {
  * inside each edit list.
  */
 export declare function applyDeterministicWorldEdit3D(world: DeterministicPhysicsWorld3D, edit: DeterministicPhysicsWorldEdit3D): DeterministicPhysicsWorld3D;
+/**
+ * Fast batch update of kinematic body transforms and velocities without
+ * allocating Set instances or re-sorting world bodies. Wakes touching dynamic
+ * bodies across active contact pairs. If linear velocity (vx, vy, vz) is omitted
+ * and dtTicks (> 0) is supplied, linear velocity is derived as (newPos - oldPos) / dtTicks.
+ */
+export declare function setDeterministicKinematicPoses3D(world: DeterministicPhysicsWorld3D, poses: readonly DeterministicKinematicPose3D[], options?: {
+    readonly dtTicks?: number;
+}): DeterministicPhysicsWorld3D;
+/**
+ * Allocation-free flat buffer batch update of kinematic body transforms.
+ * Accepts flat [x, y, z, qx, qy, qz, qw] arrays with stride 7 per bodyId,
+ * eliminating caller-side object allocations on high-frequency animation loops.
+ */
+export declare function setDeterministicKinematicTransforms3D(world: DeterministicPhysicsWorld3D, buffer: DeterministicKinematicTransformBuffer3D, options?: {
+    readonly dtTicks?: number;
+}): DeterministicPhysicsWorld3D;
 /**
  * Apply a deterministic impulse to a body (linear + angular via lever arm),
  * waking the body and its contact island. Returns a new canonical world.