# 🎮 Black Trigram (흑괘) - Complete Controls Reference

**🔐 ISMS Alignment:** This document follows [Hack23 Secure Development Policy](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md) documentation requirements.

**Version**: 0.5.37  
**Last Updated**: January 2026  
**Status**: ✅ Production Ready

This document is the **single source of truth** for all game controls in Black Trigram. It describes the currently implemented control scheme and clearly marks planned future enhancements.

---

## 📋 Quick Reference

### Desktop Controls (Currently Implemented)

| **Action** | **Key(s)** | **Korean** | **Description** |
|------------|------------|------------|-----------------|
| **Stance 1 - ☰ Geon** | `1` | 건 (Heaven) | Bone-striking force |
| **Stance 2 - ☱ Tae** | `2` | 태 (Lake) | Joint manipulation |
| **Stance 3 - ☲ Li** | `3` | 리 (Fire) | Precise nerve strikes |
| **Stance 4 - ☳ Jin** | `4` | 진 (Thunder) | Stunning techniques |
| **Stance 5 - ☴ Son** | `5` | 손 (Wind) | Continuous pressure |
| **Stance 6 - ☵ Gam** | `6` | 감 (Water) | Flow and adaptation |
| **Stance 7 - ☶ Gan** | `7` | 간 (Mountain) | Defensive mastery |
| **Stance 8 - ☷ Gon** | `8` | 곤 (Earth) | Grounding techniques |
| **Technique 1-10** | `Q` `E` `R` `T` `Y` `F` `G` `Z` `X` `C` | 기술 실행 | Execute archetype techniques (3-10 available) |
| **Movement** | `W` `A` `S` `D` or Arrow Keys | 이동 | 8-directional tactical positioning |
| **Attack** | `Space` | 공격 | Execute current stance technique |
| **Block/Guard** | `B` | 방어 | Defensive positioning and blocks |
| **Vital Points Overlay** | `V` | 급소 표시 | Toggle anatomical targeting overlay |
| **Pause Menu** | `ESC` or `M` | 일시정지 | Pause game / Return to menu |

> ✅ **NEW: Zero-Conflict Control Scheme** (Current Version):
> 
> In **v0.5.37**, all **currently implemented** controls avoid conflicts: technique keys (Q-E-R-T-Y-F-G-Z-X-C) are positioned around WASD for easy reach with your left hand while keeping WASD free for movement.
> 
> - **Techniques (now)**: Use keys around WASD (Q, E, R, T, Y, F, G, Z, X, C)
> - **Movement**: WASD remains fully functional
> - **No browser conflicts**: No function keys or Ctrl shortcuts
> - **Ergonomic**: All keys within easy reach of left hand
> - **⚠️ Future Note**: The planned **Advanced Footwork System** (NOT YET IMPLEMENTED) proposes using `X` for **Swap Front Foot** and `Z` for **Short Step**. In that future update, technique bindings for `Z`/`X` may be remapped to avoid conflicts; refer to this document's version header for the active scheme.

### Mobile Controls (Touch Screen)

| **Control** | **Location** | **Korean** | **Description** |
|-------------|--------------|------------|-----------------|
| **Virtual D-Pad** | Bottom-Left (200px from bottom) | 가상 방향키 | 8-directional movement (140x140px) |
| **Attack Button** | Bottom-Right (200px from bottom) | 공격 버튼 | Gold ⚡ button (80x80px) |
| **Block Button** | Bottom-Right (200px from bottom) | 방어 버튼 | Blue 🛡️ button (70x70px) |
| **Stance Wheel** | Right-Center | 자세 선택 | Circular 8-trigram selector (200px) |
| **Swipe Right →** | Anywhere | 전진 | Advance toward opponent |
| **Swipe Left ←** | Anywhere | 후퇴 | Retreat from opponent |
| **Swipe Up ↑** | Anywhere | 상단 공격 | High attack execution |
| **Swipe Down ↓** | Anywhere | 하단 공격 | Low attack execution |
| **Two-Finger Tap** | Anywhere | 급소 모드 | Toggle vital point targeting mode |

