# Kendama

> An in-browser kendama (けん玉). Two rigid bodies coupled by ONE unilateral inextensible
> string, judged against the Japan Kendama Association's published criteria for a catch.
> An independent reimplementation, not affiliated with the JKA, GLOKEN or Yamagata Koubou.

## What is modelled

The ken and the tama are separate rigid bodies in three dimensions. They are coupled by a
massless inextensible string that carries tension only: it is slack whenever its two
anchors are closer than its length. The slack-to-taut transition is impulsive. With n the
unit vector from the ken's string hole to the ball's, and r_A, r_E their offsets from the
bodies' centres of mass,

    K = 1/m_ken + 1/m_tama
        + n . ( I_ken^-1 (r_A x n) x r_A ) + n . ( I_tama^-1 (r_E x n) x r_E )
    j = (1 + e) v_n / K

applied along n at both anchors with opposite signs. Linear and angular momentum are
conserved exactly across it; kinetic energy falls by exactly (1/2)(1 - e^2) v_n^2 / K.
Because the ball's anchor is on its SURFACE, the same impulse spins the ball — which is
the toy's whole character, and a point-mass statement of the law misses it.

Neither of the two openly readable kendama robotics papers models this transition at all:
one latches the string permanently slack once tension reaches zero, the other treats a
taut string in free flight as a configuration to avoid.

## What is judged, and by whose rule

Two criteria, quoted from 級・段位認定試験及び公式戦におけるルールの原則 (rev. 2019-05-10):
- a cup catch requires the ENTIRE outer circumference of the cup face to contact the ball
- a spike catch requires the spike to enter the hole COMPLETELY

Both are applied geometrically. The engine measures the largest deviation of any rim point
from the ball's surface; a second, independently written judge solves the same test in
closed form and the two are diffed over randomised attempts.

## Headline result

The release-speed window is MEASURED, not assumed: the engine sweeps the pull, runs the
whole simulation, and asks the judge. Big cup 1.15-2.46 m/s; small cup the same; base cup
1.23-1.57; spike 0.67-0.76. The ordering matches the Association's own difficulty stars
except that 中皿, a one-star trick, comes out four times narrower than 大皿.

A snatch after release accompanies 22 of 23 failed big-cup attempts and 72 of 72 failed
spike attempts — but a counterfactual that removes the string entirely after release
rescues only 7 of 23 for the big cup, none net for the base cup, and makes the spike
catch WORSE. The snatch is where failures end up, not mainly what puts them there.

## What the JKA does not publish

There is no numeric dimensional specification for the certified kendama. The only numeric
requirement in any JKA regulation is that the ken be at least 15 cm long. The dimensions
used here come from the certified manufacturer and from GLOKEN's shop, and the ball's
mass, the hole's size and depth, the spike's length and the position of the string hole on
the ball are published nowhere and are reconstructed or derived.

## Verification

Four instruments: a physics oracle that computes the effective mass by finite difference
on the dynamics and is validated first against Loney's and Routh's published closed forms;
a second judge written from the documents rather than the code; a mesh-normal test with a
reversed-mesh control; and 56 deliberate single-line source mutants, all of which are
caught.

## Pages

- [The app](https://kendama.skillsafe.ai/): play it, and re-run the window scan in the tab
- [Credits and sources](https://kendama.skillsafe.ai/CREDITS.txt): every document read,
  with its revision date, and every source that could not be opened
- [Licence](https://kendama.skillsafe.ai/LICENSE.txt): MIT