Black Trigram (흑괘) - Korean Martial Arts Combat Simulator API - v0.6.52
    Preparing search index...

    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

    constructor

    Methods

    analyzeCounterOpportunity applyJeongboExploitation applyKillModeModifiers buildPsychologicalPressure calculateApproachPosition calculateCirclePosition calculateDirectApproach calculateFlankingApproach calculateRetreatPosition clampToArenaBoundsMeters decideComboAction evaluateApproach evaluateCloseRange evaluateComboStart evaluateCounter evaluateDefense evaluateFeint evaluateLimbExposureCounter evaluateMidRange evaluateStanceChange evaluateSurvival getArchetypeCloseRange getArchetypeMaxReach getArchetypeMediumRange getArchetypeMovementBias getKickReachMeters getOptimalRange getPunchReachMeters getStanceFatigueModifier isKillModeActive makeDecision reset selectStanceForDistance selectVitalPointTarget setDifficultyLevel setDifficultyParameters shouldExecutePressureStrike translateExposedLimb

    Properties

    consecutiveAttacks currentReactionDelay decisionCooldown difficultyLevel difficultyParams? lastDecisionTime lastPressureActionTime lastStanceChange psychologicalPressure stanceChangeCooldown trigramSystem FATIGUE_OVERRIDE_SCALING_FACTOR

    Constructors

    Methods

    • Analyze counter-attack opportunity from opponent's limb exposure.

      Korean: 반격 기회 분석 (Counter Opportunity Analysis)

      Detects when the opponent has exposed limbs during technique execution, enabling defensive counter-attacks and breaking techniques.

      This integrates the LimbExposureSystem with AI decision-making by:

      1. Detecting exposed limbs from opponent's current technique
      2. Calculating vulnerability windows and multipliers
      3. Providing counter opportunity data for decision prioritization

      Parameters

      • context: CombatContext

        Combat context with opponent technique data

      Returns { counterOpportunity?: CounterOpportunity; opponentVulnerability: number }

      Enhanced context with counter opportunity analysis, or undefined if no opportunity

      Returns undefined if:

      • Opponent is not executing a technique
      • Technique has no exposure window defined
      • Current time is outside the exposure window

      반격기회분석

    • 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

      정보요원 취약성 공략

    • 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

      결정타 모드 가중치 적용

    • 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

      심리적 압박 증가

    • 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

      Physics-First: All calculations in METERS.

      Parameters

      • context: CombatContext

        Combat context

      • killModeActive: boolean = false

        Whether kill mode is active

      Returns 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

      Physics-First: All calculations in METERS.

      Parameters

      • context: CombatContext

        Combat context

      • killModeActive: boolean = false

        Whether kill mode is active

      Returns Position

    • Clamp position to arena boundaries with proper margins Centralizes boundary validation logic for all movement calculations

      Physics-First: Works entirely in METERS using worldWidthMeters/worldDepthMeters. Arena is centered at origin (0,0), so bounds are -halfWidth to +halfWidth.

      Parameters

      • position: Position

        Position to clamp (in meters)

      • context: CombatContext

        Combat context with arena dimensions in meters

      Returns Position

    • 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

    • 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

    • 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

    • Evaluate counter-attack opportunity from limb exposure.

      Korean: 사지 노출 반격 평가 (Limb Exposure Counter Evaluation)

      Analyzes opportunities to exploit opponent's exposed limbs during technique execution. This is higher priority than standard counters because it targets specific anatomical vulnerabilities.

      Defensive Archetype Priority: Defensive archetypes (high defensiveness) strongly favor counter-attacks:

      • Musa: Honorable defense with precise counters (defensiveness ~0.7)
      • Amsalja: Patient assassin waiting for openings (defensiveness ~0.6)
      • Jeongbo Yowon: Analytical exploitation of weaknesses (defensiveness ~0.5)

      Breaking Techniques: When allowsBreaking is true, AI can execute joint locks and limb breaks for severe damage and mobility reduction.

      Parameters

      • context: CombatContext

        Combat context with positioning

      • personality: AIPersonality

        AI personality with archetype and defensiveness

      • counterOpportunity: CounterOpportunity

        Detected limb exposure opportunity

      • opponentVulnerability: number

        Opponent's vulnerability multiplier

      Returns AIDecision

      Counter-attack decision with priority based on archetype

      사지노출반격평가

    • 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

      Returns AIDecision

    • Get close range threshold for an archetype (punching/elbow distance). Based on arm length from physical attributes.

      Uses the shared punch reach calculation helper for consistency.

      TODO: Extract to shared utility function with PhysicalReachCalculator.ts to maintain consistency between AI range calculations and actual hit detection. Consider handling elbow techniques separately with different body pivot values.

      Parameters

      Returns number

      Close range threshold in meters

      근접 범위 (미터)

    • Calculate maximum combat reach for an archetype based on physical attributes.

      Physics-First: Returns reach in METERS based on leg length. Kicks have the longest reach (~1.0-1.3m with body pivot contribution).

      Note: This is a heuristic approximation. Actual reach also depends on stance modifiers and animation timing not included in AI range calculations.

      Parameters

      Returns number

      Maximum combat reach in meters

      원형별 최대 도달 거리 (미터)

    • Get medium range threshold for an archetype (kicking distance). Based on leg length from physical attributes.

      Includes realistic kick reach calculation:

      • Leg length converted from cm to meters
      • Body pivot contribution (hip rotation + torso lean)
      • Average baseExtension for kicks

      Parameters

      Returns number

      Medium range threshold in meters

      중거리 범위 (미터)

    • 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

      Returns number

      원형별 이동 성향

    • Calculate kick reach for an archetype based on physical attributes.

      Physics-First: Returns reach in METERS based on leg length. Includes realistic kick reach calculation:

      • Leg length converted from cm to meters
      • Body pivot contribution (hip rotation + torso lean)
      • Average baseExtension for kicks (1.05x multiplier)

      Formula: (legLength/100 + BODY_PIVOT_METERS.KICK) × TECHNIQUE_EXTENSION.KICK

      Parameters

      Returns number

      Kick reach in meters

      발차기 도달 거리 (미터)

    • Get optimal combat range based on AI personality archetype

      Uses archetype behavior profiles to determine preferred combat distance. Physics-First: Returns distance in METERS directly.

      Parameters

      • personality: AIPersonality

        AI personality with archetype behavior

      • Optional_context: CombatContext

        Combat context (unused, kept for API compatibility)

      Returns number

      Optimal range in meters

      최적 전투 거리 - 원형별 선호 거리 (미터)

    • Calculate punch reach for an archetype based on physical attributes.

      Physics-First: Returns reach in METERS based on arm length. Includes realistic punch reach calculation:

      • Arm length converted from cm to meters
      • Body pivot (shoulder offset + torso rotation)
      • Average baseExtension for punches (0.95x multiplier)

      Formula: (armLength/100 + shoulderOffset + torsoRotation) × TECHNIQUE_EXTENSION.PUNCH

      Parameters

      Returns number

      Punch reach in meters

      주먹 도달 거리 (미터)

    • 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)

      자세 피로도 배율 계산

    • 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

      Returns boolean

      True if kill mode should be active

      결정타 모드 활성화 확인

    • 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 meters

      • preferredStances: readonly TrigramStance[]

        Archetype's preferred stances

      • currentStance: TrigramStance

        Current stance (to avoid redundant switches)

      • archetype: PlayerArchetype

      Returns TrigramStance | undefined

      Optimal stance for distance, or undefined if no valid options

      거리별 자세 선택

      Physics-First: Distance parameter is in METERS.

    • 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

      Returns string | undefined

    • Set AI difficulty level for vital point targeting accuracy

      Parameters

      • level: number

        0.0 (beginner) to 1.0 (master)

      Returns 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

      Returns void

      난이도 매개변수 설정

    • 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

      Returns boolean

      True if pressure warrants decisive strike

      심리적 압박 결정타 확인

    • Translate exposed limb type to Korean.

      Korean: 노출 사지 번역 (Exposed Limb Translation)

      Parameters

      Returns string

      Korean translation

      노출사지번역

    Properties

    consecutiveAttacks: number = 0
    currentReactionDelay: number = 50
    decisionCooldown: number = 50
    difficultyLevel: number = 0.5
    difficultyParams?: DifficultyParameters
    lastDecisionTime: number = 0
    lastPressureActionTime: number = 0
    lastStanceChange: number = 0
    psychologicalPressure: number = 0
    stanceChangeCooldown: 3000
    trigramSystem: TrigramSystem
    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%.

    피로도 우선순위 무시 배율

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods
    Properties