> **🆕 Enhanced Mobile Layout (v0.6.15+)**:
> 
> - **Improved Visibility**: On-screen D-Pad and action buttons are positioned 200px from the bottom edge so they don't cover the combat arena.
> - **TechniqueBar Positioning**: TechniqueBar is positioned closer to the bottom edge at 20px (mobile) / 30px (desktop) to maximize arena visibility while remaining easily reachable.
> - **No Overlap**: Clear separation between TechniqueBar, on-screen mobile controls (D-Pad / action buttons), and the "Back to Menu" button.
> - **Portrait Mode**: Full functionality in vertical orientation
> - **Touch Targets**: Minimum 48px for accessibility compliance (WCAG 2.1 Level AA)
> - **Z-Index Layering**: On-screen mobile controls (z-index 50) > TechniqueBar (45) > HUD (40)

---

## 🎯 Detailed Control Specifications

### 1. Eight Trigram Stance System (팔괘 체계)

The core of Black Trigram combat is the Eight Trigrams stance system from the I Ching (易經). Each stance has unique combat properties and techniques.

#### ☰ 1: Geon (건 - Heaven)
- **Korean Name**: 건 (Geon)
- **English**: Heaven
- **Technique**: 천둥벽력 (Thunder Strike)
- **Combat Focus**: 골격타격 (Bone-striking force)
- **Effects**: Fractures, structural damage
- **Philosophy**: Direct overwhelming power from above

#### ☱ 2: Tae (태 - Lake)
- **Korean Name**: 태 (Tae)
- **English**: Lake
- **Technique**: 유수연타 (Flowing Strike)
- **Combat Focus**: 관절조작 (Joint manipulation)
- **Effects**: Dislocations, mobility loss
- **Philosophy**: Fluid redirection like water

#### ☲ 3: Li (리 - Fire)
- **Korean Name**: 리 (Li)
- **English**: Fire
- **Technique**: 화염지창 (Fire Spear)
- **Combat Focus**: 정밀신경타격 (Precise nerve strikes)
- **Effects**: Temporary paralysis, numbness
- **Philosophy**: Precise burning intensity

#### ☳ 4: Jin (진 - Thunder)
- **Korean Name**: 진 (Jin)
- **English**: Thunder
- **Technique**: 벽력일섬 (Lightning Strike)
- **Combat Focus**: 기절기법 (Stunning techniques)
- **Effects**: Disorientation, knockouts
- **Philosophy**: Explosive shocking power

#### ☴ 5: Son (손 - Wind)
- **Korean Name**: 손 (Son)
- **English**: Wind
- **Technique**: 선풍연격 (Whirlwind Combo)
- **Combat Focus**: 지속압박 (Continuous pressure)
- **Effects**: Gradual incapacitation
- **Philosophy**: Persistent grinding assault

#### ☵ 6: Gam (감 - Water)
- **Korean Name**: 감 (Gam)
- **English**: Water
- **Technique**: 수류반격 (Flowing Counter)
- **Combat Focus**: 적응반격 (Adaptive counters)
- **Effects**: Flow reversals, escapes
- **Philosophy**: Adaptive formless response

#### ☶ 7: Gan (간 - Mountain)
- **Korean Name**: 간 (Gan)
- **English**: Mountain
- **Technique**: 반석방어 (Rock Defense)
- **Combat Focus**: 방어전문 (Defensive mastery)
- **Effects**: Blocks, deflections, counters
- **Philosophy**: Immovable defensive positioning

#### ☷ 8: Gon (곤 - Earth)
- **Korean Name**: 곤 (Gon)
- **English**: Earth
- **Technique**: 대지포옹 (Earth Embrace)
- **Combat Focus**: 지면제압 (Ground control)
- **Effects**: Throws, takedowns, locks
- **Philosophy**: Grounding and overwhelming mass

