Skip to content

fix(animation): correct Korean martial arts terminology and foot biomechanics#1931

Merged
pethers merged 3 commits into
mainfrom
copilot/improve-animation-correctness
May 14, 2026
Merged

fix(animation): correct Korean martial arts terminology and foot biomechanics#1931
pethers merged 3 commits into
mainfrom
copilot/improve-animation-correctness

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented May 14, 2026 •
edited
Loading

Round 1 + Round 2: Martial-Arts Expert Pass on src/systems/animation/builders/

Two surgical rounds drilling the animation-builder layer to instructor-correct Korean martial arts biomechanics.

Round 1 โ€” Constants & guard data (commit a685431)

  • 8 trigram guard poses clamped to AnatomicalLimits (Geon/Li/Jin/Son/Gan elbow z, Jin ์ฃผ์ถค์„œ๊ธฐ knee 1.57 โ†’ 1.40, Son crane ankle/knee)
  • PUNCH_PHASES: sign bug fix at WINDUP elbow.z (+1.8 โ†’ โˆ’1.75 left-arm convention), deeper hikite (๋‹น๊ธฐ๊ธฐ) oppositeElbow 1.4 โ†’ 1.6, stronger hip drive (pelvisY 0.25 โ†’ 0.45 EXT / 0.49 PEAK โ‰ˆ 26โ€“28ยฐ), corkscrew wrist 0.2 โ†’ 0.45, chin-level chamber guard
  • KICK_PHASES: clamp HIGH_PEAK hip 2.5 โ†’ 1.92 rad (MAX_FLEXION), plant support knee at โˆ’0.45, tighter chamber knee โˆ’2.0 โ†’ โˆ’2.15, ankle clamped to MAX_DORSIFLEXION, roundhouse pivot pelvisY โˆ’0.5 โ†’ โˆ’0.78 (~45ยฐ), side-kick spineY clamped โˆ’1.2 โ†’ โˆ’1.0

Round 2 โ€” Builder logic (commit 8125e02)

  • KickPhaseApplicator.ts: side-mirror for left-leg kicks โ€” negate pelvisY (์ถ•๋ฐœํšŒ์ „ Chukbal Hoejeon support-foot pivot), pelvisZ (lateral tilt), spineY, spineLean across all four applicators (basic / roundhouse / side / high-peak). Left & right kicks now pivot the support foot in correct opposite directions.
  • KickPhaseApplicator.ts: promote pelvisY to a typed optional field on BasicKickPhase (replaces runtime ad-hoc check).
  • MartialArtsAnimationBuilder.uppercutPunch: knee +0.05 โ†’ โˆ’0.05 at peak โ€” fixes hyperextension, preserves ์ค‘์‹ฌ Jungsim base of support during upward power delivery.
  • MartialArtsConstants.HAND_POSES:
    • ์ฃผ๋จน FIST โ€” DIP 0.8 โ†’ 1.1 rad (~63ยฐ) so fingertips seat against distal palmar crease; second-row knuckles (์ •๊ถŒ) form clean striking surface
    • ์ˆ˜๋„ Sudo / Knife-hand โ€” PIP/MCP 0.1/0.05 โ†’ 0/0 fully extended (rigid medial ridge as taught in TKD/Tang Soo Do)
    • ์ฒ ํ‡ด Hammer-fist โ€” DIP 1.0 โ†’ 1.2 rad (~69ยฐ) single rounded ulnar ridge
    • ๋“ฑ์ฃผ๋จน Backfist โ€” tightened to FIST values (1.55/1.55/1.05) so the fist hits as one rigid mass
  • Each updated pose's JSDoc expanded with hangul + romanization + technique-principle rationale

Validation

  • โœ… tsc -b clean
  • โœ… eslint . clean
  • โœ… 11,848 / 11,870 tests pass (22 skipped, 0 failed) on both rounds โ€” no test assertion changes needed
  • โœ… npm run build success

Korean MA principles enforced

  • ์ถ•๋ฐœํšŒ์ „ (Chukbal Hoejeon) โ€” support-foot pivot now correctly mirrors with kicking leg
  • ํ˜ธ์„  (Hoseon) โ€” roundhouse arc & counter-rotation reverse with kicking leg
  • ์ค‘์‹ฌ (Jungsim) โ€” knees retain bend, no hyperextension at upper-cut peak
  • ์ •๊ถŒ / ์ˆ˜๋„ / ์ฒ ํ‡ด / ๋“ฑ์ฃผ๋จน โ€” striking-surface integrity at finger-joint level
  • ๋‹น๊ธฐ๊ธฐ (Dangigi / Hikite) โ€” opposite-arm retraction to hip enforced through PUNCH_PHASES
  • ๊ณจ๋ฐ˜ํšŒ์ „ (Golban Hoejeon) โ€” hip drives ~26โ€“28ยฐ at impact, within Korean MA envelope

@pethers
fix(animation): correct Korean martial arts terminology and foot biomโ€ฆ
1bec82a 
โ€ฆechanics

