# Spinning Top

> An in-browser spinning top built around a sliding contact point that moves across the body as
> the top tilts. A tippe top inverts and stands on its stem, a peg top rises, sleeps and wakes,
> and two 20 mm tops fight a Koma Taisen bout in a concave dohyo under the published rules.

URL: https://spinning-top.skillsafe.ai/

## What it is
A hand-written rigid-body engine (no libraries) for an axisymmetric body on a compliant contact
with Coulomb friction, plus a hand-written WebGL2 renderer. Three modes: Koma Taisen (a duel),
Tippe top (invert it), Sleeper (keep a peg top asleep), and a Bench that exposes the physics.

## The physics, in one paragraph
The contact is the single lowest point of the body's own surface, found exactly rather than by
search: h(r,z) = z cos(theta) - r sin(theta) is linear in (r,z), so a line segment's minimum is
at an endpoint and a circular arc's is at u = pi - theta. For a spherical contact surface the
vector from the centre of mass to the contact is r_c = a e3 - R zhat, which makes
J = L . r_c (Jellett's integral) an exact constant for ANY friction law - the engine conserves
it to 1.7e-16 over a second with no friction and to 2.3e-14 with friction on at small tilt, and the residual
falls at fourth order with the step, so it emerges rather than being imposed. Energy is not
conserved; the identity that IS exact is
  1/2 m|V|^2 + 1/2 L.omega + m g z + 1/2 k delta^2 + (dissipation ledger) = constant.

## The headline
A tippe top inverts and raises its own centre of mass. This engine reproduces it, and the
mechanism it gives is NOT a tipping torque: the leading-order fast-top reduction predicts
dtheta/dt = mu N (a - R cos theta)/(I3 omega3), which is negative at small tilt and would right
the top. What actually happens is that Jellett pins the state to a level set, dissipation drives
the energy down it, and the inverted state is the cheaper of the two whenever
omega3^2 > m g (R+a)^2 / (I3 R). Friction supplies loss, not a shove.

## Controls that must fail, and do
- Remove friction: the tilt holds inside a 0.04-degree band for ten seconds and nothing is
  dissipated. With mu = 0 the contact force is vertical, so L.z and L.e3 are separately
  conserved and theta is trapped in a one-dimensional effective potential. No simulation needed.
- Replace the regularised Coulomb law with a hard stick threshold: the contact can lock into
  rolling, and the outcome stops being a smooth function of the launch spin.

## Reproduced without being told
The published inversion band 1 - alpha < gamma < 1 + alpha (alpha = a/R, gamma = I1/I3),
attributed in the literature to Hugenholtz 1952. Inside it every run finished at 177-180 degrees;
below it every run stayed at 2; above it every run stopped part of the way over.

## Rules
Koma Taisen, from the NPO All-Japan Manufacturing Koma Taisen Association's own published
rulebook: phi 20.000 mm tops, 60 mm long, a phi 250 mm dohyo concave to R700 mm, two CONSECUTIVE
wins, the contact patch must be turning, and rule 6-2 - "Koma that changes spin axis are
prohibited" - which bans the tippe top from the one competition that specifies tops at all.

## Credits and limits
CREDITS.txt names the tippe top's 1891 patent (DE 63261, Fraeulein H. Sperl), the Koma Taisen
Association, every source opened, every source that could not be opened, and every claim checked
and discarded. No affiliation with anyone named. Beyblade is a trademark of its owner and is not modelled or imitated.

## Files
- /                       the app
- /CREDITS.txt            sources, failures to fetch, and what differs from the real thing
- /LICENSE.txt            MIT-style licence