---

### 2. Archetype Technique System (기술 체계)

**Implementation**: Q-E-R-T-Y-F-G-Z-X-C keys execute archetype-specific combat techniques (3-10 per archetype)

Each player archetype has unique techniques that reflect their combat philosophy. These techniques are more powerful than basic attacks but require Ki and Stamina resources.

#### Technique Properties
- **Keyboard Shortcuts**: `Q` `E` `R` `T` `Y` `F` `G` `Z` `X` `C` (up to 10 techniques)
- **Resource Cost**: Varies by technique (8-35 stamina, 10-35 Ki)
- **Cooldown**: 4-12 seconds depending on power level
- **Damage**: 25-55 base damage (higher than basic attacks)
- **Stance Requirement**: Some techniques require specific trigram stances
- **Zero Conflicts**: Keys positioned around WASD for easy access without interfering with movement

#### Archetype Technique Examples

##### 무사 (Musa) - Traditional Warrior
| Key | Technique | Korean | Damage | Cost | Stance | Description |
|-----|-----------|--------|--------|------|--------|-------------|
| `Q` | Thunder Strike | 천둥벽력 | 25-35 | 30🔋 20⚡ | ☰ Geon | Strike with power of heaven |
| `T` | Iron Defense | 철벽방어 | 0-5 | 20🔋 15⚡ | ☶ Gan | Immovable defensive stance |
| `E` | Dragon Fist | 용권 | 30-40 | 35🔋 25⚡ | Any | Pierce through with dragon's might |
| `R` | Mountain Breaker | 파산격 | 35-50 | 40🔋 30⚡ | ☰ Geon | Devastating blow that shatters mountains |

##### 암살자 (Amsalja) - Shadow Assassin
| Key | Technique | Korean | Damage | Cost | Stance | Description |
|-----|-----------|--------|--------|------|--------|-------------|
| `Q` | Shadow Strike | 암영격 | 20-35 | 25🔋 20⚡ | ☲ Li | Strike vital points with shadow speed |
| `T` | Nerve Strike | 신경타 | 15-25 | 30🔋 25⚡ | Any | Paralyze with precise nerve strikes |
| `E` | Deadly Precision | 치명정밀 | 25-45 | 35🔋 30⚡ | ☲ Li | Attack critical points with perfect accuracy |
| `R` | Silent Death | 무음살 | 40-60 | 45🔋 35⚡ | Any | Deliver a silent, lethal strike |

#### Technique Execution Flow

1. **Select Stance** (1-8) - Choose trigram stance for bonuses
2. **Check Resources** - Ensure sufficient Stamina (🔋) and Ki (⚡)
3. **Press Technique Key** (Q-E-R-T-Y-F-G-Z-X-C) - Execute the technique
4. **Cooldown Period** - Wait 4-12 seconds before reusing (varies by technique)
5. **Resource Regeneration** - Stamina and Ki regenerate over time

**Note**: Only the first 10 techniques per archetype are assigned keyboard shortcuts. Additional techniques (if any) can be accessed via mouse/touch on the technique bar.

#### Technique UI Indicators

- **Technique Bar**: Displays available techniques with icons and shortcuts
- **Green Indicator**: Technique ready to use
- **Red Indicator**: Insufficient resources or on cooldown
- **Cooldown Timer**: Shows remaining time before technique available
- **Resource Costs**: Displays 🔋 stamina and ⚡ Ki requirements

#### ✅ Zero-Conflict Design

**New Control Scheme Eliminates ALL Conflicts**:
- **Q, E, R, T, Y**: Top row keys around WASD
- **F, G**: Middle row keys near left hand
- **Z, X, C**: Bottom row keys under left hand
- **Result**: No interference with WASD movement, no browser shortcuts, no function keys

