blacktrigram 0.7.2

package/lib/systems/TrigramSystem.js

@@ -0,0 +1,512 @@
+import { TrigramStance } from "../types/common.js";
+import { TRIGRAM_STANCES_ORDER } from "./trigram/types.js";
+import { PLAYER_ARCHETYPES_DATA } from "./types.js";
+import { TrigramCalculator } from "./trigram/TrigramCalculator.js";
+import "./trigram/index.js";
+//#region src/systems/TrigramSystem.ts
+/**
+* Stance counter relationships based on I Ching philosophy
+* 
+* Each stance has a counter stance that provides tactical advantage:
+* - **GEON (Heaven)** countered by **GAM (Water)** - Water flows around Heaven's force
+* - **TAE (Lake)** countered by **GON (Earth)** - Earth contains and grounds Lake
+* - **LI (Fire)** countered by **SON (Wind)** - Wind disperses Fire's intensity
+* - **JIN (Thunder)** countered by **GAN (Mountain)** - Mountain absorbs Thunder's impact
+* - **SON (Wind)** countered by **GEON (Heaven)** - Heaven's force overpowers Wind
+* - **GAM (Water)** countered by **TAE (Lake)** - Lake contains and channels Water
+* - **GAN (Mountain)** countered by **LI (Fire)** - Fire melts Mountain's solidity
+* - **GON (Earth)** countered by **JIN (Thunder)** - Thunder breaks Earth's stability
+* 
+* Using a counter stance provides a 1.2x damage multiplier in combat.
+* 
+* @korean 팔괘 상극 관계 (Eight Trigram Counter Relationships)
+*/
+var STANCE_COUNTERS = {
+	[TrigramStance.GEON]: TrigramStance.GAM,
+	[TrigramStance.TAE]: TrigramStance.GON,
+	[TrigramStance.LI]: TrigramStance.SON,
+	[TrigramStance.JIN]: TrigramStance.GAN,
+	[TrigramStance.SON]: TrigramStance.GEON,
+	[TrigramStance.GAM]: TrigramStance.TAE,
+	[TrigramStance.GAN]: TrigramStance.LI,
+	[TrigramStance.GON]: TrigramStance.JIN
+};
+/**
+* Counter stance damage multiplier
+* Applied when using a counter stance against opponent's stance
+* 
+* @korean 상극 자세 피해 배율
+*/
+var COUNTER_STANCE_DAMAGE_MULTIPLIER = 1.2;
+/**
+* Apply counter stance damage bonus when appropriate.
+*
+* This helper should be used by combat damage calculation code after it has
+* determined whether the current stance matchup is a counter stance
+* (for example, via an `isCounterStance` check elsewhere in the system).
+*
+* When `isCounterStance` is `true`, the base damage is multiplied by
+* {@link COUNTER_STANCE_DAMAGE_MULTIPLIER}. Non-positive damage values are
+* returned unchanged to avoid introducing invalid negative or zero scaling.
+*
+* @param baseDamage - The pre-modifier damage value.
+* @param isCounterStance - Whether the attacker is using a counter stance.
+* @returns The adjusted damage value with counter stance bonus applied when relevant.
+*
+* @example
+* ```ts
+* const isCounter = trigramSystem.isCounterStance(attackerStance, defenderStance);
+* const finalDamage = applyCounterStanceDamage(baseDamage, isCounter);
+* ```
+*
+* @korean
+* 반격 자세(상극 자세)일 때만 피해 배율(1.2배)을 적용합니다.
+*/
+function applyCounterStanceDamage(baseDamage, isCounterStance) {
+	if (!isCounterStance || baseDamage <= 0) return baseDamage;
+	return baseDamage * COUNTER_STANCE_DAMAGE_MULTIPLIER;
+}
+/**
+* System for managing Eight Trigram (팔괘) stance transitions and combat calculations.
+*
+* **Korean**: 팔괘 시스템 (Eight Trigram System)
+*
+* The TrigramSystem implements the core mechanics of the Eight Trigram martial arts system,
+* managing stance transitions, calculating effectiveness, and determining resource costs.
+* Based on I Ching (易經) philosophy adapted for tactical combat.
+*
+* ## Key Responsibilities
+*
+* - Validate stance transitions based on Ki and Stamina costs
+* - Calculate transition difficulty between stances
+* - Recommend optimal stance choices
+* - Determine stance effectiveness in combat matchups
+* - Apply archetype-specific modifiers to transitions
+*
+* @example
+* ```typescript
+* const trigramSystem = new TrigramSystem();
+*
+* // Check if transition is possible
+* const canTransition = trigramSystem.canTransitionTo(
+*   TrigramStance.GEON,
+*   TrigramStance.GAM,
+*   playerState
+* );
+*
+* // Get recommended stance
+* const recommendedStance = trigramSystem.recommendStance(playerState);
+* ```
+*
+* @public
+* @category Trigram System
+* @korean 팔괘시스템
+*/
+var TrigramSystem = class {
+	calculator;
+	/**
+	* Creates a new TrigramSystem instance.
+	*
+	* Initializes the internal calculator for stance effectiveness and transition difficulty.
+	*/
+	constructor() {
+		this.calculator = new TrigramCalculator();
+	}
+	/**
+	* Gets the defensive/offensive characteristic of a stance.
+	*
+	* **Korean**: 자세 특성 조회 (Stance Characteristic Query)
+	*
+	* Returns whether a stance is primarily defensive, offensive, or balanced.
+	* This information is useful for UI display and tactical decision-making.
+	*
+	* ## Stance Classifications
+	*
+	* - **Defensive**: 간 (GAN/Mountain), 곤 (GON/Earth) - Protect vital areas
+	* - **Offensive**: 건 (GEON/Heaven), 진 (JIN/Thunder) - Expose for power
+	* - **Balanced**: 태 (TAE/Lake), 리 (LI/Fire), 손 (SON/Wind), 감 (GAM/Water)
+	*
+	* @param stance - Trigram stance to query
+	* @returns "defensive", "offensive", or "balanced"
+	*
+	* @example
+	* ```typescript
+	* const characteristic = trigramSystem.getStanceCharacteristic(TrigramStance.GAN);
+	* console.log(characteristic); // "defensive"
+	*
+	* const offensive = trigramSystem.getStanceCharacteristic(TrigramStance.GEON);
+	* console.log(offensive); // "offensive"
+	* ```
+	*
+	* @public
+	* @korean 자세특성조회
+	*/
+	getStanceCharacteristic(stance) {
+		switch (stance) {
+			case TrigramStance.GAN:
+			case TrigramStance.GON: return "defensive";
+			case TrigramStance.GEON:
+			case TrigramStance.JIN: return "offensive";
+			default: return "balanced";
+		}
+	}
+	/**
+	* Checks if a stance provides defensive advantages.
+	*
+	* **Korean**: 방어 자세 확인 (Check Defensive Stance)
+	*
+	* @param stance - Trigram stance to check
+	* @returns true if stance is defensive, false otherwise
+	*
+	* @example
+	* ```typescript
+	* if (trigramSystem.isDefensiveStance(player.currentStance)) {
+	*   console.log("Player is in defensive posture");
+	* }
+	* ```
+	*
+	* @public
+	* @korean 방어자세확인
+	*/
+	isDefensiveStance(stance) {
+		return this.getStanceCharacteristic(stance) === "defensive";
+	}
+	/**
+	* Checks if a stance provides offensive advantages.
+	*
+	* **Korean**: 공격 자세 확인 (Check Offensive Stance)
+	*
+	* @param stance - Trigram stance to check
+	* @returns true if stance is offensive, false otherwise
+	*
+	* @example
+	* ```typescript
+	* if (trigramSystem.isOffensiveStance(player.currentStance)) {
+	*   console.log("Player is in offensive posture");
+	* }
+	* ```
+	*
+	* @public
+	* @korean 공격자세확인
+	*/
+	isOffensiveStance(stance) {
+		return this.getStanceCharacteristic(stance) === "offensive";
+	}
+	/**
+	* Checks if a player can transition from one stance to another.
+	*
+	* Validates that the player has sufficient Ki (氣) and Stamina resources
+	* to perform the stance transition. Same-stance transitions are always valid.
+	*
+	* @param fromStance - Current stance
+	* @param toStance - Target stance
+	* @param player - Player state with current Ki and Stamina
+	* @returns true if transition is possible, false otherwise
+	*
+	* @example
+	* ```typescript
+	* const canChange = trigramSystem.canTransitionTo(
+	*   TrigramStance.GEON, // From Heaven
+	*   TrigramStance.GON,  // To Earth
+	*   player
+	* );
+	* ```
+	*
+	* @public
+	* @korean 자세전환가능확인
+	*/
+	canTransitionTo(fromStance, toStance, player) {
+		if (fromStance === toStance) return true;
+		const cost = this.getTransitionCost(fromStance, toStance, player);
+		const hasEnoughKi = player.ki >= cost.ki;
+		const hasEnoughStamina = player.stamina >= cost.stamina;
+		return hasEnoughKi && hasEnoughStamina;
+	}
+	/**
+	* Recommends the optimal stance for current combat situation.
+	*
+	* Calculates the least-cost stance transition from the player's current position.
+	* Uses combined cost of Ki, Stamina, and transition time to determine best option.
+	*
+	* **Algorithm**: Evaluates all eight stances and selects the one with minimum
+	* total cost (Ki + Stamina + Time).
+	*
+	* @param player - Player state with current stance
+	* @returns Recommended stance to transition to
+	*
+	* @example
+	* ```typescript
+	* const recommended = trigramSystem.recommendStance(player);
+	* console.log(`Consider switching to ${recommended}`);
+	* ```
+	*
+	* @public
+	* @korean 최적자세추천
+	*/
+	recommendStance(player) {
+		const from = player.currentStance;
+		let best = from;
+		let bestScore = Infinity;
+		for (const to of TRIGRAM_STANCES_ORDER) {
+			const costObj = this.getTransitionCost(from, to);
+			const score = costObj.ki + costObj.stamina + costObj.timeMilliseconds;
+			if (score < bestScore) {
+				bestScore = score;
+				best = to;
+			}
+		}
+		return best;
+	}
+	/**
+	* Calculates the resource cost for transitioning between stances.
+	*
+	* Determines Ki, Stamina, and time costs based on the I Ching philosophical
+	* distance between trigrams. Applies archetype-specific modifiers for favored stances.
+	*
+	* ## Cost Calculation
+	*
+	* - **Base Cost**: 10 Ki, 15 Stamina per difficulty point
+	* - **Base Time**: 500ms per difficulty point
+	* - **Archetype Modifier**: 0.8x for favored stances, 1.0x otherwise
+	* - **Same Stance**: Zero cost
+	*
+	* @param from - Starting stance
+	* @param to - Target stance
+	* @param player - Optional player for archetype modifiers
+	* @returns Transition cost breakdown
+	*
+	* @example
+	* ```typescript
+	* const cost = trigramSystem.getTransitionCost(
+	*   TrigramStance.GEON,
+	*   TrigramStance.TAE,
+	*   player
+	* );
+	* console.log(`Cost: ${cost.ki} Ki, ${cost.stamina} Stamina`);
+	* ```
+	*
+	* @public
+	* @korean 자세전환비용
+	*/
+	getTransitionCost(from, to, player) {
+		if (from === to) return {
+			ki: 0,
+			stamina: 0,
+			timeMilliseconds: 0
+		};
+		const difficulty = TrigramCalculator.calculateTransitionDifficulty(from, to);
+		const baseCost = 10;
+		const baseTime = 500;
+		let ki = Math.ceil(baseCost * difficulty);
+		let stamina = Math.ceil(baseCost * difficulty * 1.5);
+		if (player) {
+			const mod = (PLAYER_ARCHETYPES_DATA[player.archetype].favoredStances || []).includes(to) ? .8 : 1;
+			ki = Math.ceil(ki * mod);
+			stamina = Math.ceil(stamina * mod);
+		}
+		return {
+			ki,
+			stamina,
+			timeMilliseconds: Math.ceil(baseTime * difficulty)
+		};
+	}
+	/**
+	* Calculates stance effectiveness in combat matchup.
+	*
+	* Determines the multiplier advantage/disadvantage when one stance attacks another.
+	* Based on I Ching elemental relationships (e.g., Water extinguishes Fire).
+	*
+	* @param attackerStance - Attacking player's stance
+	* @param defenderStance - Defending player's stance
+	* @returns Effectiveness multiplier (0.5 = disadvantage, 1.0 = neutral, 1.5 = advantage)
+	*
+	* @example
+	* ```typescript
+	* const effectiveness = trigramSystem.calculateStanceEffectiveness(
+	*   TrigramStance.GAM,  // Water
+	*   TrigramStance.LI    // Fire
+	* ); // Returns > 1.0 (Water beats Fire)
+	* ```
+	*
+	* @public
+	* @korean 자세효과성계산
+	*/
+	calculateStanceEffectiveness(attackerStance, defenderStance) {
+		return this.calculator.calculateStanceEffectiveness(attackerStance, defenderStance);
+	}
+	/**
+	* Gets bilingual name for a stance.
+	*
+	* Returns Korean (Hangul) and English names for display purposes.
+	*
+	* @param stance - Stance to get name for
+	* @returns Object with korean and english name properties
+	*
+	* @example
+	* ```typescript
+	* const name = trigramSystem.getStanceName(TrigramStance.GEON);
+	* console.log(`${name.korean} (${name.english})`); // "건 (Heaven)"
+	* ```
+	*
+	* @public
+	* @korean 자세이름조회
+	*/
+	getStanceName(stance) {
+		return {
+			[TrigramStance.GEON]: {
+				korean: "건",
+				english: "Heaven"
+			},
+			[TrigramStance.TAE]: {
+				korean: "태",
+				english: "Lake"
+			},
+			[TrigramStance.LI]: {
+				korean: "리",
+				english: "Fire"
+			},
+			[TrigramStance.JIN]: {
+				korean: "진",
+				english: "Thunder"
+			},
+			[TrigramStance.SON]: {
+				korean: "손",
+				english: "Wind"
+			},
+			[TrigramStance.GAM]: {
+				korean: "감",
+				english: "Water"
+			},
+			[TrigramStance.GAN]: {
+				korean: "간",
+				english: "Mountain"
+			},
+			[TrigramStance.GON]: {
+				korean: "곤",
+				english: "Earth"
+			}
+		}[stance] || {
+			korean: "Unknown",
+			english: "Unknown"
+		};
+	}
+	/**
+	* Gets the counter stance for opponent's current stance.
+	* 
+	* Returns the stance that provides tactical advantage against the opponent's stance,
+	* based on I Ching elemental relationships. Using a counter stance provides a 1.2x
+	* damage multiplier in combat.
+	* 
+	* **Korean Philosophy (상극 자세)**:
+	* - Water counters Heaven (flows around force)
+	* - Earth counters Lake (grounds and contains)
+	* - Wind counters Fire (disperses intensity)
+	* - Mountain counters Thunder (absorbs impact)
+	* 
+	* @param opponentStance - Opponent's current stance
+	* @returns Counter stance that provides advantage
+	* 
+	* @example
+	* ```typescript
+	* const counterStance = trigramSystem.getCounterStance(TrigramStance.GEON);
+	* console.log(counterStance); // TrigramStance.GAM (Water counters Heaven)
+	* ```
+	* 
+	* @public
+	* @korean 상극자세조회
+	*/
+	getCounterStance(opponentStance) {
+		return STANCE_COUNTERS[opponentStance];
+	}
+	/**
+	* Checks if player's stance counters opponent's stance.
+	* 
+	* Determines if the player has a tactical advantage through stance matchup.
+	* When true, player should receive a 1.2x damage multiplier for attacks.
+	* 
+	* @param myStance - Player's current stance
+	* @param opponentStance - Opponent's current stance
+	* @returns True if player's stance counters opponent's stance
+	* 
+	* @example
+	* ```typescript
+	* const hasAdvantage = trigramSystem.isCounterStance(
+	*   TrigramStance.GAM,  // My stance: Water
+	*   TrigramStance.GEON  // Opponent: Heaven
+	* ); // Returns true - Water counters Heaven
+	* 
+	* if (hasAdvantage) {
+	*   damage *= 1.2; // Apply counter bonus
+	* }
+	* ```
+	* 
+	* @public
+	* @korean 상극자세확인
+	*/
+	isCounterStance(myStance, opponentStance) {
+		return this.getCounterStance(opponentStance) === myStance;
+	}
+	/**
+	* Gets complete stance data for UI display.
+	*
+	* Returns structured data object containing stance ID and bilingual names.
+	*
+	* @param stance - Stance to get data for
+	* @returns Stance data object
+	*
+	* @public
+	* @korean 자세데이터조회
+	*/
+	getCurrentStanceData(stance) {
+		const stanceName = this.getStanceName(stance);
+		return {
+			id: stance,
+			name: stanceName,
+			korean: stanceName.korean,
+			english: stanceName.english
+		};
+	}
+	/**
+	* Validates a stance transition with detailed feedback.
+	*
+	* Checks if transition is valid and provides reason if not.
+	* More detailed than {@link canTransitionTo}, includes specific failure reasons.
+	*
+	* @param fromStance - Current stance
+	* @param toStance - Target stance
+	* @param player - Player state
+	* @returns Validation result with optional failure reason
+	*
+	* @example
+	* ```typescript
+	* const validation = trigramSystem.validateTransition(
+	*   TrigramStance.GEON,
+	*   TrigramStance.GON,
+	*   player
+	* );
+	* if (!validation.valid) {
+	*   console.error(validation.reason);
+	* }
+	* ```
+	*
+	* @public
+	* @korean 자세전환검증
+	*/
+	validateTransition(fromStance, toStance, player) {
+		if (fromStance === toStance) return { valid: true };
+		const cost = this.getTransitionCost(fromStance, toStance, player);
+		if (player.ki < cost.ki) return {
+			valid: false,
+			reason: `Insufficient Ki: need ${cost.ki}, have ${player.ki}`
+		};
+		if (player.stamina < cost.stamina) return {
+			valid: false,
+			reason: `Insufficient Stamina: need ${cost.stamina}, have ${player.stamina}`
+		};
+		return { valid: true };
+	}
+};
+//#endregion
+export { COUNTER_STANCE_DAMAGE_MULTIPLIER, STANCE_COUNTERS, applyCounterStanceDamage, TrigramSystem as default };
+
+//# sourceMappingURL=TrigramSystem.js.map

