blacktrigram 0.7.47 → 0.7.49

package/lib/systems/animation/builders/MartialArtsConstants.js

@@ -27,7 +27,15 @@
 var HAND_POSES = {
 	/**
 	* Closed Fist - Standard punch (주먹)
-	* Fingers curled tight, thumb outside
+	* Fingers curled tight, thumb wrapped outside over index/middle PIPs.
+	*
+	* Korean martial arts (Taekwondo / Tang Soo Do / Hapkido) fist:
+	* - MCP (prox) flexed ~90° (1.57 rad)
+	* - PIP (inter) flexed ~90° (1.57 rad)
+	* - DIP (dist) flexed ~63° (1.1 rad) — fingertips pressed firmly into the
+	*   distal palmar crease so the striking surface is the front of the
+	*   second-row knuckles (정권). Previous value of 0.8 rad (~46°) left
+	*   the fingertips visibly slack and reduced impact-surface integrity.
 	*/
 	FIST: {
 		thumb_meta: [
@@ -61,7 +69,7 @@ var HAND_POSES = {
 			0
 		],
 		index_dist: [
-			.8,
+			1.1,
 			0,
 			0
 		],
@@ -81,7 +89,7 @@ var HAND_POSES = {
 			0
 		],
 		middle_dist: [
-			.8,
+			1.1,
 			0,
 			0
 		],
@@ -101,7 +109,7 @@ var HAND_POSES = {
 			0
 		],
 		ring_dist: [
-			.8,
+			1.1,
 			0,
 			0
 		],
@@ -121,7 +129,7 @@ var HAND_POSES = {
 			0
 		],
 		pinky_dist: [
-			.8,
+			1.1,
 			0,
 			0
 		]
@@ -329,8 +337,17 @@ var HAND_POSES = {
 		]
 	},
 	/**
-	* Knife Hand - Ridge hand strikes (수도)
-	* Fingers together, thumb tucked
+	* Knife Hand - Ridge hand strikes (수도, Sudo)
+	*
+	* Korean 수도치기 (Sudo Chigi): all four fingers fully extended and
+	* pressed tightly together so the medial edge of the hand (pinky-side
+	* fascia overlying the fifth metacarpal) forms a rigid striking ridge.
+	* The thumb is firmly adducted and flexed across the palm so it cannot
+	* be hooked or broken by the target.
+	*
+	* Previous values held the fingers at a slight 0.1 rad bend, which
+	* softens the ridge and is anatomically incorrect for 수도. Fingers are
+	* now strictly 0 rad (fully straight); thumb wrap is unchanged.
 	*/
 	KNIFE_HAND: {
 		thumb_meta: [
@@ -354,12 +371,12 @@ var HAND_POSES = {
 			0
 		],
 		index_prox: [
-			.1,
+			0,
 			0,
 			0
 		],
 		index_inter: [
-			.05,
+			0,
 			0,
 			0
 		],
@@ -374,12 +391,12 @@ var HAND_POSES = {
 			0
 		],
 		middle_prox: [
-			.1,
+			0,
 			0,
 			0
 		],
 		middle_inter: [
-			.05,
+			0,
 			0,
 			0
 		],
@@ -394,12 +411,12 @@ var HAND_POSES = {
 			0
 		],
 		ring_prox: [
-			.1,
+			0,
 			0,
 			0
 		],
 		ring_inter: [
-			.05,
+			0,
 			0,
 			0
 		],
@@ -414,12 +431,12 @@ var HAND_POSES = {
 			0
 		],
 		pinky_prox: [
-			.1,
+			0,
 			0,
 			0
 		],
 		pinky_inter: [
-			.05,
+			0,
 			0,
 			0
 		],
@@ -430,8 +447,15 @@ var HAND_POSES = {
 		]
 	},
 	/**
-	* Hammer Fist - Bottom fist strikes (철퇴)
-	* Tight fist for hammer blow
+	* Hammer Fist - Bottom fist strikes (철퇴, Cheoltoe)
+	*
+	* Korean martial arts hammer-fist (망치주먹): the fist is clenched
+	* tighter than a standard punching fist because the striking surface is
+	* the bottom (ulnar-side) of the rolled fingers, which must be a hard,
+	* compact mass with no give. PIP/MCP are at the upper end of voluntary
+	* flexion (~97° / 1.7 rad) and DIP is now ~69° (1.2 rad) so the
+	* fingertips bury deep into the palmar crease and present a single,
+	* rounded striking ridge along the pinky side.
 	*/
 	HAMMER_FIST: {
 		thumb_meta: [
@@ -465,7 +489,7 @@ var HAND_POSES = {
 			0
 		],
 		index_dist: [
-			1,
+			1.2,
 			0,
 			0
 		],
@@ -485,7 +509,7 @@ var HAND_POSES = {
 			0
 		],
 		middle_dist: [
-			1,
+			1.2,
 			0,
 			0
 		],
@@ -505,7 +529,7 @@ var HAND_POSES = {
 			0
 		],
 		ring_dist: [
-			1,
+			1.2,
 			0,
 			0
 		],
@@ -525,14 +549,20 @@ var HAND_POSES = {
 			0
 		],
 		pinky_dist: [
-			1,
+			1.2,
 			0,
 			0
 		]
 	},
 	/**
-	* Backfist - Knuckle strikes (등주먹)
-	* Fist with wrist extended back
+	* Backfist - Knuckle strikes (등주먹, Deungjumeok)
+	*
+	* Korean 등주먹치기 (Deungjumeok Chigi): the fist is closed exactly as
+	* for a forward punch — only the wrist orientation changes so that the
+	* dorsal surface of the second-row knuckles is the impact face. The
+	* previous values left the fist noticeably loose (1.4 / 1.4 / 0.7),
+	* which is biomechanically inconsistent with a 등주먹 strike where the
+	* fist must be a single rigid mass on impact. Now matches FIST tightness.
 	*/
 	BACKFIST: {
 		thumb_meta: [
@@ -556,17 +586,17 @@ var HAND_POSES = {
 			0
 		],
 		index_prox: [
-			1.4,
+			1.55,
 			0,
 			0
 		],
 		index_inter: [
-			1.4,
+			1.55,
 			0,
 			0
 		],
 		index_dist: [
-			.7,
+			1.05,
 			0,
 			0
 		],
@@ -576,17 +606,17 @@ var HAND_POSES = {
 			0
 		],
 		middle_prox: [
-			1.4,
+			1.55,
 			0,
 			0
 		],
 		middle_inter: [
-			1.4,
+			1.55,
 			0,
 			0
 		],
 		middle_dist: [
-			.7,
+			1.05,
 			0,
 			0
 		],
@@ -596,17 +626,17 @@ var HAND_POSES = {
 			0
 		],
 		ring_prox: [
-			1.4,
+			1.55,
 			0,
 			0
 		],
 		ring_inter: [
-			1.4,
+			1.55,
 			0,
 			0
 		],
 		ring_dist: [
-			.7,
+			1.05,
 			0,
 			0
 		],
@@ -616,17 +646,17 @@ var HAND_POSES = {
 			0
 		],
 		pinky_prox: [
-			1.4,
+			1.55,
 			0,
 			0
 		],
 		pinky_inter: [
-			1.4,
+			1.55,
 			0,
 			0
 		],
 		pinky_dist: [
-			.7,
+			1.05,
 			0,
 			0
 		]
@@ -1088,7 +1118,7 @@ var KICK_PHASES = {
 			0
 		],
 		knee: [
-			-2,
+			-2.15,
 			0,
 			0
 		],
@@ -1098,7 +1128,7 @@ var KICK_PHASES = {
 			0
 		],
 		supportKnee: [
-			-.25,
+			-.45,
 			0,
 			0
 		],
@@ -1120,17 +1150,17 @@ var KICK_PHASES = {
 			0
 		],
 		knee: [
-			-.05,
+			-.12,
 			0,
 			0
 		],
 		ankle: [
-			.5,
+			.4,
 			0,
 			0
 		],
 		supportKnee: [
-			-.35,
+			-.45,
 			0,
 			0
 		],
@@ -1143,10 +1173,13 @@ var KICK_PHASES = {
 	},
 	/**
 	* High Axe Kick Peak (높은차기) - Leg nearly vertical
+	*
+	* Hip flexion clamped to MAX_FLEXION (1.92 rad ~110°) - the previous
+	* 2.5 rad exceeded human anatomical range.
 	*/
 	HIGH_PEAK: {
 		hip: [
-			2.5,
+			1.92,
 			0,
 			0
 		],
@@ -1156,23 +1189,26 @@ var KICK_PHASES = {
 			0
 		],
 		ankle: [
-			.6,
+			.42,
 			0,
 			0
 		],
 		supportKnee: [
-			-.35,
+			-.45,
 			0,
 			0
 		],
 		pelvis: [
-			-.25,
+			-.32,
 			0,
 			0
 		]
 	},
 	/**
 	* Roundhouse Chamber (돌려차기준비) - Hip rotated out
+	*
+	* Strong support-foot pivot (pelvisY=-0.78) for authentic Korean
+	* dollyeochagi (돌려차기) hip-driven power generation.
 	*/
 	ROUNDHOUSE_CHAMBER: {
 		hip: [
@@ -1181,15 +1217,17 @@ var KICK_PHASES = {
 			.8
 		],
 		knee: [
-			-1.5,
+			-1.7,
 			0,
 			0
 		],
-		pelvisY: -.5,
-		spineY: .3
+		pelvisY: -.78,
+		spineY: .4
 	},
 	/**
 	* Side Kick Lateral (옆차기) - Turned sideways
+	*
+	* Body fully bladed: pelvis 90°, spine counter-rotated for foot-edge strike.
 	*/
 	SIDE_CHAMBER: {
 		hip: [
@@ -1198,12 +1236,12 @@ var KICK_PHASES = {
 			.3
 		],
 		knee: [
-			-1.6,
+			-1.7,
 			0,
 			0
 		],
 		pelvisY: -1.57,
-		spineY: -1.2,
+		spineY: -1,
 		spineLean: .2
 	}
 };
@@ -1213,7 +1251,7 @@ var KICK_PHASES = {
 *
 * Based on traditional Korean martial arts principles:
 * - 정권지르기 (Jeongkwon Jireugi) - Straight punch with fist rotation
-* - 역권지르기 (Yeokwon Jireugi) - Reverse punch with full hip drive
+* - 역권지르기 (Yeokkwon Jireugi) - Reverse punch with full hip drive
 * - 당기기 (Dangigi) - Pulling hand (hikite) for power generation
 * - 엉덩이회전 (Eongdeongi Hoejeon) - Hip rotation for maximum power
 * - 어깨비틀기 (Eokkae Biteulgi) - Shoulder torque coordination
@@ -1240,7 +1278,7 @@ var PUNCH_PHASES = {
 		elbow: [
 			0,
 			0,
-			-1.57
+			-1.65
 		],
 		wrist: [
 			0,
@@ -1248,46 +1286,49 @@ var PUNCH_PHASES = {
 			0
 		],
 		oppositeShoulder: [
-			-.1,
+			-.5,
 			0,
-			.2
+			.3
 		],
 		oppositeElbow: [
 			0,
 			0,
-			1.4
+			1.6
 		],
-		spineY: -.1,
-		pelvisY: -.1
+		spineY: -.2,
+		pelvisY: -.25
 	},
 	/**
 	* Wind-up (준비강화) - Brief additional coil before strike
 	*
 	* Minimal wind-up for fast punches like jab.
 	* More pronounced for power punches like cross.
+	*
+	* Elbow z is NEGATIVE in LEFT-arm convention (= flexion). Previous value
+	* of +1.8 was a sign bug that would over-extend the elbow at windup.
 	*/
 	WINDUP: {
 		shoulder: [
-			.3,
+			-.1,
 			0,
 			-.3
 		],
 		elbow: [
 			0,
 			0,
-			1.8
+			-1.75
 		],
-		spineY: -.15,
-		pelvisY: -.1
+		spineY: -.28,
+		pelvisY: -.22
 	},
 	/**
 	* Extension with Hip Drive (지르기) - Full extension with body rotation
 	*
 	* Korean martial arts extension mechanics:
 	* - Fist rotates from vertical to pronated (palm-down)
-	* - Hip drives forward and rotates (엉덩이회전)
+	* - Hip drives forward and rotates (엉덩이회전) ~25-30°
 	* - Shoulder rotates with punch (어깨비틀기)
-	* - Opposite arm pulls back to hip (당기기/hikite)
+	* - Opposite arm pulls back fully to hip (당기기/hikite)
 	* - Elbow nearly straight at impact (~170-175°)
 	*/
 	EXTENSION: {
@@ -1304,20 +1345,20 @@ var PUNCH_PHASES = {
 		wrist: [
 			0,
 			0,
-			.2
+			.4
 		],
 		oppositeShoulder: [
 			-.2,
 			0,
-			-.3
+			-.35
 		],
 		oppositeElbow: [
 			0,
 			0,
-			1.1
+			1.55
 		],
-		spineY: .4,
-		pelvisY: .25
+		spineY: .48,
+		pelvisY: .45
 	},
 	/**
 	* Peak Impact (정점) - Maximum extension and rotation
@@ -1340,20 +1381,20 @@ var PUNCH_PHASES = {
 		wrist: [
 			0,
 			0,
-			.2
+			.45
 		],
 		oppositeShoulder: [
 			-.2,
 			0,
-			-.3
+			-.35
 		],
 		oppositeElbow: [
 			0,
 			0,
-			1.1
+			1.55
 		],
-		spineY: .45,
-		pelvisY: .3
+		spineY: .52,
+		pelvisY: .49
 	}
 };
 /**