**Left Hand Layout**:
```
[1][2][3][4][5][6][7][8]  ← Stances
   [Q][W][E][R][T][Y]     ← Techniques (Q,E,R,T,Y) + Movement (W)
    [A][S][D][F][G]       ← Movement (A,S,D) + Techniques (F,G)
     [Z][X][C][V][B]      ← Techniques (Z,X,C) + Vital Points (V) + Block (B)
      [Space]             ← Attack
```

---

### 3. Movement Controls (이동 조작)

#### 3.1 Basic Movement

**WASD or Arrow Keys** - 8-directional movement
- **W / ↑**: Forward | 전진 (Jeonjin)
- **S / ↓**: Backward | 후퇴 (Hutoe)
- **A / ←**: Left | 좌 (Jwa)
- **D / →**: Right | 우 (U)
- **Diagonals**: Combine keys for 45° angles | 대각선 이동 (Daegakseon Idong)

#### 3.2 Tactical Steps (전술보법 - Shift+WASD)

**Shift + WASD** - Precise 30cm tactical repositioning (18 frames, 300ms)

Tactical steps execute committed footwork movements for positional advantage:

| **Input** | **Direction** | **Korean** | **Distance** | **Duration** |
|-----------|---------------|------------|--------------|--------------|
| `Shift+W` | Forward Step | 전진보법 | 30cm | 300ms |
| `Shift+S` | Retreat Step | 후퇴보법 | 30cm | 300ms |
| `Shift+A` | Left Step | 좌측면보법 | 30cm | 300ms |
| `Shift+D` | Right Step | 우측면보법 | 30cm | 300ms |
| `Shift+W+A` | Forward-Left | 전좌측보법 | 30cm | 300ms |
| `Shift+W+D` | Forward-Right | 전우측보법 | 30cm | 300ms |
| `Shift+S+A` | Back-Left | 후좌측보법 | 30cm | 300ms |
| `Shift+S+D` | Back-Right | 후우측보법 | 30cm | 300ms |

**Tactical Step Properties:**
- ✅ **Non-interruptible**: Committed movement (Priority 5)
- ✅ **Guard maintained**: Fighting stance preserved
- ✅ **Stamina cost**: 5 stamina per step
- ✅ **Precise distance**: Exactly 30cm (one foot width)

#### 3.3 Advanced Footwork Patterns (보법 체계 - Ctrl+WASD)

**Ctrl + WASD** - Specialized Korean martial arts footwork patterns

Advanced footwork adds 4 distinct movement patterns for tactical combat positioning:

##### Circular Steps (원형보 - Wonhyeongbo) ✅ IMPLEMENTED
Lateral movement while maintaining guard facing forward.

| **Input** | **Pattern** | **Korean** | **Distance** | **Duration** |
|-----------|-------------|------------|--------------|--------------|
| `Ctrl+A` | Circular Left | 원형보 좌 | 30cm lateral | 300ms (18 frames) |
| `Ctrl+D` | Circular Right | 원형보 우 | 30cm lateral | 300ms (18 frames) |

**Circular Step Properties:**
- 🎯 **Maintains guard facing**: Body stays oriented toward opponent
- ⚡ **Non-interruptible**: Committed footwork (Priority 5)
- 🥋 **Tactical advantage**: Circle around opponent while keeping guard
- 📊 **Same distance as tactical steps**: 30cm movement

##### Slide Steps (미끄럼보 - Mikkeureombo) ✅ IMPLEMENTED
Both feet move together without weight transfer.

| **Input** | **Pattern** | **Korean** | **Distance** | **Duration** |
|-----------|-------------|------------|--------------|--------------|
| `Ctrl+W` | Slide Forward | 미끄럼보 전 | 30cm | 200ms (12 frames) |
| `Ctrl+S` | Slide Back | 미끄럼보 후 | 30cm | 200ms (12 frames) |

