Physics System Mathematics

Physics System Mathematics Level 1 Reference Kara Rawson [email protected] December 2025 Abstract This document provides the mathematical foundation for the Level 1 physics engine used in CatGame. It contains precise equations and derivations for integration, collision detection (AABB and SDF), collision response, settling and sleep mechanics, determinism constraints, and reference constants. The emphasis is on implementation-ready formulas and parameter choices appropriate for both deterministic (fixed-point) and high-performance (GPU-accelerated) modes. Contents 1 Overview 2 2 Part 1: Rigid Body Integration 2 2.1 1.1 Linear Integration (Symplectic Euler) . . . . . . . . . . . . . . . . . . . . . . . . 2 2.2 1.2 Angular Integration (Quaternion-based) . . . . . . . . . . . . . . . . . . . . . . . 2 2.3 1.3 Inertia Tensor for Axis-Aligned Cubes . . . . . . . . . . . . . . . . . . . . . . . . 3 2.4 1.4 Deterministic Fixed-Point (Q16.16) . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3 Part 2: Collision Detection 4 3.1 2.1 Spatial Partitioning (Uniform Grid) . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.2 2.3 SDF Sampling and GPU Collision Mathematics . . . . . . . . . . . . . . . . . . . 4 3.3 2.2 Narrow-Phase Collision (AABB vs AABB) . . . . . . . . . . . . . . . . . . . . . . 5 4 Part 3: Collision Response 6 4.1 3.1 Impulse-Based Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 4.2 3.2RestitutionImpulse .................................. 6 4.3 3.3Friction ......................................... 7 4.4 3.4 Position Correction (Baumgarte Stabilization) . . . . . . . . . . . . . . . . . . . . 7 5 Part 4: Settling and Sleep 7 5.1 4.1 Angular Alignment (Righting Torque) . . . . . . . . . . . . . . . . . . . . . . . . 7 5.2 4.2 Righting Torque Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 5.3 4.3 Angular Damping During Settlement . . . . . . . . . . . . . . . . . . . . . . . . . 8 5.4 4.4 Resting Contact Velocity Cancellation . . . . . . . . . . . . . . . . . . . . . . . . 9 5.5 4.5 Low-Speed Restitution Reduction . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5.6 4.6 Linear Settling Damping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5.7 4.7 Sleep Conditions (Multi-Stage) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 6 Part 5: Wake Conditions 10 6.1 5.1 Sleeping Body Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 7 Part 6: Spatial Grid Broadphase 10 7.1 6.1 Grid-Based Collision Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 8 Part 7: Determinism and Consistency 11 8.1 7.1TimeStep........................................ 11 8.2 7.2 Order of Operations (per frame) . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 8.3 7.3 Sleeping Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 A Appendix A: Reference Constants 11 B Appendix B: Common Queries 12 C Appendix C: Validation 12 1 1 Overview This document details all mathematical equations and derivations used in the Level 1 physics engine for rigid body dynamics and collision detection/response. 2 Part 1: Rigid Body Integration 2.1 1.1 Linear Integration (Symplectic Euler) Symplectic Euler Method: The velocity update is applied before position update, making it more stable than standard Euler for energy conservation. vn+1 =vn+a·∆t(1) pn+1 =pn+vn+1 ·∆t(2) Where: •vn= velocity at frame n •a= acceleration (force/mass) •∆t= time step (0.0167 s at 60 FPS) •pn= position at frame n Force Integration: Ftotal =Fgravity +Fcollisions (3) a=Ftotal −Fdamping m(4) Gravity (when enabled): Fgravity =m·gwhere g= (0,−9.81,0) m/s2(5) Linear Damping (velocity-dependent friction): vdamped =v·(1.0−λv·∆t)(6) where λv≈0.005 (air resistance coefficient). 2.2 1.2 Angular Integration (Quaternion-based) Quaternion Time Derivative: For angular velocity ω= (ωx, ωy, ωz): ωq= (0, ωx, ωy, ωz)(7) ˙q= 0.5·ωq·q(8) Quaternion Update: qn+1 =qn+ ˙q·∆t(9) qn+1 = normalize(qn+1)(10) 2 Angular Velocity Integration: ωn+1 =ωn+α·∆t(11) α=I−1·τ(12) where I−1is the inverse inertia tensor and τis torque. Angular Damping: ωdamped =ω·(1.0−λω·∆t)(13) where λω≈0.02 (angular air resistance). 2.3 1.3 Inertia Tensor for Axis-Aligned Cubes For a cube with half-extents (hx, hy, hz)and mass m: Ixx =m 3(h2 y+h2 z)(14) Iyy =m 3(h2 x+h2 z)(15) Izz =m 3(h2 x+h2 y)(16) Diagonal Inertia Matrix: I=  Ixx 0 0 0Iyy 0 0 0 Izz  (17) Inverse Inertia: I−1=  I−1 xx 0 0 0I−1 yy 0 0 0 I−1 zz  (18) For a unit cube (half-extent 0.5) with mass 1.0: I=  1/12 0 0 0 1/12 0 0 0 1/12  (19) 2.4 1.4 Deterministic Fixed-Point (Q16.16) Fixed-Point Representation: A Q16.16 fixed-point number represents a real value xby an integer raw value Rsuch that x=R 216 .(20) Multiplication uses integer arithmetic with a fractional-bit shift to retain scale: Rmul =Ra·Rb 216 (integer arithmetic with right-shift) (21) Conversion from floating point uses rounding: R= round x·216.(22) 3 Fixed-Point Integration: When integrating using fixed representations of position P, velocity Vand acceleration A(all stored as raw integers), the symplectic update is expressed in integer form as: V′=V+A·∆Tfixed 216 (23) P′=P+V′·∆Tfixed 216 (24) where ∆Tfixed is the timestep represented in Q16.16 and floor denotes integer truncation. These integer-shift operations guarantee deterministic arithmetic across platforms when combined with a fixed iteration order. Determinism Notes: Using fixed-point arithmetic with fixed ordering and integer accumulators ensures bit-identical results for identical inputs on different platforms; avoid non-deterministic reductions and be explicit about rounding/truncation semantics. 3 Part 2: Collision Detection 3.1 2.1 Spatial Partitioning (Uniform Grid) Cell Size: cell_size = 4.0 meters (25) Cell Index from Position: cell = p cell_size(26) AABB Bounds Calculation: For entity at position pwith collider size sand rotation q: half_extent = s/2(27) rotated_half = compute_rotated_aabb_half(q, half_extent) (28) pmin =p−rotated_half (29) pmax =p+ rotated_half (30) Rotated AABB Half-Extents: For rotation matrix R= mat3_cast(q)and axis-aligned halfextent vector h: aabb_halfi= 2 X j=0 |Rij|·hj(31) This computes the bounding box of the rotated box in world space. 3.2 2.3 SDF Sampling and GPU Collision Mathematics SDF Grid and Sampling: An SDF volume is defined over an axis-aligned grid with bounds bmin,bmax and resolution (nx, ny, nz). Convert a world-space point pto continuous voxel coordinates u: u= (ux, uy, uz)=(nx−1, ny−1, nz−1) ◦p−bmin bmax −bmin (32) 4 where ◦denotes element-wise multiplication. The signed distance at pis obtained by trilinear interpolation of the eight surrounding voxel values dijk: d(p) = 1 X i=0 1 X j=0 1 X k=0 wijk d⌊ux⌋+i, ⌊uy⌋+j, ⌊uz⌋+k(33) with interpolation weights wijk coming from the fractional parts of u. Contact Normal via SDF Gradient: Approximate the gradient using central differences on the SDF field with grid spacings ∆x, ∆y, ∆z: ∇d≈d(x+ ∆x)−d(x−∆x) 2∆x,d(y+ ∆y)−d(y−∆y) 2∆y,d(z+ ∆z)−d(z−∆z) 2∆z(34) When a collider with sampling radius rsatisfies d(p)< r, penetration and normal are computed as: penetration = r−d(p)(35) n=∇d ∥∇d∥(36) c=p−d(p)n(contact point approximation) (37) Compute Cost: Each SDF sample and gradient evaluation accesses a constant number of voxels and therefore costs O(1) work, making GPU batched processing efficient for thousands of colliders. 3.3 2.2 Narrow-Phase Collision (AABB vs AABB) Overlap Test: overlapi= (half1+ half2)i−|deltai|(38) where delta = p1−p2and i∈ {x, y, z}. Collision Condition: collides = (overlapx>0) ∧(overlapy>0) ∧(overlapz>0) (39) Collision Normal: The normal points from entity 2 toward entity 1 along the axis with minimum overlap: axis = arg min(overlapi)(40) naxis = sign(deltaaxis)(41) n=0, naxis = 1.0(42) Penetration Depth: penetration = min(overlapx,overlapy,overlapz)(43) 5 4 Part 3: Collision Response 4.1 3.1 Impulse-Based Resolution Contact Point: For ground contact (axis = y), find the lowest corner of the dynamic body: cx=px±hx(44) cy= arg min(y of cube corners)(45) cz=pz±hz(46) For other collisions, use manifold midpoint: c=p1+p2 2(47) Relative Velocity at Contact: vrel =v1+ (ω1×r1)−v2−(ω2×r2)(48) where ri=c−pi(lever arm). Velocity Along Normal: vn=vrel ·n(49) Only Apply Impulse if Separating: If vn<0, apply impulse. 4.2 3.2 Restitution Impulse Coefficient of Restitution: e= min(e1, e2)(50) where e∈[0,1] represents bounciness. Effective Mass for Rotation: Let r1×ndenote the cross product; explicitly: r1×n= (r1ynz−r1zny, r1znx−r1xnz, r1xny−r1ynx)(51) meff =m−1 1+ (I−1 1(r1×n)) ·(r1×n)(52) Impulse Magnitude: j=−(1+e)vn meff (53) Velocity Update: v′ 1=v1+j·m−1 1·n(54) ω′ 1=ω1+I−1 1r1×(j·n)(55) 6 4.3 3.3 Friction Tangent Velocity: vtan =vrel −(vrel ·n)n(56) vtan_mag =|vtan|(57) Friction Impulse (Coulomb): µ=√µ1µ2(58) jt= min vtan_mag ·meff , j ·µ(59) Tangent Direction: t=vtan vtan_mag (60) Friction Application: v′ 1−=jt·m−1 1·t(61) ω′ 1−=I−1 1r1×(jt·t)(62) 4.4 3.4 Position Correction (Baumgarte Stabilization) Problem: Overlap causes continued collisions even with impulses. Solution: Push bodies apart proportionally to penetration: p′ 1=p1+n·max(0,penetration −slop) ·percent (63) Parameters: •slop = 0.001 m (tolerance) •percent = 1.0(100% of penetration corrected per frame) 5 Part 4: Settling and Sleep 5.1 4.1 Angular Alignment (Righting Torque) Best-Aligned Axis: Find which cube axis is most aligned with world up (0,1,0): axes = {q·(1,0,0), q ·(0,1,0), q ·(0,0,1)}(64) best_axis = arg max axesi·(0,1,0)(65) Alignment Score: alignment = best_axis ·(0,1,0)(66) 7 Misalignment: misalign = 1.0−alignment (67) Notes: •alignment = 1.0 →face aligned (perfectly flat) •alignment ≈0.707 →edge contact (45°) •alignment ≈0.577 →corner contact (54.7°) 5.2 4.2 Righting Torque Application Righting Axis (cross product to align): r= best_axis ×(0,1,0), r =r |r|(68) Desired Angular Velocity: ωdesired =kp·speed_factor ·misalign (69) where •kp= 30.0rad/s per unit misalignment •speed_factor = max(0.5,2.0−|v|)(stronger when slow) Angular Velocity Error: ωerror =ωdesired −(ωcurrent ·r)(70) Corrective Torque: ω′=ω+kd·ωerror ·∆t·r(71) where kd= 10.0(derivative gain). 5.3 4.3 Angular Damping During Settlement Four regimes (applied outside impulse block, every contact frame): 1. Nearly perfect alignment (alignment >0.998): ω′= 0.4·ω(72) 2. Very good alignment (alignment >0.99): ω′= 0.7·ω(73) 3. Good alignment (alignment >0.95): ω′= 0.85 ·ω(74) 4. Poor alignment (alignment ≤0.95): No damping - let righting torque work freely. 8