package/lib/systems/TrigramSystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TrigramSystem.js","names":[],"sources":["../../src/systems/TrigramSystem.ts"],"sourcesContent":["import { KoreanText, TrigramStance } from \"../types/common\";\nimport { PlayerState } from \"./player\";\n\nimport { TRIGRAM_STANCES_ORDER, TrigramTransitionCost } from \"./trigram\";\nimport { TrigramCalculator } from \"./trigram/TrigramCalculator\";\nimport { PLAYER_ARCHETYPES_DATA } from \"./types\";\n\n/**\n * Stance counter relationships based on I Ching philosophy\n * \n * Each stance has a counter stance that provides tactical advantage:\n * - **GEON (Heaven)** countered by **GAM (Water)** - Water flows around Heaven's force\n * - **TAE (Lake)** countered by **GON (Earth)** - Earth contains and grounds Lake\n * - **LI (Fire)** countered by **SON (Wind)** - Wind disperses Fire's intensity\n * - **JIN (Thunder)** countered by **GAN (Mountain)** - Mountain absorbs Thunder's impact\n * - **SON (Wind)** countered by **GEON (Heaven)** - Heaven's force overpowers Wind\n * - **GAM (Water)** countered by **TAE (Lake)** - Lake contains and channels Water\n * - **GAN (Mountain)** countered by **LI (Fire)** - Fire melts Mountain's solidity\n * - **GON (Earth)** countered by **JIN (Thunder)** - Thunder breaks Earth's stability\n * \n * Using a counter stance provides a 1.2x damage multiplier in combat.\n * \n * @korean 팔괘 상극 관계 (Eight Trigram Counter Relationships)\n */\nexport const STANCE_COUNTERS: Record<TrigramStance, TrigramStance> = {\n  [TrigramStance.GEON]: TrigramStance.GAM, // Water flows around Heaven\n  [TrigramStance.TAE]: TrigramStance.GON, // Earth grounds Lake\n  [TrigramStance.LI]: TrigramStance.SON, // Wind disperses Fire\n  [TrigramStance.JIN]: TrigramStance.GAN, // Mountain absorbs Thunder\n  [TrigramStance.SON]: TrigramStance.GEON, // Heaven overpowers Wind\n  [TrigramStance.GAM]: TrigramStance.TAE, // Lake contains Water\n  [TrigramStance.GAN]: TrigramStance.LI, // Fire melts Mountain\n  [TrigramStance.GON]: TrigramStance.JIN, // Thunder breaks Earth\n};\n\n/**\n * Counter stance damage multiplier\n * Applied when using a counter stance against opponent's stance\n * \n * @korean 상극 자세 피해 배율\n */\nexport const COUNTER_STANCE_DAMAGE_MULTIPLIER = 1.2;\n\n/**\n * Apply counter stance damage bonus when appropriate.\n *\n * This helper should be used by combat damage calculation code after it has\n * determined whether the current stance matchup is a counter stance\n * (for example, via an `isCounterStance` check elsewhere in the system).\n *\n * When `isCounterStance` is `true`, the base damage is multiplied by\n * {@link COUNTER_STANCE_DAMAGE_MULTIPLIER}. Non-positive damage values are\n * returned unchanged to avoid introducing invalid negative or zero scaling.\n *\n * @param baseDamage - The pre-modifier damage value.\n * @param isCounterStance - Whether the attacker is using a counter stance.\n * @returns The adjusted damage value with counter stance bonus applied when relevant.\n *\n * @example\n * ```ts\n * const isCounter = trigramSystem.isCounterStance(attackerStance, defenderStance);\n * const finalDamage = applyCounterStanceDamage(baseDamage, isCounter);\n * ```\n *\n * @korean\n * 반격 자세(상극 자세)일 때만 피해 배율(1.2배)을 적용합니다.\n */\nexport function applyCounterStanceDamage(\n  baseDamage: number,\n  isCounterStance: boolean\n): number {\n  if (!isCounterStance || baseDamage <= 0) {\n    return baseDamage;\n  }\n\n  return baseDamage * COUNTER_STANCE_DAMAGE_MULTIPLIER;\n}\n\n/**\n * System for managing Eight Trigram (팔괘) stance transitions and combat calculations.\n *\n * **Korean**: 팔괘 시스템 (Eight Trigram System)\n *\n * The TrigramSystem implements the core mechanics of the Eight Trigram martial arts system,\n * managing stance transitions, calculating effectiveness, and determining resource costs.\n * Based on I Ching (易經) philosophy adapted for tactical combat.\n *\n * ## Key Responsibilities\n *\n * - Validate stance transitions based on Ki and Stamina costs\n * - Calculate transition difficulty between stances\n * - Recommend optimal stance choices\n * - Determine stance effectiveness in combat matchups\n * - Apply archetype-specific modifiers to transitions\n *\n * @example\n * ```typescript\n * const trigramSystem = new TrigramSystem();\n *\n * // Check if transition is possible\n * const canTransition = trigramSystem.canTransitionTo(\n *   TrigramStance.GEON,\n *   TrigramStance.GAM,\n *   playerState\n * );\n *\n * // Get recommended stance\n * const recommendedStance = trigramSystem.recommendStance(playerState);\n * ```\n *\n * @public\n * @category Trigram System\n * @korean 팔괘시스템\n */\nexport class TrigramSystem {\n  private calculator: TrigramCalculator;\n\n  /**\n   * Creates a new TrigramSystem instance.\n   *\n   * Initializes the internal calculator for stance effectiveness and transition difficulty.\n   */\n  constructor() {\n    this.calculator = new TrigramCalculator();\n  }\n\n  /**\n   * Gets the defensive/offensive characteristic of a stance.\n   *\n   * **Korean**: 자세 특성 조회 (Stance Characteristic Query)\n   *\n   * Returns whether a stance is primarily defensive, offensive, or balanced.\n   * This information is useful for UI display and tactical decision-making.\n   *\n   * ## Stance Classifications\n   *\n   * - **Defensive**: 간 (GAN/Mountain), 곤 (GON/Earth) - Protect vital areas\n   * - **Offensive**: 건 (GEON/Heaven), 진 (JIN/Thunder) - Expose for power\n   * - **Balanced**: 태 (TAE/Lake), 리 (LI/Fire), 손 (SON/Wind), 감 (GAM/Water)\n   *\n   * @param stance - Trigram stance to query\n   * @returns \"defensive\", \"offensive\", or \"balanced\"\n   *\n   * @example\n   * ```typescript\n   * const characteristic = trigramSystem.getStanceCharacteristic(TrigramStance.GAN);\n   * console.log(characteristic); // \"defensive\"\n   *\n   * const offensive = trigramSystem.getStanceCharacteristic(TrigramStance.GEON);\n   * console.log(offensive); // \"offensive\"\n   * ```\n   *\n   * @public\n   * @korean 자세특성조회\n   */\n  getStanceCharacteristic(\n    stance: TrigramStance\n  ): \"defensive\" | \"offensive\" | \"balanced\" {\n    switch (stance) {\n      case TrigramStance.GAN: // Mountain - Immovable defense\n      case TrigramStance.GON: // Earth - Grounding and stability\n        return \"defensive\";\n\n      case TrigramStance.GEON: // Heaven - Direct force and aggression\n      case TrigramStance.JIN: // Thunder - Explosive power\n        return \"offensive\";\n\n      default:\n        return \"balanced\";\n    }\n  }\n\n  /**\n   * Checks if a stance provides defensive advantages.\n   *\n   * **Korean**: 방어 자세 확인 (Check Defensive Stance)\n   *\n   * @param stance - Trigram stance to check\n   * @returns true if stance is defensive, false otherwise\n   *\n   * @example\n   * ```typescript\n   * if (trigramSystem.isDefensiveStance(player.currentStance)) {\n   *   console.log(\"Player is in defensive posture\");\n   * }\n   * ```\n   *\n   * @public\n   * @korean 방어자세확인\n   */\n  isDefensiveStance(stance: TrigramStance): boolean {\n    return this.getStanceCharacteristic(stance) === \"defensive\";\n  }\n\n  /**\n   * Checks if a stance provides offensive advantages.\n   *\n   * **Korean**: 공격 자세 확인 (Check Offensive Stance)\n   *\n   * @param stance - Trigram stance to check\n   * @returns true if stance is offensive, false otherwise\n   *\n   * @example\n   * ```typescript\n   * if (trigramSystem.isOffensiveStance(player.currentStance)) {\n   *   console.log(\"Player is in offensive posture\");\n   * }\n   * ```\n   *\n   * @public\n   * @korean 공격자세확인\n   */\n  isOffensiveStance(stance: TrigramStance): boolean {\n    return this.getStanceCharacteristic(stance) === \"offensive\";\n  }\n\n  /**\n   * Checks if a player can transition from one stance to another.\n   *\n   * Validates that the player has sufficient Ki (氣) and Stamina resources\n   * to perform the stance transition. Same-stance transitions are always valid.\n   *\n   * @param fromStance - Current stance\n   * @param toStance - Target stance\n   * @param player - Player state with current Ki and Stamina\n   * @returns true if transition is possible, false otherwise\n   *\n   * @example\n   * ```typescript\n   * const canChange = trigramSystem.canTransitionTo(\n   *   TrigramStance.GEON, // From Heaven\n   *   TrigramStance.GON,  // To Earth\n   *   player\n   * );\n   * ```\n   *\n   * @public\n   * @korean 자세전환가능확인\n   */\n  canTransitionTo(\n    fromStance: TrigramStance,\n    toStance: TrigramStance,\n    player: PlayerState\n  ): boolean {\n    if (fromStance === toStance) return true;\n\n    const cost = this.getTransitionCost(fromStance, toStance, player);\n\n    // Check if player has sufficient resources\n    const hasEnoughKi = player.ki >= cost.ki;\n    const hasEnoughStamina = player.stamina >= cost.stamina;\n\n    return hasEnoughKi && hasEnoughStamina;\n  }\n\n  /**\n   * Recommends the optimal stance for current combat situation.\n   *\n   * Calculates the least-cost stance transition from the player's current position.\n   * Uses combined cost of Ki, Stamina, and transition time to determine best option.\n   *\n   * **Algorithm**: Evaluates all eight stances and selects the one with minimum\n   * total cost (Ki + Stamina + Time).\n   *\n   * @param player - Player state with current stance\n   * @returns Recommended stance to transition to\n   *\n   * @example\n   * ```typescript\n   * const recommended = trigramSystem.recommendStance(player);\n   * console.log(`Consider switching to ${recommended}`);\n   * ```\n   *\n   * @public\n   * @korean 최적자세추천\n   */\n  recommendStance(player: PlayerState): TrigramStance {\n    const from = player.currentStance;\n    let best = from;\n    let bestScore = Infinity;\n\n    for (const to of TRIGRAM_STANCES_ORDER) {\n      const costObj: TrigramTransitionCost = this.getTransitionCost(from, to);\n      const score = costObj.ki + costObj.stamina + costObj.timeMilliseconds;\n      if (score < bestScore) {\n        bestScore = score;\n        best = to;\n      }\n    }\n\n    return best;\n  }\n\n  /**\n   * Calculates the resource cost for transitioning between stances.\n   *\n   * Determines Ki, Stamina, and time costs based on the I Ching philosophical\n   * distance between trigrams. Applies archetype-specific modifiers for favored stances.\n   *\n   * ## Cost Calculation\n   *\n   * - **Base Cost**: 10 Ki, 15 Stamina per difficulty point\n   * - **Base Time**: 500ms per difficulty point\n   * - **Archetype Modifier**: 0.8x for favored stances, 1.0x otherwise\n   * - **Same Stance**: Zero cost\n   *\n   * @param from - Starting stance\n   * @param to - Target stance\n   * @param player - Optional player for archetype modifiers\n   * @returns Transition cost breakdown\n   *\n   * @example\n   * ```typescript\n   * const cost = trigramSystem.getTransitionCost(\n   *   TrigramStance.GEON,\n   *   TrigramStance.TAE,\n   *   player\n   * );\n   * console.log(`Cost: ${cost.ki} Ki, ${cost.stamina} Stamina`);\n   * ```\n   *\n   * @public\n   * @korean 자세전환비용\n   */\n  public getTransitionCost(\n    from: TrigramStance,\n    to: TrigramStance,\n    player?: PlayerState\n  ): TrigramTransitionCost {\n    if (from === to) {\n      return {\n        ki: 0,\n        stamina: 0,\n        timeMilliseconds: 0, // neutral\n      };\n    }\n\n    const difficulty = TrigramCalculator.calculateTransitionDifficulty(\n      from,\n      to\n    );\n    const baseCost = 10;\n    const baseTime = 500;\n\n    let ki = Math.ceil(baseCost * difficulty);\n    let stamina = Math.ceil(baseCost * difficulty * 1.5);\n\n    // apply archetype stance‐change cost modifier if player provided\n    if (player) {\n      const archData = PLAYER_ARCHETYPES_DATA[player.archetype];\n      const favs = archData.favoredStances || [];\n      const mod = favs.includes(to) ? 0.8 : 1.0;\n      ki = Math.ceil(ki * mod);\n      stamina = Math.ceil(stamina * mod);\n    }\n\n    return {\n      ki,\n      stamina,\n      timeMilliseconds: Math.ceil(baseTime * difficulty),\n    };\n  }\n\n  /**\n   * Calculates stance effectiveness in combat matchup.\n   *\n   * Determines the multiplier advantage/disadvantage when one stance attacks another.\n   * Based on I Ching elemental relationships (e.g., Water extinguishes Fire).\n   *\n   * @param attackerStance - Attacking player's stance\n   * @param defenderStance - Defending player's stance\n   * @returns Effectiveness multiplier (0.5 = disadvantage, 1.0 = neutral, 1.5 = advantage)\n   *\n   * @example\n   * ```typescript\n   * const effectiveness = trigramSystem.calculateStanceEffectiveness(\n   *   TrigramStance.GAM,  // Water\n   *   TrigramStance.LI    // Fire\n   * ); // Returns > 1.0 (Water beats Fire)\n   * ```\n   *\n   * @public\n   * @korean 자세효과성계산\n   */\n  calculateStanceEffectiveness(\n    attackerStance: TrigramStance,\n    defenderStance: TrigramStance\n  ): number {\n    return this.calculator.calculateStanceEffectiveness(\n      attackerStance,\n      defenderStance\n    );\n  }\n\n  /**\n   * Gets bilingual name for a stance.\n   *\n   * Returns Korean (Hangul) and English names for display purposes.\n   *\n   * @param stance - Stance to get name for\n   * @returns Object with korean and english name properties\n   *\n   * @example\n   * ```typescript\n   * const name = trigramSystem.getStanceName(TrigramStance.GEON);\n   * console.log(`${name.korean} (${name.english})`); // \"건 (Heaven)\"\n   * ```\n   *\n   * @public\n   * @korean 자세이름조회\n   */\n  getStanceName(stance: TrigramStance): { korean: string; english: string } {\n    const stanceNames = {\n      [TrigramStance.GEON]: { korean: \"건\", english: \"Heaven\" },\n      [TrigramStance.TAE]: { korean: \"태\", english: \"Lake\" },\n      [TrigramStance.LI]: { korean: \"리\", english: \"Fire\" },\n      [TrigramStance.JIN]: { korean: \"진\", english: \"Thunder\" },\n      [TrigramStance.SON]: { korean: \"손\", english: \"Wind\" },\n      [TrigramStance.GAM]: { korean: \"감\", english: \"Water\" },\n      [TrigramStance.GAN]: { korean: \"간\", english: \"Mountain\" },\n      [TrigramStance.GON]: { korean: \"곤\", english: \"Earth\" },\n    };\n\n    return stanceNames[stance] || { korean: \"Unknown\", english: \"Unknown\" };\n  }\n\n  /**\n   * Gets the counter stance for opponent's current stance.\n   * \n   * Returns the stance that provides tactical advantage against the opponent's stance,\n   * based on I Ching elemental relationships. Using a counter stance provides a 1.2x\n   * damage multiplier in combat.\n   * \n   * **Korean Philosophy (상극 자세)**:\n   * - Water counters Heaven (flows around force)\n   * - Earth counters Lake (grounds and contains)\n   * - Wind counters Fire (disperses intensity)\n   * - Mountain counters Thunder (absorbs impact)\n   * \n   * @param opponentStance - Opponent's current stance\n   * @returns Counter stance that provides advantage\n   * \n   * @example\n   * ```typescript\n   * const counterStance = trigramSystem.getCounterStance(TrigramStance.GEON);\n   * console.log(counterStance); // TrigramStance.GAM (Water counters Heaven)\n   * ```\n   * \n   * @public\n   * @korean 상극자세조회\n   */\n  getCounterStance(opponentStance: TrigramStance): TrigramStance {\n    return STANCE_COUNTERS[opponentStance];\n  }\n\n  /**\n   * Checks if player's stance counters opponent's stance.\n   * \n   * Determines if the player has a tactical advantage through stance matchup.\n   * When true, player should receive a 1.2x damage multiplier for attacks.\n   * \n   * @param myStance - Player's current stance\n   * @param opponentStance - Opponent's current stance\n   * @returns True if player's stance counters opponent's stance\n   * \n   * @example\n   * ```typescript\n   * const hasAdvantage = trigramSystem.isCounterStance(\n   *   TrigramStance.GAM,  // My stance: Water\n   *   TrigramStance.GEON  // Opponent: Heaven\n   * ); // Returns true - Water counters Heaven\n   * \n   * if (hasAdvantage) {\n   *   damage *= 1.2; // Apply counter bonus\n   * }\n   * ```\n   * \n   * @public\n   * @korean 상극자세확인\n   */\n  isCounterStance(myStance: TrigramStance, opponentStance: TrigramStance): boolean {\n    return this.getCounterStance(opponentStance) === myStance;\n  }\n\n  /**\n   * Gets complete stance data for UI display.\n   *\n   * Returns structured data object containing stance ID and bilingual names.\n   *\n   * @param stance - Stance to get data for\n   * @returns Stance data object\n   *\n   * @public\n   * @korean 자세데이터조회\n   */\n  getCurrentStanceData(stance: TrigramStance): {\n    id: TrigramStance;\n    name: KoreanText;\n    korean: string;\n    english: string;\n  } {\n    const stanceName = this.getStanceName(stance);\n    return {\n      id: stance,\n      name: stanceName,\n      korean: stanceName.korean,\n      english: stanceName.english,\n    };\n  }\n\n  /**\n   * Validates a stance transition with detailed feedback.\n   *\n   * Checks if transition is valid and provides reason if not.\n   * More detailed than {@link canTransitionTo}, includes specific failure reasons.\n   *\n   * @param fromStance - Current stance\n   * @param toStance - Target stance\n   * @param player - Player state\n   * @returns Validation result with optional failure reason\n   *\n   * @example\n   * ```typescript\n   * const validation = trigramSystem.validateTransition(\n   *   TrigramStance.GEON,\n   *   TrigramStance.GON,\n   *   player\n   * );\n   * if (!validation.valid) {\n   *   console.error(validation.reason);\n   * }\n   * ```\n   *\n   * @public\n   * @korean 자세전환검증\n   */\n  validateTransition(\n    fromStance: TrigramStance,\n    toStance: TrigramStance,\n    player: PlayerState\n  ): { valid: boolean; reason?: string } {\n    if (fromStance === toStance) {\n      return { valid: true };\n    }\n\n    const cost = this.getTransitionCost(fromStance, toStance, player);\n\n    if (player.ki < cost.ki) {\n      return {\n        valid: false,\n        reason: `Insufficient Ki: need ${cost.ki}, have ${player.ki}`,\n      };\n    }\n\n    if (player.stamina < cost.stamina) {\n      return {\n        valid: false,\n        reason: `Insufficient Stamina: need ${cost.stamina}, have ${player.stamina}`,\n      };\n    }\n\n    return { valid: true };\n  }\n}\n\nexport default TrigramSystem;\n"],"mappings":"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"}