**Slide Step Properties:**
- 🏃 **Faster than tactical steps**: 200ms vs 300ms
- 🔄 **Interruptible**: Can be canceled (Priority 4)
- ⚖️ **Stable base**: Both feet move together
- 🎯 **Good for spacing**: Quick in/out without commitment

##### Pivot Rotations (축족회전 - Chukjok Hoejeon) ⏳ PENDING CONTROLS
90° rotation on planted foot for angle changes.

| **Input** | **Pattern** | **Korean** | **Rotation** | **Duration** |
|-----------|-------------|------------|--------------|--------------|
| _Future Enhancement_ | Pivot Left | 축족회전 좌 | 90° counter-clockwise | 250ms (15 frames) |
| _Future Enhancement_ | Pivot Right | 축족회전 우 | 90° clockwise | 250ms (15 frames) |

**Pivot Properties:**
- 🔄 **Fast direction change**: 90° rotation in 250ms
- 🎯 **Planted foot stays**: One foot is pivot point
- ⚡ **Non-interruptible**: Committed rotation (Priority 5)
- 🥋 **Tactical repositioning**: Change facing without retreating
- ⚠️ **Status**: Skeletal animations complete, keyboard controls pending

##### Shuffle Step (섞음보 - Seokkeumbo) ⏳ PENDING CONTROLS
Quick 15cm micro-adjustment for fine positioning.

| **Input** | **Pattern** | **Korean** | **Distance** | **Duration** |
|-----------|-------------|------------|--------------|--------------|
| _Future Enhancement_ | Shuffle | 섞음보 | 15cm omnidirectional | 100ms (6 frames) |

**Shuffle Properties:**
- ⚡ **Fastest footwork**: Only 100ms (6 frames)
- 🎯 **Micro-adjustment**: Half the distance of other steps (15cm)
- 🔄 **Fully interruptible**: Can cancel anytime (Priority 3)
- 🏃 **Fine-tuning**: Perfect for precise positioning
- ⚠️ **Status**: Skeletal animations complete, keyboard controls pending

##### Footwork Pattern Comparison

| Pattern | Korean | Frames | Duration | Distance | Priority | Interruptible | Use Case |
|---------|--------|--------|----------|----------|----------|---------------|----------|
| **Tactical Step** | 전술보법 | 18 | 300ms | 30cm | 5 | ❌ | Standard repositioning |
| **Circular** | 원형보 | 18 | 300ms | 30cm | 5 | ❌ | Lateral while maintaining guard |
| **Pivot** | 축족회전 | 15 | 250ms | 90° | 5 | ❌ | Fast angle changes ⚠️ _Controls pending_ |
| **Slide** | 미끄럼보 | 12 | 200ms | 30cm | 4 | ✅ | Quick in/out spacing |
| **Shuffle** | 섞음보 | 6 | 100ms | 15cm | 3 | ✅ | Micro-adjustments ⚠️ _Controls pending_ |

**Movement Control Philosophy:**
- **Regular WASD**: Continuous movement, no commitment
- **Shift+WASD**: Tactical steps with commitment (30cm)
- **Ctrl+A/D**: Circular footwork (lateral movement)
- **Ctrl+W/S**: Slide footwork (quick spacing)
- **Note**: Pivot and Shuffle controls TBD (animations ready, awaiting keybinding)

---

**Current Implementation**: Simple 8-directional movement on arena grid

| **Keys** | **Action** | **Description** |
|----------|------------|-----------------|
| `W` or `↑` | Move Up/North | Move one grid cell north |
| `A` or `←` | Move Left/West | Move one grid cell west |
| `S` or `↓` | Move Down/South | Move one grid cell south |
| `D` or `→` | Move Right/East | Move one grid cell east |
| `W+A` or `↖` | Move Northwest | Diagonal movement northwest |
| `W+D` or `↗` | Move Northeast | Diagonal movement northeast |
| `S+A` or `↙` | Move Southwest | Diagonal movement southwest |
| `S+D` or `↘` | Move Southeast | Diagonal movement southeast |