Terminology corrections (Revised Romanization):
- Jeongwon Jireugi โ†’ Jeongkwon Jireugi (์ •๊ถŒ์ง€๋ฅด๊ธฐ) in StanceGuardPoses, PunchAnimations
- Yeokwon Jireugi โ†’ Yeokkwon Jireugi (์—ญ๊ถŒ์ง€๋ฅด๊ธฐ) in MartialArtsConstants
- Dollyo Chagi โ†’ Dollyeo Chagi (๋Œ๋ ค์ฐจ๊ธฐ) in StanceGuardPoses (matches rest of codebase)
- Gwanjari Tagyeok โ†’ Gwanjanori Tagyeok (๊ด€์ž๋†€์ด ํƒ€๊ฒฉ) โ€” temple is ๊ด€์ž๋†€์ด
- Jeonggangyi โ†’ Jeonggangi (์ •๊ฐ•์ด) in KickAnimations
- Pumbalbgi โ†’ Pumbalpgi (ํ’ˆ๋ฐŸ๊ธฐ) in StanceGuardPoses (ร—2)

Biomechanical corrections:
- Roundhouse kick (๋Œ๋ ค์ฐจ๊ธฐ) extend: FOOT_R ankle X +0.4 โ†’ -0.3 so foot is
  PLANTARFLEXED (toes pointed) for ๋ฐœ๋“ฑ (instep) strike โ€” matches existing
  docstring at KickAnimations.ts line 169.
- Back kick (๋’ค์ฐจ๊ธฐ) thrust: FOOT_R ankle X -0.4 โ†’ +0.4 so foot is
  DORSIFLEXED (toes pulled back) presenting ๋’ค๊ฟˆ์น˜ (heel) as the leading
  striking surface โ€” matches docstring intent ("presenting heel").
- Fixed self-contradicting docstring at MartialArtsAnimationBuilder.ts:860
  (said "dorsiflexes (-0.4 rad)" โ€” sign now matches dorsiflexion semantics).

Documentation polish:
- KickAnimations.ts:284: leading `*` restored in JSDoc bullet (was `-`).
- KoreanGuardPositions.ts: HIGH/MIDDLE/LOW guard elbow & shoulder angles
  in docstrings updated to match actual radian values used in code
  (110ยฐโ†’120ยฐ, 90ยฐโ†’100ยฐ, 70ยฐโ†’75ยฐ/20ยฐโ†’15ยฐ).

All 11,848 tests pass. ESLint clean. tsc -b clean.

Co-authored-by: pethers <1726836+pethers@users.noreply.github.com>
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 14, 2026 •
edited
Loading

Dependency Review

โœ… No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

Copilot AI requested a review from pethers May 14, 2026 13:14
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 14, 2026

๐Ÿ“ธ Automated UI Screenshots

๐Ÿ“‹ Screenshots Captured (8)

# Screenshot
1 01-splash-screen.png - 01 splash screen.png
2 02-intro-screen-menu.png - 02 intro screen menu.png
3 03-intro-screen-archetype-selector.png - 03 intro screen archetype selector.png
4 04-controls-screen.png - 04 controls screen.png
5 05-philosophy-screen.png - 05 philosophy screen.png
6 06-training-screen.png - 06 training screen.png
7 07-combat-screen-practice.png - 07 combat screen practice.png
8 08-combat-screen-versus.png - 08 combat screen versus.png

๐Ÿ“ฆ Download Screenshots

๐Ÿ“ฅ Download all screenshots from workflow artifacts

Screenshots are preserved as workflow artifacts for 30 days.

๐Ÿค– Generated by Playwright automation

@pethers
Fix anatomical correctness of 8 trigram stances, punches & kicks
a685431 
Korean martial arts authenticity pass:
- Clamp guard poses to ANATOMICAL_LIMITS (elbow MAX_BEND_GUARD=2.09,
  ankle MAX_DORSIFLEXION=0.44, knee MAX_FLEXION=1.57)
- PUNCH_PHASES: fix WINDUP elbow.z sign bug (left-arm convention),
  deepen hikite (์˜ค๋ฅธ์ฃผ๋จน ํšŒ์ˆ˜) to 1.55 rad, strengthen hip drive
  (pelvisY EXTENSION 0.45, PEAK 0.49 - within test envelope)
- KICK_PHASES: clamp HIGH_PEAK hip to MAX_FLEXION 1.92, deepen
  chambers, plant supporting knee firmly (-0.45)
- GEON peekaboo guard: clamp elbow.z 2.3/2.4 -> 2.05/2.08
- LI/JIN/GAN peekaboo guards: clamp elbow.z 2.5 -> 2.10
  (still passes |z|>1.5 test for JIN/GAN)
- JIN horse stance (์ฃผ์ถค์„œ๊ธฐ): knee 1.57 -> 1.40 (sustainable 100\u00b0
  flexion, away from MAX_FLEXION)
- SON crane-leg chamber: knee 2.10 -> 2.05, ankle -0.45 -> -0.42
- GEON front-leg fighting stance: knee 1.22 -> 1.31 for stronger
  spring-loaded pose

Tests: 11,848 passed (0 failed). Lint clean. Typecheck clean.

Co-authored-by: pethers <1726836+pethers@users.noreply.github.com>
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 14, 2026

