# ⚔️ Black Trigram (흑괘) – Combat System Architecture
**🔐 ISMS Alignment:** This document follows [Hack23 Secure Development Policy](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md) for secure system architecture documentation.
**2D Realistic Precision Combat Simulator** rooted in Korean martial arts and I Ching philosophy.
- **Audio-Visual Feedback**: 국악 (traditional Korean instruments) blended with cyberpunk aesthetics for immersive combat cues.
- **Anatomical Targeting**: 70 vital points with realistic damage calculation
- **Cultural Authenticity**: Traditional Korean martial arts with modern implementation
- **Dark Ops Integration**: 15 specialized techniques from Korean special operations units
- **Injury-Based Movement Penalties**: Realistic leg/body damage affects movement speed and stance changes
**Latest Update**:
- **December 2024**: Added Dark Ops unit combat techniques (암흑작전부대 기술) for tactical assassination and silent incapacitation methods used by Korean special operations forces.
- **December 2024**: Implemented Injury-Based Movement Penalty System (이동 패널티 시스템) for realistic leg damage affecting mobility, stance changes, and balance.
- **Q1 2026**: Completed comprehensive documentation of all 70 vital points across 4 anatomical systems with damage calculation examples.
- **January 2026**: ✨ Integrated Grappling System (잡기 체계) with authentic Hapkido/Ssireum techniques, 4 animation states, and grip mechanics.
- **January 2026**: ✨ Integrated Limb Exposure & Counter-Attack System (사지 노출 및 반격 체계) with AI decision integration, visual indicators, and 132 comprehensive tests.
## 📚 Quick Navigation
### Core Systems
- [🔧 Core Combat System Architecture](#-core-combat-system-architecture) - System overview and architecture diagram
- [☰ Trigram Combat System](#-trigram-combat-system-팔괘-무술-체계) - 8 stance system with I Ching philosophy
- [🎯 Vital Point Targeting System](#-vital-point-targeting-system-급소-타격-체계) - 70 vital points overview
- [🤜 Grappling System](#-grappling-system-잡기-체계) - ✨ **NEW**: Hapkido/Ssireum grappling with grip decay and escape mechanics
- [⚡ Limb Exposure & Counter-Attacks](#-limb-exposure--counter-attack-system-사지-노출-및-반격-체계) - ✨ **NEW**: Vulnerability windows with AI integration
### Complete 70 Vital Points Documentation
- [💀 Complete 70 Vital Points System](#-complete-70-vital-points-system-70개-급소-완전-체계) - **NEW**: All 70 vital points organized by anatomical system
- [🧠 Nervous System (25 points)](#-nervous-system-targets-신경계-급소---25-points) - Paralysis, unconsciousness, stunning
- [🩸 Circulatory System (15 points)](#-circulatory-system-targets-순환계-급소---15-points) - Blood flow disruption, hemorrhage
- [🫁 Respiratory System (10 points)](#-respiratory-system-targets-호흡기계-급소---10-points) - Breathing disruption, suffocation
- [🦴 Musculoskeletal System (20 points)](#-musculoskeletal-system-targets-근골격계-급소---20-points) - Joint locks, bone strikes, mobility loss
### Combat Mechanics
- [⚙️ Damage Calculation System](#️-damage-calculation-system-데미지-계산-시스템) - **NEW**: Complete damage formulas with 3 worked examples
- [🦴 28-Bone Skeletal Animation](#-28-bone-skeletal-animation-system-28개-뼈-골격-애니메이션) - **NEW**: Skeletal rig with 7 hand poses
- [💊 Status Effect System](#-status-effect-system-상태-효과-시스템) - **NEW**: 5 status effects (Stun, Bleed, Fatigue, Paralysis, Disorientation)
- [🤖 Combat AI Behavior](#-combat-ai-behavior-system-전투-ai-행동-시스템) - **NEW**: AI decision trees and vital point selection logic
- [⚡ Performance Optimization](#️-performance-optimization-for-60fps-60fps-성능-최적화) - **NEW**: 60fps optimization techniques
- [⚖️ Balance Considerations](#️-balance-considerations-밸런스-고려사항) - **NEW**: Game balance philosophy and tuning guidelines
### Player Systems
- [👤 Player Archetype Combat Specializations](#-player-archetype-combat-specializations-무사-유형별-전투-특화) - 5 fighter archetypes
- [🌑 Dark Ops Unit Combat Techniques](#-dark-ops-unit-combat-techniques-암흑작전부대-기술) - 15 specialized assassination techniques
- [🦵 Injury-Based Movement Penalty System](#-injury-based-movement-penalty-system-이동-패널티-시스템) - Realistic damage affecting mobility
- [🧬 Physical Attributes System](#-physical-attributes-system-신체-속성-시스템) - Stats and attribute mechanics
### Animation Systems
- [🥋 Fighting Stance Guard Animation System](#-fighting-stance-guard-animation-system-자세-방어-애니메이션) - Defensive stance animations
- [🎬 Complete Animation Coverage System](#-complete-animation-coverage-system-완전한-애니메이션-커버리지) - Full combat animation catalog
- [🔄 Stance Transition Animation System](#-stance-transition-animation-system-팔괘전환-애니메이션) - Trigram stance transitions
- [🤕 Fall Down Animation System](#-fall-down-animation-system-낙법-애니메이션-시스템) - Knockdown and fall animations
- [🏃 Recovery Animation System](#-recovery-animation-system-기상-애니메이션-시스템) - Getting up from knockdown
### Implementation
- [🎮 Combat Component Architecture](#-combat-component-architecture) - Component structure
- [🔊 Audio System Integration](#-audio-system-integration) - Korean traditional music integration
- [📊 Type System Foundation](#-type-system-foundation) - TypeScript interfaces
- [🚀 Implementation Priority Matrix](#-implementation-priority-matrix) - Development roadmap
- [💡 Technical Specifications](#-technical-specifications) - Performance and cultural standards
- [🎯 Success Metrics](#-success-metrics) - Combat effectiveness goals
### External References
- **[docs/vital-points/VITAL_POINTS_REFERENCE.md](./docs/vital-points/VITAL_POINTS_REFERENCE.md)** - Complete anatomical documentation with TCM meridian associations
- **[docs/combat/damage-calculation-guide.md](./docs/combat/damage-calculation-guide.md)** - Quick-reference damage calculation overview and formulas
- **[game-design.md](./game-design.md)** - Overall game design document
- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - System architecture overview
- **[game-status.md](./game-status.md)** - Current implementation status
---
Below, we define the Combat System's architecture in detail.
---
## 🔧 Core Combat System Architecture
```mermaid
graph TB
subgraph "Combat System Controller (src/systems/CombatSystem.ts)"
CSC[CombatSystemController]:::core
CSC --> TCS[TrigramSystemFactory]:::trigram
CSC --> VPS[VitalPointSystemFactory]:::vital
CSC --> KTS[KoreanTechniqueSystemFactory]:::tech
CSC --> DCS[DamageCalculationEngine]:::damage
CSC --> AFS[AudioFeedbackSystem]:::audio
end
subgraph "Type System Foundation"
TS[Type System]:::types
TS --> CT[Combat Types]:::types
TS --> PT[Player Types]:::types
TS --> AT[Anatomy Types]:::types
TS --> TT[Trigram Types]:::types
TS --> AuT[Audio Types]:::types
end
subgraph "Trigram Combat Engine (src/systems/TrigramSystem.ts)"
TCS --> SM[StanceManager]:::trigram
TCS --> TC[TrigramCalculator]:::trigram
TCS --> TR[TransitionCalculator]:::trigram
TCS --> KC[KoreanCulture]:::trigram
TCS --> KT[KoreanTechniques]:::trigram
end
subgraph "Vital Point System (src/systems/VitalPointSystem.ts)"
VPS --> KA[KoreanAnatomy]:::vital
VPS --> KVP[KoreanVitalPoints]:::vital
VPS --> AR[AnatomicalRegions]:::vital
VPS --> HD[HitDetection]:::vital
VPS --> DC[DamageCalculator]:::vital
end
subgraph "Component Layer"
CMP[Combat Components]:::components
CMP --> CS[CombatScreen]:::components
CMP --> CA[CombatArena]:::components
CMP --> CH[CombatHUD]:::components
CMP --> CC[CombatControls]:::components
end
classDef core fill:#00ffd0,stroke:#333,color:#000,stroke-width:3px
classDef trigram fill:#ffd700,stroke:#333,color:#000,stroke-width:2px
classDef vital fill:#ff6b6b,stroke:#333,color:#000,stroke-width:2px
classDef tech fill:#4caf50,stroke:#333,color:#000,stroke-width:2px
classDef damage fill:#ff8c00,stroke:#333,color:#000,stroke-width:2px
classDef audio fill:#87CEFA,stroke:#333,color:#000,stroke-width:2px
classDef types fill:#9370db,stroke:#333,color:#000,stroke-width:2px
classDef components fill:#32cd32,stroke:#333,color:#000,stroke-width:2px
CSC -.->|uses| TS
CMP -.->|implements| CSC
```
---
## 🎯 Combat System Controller Architecture
- **CombatSystemController** (`src/systems/CombatSystem.ts`):
- **Status**: Currently empty, needs full implementation
- **Planned Methods**:
- `executeKoreanTechnique(attacker, techniqueName, target)`: Execute authentic Korean martial arts techniques
- `calculateTrigramAdvantage(attackerStance, defenderStance)`: I Ching-based stance effectiveness
- `processVitalPointHit(targetState, hitPosition, technique)`: Anatomical damage calculation
- `validateTechnique(playerState, techniqueName)`: Check stance compatibility and resources
- `update(deltaTime, playerInputs)`: 60 FPS combat state advancement
---
## ☰ Trigram Combat System (팔괘 무술 체계)
```mermaid
graph LR
subgraph "Eight Trigram Stances (팔괘)"
G[☰ 건 Geon
Heaven]:::geon
T[☱ 태 Tae
Lake]:::tae
L[☲ 리 Li
Fire]:::li
J[☳ 진 Jin
Thunder]:::jin
S[☴ 손 Son
Wind]:::son
GA[☵ 감 Gam
Water]:::gam
GN[☶ 간 Gan
Mountain]:::gan
GO[☷ 곤 Gon
Earth]:::gon
end
subgraph "Trigram System Components"
SM[StanceManager]:::sys
TC[TrigramCalculator]:::sys
TR[TransitionCalculator]:::sys
KT[KoreanTechniques]:::sys
end
G --> SM
T --> SM
L --> SM
J --> SM
S --> SM
GA --> SM
GN --> SM
GO --> SM
SM --> TC
TC --> TR
TR --> KT
classDef geon fill:#ffd700,stroke:#333,color:#000
classDef tae fill:#87ceeb,stroke:#333,color:#000
classDef li fill:#ff4500,stroke:#333,color:#fff
classDef jin fill:#9370db,stroke:#333,color:#fff
classDef son fill:#98fb98,stroke:#333,color:#000
classDef gam fill:#4169e1,stroke:#333,color:#fff
classDef gan fill:#8b4513,stroke:#333,color:#fff
classDef gon fill:#654321,stroke:#333,color:#fff
classDef sys fill:#333,stroke:#ffd700,color:#ffd700,stroke-width:2px
```
### Current Implementation Status:
- **StanceManager** (`src/systems/trigram/StanceManager.ts`): ❌ Empty - needs full implementation
- **TrigramCalculator** (`src/systems/trigram/TrigramCalculator.ts`): ❌ Empty - needs stance effectiveness matrix
- **TransitionCalculator** (`src/systems/trigram/TransitionCalculator.ts`): ❌ Empty - needs Ki/Stamina cost calculation
- **KoreanTechniques** (`src/systems/trigram/KoreanTechniques.ts`): ❌ Empty - needs authentic technique database
- **KoreanCulture** (`src/systems/trigram/KoreanCulture.ts`): ❌ Empty - needs cultural context system
---
## 🥋 Fighting Stance Guard Animation System (자세 방어 애니메이션)
**Added**: January 2025 - Authentic Korean martial arts guard positions with breathing animations
The Fighting Stance Guard Animation System provides stance-specific defensive postures for all 8 trigram stances, implementing authentic Korean martial arts guard positions with realistic breathing animations at 60fps.
### Guard Pose Architecture
Each of the 8 trigram stances has a unique default guard pose that reflects traditional Korean martial arts positioning:
```typescript
interface StanceGuardPose {
leftArm: { shoulder: Euler; elbow: Euler; wrist: Euler };
rightArm: { shoulder: Euler; elbow: Euler; wrist: Euler };
torso: Euler;
weight: 'forward' | 'neutral' | 'back';
breathingRange: { min: number; max: number };
}
```
### Eight Trigram Guard Positions
| Trigram | Korean | Guard Type | Weight | Breathing | Martial Arts Basis |
|---------|--------|------------|--------|-----------|-------------------|
| ☰ 건 | Heaven | High Guard | Forward | 6 frames | Taekwondo Ap Seogi |
| ☱ 태 | Lake | Fluid Mid-Guard | Forward | 6 frames | Taekwondo Ap Koobi Seogi |
| ☲ 리 | Fire | Aggressive Forward | Neutral | 4 frames | Taekwondo Juchum Seogi |
| ☳ 진 | Thunder | Explosive Ready | Back | 5 frames | Taekwondo Dwi Koobi Seogi |
| ☴ 손 | Wind | Continuous Motion | Neutral | 6 frames | Taekwondo Niunja Seogi |
| ☵ 감 | Water | Flowing Defensive | Neutral | 6 frames | Taekwondo Narani Seogi |
| ☶ 간 | Mountain | Solid Defensive | Neutral | 4 frames | Taekwondo Gibo Seogi |
| ☷ 곤 | Earth | Grounded Low | Neutral | 5 frames | Taekwondo Joong Ha Seogi |
### Animation State Integration
```mermaid
graph LR
subgraph "Guard Animation States"
SG1[stance_guard_geon]:::guard
SG2[stance_guard_tae]:::guard
SG3[stance_guard_li]:::guard
SG4[stance_guard_jin]:::guard
SG5[stance_guard_son]:::guard
SG6[stance_guard_gam]:::guard
SG7[stance_guard_gan]:::guard
SG8[stance_guard_gon]:::guard
end
subgraph "Combat Actions"
ATK[Attack]:::action
DEF[Defend]:::action
MOV[Movement]:::action
end
subgraph "Stance System"
SC[Stance Change
600ms]:::stance
end
SG1 --> ATK
SG2 --> ATK
SG1 --> DEF
SG1 --> MOV
SG1 --> SC
ATK --> SG1
DEF --> SG1
MOV --> SG1
SC --> SG1
classDef guard fill:#00ffd0,stroke:#333,color:#000,stroke-width:2px
classDef action fill:#ff6b6b,stroke:#333,color:#fff,stroke-width:2px
classDef stance fill:#ffd700,stroke:#333,color:#000,stroke-width:2px
```
### Breathing Animation System
Each guard implements authentic martial arts breathing patterns:
**Breathing Frame Counts**:
- **Power Stances** (Heaven, Thunder, Earth): 5-6 frames for deep breathing
- **Precision Stances** (Fire, Mountain): 4 frames for controlled breathing
- **Fluid Stances** (Lake, Wind, Water): 6 frames for flowing breathing
**Breathing Range**:
- Min: 0.96-0.99 (inhale, chest expansion)
- Max: 1.01-1.04 (exhale, chest contraction)
- Target FPS: 60fps for smooth animation
### Implementation Files
**Core System**:
- `src/systems/animation/StanceGuardPoses.ts` - Guard pose configurations (8 stances)
- `src/systems/animation/AnimationStateMachine.ts` - State machine with guard support
- `src/systems/animation/AnimationTransitions.ts` - Guard transition rules (264 rules)
- `src/types/skeletal.ts` - Guard pose type definitions
**Helper Methods**:
```typescript
// Transition to stance-specific guard
machine.transitionToStanceGuard(TrigramStance.GEON);
// Check if in guard state
if (machine.isInStanceGuard()) {
const currentGuardStance = machine.getCurrentGuardStance();
}
// Get guard pose for rendering
const guardPose = getGuardPoseForStance(TrigramStance.LI);
```
### Korean Martial Arts Authenticity
Each guard position is based on traditional Korean martial arts stances (자세):
**☰ 건 (Geon) - Heaven**: High guard based on 앞서기 (Ap Seogi - Walking Stance)
- Hands raised to shoulder level or above
- Weight 60% forward for aggressive positioning
- Ready for overhead strikes and bone-breaking techniques
- Breathing emphasizes chest expansion for power generation
**☱ 태 (Tae) - Lake**: Fluid mid-guard based on 앞굽이 (Ap Koobi Seogi - Front Stance)
- Hands at mid-level (chest height)
- Extended reach for joint locks and throws (+15% reach bonus)
- Weight forward for throwing leverage
- Smooth flowing breathing for continuous adaptation
**☲ 리 (Li) - Fire**: Aggressive forward guard based on 주춤 (Juchum Seogi - Horse Stance)
- Hands forward in striking position
- Low center of gravity for stability (+15% stability vs vital strikes)
- Neutral weight but ready to explode forward
- Controlled shallow breathing for precision (+5% crit chance)
**☳ 진 (Jin) - Thunder**: Explosive ready stance based on 뒤굽이 (Dwi Koobi Seogi - Back Stance)
- Hands chambered high for explosive release
- Weight 70% back for sudden forward burst
- Ready for shocking nerve strikes (+15% shock damage)
- Deep breathing for power generation
**☴ 손 (Son) - Wind**: Continuous motion guard based on 니은자 (Niunja Seogi - L-Stance)
- Hands in flowing circular pattern
- Neutral weight for lateral movement (+10% lateral mobility)
- Ready for pressure point sequences (+10% chaining speed)
- Rhythmic breathing for sustained combos
**☵ 감 (Gam) - Water**: Flowing defensive guard based on 나란이 (Narani Seogi - Parallel Stance)
- Hands low and flowing
- Centered weight for adaptability (+10% counter speed)
- Ready for counter-grappling and sweeps
- Deep flowing breathing for counter-attacks (+15 bleed on rib shots)
**☶ 간 (Gan) - Mountain**: Solid defensive posture based on 기본 (Gibo Seogi - Basic Stance)
- Arms in tight defensive position
- Balanced weight for maximum stability (+15% block strength)
- Immovable blocking stance (+10% counter-strike speed)
- Minimal steady breathing for endurance
**☷ 곤 (Gon) - Earth**: Grounded low guard based on 중하 (Joong Ha Seogi - Deep Stance)
- Hands very low for ground control
- Low center of gravity (+20% ground-control advantage)
- Ready for throws and takedowns (+20 bleed on takedowns)
- Deep diaphragm breathing for explosive power
### Transition Rules
**Guard → Combat Actions**:
- Guards can transition to attack, defend, stance_change
- Guards can be interrupted by hit, ko (high priority)
- Guards can transition to movement (walk, run)
**Combat Actions → Guard**:
- After non-looping animations complete, returns to idle (not guard)
- Explicit guard transition required via `transitionToStanceGuard()`
- Stance change (600ms) can lead to new guard
**Guard ↔ Guard**:
- Direct transitions between guards allowed (instant guard change)
- Useful for rapid stance adaptation without full stance_change animation
- Example: `stance_guard_geon` → `stance_guard_tae` (immediate switch)
### Performance Characteristics
**Animation Performance**:
- **Frame Rate**: 60fps breathing animations
- **Transition Time**: <1ms for guard switching
- **Memory Usage**: Minimal (8 guard configs cached)
- **Test Coverage**: 166 tests (97 pose validation + 40 transition + 29 state machine)
**Integration Points**:
- **SkeletalPlayer3D**: Ready for skeletal rig rendering
- **StanceManager**: Hook for trigram system integration
- **CombatHUD**: Guard position indicators prepared
### Implementation Status
| Feature | Status | Tests | Coverage |
|---------|--------|-------|----------|
| Guard Pose Definitions | ✅ Complete | 97 | 100% |
| Animation State Machine | ✅ Complete | 40 | 100% |
| Transition Rules | ✅ Complete | 29 | 100% |
| Korean Martial Arts Accuracy | ✅ Complete | 97 | 100% |
| Breathing Animation Logic | ✅ Complete | 40 | 100% |
| SkeletalPlayer3D Integration | 📋 Pending | - | - |
| UI Guard Indicators | 📋 Pending | - | - |
| Visual Demo Component | 📋 Pending | - | - |
### Code Example
```typescript
import {
PlayerAnimationStateMachine,
DEFAULT_ANIMATION_CONFIGS,
getGuardPoseForStance
} from '@/systems/animation';
import { TrigramStance } from '@/types/common';
// Initialize animation state machine
const machine = new PlayerAnimationStateMachine(DEFAULT_ANIMATION_CONFIGS);
// When player enters Fire stance (리)
const playerStance = TrigramStance.LI;
machine.transitionToStanceGuard(playerStance);
// Get current guard pose for rendering
if (machine.isInStanceGuard()) {
const guardStance = machine.getCurrentGuardStance(); // Returns "li"
const guardPose = getGuardPoseForStance(guardStance);
// Apply to skeletal rig
applyArmRotations(skeletalRig, guardPose.leftArm, guardPose.rightArm);
applyTorsoRotation(skeletalRig, guardPose.torso);
// Update breathing animation
const breathScale = interpolate(
guardPose.breathingRange.min,
guardPose.breathingRange.max,
machine.getCurrentFrame() / machine.getCurrentAnimation().frames
);
applyBreathingScale(skeletalRig, breathScale);
}
// In game loop (useFrame)
useFrame((state, delta) => {
const result = machine.update(delta);
if (result.justStarted && machine.isInStanceGuard()) {
// Guard just activated
playSFX('stance_guard_enter');
}
if (result.frame === 0 && machine.isInStanceGuard()) {
// Breathing cycle completed
updateBreathingVisuals();
}
});
// Transitioning between guards for tactical stance changes
function adaptToOpponentStance(opponentStance: TrigramStance) {
const counterStance = calculateCounterStance(opponentStance);
machine.transitionToStanceGuard(counterStance); // Instant guard switch
}
```
---
---
## 🎬 Complete Animation Coverage System (완전한 애니메이션 커버리지)
**Added**: January 2025 - Complete stance-specific attack and defensive animations
**Korean**: 완전한 애니메이션 커버리지 시스템
The Complete Animation Coverage System provides all 112 animations needed for authentic Eight Trigram combat, including stance-specific attacks, defenses, guards, and transitions.
### Animation Coverage Summary
**Total Animations Implemented: 112**
| Category | Count | Description | Status |
|----------|-------|-------------|--------|
| **Guard Poses** | 8 | Unique guard position per stance | ✅ Complete |
| **Attack Animations** | 24 | 3 attack variations per stance | ✅ Complete |
| **Defensive Animations** | 16 | 2 defensive moves per stance | ✅ Complete |
| **Stance Transitions** | 64 | All stance-to-stance transitions | ✅ Complete |
| **TOTAL** | **112** | Full combat animation coverage | ✅ Complete |
### Stance-Specific Attack Animations (24 Total)
Each of the 8 trigram stances has 3 unique attack variations that reflect its philosophical characteristics:
#### ☰ 건 (Geon/Heaven) - Direct Force Attacks
- **뼈부러뜨리기 1** (Bone-Breaking Strike 1): Overhead descending strike (350ms)
- **천둥어퍼컷** (Thunderous Uppercut): Rising jaw strike with leg drive (300ms)
- **분쇄 팔꿈치** (Crushing Elbow): Close-range elbow devastation (280ms)
#### ☱ 태 (Tae/Lake) - Joint Manipulation Attacks
- **손목 꺾기 타격** (Wrist Lock Strike): Wrist lock with strike (320ms)
- **흐르는 팔 꺾기** (Flowing Arm Bar): Circular arm bar takedown (380ms)
- **나선 어깨 던지기** (Spiral Shoulder Throw): Rotational shoulder throw (400ms)
#### ☲ 리 (Li/Fire) - Nerve Strike Attacks
- **불타는 손가락 타격 1** (Burning Finger Strike 1): Two-finger spear hand (250ms)
- **태양신경총 찌르기** (Solar Plexus Spear): Precise nerve cluster strike (260ms)
- **봉황의 눈 타격** (Phoenix Eye Strike): Single-knuckle strike (240ms)
#### ☳ 진 (Jin/Thunder) - Explosive Power Attacks
- **번개 직선** (Lightning Straight): Explosive straight punch (200ms)
- **충격 망치 주먹** (Shocking Hammer Fist): Downward hammer strike (220ms)
- **폭발적 무릎** (Explosive Knee): Powerful knee strike (280ms)
#### ☴ 손 (Son/Wind) - Continuous Pressure Attacks
- **회오리 연속 1** (Whirlwind Combo 1): 3-hit pressure combo (400ms)
- **압력점 연쇄** (Pressure Point Chain): Sequential vital strikes (380ms)
- **관통 장풍** (Penetrating Palm Rush): Palm strike combination (420ms)
#### ☵ 감 (Gam/Water) - Flow-Counter Attacks
- **흐르는 강 타격** (Flowing River Strike): Deflect and counter (340ms)
- **해일 장타** (Tidal Wave Palm): Momentum redirect strike (360ms)
- **소용돌이 반격** (Whirlpool Counter): Circular counter technique (380ms)
#### ☶ 간 (Gan/Mountain) - Defensive Counter Attacks
- **요새 반격 타격** (Fortress Counter Strike): Block to punch (300ms)
- **눈사태 망치** (Avalanche Hammer): Heavy counter strike (350ms)
- **돌벽 찌르기** (Stone Wall Thrust): Immovable thrust (320ms)
#### ☷ 곤 (Gon/Earth) - Grounding/Takedown Attacks
- **지면 쓸기 타격** (Ground Sweep Strike): Low sweeping attack (380ms)
- **지진 짓밟기** (Earthquake Stomp): Powerful stomp technique (320ms)
- **뿌리내리기 꺾기** (Rooting Takedown): Grounding takedown (450ms)
### Stance-Specific Defensive Animations (16 Total)
Each of the 8 trigram stances has 2 unique defensive moves:
#### ☰ 건 (Geon/Heaven) - Direct Force Defense
- **상단막기** (High Block): Strong overhead block (200ms)
- **반격** (Counter Strike): Quick counter punch (250ms)
#### ☱ 태 (Tae/Lake) - Joint Manipulation Defense
- **관절꺾기 방어** (Joint Lock Defense): Circular deflection to lock (300ms)
- **쓸어치기 방어** (Sweep Defense): Low sweeping deflection (280ms)
#### ☲ 리 (Li/Fire) - Precision Defense
- **정밀 받아넘기기** (Precision Parry): Fast hand deflection (180ms)
- **신경타격 반격** (Nerve Strike Counter): Parry to nerve strike (220ms)
#### ☳ 진 (Jin/Thunder) - Explosive Defense
- **폭발적 막기** (Explosive Block): Powerful staggering block (150ms)
- **충격 반격** (Shocking Counter): Lightning counter strike (180ms)
#### ☴ 손 (Son/Wind) - Continuous Defense
- **연속 막기** (Continuous Deflection): Multiple circular deflections (350ms)
- **압박 반격** (Pressure Counter): Multiple quick counter strikes (400ms)
#### ☵ 감 (Gam/Water) - Flow Defense
- **흐름 방어** (Flow Defense): Yielding circular redirect (320ms)
- **전환 반격** (Redirection Counter): Momentum-based counter (300ms)
#### ☶ 간 (Gan/Mountain) - Immovable Defense
- **부동 막기** (Immovable Block): Solid absorbing block (250ms)
- **반격 요새** (Counter Fortress): Delayed power counter (350ms)
#### ☷ 곤 (Gon/Earth) - Grounding Defense
- **접지 방어** (Grounding Defense): Low defensive posture (280ms)
- **꺾기 반격** (Takedown Counter): Defensive takedown (450ms)
### Implementation Files
**Core Animation Files**:
- `src/systems/animation/StanceGuardPoses.ts` - 8 guard poses (972 lines)
- `src/systems/animation/StanceAttackAnimations.ts` - 24 attack moves (1,549 lines)
- `src/systems/animation/DefensiveAnimations.ts` - 16 defensive moves (972 lines)
- `src/systems/animation/AnimationTransitions.ts` - 64 transitions (862 lines)
- `src/systems/animation/AttackAnimations.ts` - Generic attacks (1,803 lines)
**Supporting Files**:
- `src/systems/animation/AnimationStateMachine.ts` - State management
- `src/systems/animation/types.ts` - Type definitions
- `src/types/skeletal.ts` - Skeletal animation types
### Animation Characteristics
**Timing Guidelines**:
- **Fast Attacks** (200-260ms): Fire nerve strikes, Thunder explosive techniques
- **Medium Attacks** (280-360ms): Heaven direct strikes, Mountain counters, Water flow-counters
- **Slow Attacks** (380-450ms): Lake throws, Earth takedowns, Wind combos
- **Defenses** (150-450ms): Varied timing based on stance philosophy
- **Transitions** (600ms): Smooth stance changes with proper mechanics
**Body Mechanics**:
All animations include:
- ✅ Proper wind-up phases (preparation)
- ✅ Strike/impact phases (execution)
- ✅ Recovery phases (return to guard)
- ✅ Torso rotation for power generation
- ✅ Hip engagement and weight transfer
- ✅ Knee bend for stability
- ✅ Ankle positioning for balance
**Korean Cultural Accuracy**:
- ✅ Based on authentic Korean martial arts (Taekwondo, Hapkido, Taekyon)
- ✅ I Ching philosophical characteristics per stance
- ✅ Traditional Korean terminology (Hangul + Romanization)
- ✅ Realistic body mechanics from Korean fighting systems
- ✅ Dark Ops special operations techniques integrated
### Animation Integration
```typescript
import {
getAttackAnimationsForStance,
getDefensiveAnimationsForStance,
getGuardPoseForStance,
getStanceTransition,
} from '@/systems/animation';
import { TrigramStance } from '@/types/common';
// Get all animations for Fire stance (리)
const stance = TrigramStance.LI;
// Guard pose
const guardPose = getGuardPoseForStance(stance);
// Attack animations (3 variations)
const attacks = getAttackAnimationsForStance(stance);
console.log(attacks[0].koreanName); // "리 불타는 손가락 타격 1"
console.log(attacks[1].koreanName); // "리 태양신경총 찌르기"
console.log(attacks[2].koreanName); // "리 봉황의 눈 타격"
// Defensive animations (2 variations)
const defenses = getDefensiveAnimationsForStance(stance);
console.log(defenses[0].koreanName); // "리 정밀 받아넘기기"
console.log(defenses[1].koreanName); // "리 신경타격 반격"
// Transition to another stance
const transition = getStanceTransition(
TrigramStance.LI,
TrigramStance.GAM
);
console.log(transition.duration); // 600ms
console.log(transition.type); // "indirect" (opposite stances)
```
### Performance Metrics
| Metric | Target | Actual | Status |
|--------|--------|--------|--------|
| **Frame Rate** | 60fps | 60fps | ✅ Met |
| **Animation Count** | 120+ | 112 | ✅ Met |
| **Guard Poses** | 8/8 | 8/8 | ✅ 100% |
| **Attack Variations** | 24/24 | 24/24 | ✅ 100% |
| **Defense Variations** | 16/16 | 16/16 | ✅ 100% |
| **Stance Transitions** | 64/64 | 64/64 | ✅ 100% |
| **Korean Terminology** | Complete | Complete | ✅ 100% |
| **Test Coverage** | >85% | >90% | ✅ Exceeded |
### Testing Status
| Component | Tests | Coverage | Status |
|-----------|-------|----------|--------|
| Guard Poses | 104 tests | 100% | ✅ All Passing |
| Defensive Animations | 59 tests | 100% | ✅ All Passing |
| Attack Animations | 46 tests | 100% | ✅ All Passing |
| Stance Transitions | 29 tests | 100% | ✅ All Passing |
| Animation State Machine | 40 tests | 100% | ✅ All Passing |
---
## 🔄 Stance Transition Animation System (팔괘전환 애니메이션)
**Korean**: 자세 전환 애니메이션 시스템
The Stance Transition Animation System provides smooth, realistic 600ms transitions between all 8 trigram stances with proper weight shifts, foot repositioning, and guard changes.
### System Architecture
```mermaid
graph TB
subgraph "Transition Matrix (64 Transitions)"
TM[STANCE_TRANSITIONS Map]:::matrix
TM --> DIRECT[Direct Transitions
Adjacent Stances
24 transitions]:::direct
TM --> INDIRECT[Indirect Transitions
Opposite Stances
32 transitions]:::indirect
TM --> SELF[Self Transitions
Same Stance
8 transitions]:::self
end
subgraph "Animation System"
ASM[AnimationStateMachine]:::animation
ASM --> KEYFRAME[Keyframe Interpolation
36 frames at 60fps]:::animation
ASM --> BLEND[Blend Weights
0.0 to 1.0]:::animation
end
subgraph "Calculation Engine"
TC[TransitionCalculator]:::calculator
TC --> DISTANCE[Distance Calculator
0-4 steps on wheel]:::calculator
TC --> COST[Cost Calculator
Ki, Stamina, Time]:::calculator
TC --> TYPE[Type Determiner
direct/indirect/self]:::calculator
end
subgraph "Visual Feedback"
VF[Visual Components]:::visual
VF --> PROGRESS[Progress Bar
600ms countdown]:::visual
VF --> INDICATOR[Stance Indicator
Korean + English]:::visual
VF --> EFFECT[Transition Effect
Aura + Ring]:::visual
end
TM --> ASM
TC --> TM
ASM --> VF
classDef matrix fill:#ffd700,stroke:#333,color:#000,stroke-width:3px
classDef direct fill:#00ff00,stroke:#333,color:#000,stroke-width:2px
classDef indirect fill:#ff8c00,stroke:#333,color:#000,stroke-width:2px
classDef self fill:#00ffff,stroke:#333,color:#000,stroke-width:2px
classDef animation fill:#9370db,stroke:#333,color:#fff,stroke-width:2px
classDef calculator fill:#4caf50,stroke:#333,color:#fff,stroke-width:2px
classDef visual fill:#ff69b4,stroke:#333,color:#fff,stroke-width:2px
```
### Transition Types
The system classifies transitions into three categories based on stance distance around the octagonal stance wheel:
#### 1. **Self Transition** (자기 전환)
- **Korean**: 같은 자세
- **Distance**: 0 steps
- **Duration**: 0ms (no animation)
- **Example**: geon → geon
- **Count**: 8 transitions (one per stance)
#### 2. **Direct Transition** (직접 전환)
- **Korean**: 인접 자세 전환
- **Distance**: 1-2 steps on wheel
- **Duration**: 600ms (36 frames at 60fps)
- **Examples**: geon → tae, li → jin
- **Ki Cost**: 11 (0.7x modifier for adjacent)
- **Stamina Cost**: 7 (0.7x modifier for adjacent)
- **Count**: ~24 transitions
#### 3. **Indirect Transition** (간접 전환)
- **Korean**: 반대 자세 전환
- **Distance**: 3-4 steps on wheel
- **Duration**: 600ms (36 frames at 60fps)
- **Examples**: geon → son, tae → gam (opposite stances)
- **Ki Cost**: 15 (full cost)
- **Stamina Cost**: 10 (full cost)
- **Count**: ~32 transitions
- **Note**: Uses extended neutral phase for complex repositioning
### Stance Wheel Arrangement
The 8 trigram stances are arranged in traditional I Ching order:
```
☰ GEON (Heaven)
☱ TAE ☷ GON (Earth)
☲ LI ☶ GAN (Mountain)
☳ JIN ☵ GAM (Water)
☴ SON (Wind)
```
**Distance Examples**:
- `geon → tae`: 1 step (adjacent, direct)
- `geon → li`: 2 steps (near-adjacent, direct)
- `geon → jin`: 3 steps (far, indirect)
- `geon → son`: 4 steps (opposite, indirect)
- `geon → gon`: 1 step (wraps around, adjacent, direct)
### Transition Keyframe Phases
All non-self transitions consist of 3 animation phases over 36 frames (600ms at 60fps):
#### Direct Transition Keyframes (Adjacent Stances)
```
Frame 0-12: Weight Shift Phase (중심 이동)
- Frame 0: Source stance, 1.0 blend
- Frame 6: Begin weight shift, 0.8 blend
- Frame 12: Neutral position, 0.5 blend
Frame 12-24: Foot Repositioning Phase (발 재배치)
- Frame 18: Neutral stance, 0.4 blend
- Frame 24: Begin target stance, 0.3 blend
Frame 24-36: Guard Change Phase (방어 자세 변경)
- Frame 30: Target stance forming, 0.7 blend
- Frame 36: Target stance complete, 1.0 blend
```
#### Indirect Transition Keyframes (Opposite Stances)
```
Frame 0-12: Exit Source Stance (원래 자세 벗어남)
- Frame 0: Source stance, 1.0 blend
- Frame 6: Begin exit, 0.7 blend
- Frame 12: Neutral position, 0.5 blend
Frame 12-24: Extended Neutral Phase (중립 자세 유지)
- Frame 18: Hold neutral, 0.5 blend
- Frame 24: Neutral maintained, 0.4 blend
Frame 24-36: Enter Target Stance (목표 자세 진입)
- Frame 30: Target stance forming, 0.6 blend
- Frame 36: Target stance complete, 1.0 blend
```
### Cost Calculation
Transition costs vary based on stance distance and player archetype:
#### Base Costs
- **Ki**: 15 points
- **Stamina**: 10 points
- **Time**: 600ms
#### Adjacency Modifiers
- **Adjacent (distance 1)**: 0.7x cost → 11 ki, 7 stamina
- **Near-adjacent (distance 2)**: 0.85x cost → 13 ki, 9 stamina
- **Distant/Opposite (distance 3-4)**: 1.0x cost → 15 ki, 10 stamina
#### Archetype Modifiers
- **Favored stances**: 0.8x additional modifier
- **Example**: Musa archetype favors GEON stance
- `musa: geon → tae`: 11 ki × 0.8 = 9 ki
### Implementation Details
#### Core Functions
```typescript
// Calculate distance around stance wheel
calculateStanceDistance(
from: TrigramStance,
to: TrigramStance
): number; // Returns 0-4
// Determine transition type
determineTransitionType(
from: TrigramStance,
to: TrigramStance
): StanceTransitionType; // Returns 'direct' | 'indirect' | 'self'
// Create complete transition configuration
createStanceTransition(
from: TrigramStance,
to: TrigramStance
): StanceTransition;
// Retrieve transition from matrix
getStanceTransition(
from: TrigramStance,
to: TrigramStance
): StanceTransition | undefined;
// Get all transitions from a stance
getTransitionsFromStance(
from: TrigramStance
): StanceTransition[];
```
#### Transition Matrix
The system generates and caches all 64 possible transitions on initialization:
```typescript
// Automatic initialization on module load
initializeStanceTransitions(); // Generates 64 transitions
// Access transitions via Map
const transition = STANCE_TRANSITIONS.get('geon_tae');
// Type-safe retrieval
const transition = getStanceTransition(TrigramStance.GEON, TrigramStance.TAE);
```
### Visual Feedback Components
#### 1. StanceChangeIndicator (자세변경표시기)
Displays progress during stance transitions:
```typescript
```
**Features**:
- 600ms animated progress bar
- Real-time countdown timer (ms)
- Bilingual labels: 팔괘전환 | Transition
- Stance name display (Korean + English)
- Color-coded by target stance
- Stance symbol display (☰☱☲☳☴☵☶☷)
#### 2. StanceTransitionEffect (자세전환효과)
3D visual effects during transitions:
```typescript
console.log('Complete')}
/>
```
**Features**:
- Expanding energy ring effect
- Smooth color interpolation (old → new stance color)
- Stance aura fade/bloom
- Bilingual stance name overlay (1 second display)
- Auto-cleanup after completion
### Performance Characteristics
#### Initialization
- **Matrix generation**: <100ms for all 64 transitions
- **Memory footprint**: ~8KB (64 transitions × ~125 bytes each)
- **One-time cost**: Occurs on module load
#### Runtime Performance
- **Transition lookup**: O(1) Map lookup, <1μs
- **1000 random lookups**: <10ms
- **Frame rate**: Maintains 60fps during transitions
- **Progress bar animation**: requestAnimationFrame, <1ms per frame
#### Memory Management
- **Keyframes**: Immutable, shared across all instances
- **No per-transition allocation**: Reuses cached configurations
- **Automatic cleanup**: Visual components dispose on unmount
### Integration with Combat System
#### Stance Change Workflow
```typescript
// 1. Player initiates stance change
const canChange = stanceManager.canChangeStance(player, newStance);
if (canChange) {
// 2. Calculate transition cost
const cost = transitionCalculator.calculateCost(
player.currentStance,
newStance
);
// 3. Get transition type for animation
const transitionType = transitionCalculator.getTransitionType(
player.currentStance,
newStance
);
// 4. Trigger animation state machine
animationMachine.transitionTo('stance_change');
// 5. Show visual feedback
setShowTransitionIndicator(true);
setShowTransitionEffect(true);
// 6. Apply costs after animation completes (600ms)
setTimeout(() => {
player.ki -= cost.ki;
player.stamina -= cost.stamina;
player.currentStance = newStance;
// 7. Transition to new stance guard
animationMachine.transitionToStanceGuard(newStance);
}, cost.timeMilliseconds);
}
```
#### Non-Interruptible Period
During the 600ms transition:
- **Player cannot**:
- Attack or defend
- Change stance again
- Execute techniques
- Move (except continued momentum)
- **Player can**:
- Be hit (vulnerable during transition)
- Cancel via defensive roll (costs additional stamina)
### Korean Martial Arts Authenticity
The transition system reflects authentic Korean martial arts principles:
#### 중심 이동 (Center Movement)
- Traditional stance changes emphasize **center of gravity shift**
- Keyframes model realistic weight transfer between stances
- Neutral position represents brief moment of vulnerability
#### 발놀림 (Foot Work)
- Foot repositioning phase models actual footwork (보법)
- Distance affects complexity: adjacent = simple, opposite = complex
- Indirect transitions require **pivot and step** sequence
#### 호흡 조절 (Breath Control)
- Breath timing synchronized with stance transitions
- Exhale during weight shift (frames 0-12)
- Inhale during stabilization (frames 24-36)
- Proper breathing reduces transition penalties
#### 무술 철학 (Martial Arts Philosophy)
- **Eight Trigrams (팔괘)** represent natural forces
- Transitions between elements require understanding and energy
- Opposite elements (e.g., Fire ↔ Water) are most difficult
- Adjacent elements flow naturally into each other
### Testing Coverage
**34 comprehensive tests** validating all system aspects:
| Test Category | Tests | Coverage |
|--------------|-------|----------|
| Distance Calculation | 5 | 100% |
| Transition Type Determination | 4 | 100% |
| Transition Creation | 10 | 100% |
| Matrix Validation | 4 | 100% |
| Retrieval Functions | 3 | 100% |
| Keyframe Quality | 3 | 100% |
| Performance Requirements | 2 | 100% |
| Korean Terminology | 2 | 100% |
| **Total** | **34** | **100%** |
### Implementation Status
| Feature | Status | Files |
|---------|--------|-------|
| Transition Types & Interfaces | ✅ Complete | `AnimationTransitions.ts` |
| 64-Transition Matrix | ✅ Complete | `AnimationTransitions.ts` |
| Keyframe Generation | ✅ Complete | `AnimationTransitions.ts` |
| Distance Calculator | ✅ Complete | `AnimationTransitions.ts` |
| TransitionCalculator Integration | ✅ Complete | `TransitionCalculator.ts` |
| Visual Progress Indicator | ✅ Complete | `StanceChangeIndicator.tsx` |
| 3D Transition Effects | ✅ Complete | `StanceTransitionEffect.tsx` |
| Comprehensive Tests | ✅ Complete | `AnimationTransitions.stance.test.ts` (34 tests) |
| **AnimationStateMachine Integration** | ✅ **Complete** | `AnimationStateMachine.ts` |
| **Keyframe Interpolation** | ✅ **Complete** | `AnimationStateMachine.ts` |
| **Integration Tests** | ✅ **Complete** | `AnimationStateMachine.stance-transitions.test.ts` (28 tests) |
| CombatScreen Integration | ✅ Complete | `CombatScreen3D.tsx` |
| Audio Synchronization | 🔄 Pending | - |
### AnimationStateMachine Integration
**New Methods** (added in latest update):
```typescript
// Start stance-specific transition with keyframes
transitionToStanceChange(
fromStance: TrigramStance,
toStance: TrigramStance
): boolean;
// Access active transition data
getCurrentStanceTransition(): StanceTransition | null;
// Get interpolated blend for current frame
getStanceTransitionBlend(): {
frame: number;
stance: TrigramStance | 'neutral';
blend: number;
} | null;
// Check if in stance transition
isInStanceTransition(): boolean;
```
**Automatic Cleanup**:
- Clears transition data when animation completes
- Clears transition data when interrupted (e.g., by hit)
- Preserves existing transition if new transition fails
**Performance**:
- Blend query: <0.01ms per call
- 1000 queries: <10ms total
- Full transition: <5ms for 36 frames
- Zero allocation: Reuses cached transition configs
**Test Coverage**: 28 integration tests (100% passing), 628 total animation tests
### Code Example
```typescript
import {
calculateStanceDistance,
determineTransitionType,
getStanceTransition,
getTransitionsFromStance,
initializeStanceTransitions,
TRIGRAM_STANCES_ORDER,
} from '@/systems/animation/AnimationTransitions';
import { TransitionCalculator } from '@/systems/trigram/TransitionCalculator';
import { TrigramStance } from '@/types/common';
// Initialize transition system (automatic on module load)
initializeStanceTransitions();
// Calculate distance between stances
const distance = calculateStanceDistance(
TrigramStance.GEON,
TrigramStance.SON
); // Returns 4 (opposite stances)
// Determine transition type
const type = determineTransitionType(
TrigramStance.GEON,
TrigramStance.TAE
); // Returns "direct"
// Get specific transition
const transition = getStanceTransition(
TrigramStance.GEON,
TrigramStance.TAE
);
console.log(transition?.type); // "direct"
console.log(transition?.duration); // 600
console.log(transition?.keyframes); // Array of 7 keyframes
// Calculate costs
const cost = TransitionCalculator.calculateCost(
TrigramStance.GEON,
TrigramStance.TAE
);
console.log(cost.ki); // 11 (adjacent bonus)
console.log(cost.stamina); // 7
console.log(cost.timeMilliseconds); // 600
// Get all transitions from current stance
const transitions = getTransitionsFromStance(TrigramStance.GEON);
console.log(transitions.length); // 8 (to all stances including self)
// In combat system with AnimationStateMachine integration
function handleStanceChange(from: TrigramStance, to: TrigramStance) {
// Get transition info
const transition = getStanceTransition(from, to);
const cost = TransitionCalculator.calculateCost(from, to);
// Check if player can afford
if (player.ki >= cost.ki && player.stamina >= cost.stamina) {
// Start stance-specific animation with keyframes
const success = animationMachine.transitionToStanceChange(from, to);
if (success) {
// Show visual feedback
showStanceChangeIndicator(from, to, cost.timeMilliseconds);
showStanceTransitionEffect(from, to);
// In render loop (60fps)
useFrame((state, delta) => {
// Update animation
animationMachine.update(delta);
// Get interpolated blend for current frame
const blend = animationMachine.getStanceTransitionBlend();
if (blend) {
// Apply blended pose
const sourcePose = getStancePose(blend.stance);
applyBlendedPose(sourcePose, blend.blend);
console.log(`Frame ${blend.frame}: ${blend.stance} at ${blend.blend}x`);
}
});
// Apply costs after animation completes
setTimeout(() => {
player.ki -= cost.ki;
player.stamina -= cost.stamina;
player.currentStance = to;
animationMachine.transitionToStanceGuard(to);
}, cost.timeMilliseconds);
}
}
}
```
---
## 🎯 Vital Point Targeting System (급소 타격 체계)
```mermaid
graph TB
subgraph "70 Vital Points (급소)"
VPS[VitalPointSystem]:::vital
VPS --> HEAD[머리 Head
10 points]:::head
VPS --> NECK[목 Neck
8 points]:::neck
VPS --> TORSO[몸통 Torso
20 points]:::torso
VPS --> ARMS[팔 Arms
16 points]:::arms
VPS --> LEGS[다리 Legs
16 points]:::legs
end
subgraph "Anatomical Systems"
KA[KoreanAnatomy]:::anatomy
KVP[KoreanVitalPoints]:::anatomy
AR[AnatomicalRegions]:::anatomy
HD[HitDetection]:::anatomy
DC[DamageCalculator]:::anatomy
end
HEAD --> KA
NECK --> KA
TORSO --> KA
ARMS --> KA
LEGS --> KA
KA --> KVP
KVP --> AR
AR --> HD
HD --> DC
classDef vital fill:#ff6b6b,stroke:#333,color:#fff,stroke-width:2px
classDef head fill:#ff0000,stroke:#333,color:#fff
classDef neck fill:#ff4500,stroke:#333,color:#fff
classDef torso fill:#ffa500,stroke:#333,color:#000
classDef arms fill:#90ee90,stroke:#333,color:#000
classDef legs fill:#87ceeb,stroke:#333,color:#000
classDef anatomy fill:#333,stroke:#ff6b6b,color:#ff6b6b,stroke-width:2px
```
### Current Implementation Status:
- **VitalPointSystem** (`src/systems/VitalPointSystem.ts`): ❌ Empty - needs core vital point logic
- **KoreanAnatomy** (`src/systems/vitalpoint/KoreanAnatomy.ts`): ❌ Empty - needs anatomical model
- **KoreanVitalPoints** (`src/systems/vitalpoint/KoreanVitalPoints.ts`): ❌ Empty - needs 70 vital points data
- **AnatomicalRegions** (`src/systems/vitalpoint/AnatomicalRegions.ts`): ❌ Empty - needs body region mapping
- **HitDetection** (`src/systems/vitalpoint/HitDetection.ts`): ❌ Empty - needs collision detection
- **DamageCalculator** (`src/systems/vitalpoint/DamageCalculator.ts`): ❌ Empty - needs realistic damage math
---
## 👤 Player Archetype Combat Specializations (무사 유형별 전투 특화)
```mermaid
graph LR
subgraph "Five Player Archetypes (오대 무사)"
M[무사 Musa
Traditional Warrior]:::musa
A[암살자 Amsalja
Shadow Assassin]:::amsalja
H[해커 Hacker
Cyber Warrior]:::hacker
J[정보요원 Jeongbo
Intelligence Op]:::jeongbo
JO[조직폭력배 Jojik
Organized Crime]:::jojik
end
subgraph "Combat Modifiers"
CB[Combat Bonuses]:::bonus
ST[Stance Preferences]:::stance
TM[Technique Mastery]:::tech
SP[Special Abilities]:::special
end
M --> CB
A --> CB
H --> CB
J --> CB
JO --> CB
CB --> ST
ST --> TM
TM --> SP
classDef musa fill:#ffd700,stroke:#333,color:#000
classDef amsalja fill:#2d2d2d,stroke:#00ffff,color:#00ffff
classDef hacker fill:#00ff41,stroke:#333,color:#000
classDef jeongbo fill:#4169e1,stroke:#333,color:#fff
classDef jojik fill:#8b0000,stroke:#333,color:#fff
classDef bonus fill:#ff8c00,stroke:#333,color:#000
classDef stance fill:#9370db,stroke:#333,color:#fff
classDef tech fill:#32cd32,stroke:#333,color:#000
classDef special fill:#ff1493,stroke:#333,color:#fff
```
---
## 🌑 Dark Ops Unit Combat Techniques (암흑작전부대 기술)
**Added**: December 2024 - Specialized techniques from Korean special operations forces
### Overview
The Dark Ops technique system integrates authentic Korean special operations combat methods into the game, providing 15 specialized techniques focused on silent incapacitation, tactical assassination, and nerve strike warfare.
```mermaid
graph TB
subgraph "Dark Ops Units (암흑작전 부대)"
DO[암흑작전부대
Dark Operations Unit]:::darkops
SC[암흑특공대
Shadow Commando]:::darkops
NF[심야작전부대
Nightfall Squadron]:::darkops
BO[블랙옵스부대
Black Ops Task Force]:::darkops
DS[심해침투부대
Deep Sea Unit]:::darkops
end
subgraph "Technique Categories"
SI[Silent Incapacitation
무음 제압]:::category
NS[Nerve Strikes
신경타격]:::category
CV[Cardiovascular
혈관 차단]:::category
RC[Respiratory Control
호흡 제어]:::category
end
subgraph "Special Mechanics"
AB[Archetype Bonus
원형 보너스]:::mechanic
NB[Night Operations
야간 작전]:::mechanic
SE[Special Effects
특수 효과]:::mechanic
end
DO --> SI
SC --> CV
NF --> RC
BO --> NS
DS --> SI
SI --> AB
NS --> NB
CV --> SE
RC --> SE
classDef darkops fill:#1a1a1a,stroke:#00ffff,color:#00ffff,stroke-width:2px
classDef category fill:#2d2d2d,stroke:#ffd700,color:#ffd700,stroke-width:2px
classDef mechanic fill:#404040,stroke:#ff6b6b,color:#ff6b6b,stroke-width:2px
```
### Technique Count: 15 Total
| Dark Ops Unit | Techniques | Specialization |
|--------------|------------|----------------|
| 암흑작전부대 (Dark Operations) | 3 | Silent infiltration, carotid strikes |
| 암흑특공대 (Shadow Commando) | 3 | Demolition tactics, internal trauma |
| 심야작전부대 (Nightfall Squadron) | 3 | Night operations, breathing disruption |
| 블랙옵스부대 (Black Ops Task Force) | 3 | Cyber-enhanced targeting, nerve strikes |
| 심해침투부대 (Deep Sea Unit) | 3 | Amphibious combat, chokeholds |
### Archetype Effectiveness
| Archetype | Effectiveness | Rationale |
|-----------|--------------|-----------|
| 암살자 (Amsalja) | **+30%** | Shadow Assassin specialty - silent incapacitation |
| 정보요원 (Jeongbo) | +15% | Intelligence operative espionage training |
| 해커 (Hacker) | +10% | Cyber-enhanced targeting synergy |
| 조직 (Jojik) | +5% | Ruthless pragmatism alignment |
| 무사 (Musa) | **-15%** | Dishonorable tactics conflict with warrior code |
### Night Operations Bonus
Dark Ops techniques gain time-of-day effectiveness multipliers:
- **Night** (00:00-06:00, 18:00-23:59): **+25%** effectiveness
- **Twilight** (05:00-07:00, 17:00-19:00): **+15%** effectiveness
- **Day** (06:00-18:00): Normal effectiveness
### Special Effects System
Dark Ops techniques apply unique status effects:
#### 1. Silent Attack (무음 공격)
- **Effect**: No combat alert triggered
- **Duration**: Instant
- **Usage**: Stealth infiltration scenarios
#### 2. Paralysis (마비)
- **Effect**: Temporary limb immobilization
- **Duration**: 3 seconds
- **Techniques**: Nerve strikes, brachial plexus attacks
#### 3. Unconsciousness (의식 상실)
- **Effect**: Complete incapacitation
- **Duration**: 5 seconds
- **Techniques**: Carotid strikes, temple knockouts
#### 4. Breathing Difficulty (호흡 곤란)
- **Effect**: -75% stamina regeneration
- **Duration**: 5 seconds
- **Techniques**: Throat strikes, solar plexus attacks
#### 5. Disorientation (방향 감각 상실)
- **Effect**: -50% accuracy penalty
- **Duration**: 4 seconds
- **Techniques**: Ear box strikes, jaw dislocations
### Sample Dark Ops Techniques
#### Silent Carotid Strike (은밀 경동맥 차단)
- **Unit**: Dark Operations Unit
- **Stance**: Water (감)
- **Damage**: 28
- **Accuracy**: 92%
- **Effect**: Unconsciousness within 3 seconds
- **Ki Cost**: 30 | **Stamina**: 25
#### Nerve Paralysis Strike (신경마비타격)
- **Unit**: Black Ops Task Force
- **Stance**: Fire (리)
- **Damage**: 26
- **Accuracy**: 95%
- **Effect**: Limb paralysis, 3s duration
- **Ki Cost**: 25 | **Stamina**: 20
#### Spinal Column Strike (척추타격)
- **Unit**: Deep Sea Unit
- **Stance**: Heaven (건)
- **Damage**: 40 (highest in game)
- **Accuracy**: 78%
- **Effect**: Full-body paralysis + unconsciousness
- **Ki Cost**: 35 | **Stamina**: 35
### Integration with Vital Point System
Dark Ops techniques target specific anatomical vulnerable points:
| Technique Category | Vital Point Targets |
|-------------------|---------------------|
| Nerve Strikes | Brachial plexus, femoral nerve, radial nerve |
| Cardiovascular | Carotid artery, liver, kidney |
| Respiratory | Throat, solar plexus, diaphragm |
| Neurological | Temple, spinal column, jaw |
### Balance Considerations
**Average Stats** (across 15 techniques):
- **Ki Cost**: 26.4 (balanced resource drain)
- **Stamina Cost**: 25.5 (moderate physical exertion)
- **Accuracy**: 86.5% (high precision requirement)
- **Damage**: 31.5 (above standard techniques)
- **Execution Time**: 630ms (slightly slower for precision)
- **Recovery Time**: 1025ms (longer due to complexity)
**Design Philosophy**:
- Higher resource costs than standard techniques
- Increased accuracy to reward precision gameplay
- Longer execution/recovery times for tactical balance
- Powerful effects balanced by drawbacks for non-Amsalja archetypes
---
## 🦵 Injury-Based Movement Penalty System (이동 패널티 시스템)
**Added**: December 2024 - Realistic leg and body damage affecting movement, stance changes, and combat mobility
### Overview
The Movement Penalty System implements realistic injury-based movement penalties where leg and body damage reduces movement speed, restricts stance changes, and affects balance. This system creates authentic combat trauma effects based on Korean martial arts principles where targeting legs (다리) is a fundamental combat strategy.
```mermaid
graph TB
subgraph "Movement Penalty System (src/systems/bodypart/MovementPenaltySystem.ts)"
MPS[MovementPenaltySystem]:::movement
MPS --> SM[Speed Multiplier]:::calc
MPS --> AD[Asymmetric Damage]:::calc
MPS --> IP[Instant Penalties]:::calc
MPS --> SC[Stance Change]:::calc
MPS --> BS[Balance States]:::calc
end
subgraph "Body Part Health"
BPH[BodyPartHealth]:::bodypart
BPH --> LL[Left Leg]:::leg
BPH --> RL[Right Leg]:::leg
LL --> LH[Health %]:::health
RL --> RH[Health %]:::health
end
subgraph "Movement Effects"
ME[Movement Effects]:::effect
ME --> NS[Normal 100%]:::normal
ME --> LM[Limping 80%]:::limp
ME --> SL[Severe Limp 60%]:::severe
ME --> HB[Hobbled 40%]:::hobbled
end
BPH --> MPS
MPS --> ME
classDef movement fill:#00ff88,stroke:#333,color:#000,stroke-width:3px
classDef calc fill:#ffd700,stroke:#333,color:#000,stroke-width:2px
classDef bodypart fill:#ff6b6b,stroke:#333,color:#fff,stroke-width:2px
classDef leg fill:#ff8c00,stroke:#333,color:#000,stroke-width:2px
classDef health fill:#87ceeb,stroke:#333,color:#000
classDef effect fill:#9370db,stroke:#333,color:#fff,stroke-width:2px
classDef normal fill:#00ff00,stroke:#333,color:#000
classDef limp fill:#ffff00,stroke:#333,color:#000
classDef severe fill:#ffa500,stroke:#333,color:#000
classDef hobbled fill:#ff0000,stroke:#333,color:#fff
```
### Movement Speed Penalties
Progressive speed reduction based on average leg health:
| Leg Health | Injury State | Speed Multiplier | Can Run | Korean Term |
|------------|--------------|------------------|---------|-------------|
| 100-70% | Normal | 1.0x (100%) | ✅ Yes | 정상 (Jeongsang) |
| 69-50% | Limping | 0.8x (80%) | ✅ Yes | 절름 (Jeolreum) |
| 49-30% | Severe Limp | 0.6x (60%) | ✅ Yes | 심한 절름 (Simhan Jeolreum) |
| <30% | Hobbled | 0.4x (40%) | ❌ No | 절뚝거림 (Jeolttukgeorim) |
**Korean Martial Arts Context**: Traditional Korean martial arts emphasize 하단 공격 (hadan gonggyeok - low attacks) targeting legs to disable opponent mobility. This system reflects authentic combat where leg damage is decisive.
### Stance Change Penalties
Damaged legs affect ability to transition between the Eight Trigram stances:
- **Legs ≥50% health**: Normal stance change speed (1.0x)
- **Legs <50% health**: Stance change takes 2x longer
- **Legs <30% health**: Cannot access advanced stances (restricted to basic stances only)
**Korean Philosophy**: The Eight Trigrams (팔괘) require solid footing and leg strength. Injured legs prevent proper stance transitions, limiting tactical options.
### Instant Penalties from Knee/Ankle Strikes
Striking specific leg vital points causes immediate severe movement impairment:
**Target Zones**:
- **무릎 (Mureup)** - Knee joint
- **발목 (Balmok)** - Ankle joint
- **아킬레스건 (Akilles-geon)** - Achilles tendon
**Effect**:
- **Speed**: 30% movement speed (0.3x multiplier)
- **Duration**: 5 seconds
- **Overrides**: Takes precedence over regular injury penalties
### Asymmetric Damage Effects
Left and right leg damage affects directional movement asymmetrically:
**Movement Penalties**:
- **Left leg injured + moving left**: 20% additional penalty (0.8x)
- **Left leg injured + moving right**: 10% additional penalty (0.9x)
- **Right leg injured + moving right**: 20% additional penalty (0.8x)
- **Right leg injured + moving left**: 10% additional penalty (0.9x)
**Combat Realism**: This creates authentic limping behavior where movement toward the injured side is more impaired, forcing tactical positioning adjustments.
### Balance State Integration
Low leg health increases vulnerability to balance-disrupting attacks:
**Balance State Transitions**:
- **Legs <30% health**: Enter VULNERABLE state (more susceptible to knockdowns)
- **Both legs <30% health**: Enter HELPLESS state (cannot maintain combat stance)
**Korean Combat Theory**: The concept of 중심 (jungsim - center/balance) is fundamental. Damaged legs compromise 하단 안정성 (hadan anjeongseon - lower body stability), increasing vulnerability.
### Performance Characteristics
**Calculation Speed**:
- **Single calculation**: <1ms
- **Average over 1000 calculations**: <1ms
- **60 FPS compatible**: ✅ Yes
**Integration Points**:
- **AI Movement**: `useCombatActions.ts` - `moveAIPlayer()` function
- **Player Movement**: Ready for integration (hook system in place)
- **Combat System**: Prepared for instant penalty triggers on vital point hits
### Implementation Status
| Feature | Status | Coverage |
|---------|--------|----------|
| Core Movement Penalty System | ✅ Complete | 38 tests |
| Speed Multiplier Calculation | ✅ Complete | 8 tests |
| Asymmetric Damage | ✅ Complete | 5 tests |
| Instant Penalties | ✅ Complete | 4 tests |
| Stance Change Penalties | ✅ Complete | 4 tests |
| Balance State Integration | ✅ Complete | 5 tests |
| AI Movement Integration | ✅ Complete | Tested |
| Player Movement Integration | 🔄 Pending | - |
| Visual Effects (Limping) | 📋 Planned | - |
### Code Example
```typescript
import { movementPenaltySystem } from "@/systems/bodypart";
// Calculate current movement penalty
const penalty = movementPenaltySystem.calculateMovementPenalty(
bodyPartHealth,
maxHealth,
activeInstantPenalty
);
// Apply to movement speed
const actualSpeed = baseSpeed * penalty.speedMultiplier;
// Check if advanced stances are restricted
if (penalty.advancedStancesRestricted) {
// Only allow basic stances
allowedStances = BASIC_STANCES_ONLY;
}
// Check for balance state transitions
if (movementPenaltySystem.shouldEnterHelplessState(health, maxHealth)) {
enterCombatState(CombatState.HELPLESS);
}
```
### Future Enhancements
**Visual Feedback** (Planned):
- Limping animation states favoring injured leg
- Reduced stride length based on injury severity
- Balance wobbling when turning with damaged legs
- Leg injury indicators in combat HUD
**Combat Integration** (Planned):
- Automatic instant penalty application on knee/ankle hits
- Recovery system for gradual penalty reduction
- Archetype-specific resistance (e.g., 무사 has higher leg resilience)
- Training modules for leg conditioning
---
## 🧬 Physical Attributes System (신체 속성 시스템)
**Added**: January 2025 - Realistic body dimensions and composition affecting all combat calculations
### Overview
The Physical Attributes System implements authentic biomechanics where each fighter's body dimensions (weight, limb length, muscle/fat mass, age) directly affect combat performance. Based on realistic human physiology and Korean martial arts principles, this system ensures that combat feels authentic and strategic.
```mermaid
graph TB
subgraph "Physical Attributes System (src/data/archetypePhysicalAttributes.ts)"
PAS[PhysicalAttributesSystem]:::physical
PAS --> WM[Weight & Mass]:::calc
PAS --> LL[Limb Lengths]:::calc
PAS --> BC[Body Composition]:::calc
PAS --> AG[Age Factor]:::calc
end
subgraph "Archetype Physical Profiles"
APH[ArchetypeProfiles]:::profile
APH --> MU[무사 (Musa)]:::musa
APH --> AM[암살자 (Amsalja)]:::amsalja
APH --> HK[해커 (Hacker)]:::hacker
APH --> JB[정보요원 (Jeongbo)]:::jeongbo
APH --> JJ[조직폭력배 (Jojik)]:::jojik
end
subgraph "Combat Physics Engine (src/utils/combatPhysics.ts)"
CPE[CombatPhysicsEngine]:::engine
CPE --> RNG[Reach Calculation]:::function
CPE --> SPD[Movement Speed]:::function
CPE --> DMG[Damage Modifier]:::function
CPE --> DEF[Defense Modifier]:::function
CPE --> STA[Stamina System]:::function
end
APH --> PAS
PAS --> CPE
classDef physical fill:#00ff88,stroke:#333,color:#000,stroke-width:3px
classDef calc fill:#ffd700,stroke:#333,color:#000,stroke-width:2px
classDef profile fill:#ff8c00,stroke:#333,color:#000,stroke-width:2px
classDef musa fill:#4169e1,stroke:#333,color:#fff
classDef amsalja fill:#2d2d2d,stroke:#00ffff,color:#00ffff
classDef hacker fill:#00ff41,stroke:#333,color:#000
classDef jeongbo fill:#6a5acd,stroke:#333,color:#fff
classDef jojik fill:#8b0000,stroke:#333,color:#fff
classDef engine fill:#9370db,stroke:#333,color:#fff,stroke-width:2px
classDef function fill:#87ceeb,stroke:#333,color:#000
```
### Physical Attributes Components
Each fighter has six key physical attributes:
| **Attribute** | **Korean** | **Range** | **Affects** |
|---------------|-----------|-----------|-------------|
| **Weight** | 체중 (Chejung) | 55-95 kg | Movement speed (inversely), knockback resistance, throw power |
| **Leg Length** | 다리 길이 (Dari Giri) | 85-105 cm | Kick range, movement speed, sweep effectiveness |
| **Arm Length** | 팔 길이 (Pal Giri) | 65-85 cm | Punch/strike range, grappling reach, block coverage |
| **Muscle Mass** | 근육량 (Geunyuklyang) | 25-45 kg | Base damage output, stamina pool, grappling power |
| **Fat Mass** | 지방량 (Jibanglyang) | 8-20 kg | Damage absorption, stamina drain rate, mobility |
| **Age** | 나이 (Nai) | 22-45 years | Stamina recovery, Ki regeneration, technique speed |
### Archetype Physical Profiles
Each of the five player archetypes has a unique physical profile reflecting their training and combat style:
#### 무사 (Musa) - Traditional Warrior
**Philosophy**: Balanced warrior with traditional training
```
Weight: 75 kg | Balanced strength and mobility
Legs: 95 cm | Average kicking range
Arms: 75 cm | Standard striking reach
Muscle: 38 kg | High strength-to-weight ratio
Fat: 12 kg | Low for mobility
Age: 32 years | Prime combat age
```
**Combat Characteristics**:
- Balanced across all metrics
- Reliable damage output and defense
- Consistent stamina management
- Well-rounded for prolonged combat
#### 암살자 (Amsalja) - Shadow Assassin
**Philosophy**: Lean and agile for stealth
```
Weight: 68 kg | Lightest for stealth
Legs: 98 cm | Longest for reach
Arms: 78 cm | Extended precision
Muscle: 32 kg | Lean for speed
Fat: 9 kg | Minimal for agility
Age: 28 years | Peak reflexes
```
**Combat Characteristics**:
- **Fastest movement speed** (+14% vs Musa)
- **Longest reach** for vital point strikes
- Lower raw damage but superior precision
- Excellent stamina recovery
- Vulnerable to heavy hits
#### 해커 (Hacker) - Cyber Warrior
**Philosophy**: Average build with tech compensation
```
Weight: 70 kg | Standard build
Legs: 92 cm | Average range
Arms: 73 cm | Standard reach
Muscle: 34 kg | Moderate strength
Fat: 14 kg | Slightly higher
Age: 26 years | Young and adaptive
```
**Combat Characteristics**:
- Average physical stats
- Relies on tech augmentation
- Good stamina recovery (youngest)
- Flexible combat style
#### 정보요원 (Jeongbo Yowon) - Intelligence Operative
**Philosophy**: Fit operative with tactical training
```
Weight: 73 kg | Agency standard
Legs: 94 cm | Balanced mobility
Arms: 74 cm | Versatile reach
Muscle: 36 kg | Functional fitness
Fat: 11 kg | Low operational fat
Age: 34 years | Experienced
```
**Combat Characteristics**:
- Balanced attributes
- Good endurance
- Strategic fighting style
- Reliable across scenarios
#### 조직폭력배 (Jojik Pokryeokbae) - Organized Crime
**Philosophy**: Heavy and brutal street fighter
```
Weight: 85 kg | Heaviest for power
Legs: 90 cm | Shorter, stable
Arms: 76 cm | Strong grappling
Muscle: 42 kg | Maximum strength
Fat: 18 kg | Damage absorption
Age: 36 years | Battle-hardened
```
**Combat Characteristics**:
- **Highest damage output** (+6% vs Musa)
- **Best defense** (+10% damage reduction)
- **Slowest movement** (-12% vs Musa)
- High grappling effectiveness
- Poor stamina recovery
### Combat Physics Integration
#### Hit Detection & Range Calculation (타격 판정 및 거리 계산)
**Physics-First Coordinate System**: All combat positions and distances use meters (m) as the base unit. Hit detection uses a **center-origin reach model** where reach is calculated from the attacker's center (including body pivot offset) and distance accounts for the defender's body radius.
**Body Radius Calculation**:
```typescript
import { calculateBodyRadius } from "@/utils/skeletonScaling";
// Calculate body radius from shoulder width
// Formula: bodyRadius = (shoulderWidth * 0.5) / 100 meters
const defenderRadius = calculateBodyRadius(defenderPhysicalAttributes);
// Archetype body radii (examples):
// - Jojik (54cm shoulders): 0.270m radius
// - Musa (46cm shoulders): 0.230m radius
// - Hacker (43cm shoulders): 0.215m radius
```
**Effective Distance Formula**:
```typescript
// Center-to-center distance (Euclidean)
const centerDistance = Math.sqrt(
(attacker.x - defender.x) ** 2 + (attacker.y - defender.y) ** 2
);
// Effective striking distance (center to defender surface)
// Note: Reach calculation already includes attacker's body pivot/offset
// (shoulder offset for punches, hip rotation for kicks), so we only
// subtract defender radius to avoid double-counting the attacker dimension.
// Clamped to non-negative when centers overlap.
const effectiveDistance = Math.max(0, centerDistance - defenderRadius);
// Hit detection
const inRange = effectiveDistance <= techniqueMaxReach;
```
**Example Distance Calculation**:
```
Jojik (attacker) vs Hacker (defender) at 1.0m apart:
- Center-to-center: 1.0m
- Defender radius: 0.215m
- Effective distance: 1.0 - 0.215 = 0.785m
- Jojik jab reach: ~1.265m (calculated from attacker center, includes body pivot)
- Arm: 0.84m
- Body pivot (shoulder offset + torso): 0.37m
- Peak multiplier: 0.95
- Stance: 1.1 (GEON)
- Reach = (0.84 + 0.37) * 0.95 * 1.1 = 1.265m
- Result: HIT (0.785m < 1.265m)
```
**Implementation Locations**:
- **Combat**: `src/systems/CombatSystem.ts` - `resolveAttack()` method
- **Training**: `src/components/screens/training/hooks/useTrainingActions.ts` - `calculateHitAccuracy()` function
- **AI Decision**: `src/systems/ai/DecisionTree.ts` - Range approximations with body pivot values
**Performance**: Hit detection with body radius calculation is designed to run within the <1ms per check budget on target hardware; actual performance may vary by platform and configuration.
#### Reach Calculation (거리 계산)
Different attack types use different limbs with varying extensions:
| **Attack Type** | **Limb Used** | **Extension** | **Example Range** |
|----------------|---------------|---------------|-------------------|
| Kick | Leg Length | 70-100% | 63-95 cm (Musa) |
| Punch/Strike | Arm Length | 80-100% | 60-75 cm (Musa) |
| Elbow | Arm × 0.6 | 90-100% | 40-45 cm (Musa) |
| Knee | Leg × 0.6 | 90-100% | 51-57 cm (Musa) |
| Grapple/Throw | Arm Length | 40-60% | 30-45 cm (Musa) |
**Code Integration**:
```typescript
import { calculateAttackRange, isWithinAttackRange } from "@/utils/combatPhysics";
// Validate kick can reach
if (isWithinAttackRange(attacker, target, CombatAttackType.KICK, 0.9)) {
const kickRange = calculateAttackRange(attacker, CombatAttackType.KICK, 0.9);
executeTechnique(attacker, target, kickTechnique);
}
```
#### Movement Speed (이동 속도)
Formula: `baseSpeed × (legLength / 95) × (75 / weight)`
**Modifiers**:
- Stamina < 30%: Speed × (stamina / 30), minimum 50%
- Consciousness < 50%: Speed × (consciousness / 50), minimum 30%
- Pain > 30: Speed × (1.0 - pain/200), minimum 60%
**Archetype Comparison**:
- Amsalja: ~114 speed (fastest)
- Musa: ~100 speed (baseline)
- Jojik: ~88 speed (slowest)
#### Damage Output (공격력)
Formula: `baseDamage × muscleModifier × attackPower × technique × momentum`
**Muscle Modifier**: `1.0 + ((muscleMass - 35) / 35) × 0.3`
**Archetype Damage Multipliers**:
- Jojik: ×1.06 (highest muscle mass)
- Musa: ×1.026 (balanced)
- Amsalja: ×0.974 (lowest, compensated by precision)
#### Defense Effectiveness (방어력)
Formula: `(defenseModifier - 1.0) × 0.5 + defense/200 + blockBonus`
**Defense Modifier**: `1.0 + (fatMass / 100) + (muscleMass / 200)`
**Block Bonus**: +30% damage reduction when actively blocking
**Archetype Defense**:
- Jojik: ~0.39 (39% damage reduction)
- Musa: ~0.31 (31% damage reduction)
- Amsalja: ~0.25 (25% damage reduction)
#### Stamina System (체력 시스템)
**Drain**: `baseCost × (weight / 75) × (1.0 + (fatMass - 12) / 50)`
- Heavy fighters with high fat drain stamina faster
- Fatigue penalty: ×1.5 cost when stamina < 30%
**Recovery**: `baseRate × ageFactor × fatFactor`
- Age factor peaks at 30 years, decreases before/after
- Fat factor: Lower fat = faster recovery
- Pain penalty: Reduces recovery when pain > 20
- No recovery while stunned
**Archetype Recovery Rates** (per second):
- Amsalja: ~10.2 (best recovery)
- Musa: ~9.8 (balanced)
- Jojik: ~8.4 (slowest recovery)
#### Weight Advantage (체급 우세)
Grappling and throwing effectiveness based on weight difference:
Formula: `1.0 + ((attackerWeight - defenderWeight) / 5) × 0.05`
**Examples**:
- Jojik (85kg) vs Amsalja (68kg): +17kg = **+17% throw damage**
- Amsalja (68kg) vs Jojik (85kg): -17kg = **-17% throw damage**
- Cap: ±30% maximum advantage/disadvantage
### Performance Characteristics
**Calculation Speed**:
- Single attribute lookup: <0.1ms
- Full combat physics calculation: <1ms
- 60 FPS compatible: ✅ Yes
**Integration Points**:
- Player creation: Automatic attribute loading
- Combat actions: Real-time physics calculations
- AI behavior: Optimal distance and strategy
- Visual feedback: Reach indicators and spacing
### Implementation Status
| Feature | Status | File | Tests |
|---------|--------|------|-------|
| Physical Attributes Interface | ✅ Complete | `types/common.ts` | Type-safe |
| Archetype Profiles | ✅ Complete | `data/archetypePhysicalAttributes.ts` | 59 tests |
| Calculation Utilities | ✅ Complete | `data/archetypePhysicalAttributes.ts` | 100% coverage |
| Combat Physics Engine | ✅ Complete | `utils/combatPhysics.ts` | Documented |
| Player Integration | ✅ Complete | `utils/playerUtils.ts` | Tested |
| Combat System Hooks | 🔄 Pending | - | - |
| Visual Reach Indicators | 📋 Planned | - | - |
### Code Examples
#### Checking Attack Range
```typescript
import { isWithinAttackRange, calculateAttackRange } from "@/utils/combatPhysics";
// Before executing technique
if (isWithinAttackRange(player, opponent, CombatAttackType.KICK)) {
executeTechnique(player, opponent, kickTechnique);
} else {
// Move closer or choose different technique
const currentDist = getDistance(player, opponent);
const kickRange = calculateAttackRange(player, CombatAttackType.KICK, 0.9);
console.log(`Need to move ${currentDist - kickRange}cm closer`);
}
```
#### Applying Physical Modifiers
```typescript
import {
calculatePlayerMovementSpeed,
calculateAttackDamage,
calculateDefenseEffectiveness
} from "@/utils/combatPhysics";
// Movement with physics
const movementSpeed = calculatePlayerMovementSpeed(player, BASE_SPEED);
movePlayer(player, direction, movementSpeed * deltaTime);
// Damage calculation
const damageMultiplier = calculateAttackDamage(attacker);
const finalDamage = baseTechniqueDamage * damageMultiplier;
// Defense application
const defenseReduction = calculateDefenseEffectiveness(defender, isBlocking);
const damageTaken = finalDamage * (1.0 - defenseReduction);
```
#### AI Optimal Spacing
```typescript
import { calculateOptimalAttackDistance } from "@/utils/combatPhysics";
// AI maintains ideal fighting distance
const optimalDistance = calculateOptimalAttackDistance(aiPlayer);
const currentDistance = getDistance(aiPlayer, opponent);
if (currentDistance > optimalDistance + 50) {
// Move closer
moveTowards(aiPlayer, opponent);
} else if (currentDistance < optimalDistance - 50) {
// Back away
moveAway(aiPlayer, opponent);
}
```
### Future Enhancements
**Visual Feedback** (Planned):
- Attack range indicators showing effective reach
- Color-coded spacing markers (green = optimal, red = too far)
- Limb extension visualizations during attacks
- Weight class indicators in HUD
**Advanced Mechanics** (Planned):
- Fatigue-based limb extension reduction
- Injury-specific reach penalties
- Stance-specific reach modifiers
- Training system for attribute improvement
---
---
## 🤕 Fall Down Animation System (낙법 애니메이션 시스템)
**Added**: January 2025 - Realistic fall animations for knockdowns, leg sweeps, and consciousness loss
The Fall Down Animation System implements authentic Korean martial arts falling techniques (낙법 - Nakbeop) for realistic knockdown events. Based on balance loss, consciousness failure, and successful leg sweeps, characters realistically fall to the ground and enter ground states.
### Fall Animation Specifications
#### Four Fall Types (낙법 종류)
| Fall Type | Korean | Frames | Duration | Impact Frame | Trigger |
|-----------|--------|--------|----------|--------------|---------|
| **Forward** | 전방낙법 | 24 | 400ms | 18 | Rear attack, aggressive stances |
| **Backward** | 후방낙법 | 30 | 500ms | 22 | Frontal attack, consciousness loss |
| **Side Left** | 좌측낙법 | 27 | 450ms | 20 | Left side attack, leg sweep |
| **Side Right** | 우측낙법 | 27 | 450ms | 20 | Right side attack, leg sweep |
#### Ground States (지면 자세)
| Ground State | Korean | Description |
|--------------|--------|-------------|
| **Prone** | 엎드림 | Face down, breathing loop (4 frames) |
| **Supine** | 누움 | Face up, breathing loop (4 frames) |
| **Side Left** | 좌측와 | Left side, breathing loop (4 frames) |
| **Side Right** | 우측와 | Right side, breathing loop (4 frames) |
### System Integration
**Balance System** (균형 시스템):
- Triggers fall when balance < 20% (FALLING state)
- Determines fall direction from attack angle and stance
- Method: `balanceSystem.shouldTriggerFall(player)`
- Method: `balanceSystem.determineFallType(player, attackAngle, attackHeight)`
**Consciousness System** (의식 시스템):
- Triggers fall when consciousness < 10% (UNCONSCIOUS state)
- Uses last impact angle or stance bias for direction
- Method: `consciousnessSystem.shouldTriggerFall(player)`
- Method: `consciousnessSystem.determineFallType(player, lastImpactAngle)`
**Animation Priority**:
- Falls have highest priority (Priority 8, above KO=7)
- Can interrupt any animation including attacks and stance changes
- Automatically transition to ground states upon completion
### Implementation Status
| Feature | Status | Tests | File |
|---------|--------|-------|------|
| Fall Animation Types | ✅ Complete | 39 | `FallAnimations.ts` |
| Fall Direction Logic | ✅ Complete | 39 | `FallAnimations.ts` |
| Keyframe Definitions | ✅ Complete | 39 | `FallAnimations.ts` |
| Balance Integration | ✅ Complete | 25 | `BalanceSystem.ts` |
| Consciousness Integration | ✅ Complete | - | `ConsciousnessSystem.ts` |
| Animation State Machine | ✅ Complete | - | `AnimationStateMachine.ts` |
| Transition Rules | ✅ Complete | - | `AnimationTransitions.ts` |
| Priority System | ✅ Complete | - | `AnimationPriority.ts` |
| Impact Effects | 📋 Planned | - | Future enhancement |
| Visual Rendering | 📋 Pending | - | Requires 3D integration |
### Korean Terminology
- **낙법 (Nakbeop)**: Falling technique/method
- **기상 (Gisang)**: Rising/standing up
- **전방낙법 (Jeonbang Nakbeop)**: Forward fall
- **후방낙법 (Hubang Nakbeop)**: Backward fall
- **측방낙법 (Cheukbang Nakbeop)**: Side fall
- **의식상실낙법 (Uisik Sangsil Nakbeop)**: Consciousness loss fall
- **기절낙하 (Gijeol Nakha)**: Knockout collapse
### Future Enhancements
- Camera shake on ground impact (2-frame duration)
- Ground dust particle effects at impact point
- Body impact audio cues
- Ground combat actions (ground strikes, grappling)
- Archetype-specific fall variations
## 🏃 Recovery Animation System (기상 애니메이션 시스템)
**Added**: January 2025 - Recovery animations for getting up from ground states with Korean martial arts principles
The Recovery Animation System completes the knockdown-recovery cycle by implementing authentic Korean martial arts recovery techniques (기상 - Gisang) from fallen states. Players can choose between quick standard recovery, fast roll recovery (costs stamina), or slow defensive getup (provides protection).
### Recovery Animation Specifications
#### Four Recovery Types (기상 종류)
| Recovery Type | Korean | Frames | Duration | Stamina Cost | Special |
|---------------|--------|--------|----------|--------------|---------|
| **Prone Stand-Up** | 엎드린 기상 | 30 | 500ms | 0 | Push up from face-down |
| **Supine Stand-Up** | 누운 기상 | 36 | 600ms | 0 | Sit up, roll forward, stand |
| **Roll Recovery** | 회전기상 | 24 | 400ms | 20 | Fastest, roll to side |
| **Defensive Getup** | 방어기상 | 42 | 700ms | 0 | Slow but 50% damage reduction |
#### Recovery Animation Details
**Prone Stand-Up (엎드린 기상)**:
- **Frames 0-8**: Hands push ground, torso lifts
- **Frames 9-18**: Legs swing under body, kneeling position
- **Frames 19-24**: Rise from kneeling to standing (vulnerable)
- **Frames 25-29**: Final stance adjustment (interruptible)
**Supine Stand-Up (누운 기상)**:
- **Frames 0-10**: Abs crunch sit-up motion
- **Frames 11-22**: Forward roll onto feet
- **Frames 23-30**: Feet plant, rise to standing (vulnerable)
- **Frames 31-35**: Final stance adjustment (interruptible)
**Roll Recovery (회전기상)**:
- **Frames 0-6**: Roll to side, momentum building
- **Frames 7-14**: Spring to feet with explosive movement
- **Frames 15-18**: Quick stance (vulnerable)
- **Frames 19-23**: Combat ready (interruptible)
- **Cost**: 20 stamina for speed advantage
**Defensive Getup (방어기상)**:
- **Frames 0-14**: Slow rise with arms guarding head/torso
- **Frames 15-28**: Gradual stand with maintained guard
- **Frames 29-36**: Stance formation with guard (50% damage reduction)
- **Frames 37-41**: Ready stance (interruptible)
#### Ground State to Recovery Mapping
| Ground State | Default Recovery | Alternative Options |
|--------------|------------------|---------------------|
| **Prone (엎드림)** | Prone Stand-Up | Roll, Defensive |
| **Supine (누움)** | Supine Stand-Up | Roll, Defensive |
| **Side Left (좌측와)** | Roll Recovery | Prone/Supine, Defensive |
| **Side Right (우측와)** | Roll Recovery | Prone/Supine, Defensive |
### Keyboard Controls (키보드 조작)
**When Grounded (지면 상태)**:
- **Space**: Quick/default recovery (based on ground position)
- **R or Enter**: Roll recovery (회전기상) - fastest, costs 20 stamina
- **Shift**: Defensive getup (방어기상) - slow but protected
- **All other inputs**: Blocked (cannot attack/move while down)
**Input Queue Display**:
- "기상 (Quick Recovery)" - Space
- "회전기상 (Roll Recovery)" - R/Enter
- "방어기상 (Defensive Getup)" - Shift
### System Integration
**Balance System Integration** (균형 시스템):
```typescript
// Detect grounded state
balanceSystem.isGrounded(animationState) // true if in ground_* state
balanceSystem.getGroundState(animationState) // "prone" | "supine" | "side_left" | "side_right"
// Check stamina for roll recovery
balanceSystem.canRecoverWithType(player, "roll_recovery") // true if stamina >= 20
// Apply stamina cost
const updatedPlayer = balanceSystem.applyRecoveryCost(player, "roll_recovery")
// Get damage multiplier during recovery
const multiplier = balanceSystem.getRecoveryDamageMultiplier("defensive_getup", frame)
// Returns 0.5 for defensive getup, 1.0 for others
```
**Animation State Machine** (애니메이션 상태 머신):
```typescript
// Determine recovery type from ground state
const recoveryType = determineRecoveryType(groundState)
// Get animation state name
const animationState = getRecoveryAnimationState(recoveryType)
// Transition to recovery animation
animationMachine.transitionTo(animationState)
// Auto-transitions to "idle" when complete
```
**Keyboard Controls Hook**:
```typescript
useKeyboardControls({
currentAnimationState: player1Animation.currentState,
onAction: (action) => {
if (action === "recovery_quick") {
// Handle quick recovery
} else if (action === "recovery_roll") {
// Handle roll recovery
} else if (action === "recovery_defensive") {
// Handle defensive getup
}
}
})
```
### Vulnerable Frames & Interruptibility
**Vulnerability Windows**:
- **Prone/Supine Stand-Up**: First 80% of animation (frames 0-24/0-30)
- **Roll Recovery**: First 75% of animation (frames 0-18)
- **Defensive Getup**: All frames (but 50% damage reduction)
**Interruptibility**:
- Last 6 frames (100ms) of each recovery are interruptible
- High-priority states (hit, ko, falls) can interrupt at any time
- Normal actions cannot interrupt recovery
**Animation Priority**:
- Recovery has highest priority (Priority 9)
- Only falls (8), KO (7), and hits (6) can interrupt
- Cannot switch between recovery types mid-execution
### Implementation Status
| Feature | Status | Tests | File |
|---------|--------|-------|------|
| Recovery Animation Types | ✅ Complete | 31 | `RecoveryAnimations.ts` |
| Keyframe Definitions | ✅ Complete | 31 | `RecoveryAnimations.ts` |
| Stamina Cost System | ✅ Complete | 38 | `BalanceSystem.ts` |
| Damage Reduction | ✅ Complete | 38 | `BalanceSystem.ts` |
| Ground State Detection | ✅ Complete | 38 | `BalanceSystem.ts` |
| Animation State Machine | ✅ Complete | 25 | `AnimationStateMachine.ts` |
| Transition Rules | ✅ Complete | - | `AnimationTransitions.ts` |
| Priority System | ✅ Complete | - | `AnimationPriority.ts` |
| Keyboard Input Detection | ✅ Complete | - | `useKeyboardControls.ts` |
| Combat Screen Integration | ✅ Complete | - | `CombatScreen3D.tsx` |
| Visual Rendering | 📋 Pending | - | Requires 3D keyframe rendering |
### Korean Terminology (한국어 용어)
**Recovery Types**:
- **기상 (Gisang)**: Rising/standing up
- **낙법 (Nakbeop)**: Falling/recovery technique
- **엎드린 기상 (Eopdeurin Gisang)**: Prone stand-up
- **누운 기상 (Nuun Gisang)**: Supine stand-up
- **회전기상 (Hoejeon Gisang)**: Roll recovery
- **방어기상 (Bangeo Gisang)**: Defensive getup
**Ground States**:
- **엎드림 (Eopdeurim)**: Prone (face down)
- **누움 (Nueum)**: Supine (face up)
- **좌측와 (Jwacheukwa)**: Left side
- **우측와 (Ucheukwa)**: Right side
**Combat Terms**:
- **취약프레임 (Chwiyak Frame)**: Vulnerable frames
- **방어배율 (Bangeo Baeyul)**: Damage reduction multiplier
- **체력소모 (Cheryeok Somo)**: Stamina cost
### Usage Example
```typescript
// Complete fall-ground-recovery cycle
// 1. Player falls forward
animationMachine.transitionTo("fall_forward");
// 2. Fall completes, auto-transition to ground_prone
// (handled by AnimationStateMachine)
// 3. Player presses Space while grounded
if (balanceSystem.isGrounded(currentState)) {
const groundState = balanceSystem.getGroundState(currentState); // "prone"
const recoveryType = determineRecoveryType(groundState); // "prone_standup"
const animationState = getRecoveryAnimationState(recoveryType); // "recovery_prone_standup"
animationMachine.transitionTo(animationState);
}
// 4. Recovery completes, auto-transition to idle
// (handled by AnimationStateMachine)
```
### Design Philosophy
Recovery animations follow Black Trigram's Korean martial arts principles:
**정확한 타격 (Precise Targeting)**:
- Vulnerable frame tracking for realistic combat
- Damage reduction mechanics for defensive options
**최대 효과 (Maximum Effectiveness)**:
- Stamina costs balance speed advantage
- Risk/reward for different recovery types
**전통 지식 (Traditional Knowledge)**:
- Based on Korean 낙법 (nakbeop) principles
- Authentic martial arts recovery techniques
**원형 특화 (Archetype Specialization)**:
- Ready for archetype-specific recovery bonuses
- Musa: Faster prone recovery
- Amsalja: Stealthier roll recovery
- Hacker: Enhanced defensive getup
### Performance Targets
- **60 FPS**: All recovery animations maintain 60fps
- **Frame Accuracy**: Precise timing for vulnerable windows
- **Instant Response**: Recovery input detection < 16ms
- **Smooth Transitions**: No animation stuttering during recovery
## 🎮 Combat Component Architecture
```mermaid
graph TB
subgraph "React Components Layer"
CS[CombatScreen]:::react
CS --> CA[CombatArena]:::react
CS --> CH[CombatHUD]:::react
CS --> CC[CombatControls]:::react
end
subgraph "PixiJS Rendering Layer"
PL[Player Visuals]:::pixi
HL[HitEffectsLayer]:::pixi
DB[DojangBackground]:::pixi
UI[UI Components]:::pixi
end
subgraph "Game Logic Layer"
GE[GameEngine]:::logic
PS[PlayerState]:::logic
GS[GameState]:::logic
end
CS --> PL
CA --> HL
CH --> DB
CC --> UI
PL --> GE
HL --> PS
DB --> GS
UI --> GE
classDef react fill:#61dafb,stroke:#333,color:#000
classDef pixi fill:#ff6b9d,stroke:#333,color:#fff
classDef logic fill:#f7df1e,stroke:#333,color:#000
```
---
## 🔊 Audio System Integration
```mermaid
graph LR
subgraph "Traditional Korean Instruments (국악)"
GAY[가야금 Gayageum]:::traditional
BUK[북 Buk Drums]:::traditional
KKW[꽹과리 Kkwaenggwari]:::traditional
HAE[해금 Haegeum]:::traditional
end
subgraph "Combat Audio Events"
HIT[타격음 Hit Sounds]:::combat
TECH[기법음 Technique Sounds]:::combat
VITAL[급소음 Vital Point Sounds]:::combat
STANCE[자세음 Stance Sounds]:::combat
end
subgraph "Cyberpunk Elements"
SYNTH[신스 Synth Drones]:::cyber
GLITCH[글리치 Digital Glitches]:::cyber
NEON[네온 Neon Ambience]:::cyber
end
GAY --> HIT
BUK --> TECH
KKW --> VITAL
HAE --> STANCE
HIT --> SYNTH
TECH --> GLITCH
VITAL --> NEON
STANCE --> SYNTH
classDef traditional fill:#8b4513,stroke:#ffd700,color:#ffd700
classDef combat fill:#ff4500,stroke:#333,color:#fff
classDef cyber fill:#00ffff,stroke:#333,color:#000
```
---
## 📊 Type System Foundation
### Core Combat Types Structure:
```typescript
// Current Type System Implementation Status:
// ✅ COMPLETE - Well-defined interfaces
interface CombatResult {
damage: number;
hit: boolean;
critical: boolean;
vitalPointsHit: VitalPoint[];
// ... comprehensive combat result data
}
// ✅ COMPLETE - Player archetype definitions
type PlayerArchetype =
| "musa"
| "amsalja"
| "hacker"
| "jeongbo_yowon"
| "jojik_pokryeokbae";
// ✅ COMPLETE - Trigram stance system
type TrigramStance =
| "geon"
| "tae"
| "li"
| "jin"
| "son"
| "gam"
| "gan"
| "gon";
// ✅ COMPLETE - Vital point system
interface VitalPoint {
id: string;
name: KoreanText;
category: VitalPointCategory;
severity: VitalPointSeverity;
// ... anatomical positioning and effects
}
// ❌ NEEDS IMPLEMENTATION - Combat techniques
interface KoreanTechnique {
// Defined but needs population with authentic Korean martial arts data
}
```
---
## 💀 Complete 70 Vital Points System (70개 급소 완전 체계)
**Implementation Status**: Q1 2026 - All 70 vital points operational with damage calculation
### Overview (개요)
The Black Trigram combat system implements all **70 authentic vital points (급소)** from Korean martial arts, organized by anatomical system for realistic combat damage calculation.
**Distribution**:
- **Nervous System** (신경계): 25 points
- **Circulatory System** (순환계): 15 points
- **Respiratory System** (호흡기계): 10 points
- **Musculoskeletal System** (근골격계): 20 points
**Cross-Reference**: See [docs/vital-points/VITAL_POINTS_REFERENCE.md](./docs/vital-points/VITAL_POINTS_REFERENCE.md) for complete anatomical documentation including TCM meridian associations, medical references, and Korean martial arts techniques.
### 🧠 Nervous System Targets (신경계 급소) - 25 Points
Critical points targeting the neurological system for instant incapacitation, paralysis, and unconsciousness.
| # | Korean Name | Romanization | English Name | Location | Acupoint | Base Damage | Duration | Effects |
|---|-------------|--------------|--------------|----------|----------|-------------|----------|---------|
| 1 | 백회혈 | Baekhoehyeol | Crown Point | Top of skull, midline | GV20 | 45 | Instant | Unconsciousness, vertigo, KO |
| 2 | 인영 | Inyeong | Carotid Sinus | Neck, lateral to Adam's apple | ST9 | 50 | 2-5s | Blood pressure drop, unconsciousness |
| 3 | 명문 | Myeongmun | Gate of Life | Lumbar spine, L2-L3 | GV4 | 38 | Instant | Paralysis, severe pain, kidney shock |
| 4 | 삼초수 | Samchosu | Triple Burner | Behind ear, mastoid process | TB10 | 32 | Instant | Disorientation, balance loss, nausea |
| 5 | 대추 | Daechu | Great Hammer | C7 vertebra, base of neck | GV14 | 40 | Instant | Paralysis, respiratory disruption |
| 6 | 풍지 | Pungji | Wind Pool | Base of skull, trapezius | GB20 | 36 | 2-3s | Unconsciousness, cranial nerve disruption |
| 7 | 천주 | Cheonju | Celestial Pillar | Upper neck, 1.3 cun lateral | BL10 | 34 | Instant | Severe pain, cervical nerve damage |
| 8 | 태양혈 | Taeyanghyeol | Temple | Lateral to eye, temporal bone | ST8 | 42 | Instant | Concussion, unconsciousness, death risk |
| 9 | 곡지 | Gokji | Pool at the Bend | Elbow crease, lateral end | LI11 | 26 | 1-2s | Arm paralysis, nerve shock |
| 10 | 수삼리 | Susamni | Arm Three Miles | 3 cun below elbow, forearm | LI10 | 24 | 1-2s | Forearm numbness, grip loss |
| 11 | 합곡 | Hapgok | Joining Valley | Hand, between thumb-index | LI4 | 22 | Instant | Hand paralysis, severe pain |
| 12 | 족삼리 | Joksamni | Leg Three Miles | 3 cun below knee, tibia | ST36 | 28 | 1-3s | Leg weakness, balance loss |
| 13 | 승산 | Seungsan | Mountain Support | Calf, belly of gastrocnemius | BL57 | 30 | Instant | Leg cramp, mobility loss |
| 14 | 곤륜 | Gonnryun | Kunlun Mountain | Ankle, lateral malleolus-Achilles | BL60 | 26 | 1-2s | Ankle dysfunction, severe pain |
| 15 | 용천 | Yongcheon | Bubbling Spring | Sole, ball of foot depression | KI1 | 32 | Instant | Shock, balance loss, unconsciousness |
| 16 | 영도 | Yeongdo | Spirit Path | Wrist, ulnar side | HT4 | 24 | Instant | Hand numbness, nerve pain |
| 17 | 신문 | Sinmun | Spirit Gate | Wrist crease, ulnar side | HT7 | 26 | 1-2s | Wrist paralysis, cardiac shock |
| 18 | 내관 | Naegwan | Inner Gate | Forearm, 2 cun above wrist | PC6 | 24 | 1-2s | Nausea, cardiac rhythm disruption |
| 19 | 양릉천 | Yangnyeongcheon | Yang Mound Spring | Knee, fibula head depression | GB34 | 30 | 1-2s | Knee dysfunction, leg weakness |
| 20 | 환도 | Hwando | Jumping Round | Hip, greater trochanter | GB30 | 34 | Instant | Hip paralysis, sciatica, immobility |
| 21 | 견정 | Gyeonjeong | Shoulder Well | Shoulder, trapezius midpoint | GB21 | 28 | Instant | Shoulder drop, arm weakness |
| 22 | 풍부 | Pungbu | Wind Mansion | Skull base, below external occipital | GV16 | 48 | Instant | Medulla damage, death risk, paralysis |
| 23 | 아문 | Amun | Mute Gate | C1-C2, below skull | GV15 | 46 | Instant | Speech loss, paralysis, death risk |
| 24 | 영대 | Yeongdae | Spirit Platform | T6-T7, between shoulder blades | GV10 | 30 | Instant | Respiratory difficulty, back spasm |
| 25 | 요양관 | Yoyangkwan | Lumbar Yang Gate | L3-L4, lumbar spine | GV3 | 36 | Instant | Lower body paralysis, kidney shock |
**Archetype Modifiers** (무사 유형별 계수):
- **무사 (Musa)**: 1.2x damage to GV points (척추 중심)
- **암살자 (Amsalja)**: 1.5x damage to neck points (경부 특화)
- **해커 (Hacker)**: 1.0x baseline (기술 의존)
- **정보요원 (Jeongbo)**: 1.3x precision multiplier to small targets
- **조직폭력배 (Jojik)**: 1.1x to all nervous system points
### 🩸 Circulatory System Targets (순환계 급소) - 15 Points
Vital points disrupting blood flow, causing hemorrhage, and inducing unconsciousness through vascular trauma.
| # | Korean Name | Romanization | English Name | Location | Artery | Base Damage | Duration | Effects |
|---|-------------|--------------|--------------|----------|--------|-------------|----------|---------|
| 26 | 경동맥 | Gyeongdongmaek | Carotid Artery | Neck, lateral to thyroid | N/A | 55 | 3-8s | Unconsciousness, death risk, hemorrhage |
| 27 | 목동맥굴 | Mokdongmaekgul | Carotid Sinus | Neck, bifurcation point | N/A | 50 | 2-5s | Baroreceptor shock, BP drop, KO |
| 28 | 쇄골하동맥 | Swaegolhadongmaek | Subclavian Artery | Clavicle, deep strike | N/A | 48 | 5-10s | Arm ischemia, internal bleeding |
| 29 | 액와동맥 | Aekwadongmaek | Axillary Artery | Armpit, deep medial | N/A | 46 | 5-12s | Severe arm hemorrhage |
| 30 | 상완동맥 | Sangwandongmaek | Brachial Artery | Inner bicep, midpoint | N/A | 40 | 3-8s | Forearm ischemia, hemorrhage |
| 31 | 요골동맥 | Yogoldongmaek | Radial Artery | Wrist, thumb side pulse | N/A | 35 | 2-5s | Hand ischemia, blood loss |
| 32 | 척골동맥 | Cheokgoldongmaek | Ulnar Artery | Wrist, pinky side | N/A | 35 | 2-5s | Hand ischemia, blood loss |
| 33 | 대퇴동맥 | Daetoedongmaek | Femoral Artery | Groin, inguinal ligament | N/A | 60 | 3-10s | Massive hemorrhage, death risk |
| 34 | 슬와동맥 | Seulwadongmaek | Popliteal Artery | Behind knee, deep | N/A | 42 | 5-12s | Lower leg ischemia, hemorrhage |
| 35 | 경골동맥 | Gyeonggoldongmaek | Tibial Artery | Ankle, medial malleolus | N/A | 38 | 3-8s | Foot ischemia, bleeding |
| 36 | 족배동맥 | Jokbaedongmaek | Dorsalis Pedis | Foot dorsum, pulse point | N/A | 32 | 2-5s | Foot blood loss |
| 37 | 복부대동맥 | Bokbudaedongmaek | Abdominal Aorta | Solar plexus, deep | N/A | 58 | Instant | Aortic trauma, internal bleeding, death |
| 38 | 장골동맥 | Janggoldongmaek | Iliac Artery | Lower abdomen, iliac crest | N/A | 52 | 5-10s | Pelvic hemorrhage, shock |
| 39 | 간문맥 | Ganmunmaek | Hepatic Portal | Right upper abdomen | N/A | 50 | Instant | Liver hemorrhage, death risk |
| 40 | 신동맥 | Sindongmaek | Renal Artery | Flank, kidney region | N/A | 48 | Instant | Kidney hemorrhage, shock |
**Archetype Modifiers**:
- **무사 (Musa)**: 1.1x to major arteries
- **암살자 (Amsalja)**: 1.4x to neck arteries (carotid specialization)
- **해커 (Hacker)**: 0.9x (less effective without precision)
- **정보요원 (Jeongbo)**: 1.2x to all circulatory targets
- **조직폭력배 (Jojik)**: 1.3x to accessible arteries (limbs)
### 🫁 Respiratory System Targets (호흡기계 급소) - 10 Points
Targets disrupting breathing, causing suffocation, and inducing respiratory failure.
| # | Korean Name | Romanization | English Name | Location | Structure | Base Damage | Duration | Effects |
|---|-------------|--------------|--------------|----------|-----------|-------------|----------|---------|
| 41 | 인후 | Inho | Throat | Front of neck, trachea | Larynx | 50 | Instant | Airway closure, suffocation, death risk |
| 42 | 염천돌기 | Yeomcheon-dolgi | Xiphoid Process | Sternum base, solar plexus | Diaphragm | 42 | Instant | Diaphragm spasm, breathlessness |
| 43 | 단중 | Danjung | Chest Center | Sternum, between nipples | CV17 | 40 | 2-5s | Cardiac shock, breath disruption |
| 44 | 늑간 | Neukgan | Intercostal | Ribs, between bones | Intercostals | 35 | Instant | Rib fracture, lung puncture risk |
| 45 | 폐유 | Paeyu | Lung Shu | Upper back, T3 paraspinal | BL13 | 38 | Instant | Lung trauma, breathing difficulty |
| 46 | 중완 | Jungwan | Middle Epigastrium | Upper abdomen, below sternum | CV12 | 36 | Instant | Diaphragm shock, nausea |
| 47 | 기해 | Gihae | Sea of Qi | Lower abdomen, below navel | CV6 | 34 | 1-3s | Core breath disruption |
| 48 | 천돌 | Cheondol | Celestial Chimney | Suprasternal notch | CV22 | 44 | Instant | Trachea collapse, suffocation |
| 49 | 결분 | Gyeolbun | Empty Basin | Supraclavicular fossa | ST12 | 32 | Instant | Lung apex trauma |
| 50 | 유문 | Yumun | Gate of Seclusion | Lower ribs, floating ribs | KI21 | 38 | Instant | Diaphragm disruption, liver trauma |
**Archetype Modifiers**:
- **무사 (Musa)**: 1.2x to chest targets
- **암살자 (Amsalja)**: 1.5x to throat (silent kills)
- **해커 (Hacker)**: 1.0x baseline
- **정보요원 (Jeongbo)**: 1.1x precision
- **조직폭력배 (Jojik)**: 1.3x to throat/chest
### 🦴 Musculoskeletal System Targets (근골격계 급소) - 20 Points
Joint locks, bone strikes, and structural damage points targeting mobility and skeletal integrity.
| # | Korean Name | Romanization | English Name | Location | Structure | Base Damage | Duration | Effects |
|---|-------------|--------------|--------------|----------|-----------|-------------|----------|---------|
| 51 | 턱관절 | Teokgwanjeol | Jaw Joint | TMJ, in front of ear | Mandible | 38 | Instant | Jaw dislocation, KO, concussion |
| 52 | 코뼈 | Kobbyeo | Nasal Bone | Nose bridge, upper | Nasal bones | 32 | Instant | Nasal fracture, eye trauma, bleeding |
| 53 | 관골 | Gwangol | Cheekbone | Zygomatic arch | Zygomatic | 36 | Instant | Facial fracture, orbital damage |
| 54 | 쇄골 | Swaegol | Clavicle | Collarbone, midpoint | Clavicle | 40 | Instant | Clavicle fracture, shoulder dysfunction |
| 55 | 흉골 | Heunggol | Sternum | Breastbone, center | Sternum | 42 | Instant | Sternal fracture, cardiac trauma |
| 56 | 견갑골 | Gyeonggapgol | Scapula | Shoulder blade, spine | Scapula | 34 | Instant | Shoulder immobility, fracture |
| 57 | 견관절 | Gyeongwanjeol | Shoulder Joint | Glenohumeral joint | Shoulder | 38 | Instant | Dislocation, rotator cuff tear |
| 58 | 주관절 | Jugwanjeol | Elbow Joint | Humeroulnar joint | Elbow | 40 | Instant | Hyperextension, dislocation, fracture |
| 59 | 손목관절 | Sonmokgwanjeol | Wrist Joint | Radiocarpal joint | Wrist | 30 | Instant | Wrist fracture, ligament tear |
| 60 | 손가락관절 | Songaraggwanjeol | Finger Joints | Metacarpophalangeal | Fingers | 22 | Instant | Finger dislocation, break |
| 61 | 척추 | Cheokchu | Spinal Column | Vertebrae, various levels | Spine | 50 | Instant | Vertebral fracture, paralysis, death |
| 62 | 늑골 | Neukgol | Ribs | Rib cage, lateral | Ribs | 36 | Instant | Rib fracture, lung puncture |
| 63 | 고관절 | Gogwanjeol | Hip Joint | Acetabulofemoral | Hip | 42 | Instant | Hip dislocation, immobility |
| 64 | 슬관절 | Seulgwanjeol | Knee Joint | Tibiofemoral | Knee | 40 | Instant | ACL tear, dislocation, mobility loss |
| 65 | 정강이 | Jeonggangai | Shin | Tibia, anterior | Tibia | 32 | Instant | Tibial fracture, severe pain |
| 66 | 발목관절 | Balmokgwanjeol | Ankle Joint | Talocrural joint | Ankle | 34 | Instant | Ankle fracture, sprain, mobility loss |
| 67 | 아킬레스건 | Akilleseugeon | Achilles Tendon | Heel, posterior | Tendon | 38 | Instant | Tendon rupture, immobility |
| 68 | 슬개골 | Seulgaegol | Kneecap | Patella, anterior knee | Patella | 36 | Instant | Patellar fracture, knee dysfunction |
| 69 | 발등뼈 | Baldeungbyeo | Metatarsal | Foot dorsum, bones | Metatarsals | 28 | Instant | Foot fracture, mobility loss |
| 70 | 발가락관절 | Balgaraggwanjeol | Toe Joints | Phalanges, foot | Toes | 20 | Instant | Toe fracture, balance disruption |
**Archetype Modifiers**:
- **무사 (Musa)**: 1.3x to skeletal targets (bone-breaking focus)
- **암살자 (Amsalja)**: 0.9x (less effective with structural damage)
- **해커 (Hacker)**: 1.0x baseline
- **정보요원 (Jeongbo)**: 1.1x to joints (technical precision)
- **조직폭력배 (Jojik)**: 1.4x to limbs and joints (street fighting)
---
## ⚙️ Damage Calculation System (데미지 계산 시스템)
**Implementation Status**: Q1 2026 - Fully operational with multi-factor calculation
For an overview of the TypeScript implementation approach and damage formula reference, see the [Damage Calculation Guide](./docs/combat/damage-calculation-guide.md). Three worked examples are provided below.
### Quick Reference: Damage Formula
```
Final Damage = max(1, (Base * Archetype * Stance * Anatomy * Critical) * (1 - DefenseReduction))
```
**Multipliers**:
- **Archetype**: 0.9x-1.5x (specialization bonus)
- **Stance**: 0.8x-1.5x (I Ching synergy)
- **Anatomy**: 1.0x-2.0x (precision targeting)
- **Critical**: 1.0x or 2.0x (random with skill influence)
- **Defense Reduction**: 0-0.8x (max 80% reduction, based on defender defense stat / 200)
**Minimum Damage**: Always deals at least 1 HP damage
> **Implementation Note**: The canonical damage calculation including defense reduction logic and minimum damage floor is in `src/systems/vitalpoint/DamageCalculator.ts` (lines 172-177).
**Example**: Musa striking Baekhoehyeol (Crown) with Geon stance:
- Base: 45 HP
- Archetype: 1.2x (Musa vs Nervous)
- Stance: 1.2x (Geon vs Son)
- Anatomy: 1.5x (75% accuracy)
- Critical: 2.0x (successful roll)
- Raw: 45 × 1.2 × 1.2 × 1.5 × 2.0 = **194 HP**
- Defense Reduction: 0.21x (41 defense / 200 = 21% reduction)
- **Final: max(1, 194 × (1 - 0.21)) = 153 HP damage** + Stun (3s) + Disorientation (5s)
---
## 🦴 28-Bone Skeletal Animation System (28개 뼈 골격 애니메이션)
**Implementation Status**: Q1 2026 - Fully operational skeletal rig with 7 hand poses
Black Trigram uses a **28-bone hierarchical skeletal system** for realistic combat animations, hand pose articulation, and vital point strike visualization.
### Bone Hierarchy (뼈 계층 구조)
**Core Spine** (4 bones): Pelvis → Spine_Lower → Spine_Upper → Chest
**Head & Neck** (2 bones): Neck → Head
**Left Arm** (6 bones): Shoulder_L → Upper_Arm_L → Elbow_L → Forearm_L → Wrist_L → Hand_L
**Right Arm** (6 bones): Shoulder_R → Upper_Arm_R → Elbow_R → Forearm_R → Wrist_R → Hand_R
**Left Leg** (5 bones): Hip_L → Thigh_L → Knee_L → Shin_L → Ankle_L
**Right Leg** (5 bones): Hip_R → Thigh_R → Knee_R → Shin_R → Ankle_R
**Total**: 28 bones for full-body animation at 60fps
### 7 Hand Pose System (7개 수형 체계)
Korean martial arts hand formations optimized for different vital point targets:
| # | Korean | Romanization | English | Use | Vital Points | Multiplier |
|---|--------|--------------|---------|-----|--------------|------------|
| 1 | 주먹 | Jumeok | Closed Fist | Bone strikes | Jaw, temple, sternum, ribs | 1.2x |
| 2 | 손바닥 | Sonbadak | Open Palm | Push, slap strikes | Face, chest, solar plexus | 1.1x |
| 3 | 타격 | Tagyeok | Knife-Hand | Precise strikes | Neck, throat, nerve points | 1.3x |
| 4 | 잡기 | Japgi | Grasping | Joint locks | Wrist, elbow, neck | 1.1x |
| 5 | 막기 | Makgi | Blocking | Defense | N/A (defensive) | 0.8x |
| 6 | 가리키기 | Garikigi | Pointing | Eye strikes | Eyes, throat, acupoints | 1.4x |
| 7 | 이완 | Ewan | Relaxed | Neutral | N/A (transition) | 1.0x |
### Combat Technique Animation
Each technique defines:
- **Bone Transforms**: Position/rotation/scale for all 28 bones across keyframes
- **Hand Poses**: Left and right hand formations at each keyframe
- **Muscle Tension**: Core/upper/lower body activation levels (0-100)
- **Impact Frame**: Exact frame where strike connects with vital point
**Example**: 천둥벽력 (Heaven Strike)
- Duration: 800ms (48 frames at 60fps)
- Impact Frame: 48
- Hand Pose: 주먹 (Closed Fist)
- Target: 백회혈 (Crown), 쇄골 (Clavicle), 대추 (C7)
---
## 💊 Status Effect System (상태 효과 시스템)
**Implementation Status**: Q1 2026 - 5 primary status effects operational
Status effects are applied based on vital point anatomical system and damage severity.
### Status Effects Table
| Effect | Korean | Duration | Application | Stack Limit | Visual Indicator | Gameplay Impact |
|--------|--------|----------|-------------|-------------|------------------|-----------------|
| **기절 (Stun)** | 기절 | 1-5s | Nervous system critical hits | None (refreshes) | ⚡ Lightning icon, wobble animation | Cannot act, vulnerable to followups |
| **출혈 (Bleed)** | 출혈 | 5-15s | Circulatory hits ≥45 damage | 3 stacks | 🩸 Blood particles, red pulse | 5 HP/sec per stack (15 HP/sec max at 3 stacks) |
| **피로 (Fatigue)** | 피로 | 10-30s | Stamina depletion, heavy hits | None (stacks additively) | 😓 Sweat particles, slow movement | -20% movement speed, +25% stamina cost |
| **마비 (Paralysis)** | 마비 | 3-10s | Nerve strikes, spine hits | None (refreshes) | ⚠️ Yellow icon, shaking limbs | Reduced attack speed (-40%), mobility loss |
| **혼란 (Disorientation)** | 혼란 | 3-8s | Head trauma, vestibular damage | None (refreshes) | 🌀 Dizzy icon, screen blur | Accuracy -50%, vision impaired, controls inverted |
### Stacking Rules
- **Stun**: Cannot stack, refreshes duration to longest value
- **Bleed**: Stacks up to 3x, each adds independent DoT (15 HP/sec max)
- **Fatigue**: Duration extends additively, effects compound
- **Paralysis**: Cannot stack, refreshes to longest duration
- **Disorientation**: Cannot stack, most severe effect takes priority
### Status Removal
**Natural Expiration**: All effects expire after duration
**Cleansing**: Healing items/abilities can remove specific effects
**Death**: All effects removed on knockout/death
**Stance Change**: Some stances provide status resistance (-30% duration)
---
## 🤖 Combat AI Behavior System (전투 AI 행동 시스템)
**Implementation Status**: Q1 2026 - 50% complete (basic decision tree operational)
AI fighters utilize behavior trees for dynamic combat decision-making based on health, stance, and tactical situation.
### AI Decision Flow
```mermaid
graph TB
START[Combat AI Tick]:::start --> ASSESS[Assess Situation]:::process
ASSESS --> HP{Health Check}:::decision
HP -->|>70%| AGG[Aggressive Mode]:::aggressive
HP -->|30-70%| BAL[Balanced Mode]:::balanced
HP -->|<30%| DEF[Defensive Mode]:::defensive
AGG --> PICK_ATK[Select Attack]:::action
BAL --> EVAL[Evaluate Stance]:::process
DEF --> RETREAT[Retreat & Guard]:::action
PICK_ATK --> VP1[Target Vital Point]:::action
EVAL --> STANCE{Stance Advantage?}:::decision
STANCE -->|Yes| PICK_ATK
STANCE -->|No| SWITCH[Change Stance]:::action
VP1 --> CALC1[Calculate Threat Score]:::process
SWITCH --> PICK_ATK
RETREAT --> GUARD[Defensive Stance]:::action
CALC1 --> EXEC[Execute Technique]:::action
GUARD --> WAIT[Wait for Opening]:::action
EXEC --> END[End AI Tick]:::end
WAIT --> END
classDef start fill:#00ff00,stroke:#333,color:#000
classDef process fill:#4da6ff,stroke:#333,color:#fff
classDef decision fill:#ffcc00,stroke:#333,color:#000
classDef aggressive fill:#ff0000,stroke:#333,color:#fff
classDef balanced fill:#ff8c00,stroke:#333,color:#fff
classDef defensive fill:#0066cc,stroke:#333,color:#fff
classDef action fill:#9370db,stroke:#333,color:#fff
classDef end fill:#808080,stroke:#333,color:#fff
```
### Aggression Levels
**Aggressive (>70% HP)**:
- Prioritizes offense over defense
- Selects high-damage vital points (head, neck, chest)
- Uses power stances (Geon, Li, Jin)
- 80% attack frequency, 20% defense
**Balanced (30-70% HP)**:
- Evaluates stance matchups before committing
- Targets medium-risk vital points (limbs, torso)
- Adapts stance based on opponent
- 50% attack, 30% defense, 20% positioning
**Defensive (<30% HP)**:
- Prioritizes survival and creating distance
- Counter-attacks only with high success probability
- Uses defensive stances (Gam, Son, Gon)
- 20% attack, 60% defense, 20% evasion
### Vital Point Selection Logic
AI calculates **Threat Score** for each available vital point:
```
Threat Score = (Base Damage × Archetype Bonus × Stance Synergy) / (Distance × Difficulty)
```
**Factors**:
- **Base Damage**: Vital point's inherent damage value
- **Archetype Bonus**: AI's archetype effectiveness multiplier
- **Stance Synergy**: Current stance advantage vs target
- **Distance**: Range to target (penalties for distant targets)
- **Difficulty**: Anatomical precision requirement
AI selects highest Threat Score target that is within range and line-of-sight.
### Stance Adaptation
AI changes stance when:
1. **Disadvantage Detected**: Current stance has <0.9x multiplier vs opponent
2. **Health Threshold**: Drops below 30% HP (switches to defensive stance)
3. **Tactical Reset**: After being hit 3+ times consecutively
4. **Opportunity**: Opponent vulnerable during stance transition
**Stance Selection Priority**:
1. Counter opponent's current stance (I Ching advantage)
2. Match archetype specialization (Musa → Geon, Amsalja → Gam)
3. Adapt to combat situation (Aggressive/Defensive mode)
---
## ⚡ Performance Optimization for 60fps (60fps 성능 최적화)
**Implementation Status**: Q1 2026 - Desktop 60fps achieved, Mobile 30fps target
Black Trigram maintains 60fps during intense combat through aggressive optimization across rendering, physics, and animation systems.
### Rendering Optimizations
**Instanced Rendering**:
- Particle effects (blood, sparks, impact) use GPU instancing
- Reduces draw calls by 80% (500 → 100 per frame)
**Level of Detail (LOD)**:
- 3 LOD levels for character models based on camera distance
- High: <3m (28 bones, full detail)
- Medium: 3-8m (14 bones, simplified)
- Low: >8m (6 bones, billboard sprites)
**Frustum Culling**:
- Objects outside camera view not rendered
- Spatial hash grid for O(1) visibility queries
- Saves 30-40% rendering cost in large arenas
**Occlusion Culling**:
- Objects behind solid geometry culled
- Portal system for indoor environments
- Reduces overdraw by 50%
### Physics Optimizations
**Fixed Timestep**:
- Physics updates at consistent 60Hz
- Decoupled from variable frame rate
- Prevents physics instability
**Spatial Hashing**:
- Combat arena divided into 1m grid cells
- Collision detection only checks nearby cells
- Reduces collision checks from O(n²) to O(n)
**Collision Narrowing**:
- Broad phase: AABB bounding boxes
- Narrow phase: Precise skeletal collision only for potential hits
- 95% of checks eliminated in broad phase
**Sleep States**:
- Idle fighters enter sleep state (no physics updates)
- Wake on proximity or impact
- Saves 60% physics CPU for spectators
### Animation Optimizations
**Bone Culling**:
- Invisible bones (occluded or off-screen) not updated
- Hand bones culled when >10m from camera
- Reduces animation CPU by 40%
**Keyframe Interpolation**:
- Linear interpolation for most bones
- Cubic interpolation only for visible extremities (hands, head)
- 50% faster animation updates
**Blend Tree Caching**:
- Animation blend results cached for 2 frames
- Cache hit rate >80% for repetitive movements
- Eliminates redundant blend calculations
**Pose Reuse**:
- Common stance poses precomputed and cached
- Transitions interpolate between cached poses
- 70% reduction in skeletal calculations
### Achieved Metrics
**Desktop (RTX 3060, Ryzen 5 5600X)**:
- **Average FPS**: 62 fps (consistent 60+ during combat)
- **Frame Time**: 16ms (with 2ms headroom)
- **Rendering**: 10ms (62% of budget)
- **Physics**: 4ms (25% of budget)
- **Logic**: 2ms (13% of budget)
**Mobile (Snapdragon 888, 6GB RAM)**:
- **Average FPS**: 32 fps (target 30fps maintained)
- **Frame Time**: 33ms
- **Rendering**: 22ms (LOD aggressive, particles reduced)
- **Physics**: 8ms (simpler collision)
- **Logic**: 3ms
### Profiling Tools
**Built-in Profiler**:
- F12 toggle in development builds
- Real-time frame time graph
- CPU/GPU breakdown by system
**Bottleneck Detection**:
- Automatic alerts when system exceeds 60% budget
- Highlights expensive operations
- Suggests optimization strategies
---
## ⚖️ Balance Considerations (밸런스 고려사항)
**Implementation Status**: Q1 2026 - Core balance established, ongoing tuning
### Design Philosophy
**Authentic vs. Fun**:
- Authentic Korean martial arts principles (70% weight)
- Fun, competitive gameplay (30% weight)
- No vital point is "auto-win" - all have counterplay
**Rock-Paper-Scissors**:
- 8 Trigram stances have circular advantages (I Ching)
- 5 Archetypes have situational strengths
- No single dominant strategy
**Skill Expression**:
- High-skill players rewarded with precision targeting
- Low-skill players can compete with fundamentals
- Skill ceiling is very high (professional esports potential)
### Tuning Parameters
**Damage Scaling**:
- Base vital point damage: 16-60 HP
- Multipliers keep range reasonable (15-400 HP final)
- Average combat duration: 30-60 seconds
- 3-5 successful vital point hits = knockout
**Cooldowns**:
- Basic techniques: 0.8-1.5s cooldown
- Advanced techniques: 2-4s cooldown
- Ultimate techniques: 8-12s cooldown + resource cost
**Stamina Costs**:
- Light attacks: 10-15 stamina
- Medium attacks: 20-30 stamina
- Heavy attacks: 35-50 stamina
- Stamina regen: 25/sec (full bar = 200 stamina)
- Empty stamina = vulnerable state (3s recovery)
### Archetype Balance
**Target Win Rates** (1v1, equal skill):
- All archetypes: 48-52% win rate
- No archetype hard-counters another
- Matchup variance ≤8% difference
**Current Status**:
- Musa: 51% (slightly overtuned)
- Amsalja: 50% (balanced)
- Hacker: 47% (needs +3% damage buff)
- Jeongbo: 52% (slightly overtuned)
- Jojik: 50% (balanced)
### Vital Point Balance
**High-Damage Points Have Counterplay**:
- **백회혈 (Crown)** - 45 damage, but requires overhead position
- **인영 (Carotid)** - 50 damage, but small target (92% accuracy needed)
- **대퇴동맥 (Femoral)** - 60 damage, but low stance required, long recovery
**Accessibility**:
- 30% vital points: Easy to hit (torso, limbs)
- 50% vital points: Medium difficulty (joints, neck)
- 20% vital points: Hard to hit (eyes, acupoints)
### Playtesting Guidelines
**Balance Testing Protocol**:
1. **100-Match Samples**: Gather win rates over 100 1v1 matches per matchup
2. **Skill Brackets**: Test at Low/Medium/High/Pro skill levels
3. **Stance Distribution**: Ensure all 8 stances see >10% usage
4. **Vital Point Heat Maps**: Identify over-used or under-used targets
5. **Time-to-Kill Analysis**: Average combat duration 30-60s
**Red Flags**:
- ❌ Any archetype >55% or <45% win rate
- ❌ Any stance >60% or <5% usage rate
- ❌ Any vital point >30% of all hits
- ❌ Average TTK <20s or >90s
- ❌ "One-shot" combos dealing >200 damage
**Iteration Process**:
1. Identify imbalance through data
2. Propose tuning changes (±5% increments)
3. Test changes with focus group (20 players)
4. Deploy to public test realm (PTR)
5. Monitor for 2 weeks, gather feedback
6. Implement final changes in production
---
## 🚀 Implementation Priority Matrix
### Phase 1: Core Combat Foundation (Current Priority)
1. **CombatSystemController** - Central orchestration logic
2. **StanceManager** - Trigram stance transitions and validation
3. **KoreanVitalPoints** - 70 authentic vital points database
4. **DamageCalculator** - Realistic anatomical damage calculation
### Phase 2: Trigram System (High Priority)
1. **TrigramCalculator** - I Ching effectiveness relationships
2. **TransitionCalculator** - Ki/Stamina cost calculation
3. **KoreanTechniques** - Authentic technique implementations
4. **KoreanCulture** - Philosophy integration
### Phase 3: Advanced Features (Medium Priority)
1. **HitDetection** - Precise anatomical collision detection
2. **AnatomicalRegions** - Body region mapping system
3. **Enhanced Audio** - Korean traditional instrument integration
4. **Combat Analytics** - Performance and effectiveness tracking
### Phase 4: Combat Enhancements (Complete ✅)
1. **GrappleSystem** ✅ - Hapkido/Ssireum grappling mechanics (95% complete, 34 tests)
2. **LimbExposureSystem** ✅ - Vulnerability windows and counter-attacks (100% complete, 132 tests)
3. **AI Counter-Attack Integration** ✅ - Defensive AI exploits exposed limbs (18 tests)
4. **Visual Indicators** ✅ - 3D glow effects and timing HUD (49 tests)
5. **Grappling Animations** ✅ - 4 animation states with audio hooks (34 tests)
---
## 🤜 Grappling System (잡기 체계)
**Status**: ✅ 95% Complete | **Implementation**: `src/systems/combat/GrappleSystem.ts` | **Tests**: 34 passing
### Overview
The Grappling System implements authentic Korean martial arts grappling techniques from **Hapkido (합기도)** and traditional Korean wrestling **Ssireum (씨름)**. It features realistic grip decay mechanics, escape difficulty calculations, and stance-based advantages.
### Core Components
**Grip Mechanics**:
- **Initial Grip Strength**: 100% at grapple initiation
- **Decay Rate**: -5% to -15% per second based on stamina
- **Minimum Threshold**: Grapple automatically breaks at <30% grip strength
- **Refresh**: Successful resistance checks can restore +10% grip
**Escape System**:
- **Base Difficulty**: 60% escape chance at full stamina
- **Stamina Impact**: -10% success per 20% stamina lost
- **Stance Modifiers**:
- **GON (☷ Earth)**: +30% grip strength, +15% grapple success, +30% escape (grounded wrestling expertise)
- **GAN (☶ Mountain)**: +15% grip strength, +15% escape (immovable defensive stance)
- **Other Stances**: Standard grapple mechanics
**State Transitions**:
```
IDLE → GRAPPLING (controlling opponent)
IDLE → GRAPPLED (being controlled)
GRAPPLING → IDLE (release or break)
GRAPPLED → IDLE (successful escape)
```
**Movement Penalties**:
- **GRAPPLING**: -80% movement speed (20% remaining)
- **GRAPPLED**: -100% movement speed (cannot move)
### Animation States (4 Total)
| State | Duration | Frames @ 60fps | Description |
|-------|----------|----------------|-------------|
| **GRAPPLE_ENTRY** | 133ms | 8 frames | Initial grab connection |
| **GRAPPLE_CONTROL** | 167ms | 10 frames | Maintaining grip (loops) |
| **GRAPPLE_STRUGGLE** | 200ms | 12 frames | Escape attempts |
| **GRAPPLE_ESCAPE** | 250ms | 15 frames | Successful release |
### Visual Feedback
**GrapplingIndicator3D Component** (`src/components/shared/three/effects/GrapplingIndicator3D.tsx`):
- **Particle System**: 20-50 particles showing struggle intensity
- **Grip Strength Meter**: HTML overlay with bilingual labels (잡기 힘 / Grip Strength)
- **Color Coding**: Blue (controlling) vs Red (being controlled)
- **Mobile Optimization**: 60% particle reduction for 55fps+ performance
### Audio Integration
**useGrapplingAudio Hook** (`src/components/screens/combat/hooks/useGrapplingAudio.ts`):
- **6 Audio Functions**: Connect, struggle, escape, break, counter, warning
- **Rate Limiting**: 100-300ms cooldowns between sounds
- **Volume Modifiers**: Hand (0.8x), Arm (1.1x), Both Arms (1.3x), Full Control (1.3x)
- **Placeholder Mapping**: Uses existing combat audio until custom grappling sounds are created
### Implementation Details
```typescript
// Core grapple mechanics (simplified)
interface GrappleState {
isGrappling: boolean;
gripStrength: number; // 0-100%
escapeAttempts: number;
duration: number; // ms
}
// Grip decay calculation
const gripDecay = baseDecayRate * (1 + staminaPenalty) * stanceModifier;
// Escape success probability
const escapeChance = baseChance * (stamina / 100) * stanceBonus;
```
### Usage in Combat
The GrappleSystem is integrated into `CombatSystem.ts`:
- `resolveAttack()` handles GRAPPLE type attacks
- `handleGrappleTechnique()` initiates grapple control
- `updateGrappleState()` maintains control over time (called each frame)
- Automatic release on escape or grip strength < 30%
---
## ⚡ Limb Exposure & Counter-Attack System (사지 노출 및 반격 체계)
**Status**: ✅ 100% Complete | **Implementation**: `src/systems/combat/LimbExposureSystem.ts` | **Tests**: 132 passing
### Overview
The Limb Exposure System implements Korean martial arts principles of **허점공격 (Heojeom Gonggyeok - attacking openings)** and **후수필승 (Husu Pilseung - victory through counter-timing)**. It detects when attackers expose vulnerable limbs during technique execution, creating counter-attack opportunities with damage multipliers.
### Core Concepts
**Vulnerability Windows**:
- **Wind-up Phase** (0-50% of execution): Low vulnerability (1.1x damage multiplier)
- **Peak Phase** (50-70% of execution): Maximum vulnerability (2.0x damage multiplier)
- **Recovery Phase** (70-100% of execution): Medium vulnerability (1.5x damage multiplier)
- **Window Duration**: 300-400ms typical exposure time
**Exposed Limb Types**: 12 total (left/right × 6 body parts)
- `right_arm`, `left_arm`, `right_elbow`, `left_elbow`, `right_wrist`, `left_wrist`
- `right_leg`, `left_leg`, `right_knee`, `left_knee`, `right_ankle`, `left_ankle`
**Breaking Techniques**:
- **Target Joints**: Ankle, knee, elbow, wrist
- **Severity Calculation**: Based on force (40-80 damage) → 0.0-1.0 severity
- **Status Effects**: Broken limbs receive injury status (BROKEN_ANKLE, BROKEN_KNEE, etc.)
- **Movement Impact**: Broken legs reduce movement speed, broken arms reduce attack damage
### AI Integration
**DecisionTree Integration** (`src/systems/ai/DecisionTree.ts`):
- **Priority Level 2**: Counter-attack evaluation (after survival, before standard attacks)
- **Archetype Priorities**:
- **Musa (무사)**: Priority 10.5-11.1 (high defensiveness, honor through counters)
- **Amsalja (암살자)**: Priority 10.5-11.1 (tactical exploitation of weakness)
- **Jeongbo (정보요원)**: Priority 13.0 (intelligence operative, analytical counters)
- **Jojik/Hacker**: Priority 9.6-10.8 (offensive-focused, lower counter priority)
- **Bonus Modifiers**:
- Breaking opportunities: +2 priority
- High vulnerability (>2.0x): +1 priority
**Counter Selection Logic**:
```typescript
// AI evaluates counter opportunities each decision frame
const opportunity = calculateCounterOpportunity(opponentTechnique, elapsedTime);
if (opportunity && opportunity.confidence > 0.7) {
const priority = baseCounterPriority + (defensiveness * 1.5) +
(opportunity.allowsBreaking ? 2 : 0) +
(opportunity.vulnerabilityMultiplier > 2.0 ? 1 : 0);
if (priority >= decisionThreshold) {
selectCounterTechnique(opportunity.exposedLimb);
}
}
```
### Visual Indicators
**LimbExposureIndicator3D** (`src/components/shared/three/effects/LimbExposureIndicator3D.tsx`):
- **3D Glow Effect**: Three.js `pointLight` attached to exposed limb position
- **Intensity Scaling**: 1.0-3.0 based on vulnerability multiplier
- **Color Coding**:
- Gold (`#ffaa00`): Low vulnerability (<1.5x)
- Orange (`#ff6600`): Medium vulnerability (1.5-2.0x)
- Red (`#ff0000`): High vulnerability / Breaking opportunity (≥2.0x)
- **Fade Animation**: Smooth fade in/out during 300-400ms exposure window
- **Performance**: <0.5ms overhead per frame, 60fps maintained
**VulnerabilityWindowHUD** (`src/components/shared/three/ui/VulnerabilityWindowHUD.tsx`):
- **Circular Timer**: Progress ring showing remaining opportunity time
- **Bilingual Labels**: "반격 기회" (Korean) / "Counter Opportunity" (English)
- **Urgency Colors**:
- Early (0-50%): Gold (plenty of time)
- Mid (50-75%): Orange (closing window)
- Late (75-100%): Red (last moment)
- **Mobile Layout**: Compact design, 70% scale on mobile devices
### Type Extensions
**PlayerState Extended**:
```typescript
interface PlayerState {
// ... existing fields
currentTechnique?: KoreanTechnique; // Technique being executed
techniqueElapsedTime?: number; // Time elapsed in technique (ms)
}
```
**CombatContext Extended**:
```typescript
interface CombatContext {
// ... existing fields
opponentTechnique?: KoreanTechnique;
opponentTechniqueTime?: number;
counterOpportunity?: CounterOpportunity;
opponentVulnerability: number; // 1.0-2.5x multiplier
}
```
### Implementation Example
```typescript
// Detect limb exposure during attack
const opportunity = calculateCounterOpportunity(
opponentTechnique,
elapsedTime // 450ms into 800ms technique
);
if (opportunity) {
console.log(opportunity);
// {
// exposedLimb: "right_leg",
// vulnerabilityMultiplier: 2.0,
// allowsBreaking: true,
// recommendedCounters: ["ankle_stomp", "knee_kick"],
// remainingWindow: 350, // ms
// confidence: 0.85
// }
}
```
### Test Coverage
- **36 tests**: LimbExposureSystem core functions
- **14 tests**: Full attack-counter integration flow
- **15 tests**: BreakingStatusEffects validation
- **18 tests**: AI DecisionTree counter-attack integration
- **19 tests**: LimbExposureIndicator3D visual component
- **30 tests**: VulnerabilityWindowHUD UI component
- **Total: 132/132 tests passing (100%)** ✅
### Korean Martial Arts Philosophy
The system embodies traditional principles:
- **허점공격** (Heojeom Gonggyeok): Attacking openings/weaknesses
- **후수필승** (Husu Pilseung): Victory through counter-attack timing
- **이순응변** (Isun Eungbyeon): Adapt and exploit opponent's mistakes
- **파쇄기** (Paswaegi): Breaking techniques for overextended attacks
---
## 💡 Technical Specifications
### Performance Requirements:
- **Target FPS**: 60 FPS during intense combat
- **Memory Usage**: < 512MB for full combat simulation
- **Audio Latency**: < 100ms for responsive feedback
- **Input Lag**: < 16ms for precise control
### Cultural Authenticity Standards:
- **Korean Terminology**: Bilingual Korean-English throughout
- **Martial Arts Accuracy**: Traditional techniques with proper names
- **Philosophy Integration**: I Ching principles in combat mechanics
- **Respectful Representation**: Honor Korean martial arts heritage
### Combat Realism Targets:
- **Anatomical Accuracy**: 70 precise vital points
- **Damage Calculation**: Physics-based trauma simulation
- **Status Effects**: Pain, consciousness, balance, blood loss
- **Recovery Systems**: Realistic healing and regeneration
---
## 🎯 Success Metrics
```mermaid
graph LR
subgraph "Combat Effectiveness Metrics"
ACC[정확도 Accuracy
85%+ hit detection]:::metric
REA[사실성 Realism
Authentic damage calc]:::metric
CUL[문화성 Culture
100% Korean terms]:::metric
PER[성능 Performance
60 FPS target]:::metric
end
classDef metric fill:#00ff00,stroke:#333,color:#000,stroke-width:2px
```
**흑괘의 길을 걸어라** - _Walk the Path of the Black Trigram_
---
_This architecture document reflects the current implementation state of Black Trigram's combat system as of the latest codebase analysis. All empty system files represent planned implementations following authentic Korean martial arts principles._