MODEL SETTINGS
Changes apply immediately, including during a shot. Re-rack to compare identical starting conditions.
What these parameters mean
Restitution e is separation speed / approach speed along the normal. With friction disabled, e = 1 preserves kinetic energy in an isolated collision; e < 1 dissipates it.
Sliding friction opposes velocity at the cloth contact, coupling translation to spin. Rolling resistance slows a ball once it rolls without slipping. Axial resistance damps spin around the vertical axis.
Ball and cushion friction clamp tangential impulses by |J_t| ≤ μ J_n. They transfer spin during contact. A cushion acts as an infinite-mass body.
The cue gesture uses an idealized spring: ½kd² = ½mv², k = 46.68 N/m. An off-center hit adds rotational energy through Δω = I⁻¹(r × J); this input model is not a measured flexible cue.
Lengths are metres, time seconds, mass kilograms. Balls: m = 0.17 kg, r = 0.028575 m; gravity g = 9.81 m/s². The x and z axes lie on the felt; y points up.
Four contact passes per fixed step resolve overlapping contacts. Position correction reduces overlap. Pocket capture is a geometric approximation; the guide predicts only the first geometric impact. There is no cloth deformation, air drag, masse curvature, or tournament rules adjudication.
Vector algebra & the solver, step by step
A vector has three components: [x, y, z]. Length is |v| = √(v_x² + v_y² + v_z²). The dot product a · b = a_x b_x + a_y b_y + a_z b_z measures how much two vectors align. Projecting relative velocity onto the collision normal gives v_n = v_r · n.
The cross product r × J = [r_y J_z − r_z J_y, r_z J_x − r_x J_z, r_x J_y − r_y J_x] gives angular impulse, perpendicular to both input vectors. A central hit has r parallel to J, so r × J = 0. Moving the cue contact off-center creates spin.
At contact, v_r = (v_B + ω_B × r_B) − (v_A + ω_A × r_A). Split it into v_n n and a tangent v_t = v_r − v_n n. The normal impulse separates approaching bodies; a tangent impulse opposes slip.
For a tangent contact between two solid spheres, the effective inverse mass is 2/m + 2r²/I = 7/m. The solver requests |v_t| divided by this value, then limits it by μ J_n. The cushion equivalent is 1/m + r²/I.
Every 1/480 second: apply cloth friction and gravity; integrate positions; capture pockets; make four passes through ball and cushion contacts; correct small overlaps; integrate each quaternion with the angular-velocity exponential map and normalize it.
For angle θ = |ω|Δt, the incremental quaternion is [ω_hat sin(θ/2), cos(θ/2)]. Left-multiplying it by q advances orientation in world coordinates. The inspector turns q into a live orthogonal 3×3 matrix R, whose inverse is its transpose.
Linear momentum is conserved by equal-and-opposite ball impulses. Cloth and cushions exchange momentum with the table. Friction and restitution below 1 remove energy; pocketed balls leave the active energy total. Tiny numerical differences can arise from discrete contact ordering and overlap correction.