Class AIDecisionTree

AI Decision Tree System

Korean Combat Philosophy (한국 무술 철학): This system embodies traditional Korean martial arts principles:

팔괘 응용 (Trigram Application): Uses Eight Trigram system for stance transitions
급소 타격 (Vital Point Strikes): Targets anatomical weak points with precision
상황 판단 (Situational Awareness): Adapts tactics based on combat context
기술 조합 (Technique Combinations): Chains attacks into flowing combos
방어 우선 (Defense First): Prioritizes survival and tactical retreat when needed
취약성 공략 (Vulnerability Exploitation): Exploits defenseless states with precision (Issue #enhance-intelligence-operative-ai)

Index

Constructors

Properties

consecutiveAttacks currentReactionDelay decisionCooldown difficultyLevel difficultyParams? lastDecisionTime lastPressureActionTime lastStanceChange psychologicalPressure stanceChangeCooldown trigramSystem ARENA_MARGIN_X ARENA_MARGIN_Y FATIGUE_OVERRIDE_SCALING_FACTOR MIN_DISTANCE_THRESHOLD MOVE_STEP_SIZE

Constructors

constructor

new AIDecisionTree(): AIDecisionTree
Returns AIDecisionTree
- Defined in systems/ai/DecisionTree.ts:205

Methods

`Private`applyJeongboExploitation

applyJeongboExploitation(
    weights: {
        approach: number;
        attack: number;
        circle: number;
        defend: number;
        feint: number;
        technique: number;
    },
    vulnerability: VulnerabilityContext,
    personality: AIPersonality,
): {
    approach: number;
    attack: number;
    circle: number;
    defend: number;
    feint: number;
    technique: number;
}
Apply Intelligence Operative (Jeongbo Yowon) vulnerability exploitation

Enhances decision weights to exploit opponent's defenseless states with precision:
- HELPLESS (balance === HELPLESS): 90% takedown priority - Execute precision takedown
- VULNERABLE (balance === VULNERABLE): 70% aggressive attack - Sustained pressure tactics
- SHAKEN (balance === SHAKEN): 50% pressure increase - Psychological warfare
- Low Stamina (< 20%): 60% exploitation - Force defensive positions
- No Ki (< 10%): 50% technique spam - Prevent powerful techniques
Multiplier Stacking Behavior: When multiple vulnerabilities are present, multipliers stack multiplicatively:
- VULNERABLE (2.0x attack) + low stamina (1.5x attack) = 3.0x total attack multiplier
- VULNERABLE (1.8x technique) + low ki (1.4x technique) = 2.52x total technique multiplier This creates increasingly aggressive exploitation as opponent becomes more vulnerable. Note: HELPLESS state uses exclusive else-if, so it doesn't stack with VULNERABLE/SHAKEN.
Jeongbo Philosophy (정보요원 전략):
- Knowledge through observation (관찰을 통한 지식)
- Psychological manipulation (심리적 조작)
- Precise timing (정확한 타이밍)
- Strategic exploitation (전략적 공략)
This function provides 3x higher vulnerability exploitation rate than Musa, 2x higher psychological warfare usage than Amsalja, and 5x higher takedown success rate when opponent is HELPLESS.
Parameters
- weights: {
      approach: number;
      attack: number;
      circle: number;
      defend: number;
      feint: number;
      technique: number;
  }
  Base action weight multipliers
- vulnerability: VulnerabilityContext
  Vulnerability assessment context
- personality: AIPersonality
  AI personality archetype
Returns {
    approach: number;
    attack: number;
    circle: number;
    defend: number;
    feint: number;
    technique: number;
}
Modified action weights for Jeongbo exploitation

Korean
정보요원 취약성 공략
- Defined in systems/ai/DecisionTree.ts:406

`Private`applyKillModeModifiers

applyKillModeModifiers(
    baseWeights: {
        attack: number;
        defend: number;
        retreat: number;
        technique: number;
    },
    personality: AIPersonality,
    isKillMode: boolean,
): { attack: number; defend: number; retreat: number; technique: number }
Apply kill mode modifiers to action weights for finishing behavior

Kill Mode Behavior (결정타 행동): Each archetype has unique finishing behavior based on combat philosophy:
- Musa: All-in overwhelming force (2.5x attack, 0x retreat)
- Amsalja: Instant takedown focus (3.0x technique, feints disabled)
- Hacker: Analytical precision (2.0x technique, counter focus)
- Jeongbo Yowon: Strategic control (1.8x technique, balanced approach)
- Jojik Pokryeokbae: Brutal pragmatism (2.2x attack, dirty tactics)
Parameters
- baseWeights: { attack: number; defend: number; retreat: number; technique: number }
  Base action weight multipliers
- personality: AIPersonality
  AI personality archetype
- isKillMode: boolean
  Whether kill mode is active
Returns { attack: number; defend: number; retreat: number; technique: number }
Modified action weights for kill mode

Korean
결정타 모드 가중치 적용
- Defined in systems/ai/DecisionTree.ts:315

`Private`buildPsychologicalPressure

buildPsychologicalPressure(actionType: AIActionType, now: number): void
Build psychological pressure through intimidation tactics

Intelligence Operative uses feints, circling, and approach/retreat patterns to build cumulative psychological pressure on opponent. When pressure reaches 50+ and opponent is VULNERABLE, triggers decisive strike.

Psychological Tactics (심리전 전술):
- Feints: +10 pressure (fake attacks create hesitation)
- Circling: +5 pressure (predator circling prey)
- Approach: +3 pressure (aggressive positioning)
- Decay: -3 pressure per second (pressure fades without action)
Parameters
- actionType: AIActionType
  Type of action taken (FEINT, CIRCLE, APPROACH, etc.)
- now: number
  Current timestamp for decay calculation
Returns void
Korean
심리적 압박 증가
- Defined in systems/ai/DecisionTree.ts:481

`Private`calculateApproachPosition

calculateApproachPosition(context: CombatContext): Position
Calculate approach position
Parameters
- context: CombatContext
Returns Position
- Defined in systems/ai/DecisionTree.ts:1934

`Private`calculateCirclePosition

calculateCirclePosition(context: CombatContext): Position
Calculate circle position
Parameters
- context: CombatContext
Returns Position
- Defined in systems/ai/DecisionTree.ts:1950

`Private`calculateDirectApproach

calculateDirectApproach(
context: CombatContext,
killModeActive?: boolean,
): Position
Calculate direct approach position (straight line to opponent) Used primarily by Musa archetype for charging attacks

Kill Mode Enhancement (결정타 돌격):
- Larger step size for faster closing with leg shifts
- Aggressive stride pattern for maximum forward momentum
Parameters
- context: CombatContext
  Combat context
- killModeActive: boolean = false
  Whether kill mode is active
Returns Position
- Defined in systems/ai/DecisionTree.ts:1664

`Private`calculateFlankingApproach

calculateFlankingApproach(
context: CombatContext,
killModeActive?: boolean,
): Position
Calculate flanking approach position (diagonal/side approach) Used primarily by Amsalja archetype for stealth positioning

Kill Mode Enhancement (결정타 측면 공격):
- Tighter flanking angle for more aggressive positioning
- Swift stepping pattern for rapid side movement
Parameters
- context: CombatContext
  Combat context
- killModeActive: boolean = false
  Whether kill mode is active
Returns Position
- Defined in systems/ai/DecisionTree.ts:1701

`Private`calculateRetreatPosition

calculateRetreatPosition(context: CombatContext): Position
Calculate retreat position
Parameters
- context: CombatContext
Returns Position
- Defined in systems/ai/DecisionTree.ts:1900

`Private`clampToArenaBounds

clampToArenaBounds(
position: Position,
arenaBounds: { height: number; width: number; x: number; y: number },
): Position
Clamp position to arena boundaries with proper margins Centralizes boundary validation logic for all movement calculations
Parameters
- position: Position
- arenaBounds: { height: number; width: number; x: number; y: number }
Returns Position
- Defined in systems/ai/DecisionTree.ts:1734

`Private`decideComboAction

decideComboAction(
_context: CombatContext,
_personality: AIPersonality,
): AIDecision
Decide combo action
Parameters
- _context: CombatContext
- _personality: AIPersonality
Returns AIDecision
- Defined in systems/ai/DecisionTree.ts:1886

`Private`evaluateApproach

evaluateApproach(
    context: CombatContext,
    personality: AIPersonality,
    killModeActive?: boolean,
): AIDecision
Evaluate approach tactics with archetype-specific behavior

Korean Philosophy (접근 전략):
- Musa charges directly (70% direct path)
- Amsalja uses flanking movements (40% diagonal approach)
- Hacker maintains optimal distance (prefers not to close too much)
Kill Mode Enhancement (결정타 접근): All archetypes enhance movement speed in kill mode based on combat philosophy:
- Musa: Direct charging with leg shifts for maximum speed (40% faster)
- Amsalja: Swift stepping patterns for rapid positioning (30% faster)
- Hacker: Calculated approach for optimal strike position (20% faster)
- Jeongbo Yowon: Strategic positioning for control (25% faster)
- Jojik Pokryeokbae: Unpredictable rush for brutal finish (35% faster)
Parameters
- context: CombatContext
  Combat context
- personality: AIPersonality
  AI personality
- killModeActive: boolean = false
  Whether kill mode is active
Returns AIDecision
- Defined in systems/ai/DecisionTree.ts:1514

`Private`evaluateCloseRange

evaluateCloseRange(
    context: CombatContext,
    personality: AIPersonality,
    killModeActive?: boolean,
): AIDecision
Evaluate close range tactics with vital point targeting

Korean Philosophy (급소 공격): At close range, AI targets specific vital points based on difficulty level. Higher difficulty = more precise targeting of critical points.

Kill Mode Enhancement (결정타): When kill mode is active, AI prioritizes finishing techniques with boosted priority.
Parameters
- context: CombatContext
  Combat context
- personality: AIPersonality
  AI personality
- killModeActive: boolean = false
  Whether kill mode is active (opponent <30% health or vulnerable)
Returns AIDecision
- Defined in systems/ai/DecisionTree.ts:1292

`Private`evaluateComboStart

evaluateComboStart(
    context: CombatContext,
    personality: AIPersonality,
    comboSystem: AIComboSystem,
): AIDecision
Evaluate combo initiation (fix for issue #2529467014)
Parameters
- context: CombatContext
- personality: AIPersonality
- comboSystem: AIComboSystem
Returns AIDecision
- Defined in systems/ai/DecisionTree.ts:993

`Private`evaluateCounter

evaluateCounter(
    context: CombatContext,
    personality: AIPersonality,
    killModeActive?: boolean,
): AIDecision
Evaluate counter-attack opportunity

Kill Mode Enhancement (결정타 반격): All archetypes enhance counter behavior during kill mode based on philosophy:
- Musa: Increased counter frequency (honor demands swift response)
- Amsalja: Enhanced counter timing with precision strikes
- Hacker: Calculated counter-attacks (analytical opportunity)
- Jeongbo Yowon: Strategic counters (psychological advantage)
- Jojik Pokryeokbae: Opportunistic counters (dirty tactics)
Parameters
- context: CombatContext
  Combat context
- personality: AIPersonality
  AI personality
- killModeActive: boolean = false
  Whether kill mode is active
Returns AIDecision
- Defined in systems/ai/DecisionTree.ts:906

`Private`evaluateDefense

evaluateDefense(context: CombatContext, personality: AIPersonality): AIDecision
Evaluate defensive tactics
Parameters
- context: CombatContext
- personality: AIPersonality
Returns AIDecision
- Defined in systems/ai/DecisionTree.ts:1860

`Private`evaluateFeint

evaluateFeint(context: CombatContext, personality: AIPersonality): AIDecision
Evaluate feint attack
Parameters
- context: CombatContext
- personality: AIPersonality
Returns AIDecision
- Defined in systems/ai/DecisionTree.ts:1255

`Private`evaluateMidRange

evaluateMidRange(context: CombatContext, personality: AIPersonality): AIDecision
Evaluate mid-range tactics with distance awareness

Korean Philosophy (중거리 전술):
- Considers optimal range for archetype
- Hacker prefers to maintain this range (analytical pattern)
- Jeongbo uses strategic timing and analysis
- Others may close or open distance based on situation
Parameters
- context: CombatContext
- personality: AIPersonality
Returns AIDecision
- Defined in systems/ai/DecisionTree.ts:1765

`Private`evaluateStanceChange

evaluateStanceChange(
    context: CombatContext,
    personality: AIPersonality,
    now: number,
): AIDecision
Evaluate stance change using TrigramSystem and distance-based selection

Korean Philosophy (자세 전환): Uses I Ching-based trigram system to find optimal stance transitions. Considers resource costs, counter-stance effectiveness, archetype preferences, and distance-based tactical positioning.

Dynamic Stance Rotation (Issue #dynamic-ai-stance-rotation):
- Integrates distance-based stance selection for tactical variety
- Prioritizes counter-stances for opponent matchup advantage
- Expands tactical repertoire beyond archetype preferences when needed
Parameters
- context: CombatContext
- personality: AIPersonality
- now: number
Returns AIDecision
- Defined in systems/ai/DecisionTree.ts:1104

`Private`evaluateSurvival

evaluateSurvival(context: CombatContext, personality: AIPersonality): AIDecision
Evaluate survival tactics when critically low health

Korean Philosophy (생존 전략):
- Consider both health and pain levels
- Archetype affects retreat threshold and behavior
- Honor code (Musa) prevents retreat above threshold
Parameters
- context: CombatContext
- personality: AIPersonality
Returns AIDecision
- Defined in systems/ai/DecisionTree.ts:852

`Private`getArchetypeMovementBias

getArchetypeMovementBias(archetype: PlayerArchetype): number
Get archetype-specific movement bias multipliers

Applies movement pattern modifiers based on archetype behavior profiles:
- Aggressive: High forward pressure (2.0x)
- Evasive: Moderate mobility (1.5x)
- Analytical: Conservative approach (0.8x-1.0x)
- Unpredictable: Variable movement (1.3x)
Parameters
- archetype: PlayerArchetype
Returns number
Korean
원형별 이동 성향
- Defined in systems/ai/DecisionTree.ts:1636

`Private`getOptimalRange

getOptimalRange(personality: AIPersonality): number
Get optimal combat range based on AI personality archetype

Uses archetype behavior profiles to determine preferred combat distance. Range is converted from cell units to pixels (1 cell = ~40px).
Parameters
- personality: AIPersonality
Returns number
Korean
최적 전투 거리 - 원형별 선호 거리
- Defined in systems/ai/DecisionTree.ts:1484

`Private`getStanceFatigueModifier

getStanceFatigueModifier(timeInStance: number): number
Calculate stance fatigue modifier for increased switching probability

Applies time-based modifiers to encourage dynamic stance rotation:
- 0-10 seconds: No modifier (1.0x)
- 10-20 seconds: +20% increase (1.2x multiplier)
- 20+ seconds: +50% increase (1.5x multiplier)
This ensures AI doesn't stay locked in one stance for extended periods, promoting the use of all 8 trigram stances throughout combat.

Korean Philosophy (자세 피로도): Remaining in one stance too long reduces tactical flexibility and makes the fighter predictable. The Eight Trigram system requires constant adaptation and flow between stances.
Parameters
- timeInStance: number
  Time in current stance in milliseconds
Returns number
Stance switch frequency multiplier (1.0 = no change, >1.0 = increased probability)

Korean
자세 피로도 배율 계산
- Defined in systems/ai/DecisionTree.ts:1466

`Private`isKillModeActive

isKillModeActive(context: CombatContext, personality: AIPersonality): boolean
Check if kill mode should be activated based on archetype behavior

Kill mode activates when:
- Opponent health is low (<30%)
- Opponent is in vulnerable balance state (HELPLESS/VULNERABLE)
Korean Philosophy (결정타 모드): Each archetype activates kill mode differently based on combat philosophy:
- Musa: Honor demands finishing the fight decisively
- Amsalja: Opportunity for instant takedown with precision
- Hacker: Analytical window for calculated strike
- Jeongbo Yowon: Strategic opportunity for submission
- Jojik Pokryeokbae: Pragmatic moment to finish brutally
Parameters
- context: CombatContext
  Current combat context
- personality: AIPersonality
  AI personality archetype
Returns boolean
True if kill mode should be active

Korean
결정타 모드 활성화 확인
- Defined in systems/ai/DecisionTree.ts:260

makeDecision

makeDecision(
    context: CombatContext,
    personality: AIPersonality,
    comboSystem: AIComboSystem,
): AIDecision
Make strategic decision based on combat context

Applies difficulty-based reaction time delays if difficulty parameters are set
Parameters
- context: CombatContext
- personality: AIPersonality
- comboSystem: AIComboSystem
Returns AIDecision
- Defined in systems/ai/DecisionTree.ts:537

reset

reset(): void
Reset decision state

Returns void
- Defined in systems/ai/DecisionTree.ts:1969

`Private`selectStanceForDistance

selectStanceForDistance(
    distance: number,
    preferredStances: readonly TrigramStance[],
    currentStance: TrigramStance,
): TrigramStance | undefined
Select stance based on distance to opponent

Chooses optimal stance for current combat range, prioritizing:
1. Overlap between distance-optimal stances and archetype preferred stances
2. Any distance-optimal stance if no overlap exists (expands tactical repertoire)
3. Avoids switching to current stance
Distance Categories:
- CLOSE (≤2 cells / 80px): GEON, JIN, LI, SON - Aggressive close-quarters stances
- MID (3-4 cells / 120-160px): GAM, TAE, GAN - Adaptive mid-range stances
- FAR (≥5 cells / 200px+): GAN, GON - Defensive distance stances
Parameters
- distance: number
  Distance to opponent in pixels
- preferredStances: readonly TrigramStance[]
  Archetype's preferred stances
- currentStance: TrigramStance
  Current stance (to avoid redundant switches)
Returns TrigramStance | undefined
Optimal stance for distance, or undefined if no valid options

Korean
거리별 자세 선택
- Defined in systems/ai/DecisionTree.ts:1058

`Private`selectVitalPointTarget

selectVitalPointTarget(
context: CombatContext,
personality: AIPersonality,
): string | undefined
Select vital point to target based on difficulty and stance

Korean Philosophy (급소 선택):
- Beginner AI: Random targeting or no specific target
- Intermediate AI: Favors easier vital points
- Advanced AI: Targets appropriate points for current stance
- Master AI: Targets critical points with high precision
Parameters
- context: CombatContext
- personality: AIPersonality
Returns string | undefined
- Defined in systems/ai/DecisionTree.ts:1372

setDifficultyLevel

setDifficultyLevel(level: number): void
Set AI difficulty level for vital point targeting accuracy
Parameters
- level: number
  0.0 (beginner) to 1.0 (master)
Returns void
- Defined in systems/ai/DecisionTree.ts:213

setDifficultyParameters

setDifficultyParameters(params: DifficultyParameters): void
Set difficulty parameters for AI behavior Affects reaction time, accuracy, decision quality, etc.

Calculates a randomized reaction delay (within parameter range) once when parameters change. This provides varied AI timing while maintaining consistent behavior throughout the current parameter set.
Parameters
- params: DifficultyParameters
  Difficulty parameters to apply
Returns void
Korean
난이도 매개변수 설정
- Defined in systems/ai/DecisionTree.ts:228

`Private`shouldExecutePressureStrike

shouldExecutePressureStrike(vulnerability: VulnerabilityContext): boolean
Check if psychological pressure should trigger decisive strike

Jeongbo executes decisive technique when:
- Psychological pressure ≥ 50 (sustained intimidation)
- Opponent is VULNERABLE or worse (balance < 30)
- Returns true to boost technique priority
Parameters
- vulnerability: VulnerabilityContext
  Vulnerability assessment context
Returns boolean
True if pressure warrants decisive strike

Korean
심리적 압박 결정타 확인
- Defined in systems/ai/DecisionTree.ts:525

Properties

`Private`consecutiveAttacks

consecutiveAttacks: number = 0

`Private`currentReactionDelay

currentReactionDelay: number = 50

`Private`decisionCooldown

decisionCooldown: number = 50

`Private`difficultyLevel

difficultyLevel: number = 0.5

`Private` `Optional`difficultyParams

difficultyParams?: DifficultyParameters

`Private`lastDecisionTime

lastDecisionTime: number = 0

`Private`lastPressureActionTime

lastPressureActionTime: number = 0

`Private`lastStanceChange

lastStanceChange: number = 0

`Private`psychologicalPressure

psychologicalPressure: number = 0

`Private` `Readonly`stanceChangeCooldown

stanceChangeCooldown: 3000

`Private`trigramSystem

trigramSystem: TrigramSystem

`Static` `Readonly`ARENA_MARGIN_X

ARENA_MARGIN_X: 60

Arena boundary margins - exported for test validation These values represent the player character size/collision margins

`Static` `Readonly`ARENA_MARGIN_Y

ARENA_MARGIN_Y: 180

`Private` `Static` `Readonly`FATIGUE_OVERRIDE_SCALING_FACTOR

FATIGUE_OVERRIDE_SCALING_FACTOR: 0.5

Scaling factor for fatigue override probability calculation. Used to convert fatigue modifier to override chance in non-linear manner. Value of 0.5 provides gradual scaling: 1.2x fatigue → ~10% override, 1.5x → ~25%.

Korean

피로도 우선순위 무시 배율

`Private` `Static` `Readonly`MIN_DISTANCE_THRESHOLD

MIN_DISTANCE_THRESHOLD: 5

`Private` `Static` `Readonly`MOVE_STEP_SIZE

MOVE_STEP_SIZE: 50

Class AIDecisionTree

Index

Constructors

Methods

Properties

Constructors

constructor

Returns AIDecisionTree

Methods

PrivateapplyJeongboExploitation

Parameters

Returns { approach: number; attack: number; circle: number; defend: number; feint: number; technique: number;}

Korean

PrivateapplyKillModeModifiers

Parameters

Returns { attack: number; defend: number; retreat: number; technique: number }

Korean

PrivatebuildPsychologicalPressure

Parameters

Returns void

Korean

PrivatecalculateApproachPosition

Parameters

Returns Position

PrivatecalculateCirclePosition

Parameters

Returns Position

PrivatecalculateDirectApproach

Parameters

Returns Position

PrivatecalculateFlankingApproach

Parameters

Returns Position

PrivatecalculateRetreatPosition

Parameters

Returns Position

PrivateclampToArenaBounds

Parameters

Returns Position

PrivatedecideComboAction

Parameters

Returns AIDecision

PrivateevaluateApproach

Parameters

Returns AIDecision

PrivateevaluateCloseRange

Parameters

Returns AIDecision

PrivateevaluateComboStart

Parameters

Returns AIDecision

PrivateevaluateCounter

Parameters

Returns AIDecision

PrivateevaluateDefense

Parameters

Returns AIDecision

PrivateevaluateFeint

Parameters

Returns AIDecision

PrivateevaluateMidRange

Parameters

Returns AIDecision

PrivateevaluateStanceChange

Parameters

Returns AIDecision

PrivateevaluateSurvival

Parameters

Returns AIDecision

PrivategetArchetypeMovementBias

Parameters

Returns number

Korean

PrivategetOptimalRange

Parameters

Returns number

Korean

PrivategetStanceFatigueModifier

Parameters

Returns number

`Private`applyJeongboExploitation

Returns {
approach: number;
attack: number;
circle: number;
defend: number;
feint: number;
technique: number;
}

`Private`applyKillModeModifiers

`Private`buildPsychologicalPressure

`Private`calculateApproachPosition

`Private`calculateCirclePosition

`Private`calculateDirectApproach

`Private`calculateFlankingApproach

`Private`calculateRetreatPosition

`Private`clampToArenaBounds

`Private`decideComboAction

`Private`evaluateApproach

`Private`evaluateCloseRange

`Private`evaluateComboStart

`Private`evaluateCounter

`Private`evaluateDefense

`Private`evaluateFeint

`Private`evaluateMidRange

`Private`evaluateStanceChange

`Private`evaluateSurvival

`Private`getArchetypeMovementBias

`Private`getOptimalRange

`Private`getStanceFatigueModifier

`Private`isKillModeActive

`Private`selectStanceForDistance

`Private`selectVitalPointTarget

`Private`shouldExecutePressureStrike

`Private`consecutiveAttacks

`Private`currentReactionDelay

`Private`decisionCooldown

`Private`difficultyLevel

`Private` `Optional`difficultyParams

`Private`lastDecisionTime

`Private`lastPressureActionTime

`Private`lastStanceChange

`Private`psychologicalPressure

`Private` `Readonly`stanceChangeCooldown

`Private`trigramSystem

`Static` `Readonly`ARENA_MARGIN_X

`Static` `Readonly`ARENA_MARGIN_Y

`Private` `Static` `Readonly`FATIGUE_OVERRIDE_SCALING_FACTOR

`Private` `Static` `Readonly`MIN_DISTANCE_THRESHOLD

`Private` `Static` `Readonly`MOVE_STEP_SIZE