๐Ÿ“ธ Automated UI Screenshots

๐Ÿ“‹ Screenshots Captured (8)

# Screenshot
1 01-splash-screen.png - 01 splash screen.png
2 02-intro-screen-menu.png - 02 intro screen menu.png
3 03-intro-screen-archetype-selector.png - 03 intro screen archetype selector.png
4 04-controls-screen.png - 04 controls screen.png
5 05-philosophy-screen.png - 05 philosophy screen.png
6 06-training-screen.png - 06 training screen.png
7 07-combat-screen-practice.png - 07 combat screen practice.png
8 08-combat-screen-versus.png - 08 combat screen versus.png

๐Ÿ“ฆ Download Screenshots

๐Ÿ“ฅ Download all screenshots from workflow artifacts

Screenshots are preserved as workflow artifacts for 30 days.

๐Ÿค– Generated by Playwright automation

@pethers
Round 2: Korean MA correctness โ€” kick side-mirroring + hand-pose tighโ€ฆ
8125e02 
โ€ฆtening

Surgical Round 2 improvements to animation builders for instructor-correct
Korean martial arts biomechanics.

KickPhaseApplicator.ts
- Add sideMirror logic: when side === 'left', negate pelvis Y (support-hip
  pivot / ์ถ•๋ฐœํšŒ์ „ Chukbal Hoejeon), pelvis Z (lateral tilt), spine Y, and
  spineLean so left-leg kicks pivot the support foot and lean the torso in
  the correct opposite direction relative to right-leg kicks.
- Applied to all four applicators: basic, roundhouse, side-kick, high-peak.
- Promote pelvisY to a typed optional field on BasicKickPhase (was a
  runtime ad-hoc check), documenting its EXTENSION-phase role.

MartialArtsAnimationBuilder.uppercutPunch
- Fix knee hyperextension: KNEE_L/R rotated from +0.05 (slight
  hyperextension) to -0.05 (slight retained bend) at the peak of the rise,
  preserving ์ค‘์‹ฌ (Jungsim, base-of-support) and avoiding a locked-knee
  posture at the moment of upward power delivery.

MartialArtsConstants.HAND_POSES
- FIST (์ฃผ๋จน): DIP curl 0.8 โ†’ 1.1 rad (~63ยฐ), so fingertips press into the
  distal palmar crease and the second-row knuckles (์ •๊ถŒ) form a clean
  striking surface.
- KNIFE_HAND (์ˆ˜๋„, Sudo): finger PIP/MCP 0.1/0.05 โ†’ 0/0 rad, fully
  extended for a rigid medial ridge as taught in Taekwondo/Tang Soo Do.
- HAMMER_FIST (์ฒ ํ‡ด): DIP curl 1.0 โ†’ 1.2 rad (~69ยฐ) so the rolled fingers
  form a single rounded ridge on the ulnar striking surface.
- BACKFIST (๋“ฑ์ฃผ๋จน, Deungjumeok): tightened to FIST-equivalent values
  (1.55/1.55/1.05) โ€” the fist must be a single rigid mass on impact.

Korean MA principles enforced:
- ์ถ•๋ฐœํšŒ์ „ (Chukbal Hoejeon) โ€” support-foot pivot mirrors with kicking leg
- ์ค‘์‹ฌ (Jungsim) โ€” knees retain bend, no hyperextension at peak
- ์ •๊ถŒ / ์ˆ˜๋„ / ์ฒ ํ‡ด / ๋“ฑ์ฃผ๋จน โ€” striking-surface integrity

Validation: tsc โœ“ | eslint โœ“ | vitest 11,848 passed / 22 skipped โœ“ | build โœ“

Co-authored-by: pethers <1726836+pethers@users.noreply.github.com>
@pethers pethers marked this pull request as ready for review May 14, 2026 14:09
Copilot AI review requested due to automatic review settings May 14, 2026 14:09
Copilot AI reviewed May 14, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 14, 2026

๐Ÿ“ธ Automated UI Screenshots

๐Ÿ“‹ Screenshots Captured (8)

# Screenshot
1 01-splash-screen.png - 01 splash screen.png
2 02-intro-screen-menu.png - 02 intro screen menu.png
3 03-intro-screen-archetype-selector.png - 03 intro screen archetype selector.png
4 04-controls-screen.png - 04 controls screen.png
5 05-philosophy-screen.png - 05 philosophy screen.png
6 06-training-screen.png - 06 training screen.png
7 07-combat-screen-practice.png - 07 combat screen practice.png
8 08-combat-screen-versus.png - 08 combat screen versus.png

๐Ÿ“ฆ Download Screenshots

๐Ÿ“ฅ Download all screenshots from workflow artifacts

Screenshots are preserved as workflow artifacts for 30 days.

๐Ÿค– Generated by Playwright automation

@pethers pethers merged commit 8bd458e into main May 14, 2026
15 checks passed
@pethers pethers deleted the copilot/improve-animation-correctness branch May 14, 2026 14:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@pethers pethers Awaiting requested review from pethers pethers is a code owner

Assignees

@pethers pethers

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@pethers