**Movement Properties**:
- Speed varies by stance (fast stances: Geon/Son, slow stances: Gon/Jin)
- Stamina cost: 5-7 per cell moved
- Animation: 8-10 frames per movement
- Boundaries: Octagonal arena with out-of-bounds detection

---

### 3. Combat Actions (전투 조작)

#### Attack (Space)
- **Key**: `Spacebar`
- **Korean**: 공격 (Gonggyeok)
- **Function**: Execute the current stance's primary technique
- **Properties**:
  - Damage determined by stance and vital point targeting
  - Stamina cost: 8-15 depending on technique
  - Animation frames: 12-20
  - Range: Melee (adjacent cells)
  - Can be blocked or parried

#### Block/Guard (B)
- **Key**: `B`
- **Korean**: 방어 (Bang-eo)
- **Function**: Enter defensive guard position
- **Properties**:
  - Reduces incoming damage by stance-specific percentage
  - Stamina cost: 3 (tap) or 2/sec (hold)
  - Vital Resistance Bonus: +15-30% depending on stance
  - Best stances for blocking: Gan (Mountain), Gon (Earth)

---

### 4. Special Features (특수 기능)

#### Vital Points Overlay (V)
- **Key**: `V`
- **Korean**: 급소 표시 (Geupso Pyosi)
- **Function**: Toggle anatomical vital point overlay
- **Features**:
  - Shows all 70 authentic vital points
  - Filter by severity (Lethal, Critical, Major, Moderate, Minor)
  - Filter by body region (Head, Torso, Arms, Legs)
  - Search by Korean or English name
  - Scale adjustment (0.5x - 2.0x)
  - Label toggle
  - Animation toggle

#### Pause/Menu (ESC or M)
- **Keys**: `ESC` or `M`
- **Korean**: 일시정지 (Ilsijeongji)
- **Function**: Pause game or return to menu
- **Options in Pause Menu**:
  - Resume (다시 시작)
  - Restart Match (재시합)
  - Return to Menu (메뉴로 돌아가기)
  - Audio Volume Controls

---

### 5. Mobile Touch Controls (모바일 터치 조작)

Black Trigram provides comprehensive touch controls optimized for mobile devices (375x667px and larger).

#### Virtual D-Pad (가상 방향키)
- **Location**: Bottom-left corner
- **Size**: 140x140px total, 48x48px buttons
- **Function**: 8-directional movement
- **Safe Area**: 34px from bottom for iOS/Android notches
- **Haptic Feedback**: Light vibration (10ms) on direction press

#### Action Buttons (행동 버튼)
- **Location**: Bottom-right corner
- **Attack Button**:
  - Size: 80x80px
  - Icon: ⚡ (Gold)
  - Function: Execute stance technique
  - Haptic: Medium vibration (50ms)
- **Block Button**:
  - Size: 70x70px
  - Icon: 🛡️ (Blue)
  - Function: Activate guard
  - Haptic: Medium vibration (50ms)

#### Stance Wheel (자세 휠)
- **Location**: Bottom-center
- **Size**: 200px diameter when expanded
- **Function**: Select one of 8 trigram stances
- **Layout**: Circular with 8 trigram symbols
- **Activation**: Tap to expand, tap symbol to select
- **Korean Names**: 건 태 리 진 손 감 간 곤
- **Haptic**: Light vibration (10ms) on selection

#### Gesture Controls (제스처 조작)
- **Swipe Right** (→): Advance/forward dash
- **Swipe Left** (←): Retreat/backward dash
- **Swipe Up** (↑): High attack/jump attack
- **Swipe Down** (↓): Low attack/sweep
- **Two-Finger Tap**: Toggle vital point overlay

