Documentation Index
Fetch the complete documentation index at: https://mintlify.com/losyoguis/149tresbandas/llms.txt
Use this file to discover all available pages before exploring further.
The Entrenador de Carambola Guiada runs a fully custom JavaScript physics engine entirely inside the browser — no server, no external library. Every shot is resolved through sub-step collision detection so balls never tunnel through each other even at high impact speeds, and the same engine powers both the predictive yellow guide and the real shot when you press Tirar.
How the Engine Works
The simulation advances in small discrete steps. Each step the engine checks for ball-to-ball overlaps and ball-to-cushion contacts, resolves them with restitution and friction coefficients, applies spin decay, and accumulates the result. The maximum step size is bounded by PHYSICS_MAX_STEP = R * 0.22, which guarantees that a fast ball cannot skip past a contact point between frames.
After the second object ball is reached and the carom is resolved, all balls stop automatically after 520 ms (AUTO_STOP_AFTER_CAROM_MS = 520). This prevents long run-out animations and lets you move on to the next attempt quickly.
Cloth Friction
The felt surface applies a multiplicative speed decay on every physics step:
| Mode | Constant | Value |
|---|
| Normal shots | FRICTION | 0.99505 |
| Long routes (3+ long cushions) | LONG_SHOT_FRICTION | 0.99635 |
Cushion Restitution
Cushion contacts use separate restitution values for the normal (perpendicular) and tangential (parallel) velocity components:
| Constant | Value | Purpose |
|---|
RAIL_RESTITUTION | 0.932 | Normal energy return — standard shots |
LONG_RAIL_RESTITUTION | 0.958 | Livelier rebound on long-route plays |
RAIL_TANGENT_FRICTION | 0.982 | Lateral speed loss on cushion contact |
LONG_RAIL_TANGENT_FRICTION | 0.992 | Less tangential loss on long routes |
RAIL_TANGENT_FRICTION = 0.982) is what makes the ball “grip” the rail slightly on contact instead of sliding away at full speed — a behaviour you feel on real tournament cloth.
Ball-to-Ball Collision
| Constant | Value | Purpose |
|---|
BALL_RESTITUTION | 0.965 | Energy returned after ball-to-ball impact |
BALL_THROW | 0.016 | Soft lateral transfer from friction between balls |
COLLISION_THROW_SCALE | 0.028 | Throw scaling for friction at contact point |
Lateral Spin (Effect)
The blue dot on the cue-ball control sets the English applied to the shot. Spin interacts with every surface the ball touches:
| Constant | Value | Purpose |
|---|
SPIN_THROW | 0.098 | Lateral spin effect on first object ball — normal |
LONG_SPIN_THROW | 0.122 | Sustained spin effect on long-route plays |
SPIN_CLOTH_DECAY | 0.9984 | Spin diminishes gradually through cloth contact |
CUE_SWERVE_STRENGTH | 0.00072 | Subtle lateral curve from spin before cushion contact |
RAIL_SPIN_OPEN_CLOSE | 0.118 | Spin opens or closes the rebound angle at the rail |
SPIN_CLOTH_DECAY = 0.9984 means spin does not vanish on the first roll — it fades progressively, matching how real ivory or phenolic balls behave on high-quality cloth.
Follow and Draw Transfer
| Constant | Value | Purpose |
|---|
FOLLOW_DRAW_TRANSFER | 0.064 | Top/back-spin effect on post-contact cue ball path |
Object Ball Behaviour
When the cue ball strikes the first object ball, the engine applies a separate set of limits so the struck ball does not fly off the table at unrealistic speed:
| Constant | Value | Purpose |
|---|
FIRST_OBJECT_TRANSFER_SCALE | 0.76 | Scales down the momentum transferred to the first object ball to prevent exaggerated departures |
FIRST_OBJECT_MAX_SPEED | 8.4 | Hard speed ceiling (internal units) applied to the first object ball after impact |
FIRST_OBJECT_POWER_RATIO | 0.53 | Fraction of cue-ball power actually delivered to the first object ball |
Additional Cushion Physics
| Constant | Value | Purpose |
|---|
RAIL_INCIDENT_LOSS | 0.052 | Extra energy loss when the cue ball arrives at a shallow (flat) angle to the rail |
RAIL_INCIDENT_LOSS = 0.052 models this geometry-dependent damping that experienced players feel on real tournament cushions.
Professional Physics Build
The engine ships as a named build that combines all calibration values above into a single, stable cloth model:
| Constant | Value |
|---|
PROFESSIONAL_PHYSICS_VERSION | 'production_v235_corner_power' |
PROFESSIONAL_TABLE_FRICTION | 0.99532 |
PROFESSIONAL_OBJECT_FRICTION | 0.99472 |
PROFESSIONAL_TABLE_FRICTION and PROFESSIONAL_OBJECT_FRICTION are applied at a higher level than the per-step FRICTION constant — they govern the cumulative cloth resistance for the full rolling phase of the cue ball and the object balls respectively.
Key Constants — Source Reference
const FRICTION = 0.99505; // cloth friction per step
const LONG_SHOT_FRICTION = 0.99635; // cloth friction — long routes
const RAIL_RESTITUTION = 0.932; // cushion energy return
const LONG_RAIL_RESTITUTION = 0.958; // cushion energy return — long routes
const BALL_RESTITUTION = 0.965; // ball-to-ball energy return
const SPIN_THROW = 0.098; // lateral spin effect — normal
const LONG_SPIN_THROW = 0.122; // lateral spin effect — long routes
const FOLLOW_DRAW_TRANSFER = 0.064; // follow/draw post-contact
const CUE_SWERVE_STRENGTH = 0.00072; // spin-induced swerve
const RAIL_INCIDENT_LOSS = 0.052; // flat-angle arrival energy loss
const FIRST_OBJECT_TRANSFER_SCALE = 0.76; // object ball departure scale
const FIRST_OBJECT_MAX_SPEED = 8.4; // object ball speed ceiling
const FIRST_OBJECT_POWER_RATIO = 0.53; // power fraction to first object ball
const PROFESSIONAL_TABLE_FRICTION = 0.99532; // rolling cloth resistance
const PROFESSIONAL_OBJECT_FRICTION= 0.99472; // object ball rolling resistance
const AUTO_STOP_AFTER_CAROM_MS = 520; // quick stop after carom
const DEMO_COUNTS_AS_SCORE = false; // Demostración never adds score
Tirar vs. Demostración
Tirar always fires real physics. The cue ball travels exactly where the physics engine sends it — no path is forced, no carom is scripted. If you aim wrong, the ball goes wrong.
Demostración replays the calibrated reference route extracted from the tutorial video. The three balls animate along the play’s pre-built guidePath — the same data the green master guide is drawn from — and the shot is flagged demoMode: true so it never counts as an attempt or adds to your score.
The predictive yellow guide is computed with the same physics engine used for the real shot. Every friction constant, spin coefficient, and restitution value is shared between the guide calculation and the actual Tirar execution. What you see in the yellow line is exactly what the ball will do when you fire.