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 ships with 148 active plays drawn directly from a professional three-cushion billiards tutorial video. Each play has its own photograph of the initial ball layout, a photograph showing the reference route on the table, and a transparent guide overlay that the app projects as a green band during practice.
Play Range
Plays are numbered 001–079 and 081–149. The number 080 is intentionally absent — no reference images or guide assets exist for that sequence position. The dropdown selector keeps 080 visible but disabled so the continuous numbering of the series remains clear.
Play 080 appears in the Selecciona la carambola dropdown as a disabled option to preserve the visual continuity of the sequence. It cannot be selected, loaded, or practiced. Selecting it has no effect and no assets for it exist in assets/jugadas/.
Asset Files per Play
All assets live in a single flat folder — assets/jugadas/ — with no numbered subdirectories. Each play NNN is served by exactly three files:
| File | Description |
|---|
posicion_inicial_NNN.webp | Photograph of the initial ball positions on the real table |
recorrido_guia_NNN.webp | Photograph showing the reference route with the trajectory already drawn |
guia_referencia_NNN.png | Transparent PNG extracted from the route photograph, used as the green overlay band |
Shot Data Structure
Each play is stored as an object in the practiceShots array inside js/app.js, built by buildPracticeShotLibrary() and then patched by applyReferenceGuideCorrections(). The key fields are:
| Field | Type | Description |
|---|
code | string | Zero-padded play number, e.g. "001" |
title | string | Display title shown in the UI |
family | string | Series name grouping related plays |
focus | string | Short description of the skill the play trains |
balls | array | Ball objects — see below |
aimAt | object | Target point { x, y, label } — where the cue is aimed |
first | string | Which ball to hit first: "red" or "yellow" |
second | string | The ball that completes the carambola |
power | number | Shot power as a percentage (1–160) |
effect | object | Spin point { x, y } in design coordinates (−85 to 85 per axis) |
route | string | Human-readable description of the reference route |
guidePath | array | Points { x, y } that define the master green guide line |
tip | string | Coaching note shown after a failed attempt |
src | string | Path to recorrido_guia_NNN.webp |
referenceGuideImage | string | Path to guia_referencia_NNN.png |
Ball Objects
Each entry in the balls array uses design coordinates on a 1000 × 560 canvas:
| Field | Type | Description |
|---|
id | string | Ball identifier: "cue", "yellow", or "red" |
name | string | Human-readable name: "Blanca", "Amarilla", or "Roja" |
x | number | Horizontal position (design px, 0–1000) |
y | number | Vertical position (design px, 0–560) |
vx | number | Initial horizontal velocity (always 0 at load) |
vy | number | Initial vertical velocity (always 0 at load) |
Physics Overrides
Six plays in the first sixty require special aiming corrections that override the default angle calculated from ball positions. These are stored in FIRST_SIXTY_PHYSICAL_OVERRIDES:
| Field | Description |
|---|
offsetDeg | Angular correction in degrees added to the default aim angle |
power | Overridden power percentage |
effect | Overridden spin point { x, y } |
011, 012, 023, 032, 036, and 040 — plays where the standard geometry alone would not produce the required three-cushion closure.
Concrete Example — Play 001
Below is a representative reconstruction of play 001 as it is stored after all corrections are applied. The coordinates come directly from js/app.js:
// Play 001 — from js/app.js (shots[0])
{
code: '001',
title: 'Jugada 001 del video — configuración exacta',
family: 'Video original · posición inicial + recorrido',
focus: 'Jugada inicial configurada para que el taco apunte hacia la roja. La salida de referencia queda revisada con tres bandas antes del cierre a la amarilla.',
balls: [
{ id: 'cue', name: 'Blanca', x: 275, y: 348, vx: 0, vy: 0 },
{ id: 'yellow', name: 'Amarilla', x: 275, y: 286, vx: 0, vy: 0 },
{ id: 'red', name: 'Roja', x: 708, y: 286, vx: 0, vy: 0 }
],
aimAt: { x: 708, y: 286, label: 'taco apuntando directo a la roja' },
first: 'red',
second: 'yellow',
power: 70,
effect: { x: 42, y: -28 },
src: 'assets/jugadas/recorrido_guia_001.webp',
referenceGuideImage: 'assets/jugadas/guia_referencia_001.png',
route: 'roja → banda superior/derecha → banda inferior → banda izquierda → cierre a la amarilla',
guidePath: [
{ x: 275, y: 348 }, { x: 708, y: 286 },
{ x: 925, y: 78 }, { x: 515, y: 500 },
{ x: 54, y: 315 }, { x: 275, y: 286 }
]
}
guidePath is the master green band displayed on the table. It was manually reviewed in v202 to confirm three full cushion contacts before the closure to the second ball.
Play Selection
Use the Selecciona la carambola dropdown in the practice panel to load any play. The dropdown is populated at startup from the full practiceShots array and lists entries in order from 001 to 149.
When a play is selected:
- The three balls are placed at the play’s
balls positions.
- The green master guide (
guidePath) appears on the table immediately.
- The cue aims toward
aimAt, power is set from power, and the spin point moves to effect.
- The yellow predictive line reflects the current physical setup.
Video Time Index
Each play maps to a specific position and route timestamp in the tutorial video. The two timestamps are stored as posicion and recorrido fields (e.g. "0:33" and "1:13" for play 001). Clicking Videotutorial opens the video modal and seeks directly to the posicion time of the currently selected play so you can study the ball layout before attempting the shot.
Play Families
The 148 active plays are organized into seven internal series inside buildPracticeShotLibrary(). Plays 001–060 are built by series loops and then overridden with exact video data; plays 061–149 use video-original ball positions directly.
| Series | Plays | Family label in code |
|---|
| Serie 1/6 | 25 plays | Serie 1/6 · patrón natural del video |
| Serie 2/6 | 24 plays | Serie 2/6 · espejo del patrón natural |
| Serie 3/6 | 25 plays | Serie 3/6 · sistema visual de tres bandas |
| Serie 4/6 | 20 plays | Serie 4/6 · banda-bola-bandas-bola |
| Serie 5/6 | 25 plays | Serie 5/6 · extensión del recorrido |
| Serie 6/6 | 20 plays | Serie 6/6 · medición de velocidad |
| Serie final | 10 plays | Serie final · corrección y precisión |
Video original · posición inicial + recorrido. The family field on every shot object identifies which series it belongs to.