#### Mobile Haptic Feedback
- **Light** (10ms): Menu navigation, D-pad movement
- **Medium** (50ms): Attack execution, block activation
- **Heavy** (100ms): Critical hits, vital point strikes, match events

---

## 🚧 Future Control Enhancements (Planned)

The following controls are documented in `game-design.md` but **NOT YET IMPLEMENTED**. They are planned for future releases.

### Advanced Footwork System (PLANNED)

#### Swap Front Foot (X)
- **Status**: 🚧 Not Implemented
- **Key**: `X`
- **Function**: Mirror stance by swapping which foot is forward
- **Properties**:
  - Stamina cost: 2
  - Frames: 6
  - No position change
  - Changes attack/defense angles

#### Short Step (Z + Arrow)
- **Status**: 🚧 Not Implemented
- **Keys**: `Z` + Direction Arrow
- **Function**: Move one cell while keeping current front foot forward
- **Properties**:
  - Stamina cost: 5
  - Frames: 10
  - No auto-pivot
  - Maintains attack angle

#### Step & Swap (X + Arrow)
- **Status**: 🚧 Not Implemented
- **Keys**: `X` + Direction Arrow
- **Function**: Mirror foot, then move one cell
- **Properties**:
  - Stamina cost: 10
  - Frames: 14
  - Changes both position and foot
  - Full orientation change

### Advanced Attack System (PLANNED)

#### Directional Attacks (PLANNED)
- **Space + ↑**: Front-leg kick (12 stamina, 16 frames)
- **Space + ←**: Front-elbow strike (10 stamina, 14 frames)
- **Space + ↓**: Front-knee strike (10 stamina, 14 frames)
- **Space + →**: Back-hand strike (9 stamina, 13 frames)

#### Rotational Backcast (PLANNED)
- **Keys**: `Space` then `↓` in same frame
- **Function**: 180° pivot + spinning back strike
- **Properties**:
  - Stamina cost: 15
  - Frames: 20 (10 pivot + 10 strike)
  - Full position reversal

#### Queued Attacks (PLANNED)
- **Keys**: Hold `Space+Arrow` during movement
- **Function**: Queue attack to execute immediately after movement lands
- **Properties**:
  - Reduces reaction time
  - Enables smooth combos

---

## ⚙️ Control Customization

### Current State
- Controls are **hardcoded** with defaults defined in `src/utils/controlMapping.ts`
- No in-game customization UI currently available
- LocalStorage persistence implemented but not exposed to users

### Planned Customization Features
- [ ] In-game control remapping UI
- [ ] Preset control schemes (Classic, FPS-style, Fighting Game)
- [ ] Gamepad support with customization
- [ ] Control conflict detection and resolution
- [ ] Export/import control configurations

---

## 🎮 Control Design Philosophy

### Principles
1. **Accessibility First**: All actions available via keyboard, mouse, touch, and gamepad
2. **No Hidden Inputs**: All controls clearly documented and discoverable
3. **Muscle Memory**: Consistent key positions across all screens
4. **Cultural Respect**: Korean terminology and philosophy integrated authentically
5. **60fps Responsive**: All inputs processed at 60Hz with minimal latency

### Korean Martial Arts Integration
- **8 Stances** based on I Ching trigrams (팔괘)
- **70 Vital Points** from Korean martial arts anatomy (급소)
- **Authentic Techniques** with Korean and English names
- **Philosophy-Driven**: Each stance embodies a natural element's combat principle

---

## 📱 Platform-Specific Notes

### Desktop
- ✅ Full keyboard support
- ✅ Mouse support for menus
- ⚠️ Gamepad support planned but not implemented
- Target: 60fps at 1920x1080

### Mobile
- ✅ Touch controls (375x667px minimum)
- ✅ Gesture recognition
- ✅ Haptic feedback
- ✅ Safe area aware (iOS/Android notches)
- Target: 30-60fps on mid-range devices

### Tablet
- ✅ Touch controls scaled for larger screens
- ✅ Landscape and portrait modes
- ⚠️ Stylus support planned
- Target: 60fps at 1024x768+

---

## 🧪 Testing Controls

### Manual Testing Checklist
- [ ] All 8 stances accessible via 1-8 keys
- [ ] WASD and Arrow keys both work for movement
- [ ] Spacebar executes attacks in all stances
- [ ] B key activates block in all stances
- [ ] V key toggles vital points overlay
- [ ] ESC and M both open pause menu
- [ ] Mobile D-pad responds to all 8 directions
- [ ] Mobile attack/block buttons responsive
- [ ] Mobile stance wheel selects all 8 stances
- [ ] Gesture recognition works (swipes, two-finger tap)
- [ ] Haptic feedback triggers correctly

### Automated Testing
- Control mapping tests: `src/utils/controlMapping.test.ts`
- Keyboard controls tests: `src/hooks/useKeyboardControls.test.ts`
- Combat controls tests: `src/components/combat/components/CombatControlsPanel.test.tsx`
- Mobile controls tests: `src/components/mobile/ActionButtons.test.tsx`

---

## 📖 References

### Code Implementation
- **Control Mapping**: `src/utils/controlMapping.ts`
- **Combat Controls**: `src/systems/types.ts` (line 744: `COMBAT_CONTROLS`)
- **Keyboard Hooks**: `src/hooks/useKeyboardControls.ts`
- **Mobile Controls**: `src/components/mobile/*`
- **Controls Screen**: `src/components/screens/controls/ControlsScreen3D.tsx`

### Documentation
- **Game Design**: `game-design.md` (lines 939-1133: Combat Controls & Stamina)
- **README Controls**: `README.md` (lines 213-287: Combat Controls section)
- **Game Status**: `game-status.md` (Overall implementation: 7.9/10)

### Testing
- **E2E Controls Test**: `cypress/e2e/screens/controls-screen.cy.ts`
- **Combat Screen Test**: `cypress/e2e/screens/combat-screen.cy.ts`
- **Unit Tests**: Multiple files in `src/` directories

---

## 📝 Version History

| Version | Date | Changes |
|---------|------|---------|
| 0.5.44 | Jan 2026 | **✅ FIXED: Arrow key bug** - ArrowUp now moves UP, ArrowDown moves DOWN (inverted forward mapping). Enhanced ControlsScreen with complete documentation including techniques, movement, and special features. |
| 0.5.37 | Jan 2026 | **Zero-conflict control redesign**: Technique keys changed from Q-W-E-R-T-Y-U-I-O-P to Q-E-R-T-Y-F-G-Z-X-C to eliminate WASD movement conflicts |
| 0.5.37 | Jan 2026 | Initial comprehensive controls documentation |
| 0.5.36 | Dec 2025 | Vital points overlay (V key) implemented |
| 0.5.30 | Nov 2025 | Mobile touch controls complete |
| 0.5.20 | Oct 2025 | Eight trigram stances finalized |

---

## 💡 Tips for Players

### Combat Effectiveness
- **Master Stances**: Each trigram has strengths against specific body regions
- **Mix Movement**: Don't just face-tank - positioning matters
- **Block Timing**: Tap B right before impact for bonus resistance
- **Vital Points**: Press V to study anatomy and target critical zones
- **Stance Cycling**: 1-8 keys cycle quickly - find your flow

### Mobile Players
- **Two-Handed**: Use D-pad with left thumb, buttons with right
- **Swipe Combos**: Combine swipes with button taps for variety
- **Stance Wheel**: Master quick taps - don't hold the wheel open
- **Haptics**: Feel the feedback - it tells you when inputs register

---

**흑괘의 길을 걸어라** - _Walk the Path of the Black Trigram_

🥋 Master the controls. Master the combat. Master the art. 🥋