blacktrigram 0.7.2

package/lib/systems/physics/CoordinateMapper.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Coordinate Mapper for 2D→3D conversion in Black Trigram.
+ *
+ * **Korean**: 좌표 변환기 (2D → 3D)
+ *
+ * Maps 2D pixel coordinates from the vital points data (UI overlay) to 3D world
+ * coordinates for physics-based collision detection. This allows the UI-based
+ * vital point system to work seamlessly with Three.js 3D collision detection.
+ *
+ * ## Coordinate Systems
+ *
+ * - **2D Pixel Space**: Origin (0,0) at top-left, used by vital points UI overlay
+ * - **3D World Space**: Origin (0,0,0) at character center, used by collision detection
+ *
+ * ## Character Model Assumptions
+ *
+ * - Character height: 1.75m (average adult)
+ * - Character width: 0.5m (shoulder width)
+ * - Character depth: 0.3m (chest to back)
+ * - Standing position: feet at y=0, head at y=1.75
+ *
+ * ## Mapping Strategy
+ *
+ * The mapper uses anatomical regions to determine the Z-depth (front-to-back position)
+ * of vital points, ensuring physically accurate 3D positions for collision detection.
+ *
+ * @module systems/physics/CoordinateMapper
+ * @category Physics System
+ * @korean 좌표변환
+ */
+import type { Position } from "../../types/common";
+import type { Position3D, AnatomicalRegionPhysics } from "../../types/physics";
+import type { VitalPoint } from "../vitalpoint/types";
+/**
+ * Configuration for the character model coordinate mapping.
+ *
+ * **Korean**: 캐릭터 모델 설정
+ */
+export interface CharacterModelConfig {
+    /** Character height in meters (default: 1.75m) */
+    readonly height: number;
+    /** Character shoulder width in meters (default: 0.5m) */
+    readonly width: number;
+    /** Character depth (chest to back) in meters (default: 0.3m) */
+    readonly depth: number;
+    /** UI overlay width in pixels (default: 200px) */
+    readonly overlayWidth: number;
+    /** UI overlay height in pixels (default: 300px) */
+    readonly overlayHeight: number;
+}
+/**
+ * Coordinate Mapper for converting 2D pixel coordinates to 3D world coordinates.
+ *
+ * **Korean**: 좌표 변환기
+ *
+ * Provides bidirectional mapping between the 2D UI overlay coordinate system
+ * and the 3D physics world coordinate system.
+ *
+ * @public
+ * @category Physics System
+ * @korean 좌표변환기
+ */
+export declare class CoordinateMapper {
+    private readonly config;
+    /**
+     * Creates a new CoordinateMapper with optional custom configuration.
+     *
+     * @param config - Optional character model configuration
+     */
+    constructor(config?: Partial<CharacterModelConfig>);
+    /**
+     * Converts a 2D pixel position to a 3D world position.
+     *
+     * **Korean**: 2D → 3D 변환
+     *
+     * Maps UI overlay pixel coordinates to 3D world space coordinates suitable
+     * for physics collision detection.
+     *
+     * @param pixel2D - 2D pixel position (origin top-left)
+     * @param region - Anatomical region for Z-depth calculation
+     * @returns 3D world position in meters (origin at character center)
+     *
+     * @example
+     * ```typescript
+     * const mapper = new CoordinateMapper();
+     * const vitalPoint = { position: { x: 100, y: 50 } };
+     * const worldPos = mapper.pixel2DToWorld3D(vitalPoint.position, "head");
+     * // worldPos: { x: 0, y: 1.45, z: 0.05 }
+     * ```
+     */
+    pixel2DToWorld3D(pixel2D: Position, region: AnatomicalRegionPhysics): Position3D;
+    /**
+     * Converts a 3D world position to a 2D pixel position.
+     *
+     * **Korean**: 3D → 2D 변환
+     *
+     * Maps 3D world space coordinates back to UI overlay pixel coordinates.
+     * Useful for debugging and visual feedback.
+     *
+     * @param world3D - 3D world position in meters
+     * @returns 2D pixel position (origin top-left)
+     *
+     * @example
+     * ```typescript
+     * const mapper = new CoordinateMapper();
+     * const worldPos = { x: 0, y: 1.45, z: 0.05 };
+     * const pixelPos = mapper.world3DToPixel2D(worldPos);
+     * // pixelPos: { x: 100, y: 50 }
+     * ```
+     */
+    world3DToPixel2D(world3D: Position3D): Position;
+    /**
+     * Converts a vital point's 2D position to 3D world position.
+     *
+     * **Korean**: 급소 위치 변환
+     *
+     * Convenience method that extracts position and region from a VitalPoint object.
+     *
+     * @param vitalPoint - Vital point with 2D position
+     * @returns 3D world position
+     *
+     * @example
+     * ```typescript
+     * const mapper = new CoordinateMapper();
+     * const temple = VITAL_POINTS_DATA.find(vp => vp.id === "head_temple");
+     * const worldPos = mapper.vitalPointToWorld3D(temple);
+     * ```
+     */
+    vitalPointToWorld3D(vitalPoint: VitalPoint): Position3D;
+    /**
+     * Infers the anatomical region from a vital point ID.
+     *
+     * **Korean**: 급소 ID에서 영역 추론
+     *
+     * @param vitalPointId - Vital point ID (e.g., "head_temple", "torso_solar_plexus")
+     * @returns Anatomical region
+     *
+     * @private
+     */
+    private inferRegionFromId;
+    /**
+     * Calculates the distance between a 3D point and a vital point's 3D position.
+     *
+     * **Korean**: 거리 계산
+     *
+     * @param point3D - Point in 3D world space
+     * @param vitalPoint - Vital point to measure distance to
+     * @returns Distance in meters
+     *
+     * @example
+     * ```typescript
+     * const mapper = new CoordinateMapper();
+     * const attackPoint = { x: 0, y: 1.5, z: 0.1 };
+     * const temple = VITAL_POINTS_DATA.find(vp => vp.id === "head_temple");
+     * const distance = mapper.distanceToVitalPoint(attackPoint, temple);
+     * ```
+     */
+    distanceToVitalPoint(point3D: Position3D, vitalPoint: VitalPoint): number;
+    /**
+     * Finds the closest vital point to a 3D position within a given region.
+     *
+     * **Korean**: 가장 가까운 급소 찾기
+     *
+     * @param point3D - Point in 3D world space
+     * @param vitalPoints - Array of vital points to search
+     * @param region - Optional region filter
+     * @returns Closest vital point and distance, or null if none found
+     *
+     * @example
+     * ```typescript
+     * const mapper = new CoordinateMapper();
+     * const hitPoint = { x: 0, y: 1.7, z: 0.05 };
+     * const result = mapper.findClosestVitalPoint(hitPoint, VITAL_POINTS_DATA, "head");
+     * if (result) {
+     *   console.log(`Hit ${result.vitalPoint.names.english} at ${result.distance}m`);
+     * }
+     * ```
+     */
+    findClosestVitalPoint(point3D: Position3D, vitalPoints: readonly VitalPoint[], region?: AnatomicalRegionPhysics): {
+        vitalPoint: VitalPoint;
+        distance: number;
+    } | null;
+    /**
+     * Gets the current character model configuration.
+     *
+     * @returns Current configuration
+     */
+    getConfig(): CharacterModelConfig;
+}
+/**
+ * Default singleton instance for convenient access.
+ *
+ * **Korean**: 기본 인스턴스
+ *
+ * @example
+ * ```typescript
+ * import { defaultCoordinateMapper } from './CoordinateMapper';
+ *
+ * const worldPos = defaultCoordinateMapper.pixel2DToWorld3D({ x: 100, y: 50 }, "head");
+ * ```
+ */
+export declare const defaultCoordinateMapper: CoordinateMapper;
+//# sourceMappingURL=CoordinateMapper.d.ts.map

package/lib/systems/physics/CoordinateMapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoordinateMapper.d.ts","sourceRoot":"","sources":["../../../src/systems/physics/CoordinateMapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,kDAAkD;IAClD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,mDAAmD;IACnD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAqFD;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAE9C;;;;OAIG;gBACS,MAAM,GAAE,OAAO,CAAC,oBAAoB,CAAM;IAItD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,gBAAgB,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,uBAAuB,GAAG,UAAU;IAuBhF;;;;;;;;;;;;;;;;;;OAkBG;IACH,gBAAgB,CAAC,OAAO,EAAE,UAAU,GAAG,QAAQ;IAc/C;;;;;;;;;;;;;;;;OAgBG;IACH,mBAAmB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU;IAMvD;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;;;;;;;;;;;;;;OAgBG;IACH,oBAAoB,CAAC,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,GAAG,MAAM;IAUzE;;;;;;;;;;;;;;;;;;;OAmBG;IACH,qBAAqB,CACnB,OAAO,EAAE,UAAU,EACnB,WAAW,EAAE,SAAS,UAAU,EAAE,EAClC,MAAM,CAAC,EAAE,uBAAuB,GAC/B;QAAE,UAAU,EAAE,UAAU,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IA6BtD;;;;OAIG;IACH,SAAS,IAAI,oBAAoB;CAGlC;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,kBAAyB,CAAC"}

package/lib/systems/physics/CoordinateMapper.js

@@ -0,0 +1,242 @@
+//#region src/systems/physics/CoordinateMapper.ts
+/**
+* Default character model configuration based on average adult proportions.
+*/
+var DEFAULT_CHARACTER_CONFIG = {
+	height: 1.75,
+	width: .5,
+	depth: .3,
+	overlayWidth: 200,
+	overlayHeight: 300
+};
+/**
+* Z-depth (front-to-back) offsets for different anatomical regions.
+* 
+* Units are **meters in model space**, measured along the character's local Z axis,
+* and are applied relative to the character's center plane (Z = 0) and the
+* configured {@link CharacterModelConfig.depth}. With the default depth of
+* `0.3m`, an offset of `0.05` corresponds to ≈5 cm of forward displacement.
+*
+* These values were chosen as simple, stable approximations based on average
+* adult proportions and validated visually against the default rig:
+*
+* - `head: 0.05` → head center sits slightly in front of the torso plane
+*   (≈1/6 of torso depth) to match typical forward head posture.
+* - `neck: 0.02` → neck base is close to the torso plane but not perfectly
+*   centered, acknowledging slight anterior offset of the trachea/sternum.
+* - `torso: 0.0` → torso vital points lie on the reference center plane that
+*   approximates the mid‑chest / spine midpoint.
+* - `arms: 0.05` → relaxed arms hang slightly in front of the torso plane,
+*   using the same forward offset as the head for consistency.
+* - `legs: 0.0` → leg targets (front of thighs/shins) are modeled on the
+*   center plane; depth variation is instead captured by vertical placement.
+*
+* If you change {@link CharacterModelConfig.depth}, you may keep these absolute
+* meter values (for physical fidelity) or re‑express them as fractions of the
+* new depth, but they should continue to represent small (≈0–5 cm) anatomical
+* offsets from the torso midline.
+*/
+var REGION_DEPTH_OFFSETS = {
+	head: .05,
+	neck: .02,
+	torso: 0,
+	arms: .05,
+	legs: 0
+};
+/**
+* Coordinate Mapper for converting 2D pixel coordinates to 3D world coordinates.
+* 
+* **Korean**: 좌표 변환기
+* 
+* Provides bidirectional mapping between the 2D UI overlay coordinate system
+* and the 3D physics world coordinate system.
+* 
+* @public
+* @category Physics System
+* @korean 좌표변환기
+*/
+var CoordinateMapper = class {
+	config;
+	/**
+	* Creates a new CoordinateMapper with optional custom configuration.
+	* 
+	* @param config - Optional character model configuration
+	*/
+	constructor(config = {}) {
+		this.config = {
+			...DEFAULT_CHARACTER_CONFIG,
+			...config
+		};
+	}
+	/**
+	* Converts a 2D pixel position to a 3D world position.
+	* 
+	* **Korean**: 2D → 3D 변환
+	* 
+	* Maps UI overlay pixel coordinates to 3D world space coordinates suitable
+	* for physics collision detection.
+	* 
+	* @param pixel2D - 2D pixel position (origin top-left)
+	* @param region - Anatomical region for Z-depth calculation
+	* @returns 3D world position in meters (origin at character center)
+	* 
+	* @example
+	* ```typescript
+	* const mapper = new CoordinateMapper();
+	* const vitalPoint = { position: { x: 100, y: 50 } };
+	* const worldPos = mapper.pixel2DToWorld3D(vitalPoint.position, "head");
+	* // worldPos: { x: 0, y: 1.45, z: 0.05 }
+	* ```
+	*/
+	pixel2DToWorld3D(pixel2D, region) {
+		const normalizedX = pixel2D.x / this.config.overlayWidth;
+		const normalizedY = pixel2D.y / this.config.overlayHeight;
+		return {
+			x: (normalizedX - .5) * this.config.width,
+			y: (1 - normalizedY) * this.config.height,
+			z: REGION_DEPTH_OFFSETS[region]
+		};
+	}
+	/**
+	* Converts a 3D world position to a 2D pixel position.
+	* 
+	* **Korean**: 3D → 2D 변환
+	* 
+	* Maps 3D world space coordinates back to UI overlay pixel coordinates.
+	* Useful for debugging and visual feedback.
+	* 
+	* @param world3D - 3D world position in meters
+	* @returns 2D pixel position (origin top-left)
+	* 
+	* @example
+	* ```typescript
+	* const mapper = new CoordinateMapper();
+	* const worldPos = { x: 0, y: 1.45, z: 0.05 };
+	* const pixelPos = mapper.world3DToPixel2D(worldPos);
+	* // pixelPos: { x: 100, y: 50 }
+	* ```
+	*/
+	world3DToPixel2D(world3D) {
+		const normalizedX = world3D.x / this.config.width + .5;
+		const normalizedY = 1 - world3D.y / this.config.height;
+		return {
+			x: Math.round(normalizedX * this.config.overlayWidth),
+			y: Math.round(normalizedY * this.config.overlayHeight)
+		};
+	}
+	/**
+	* Converts a vital point's 2D position to 3D world position.
+	* 
+	* **Korean**: 급소 위치 변환
+	* 
+	* Convenience method that extracts position and region from a VitalPoint object.
+	* 
+	* @param vitalPoint - Vital point with 2D position
+	* @returns 3D world position
+	* 
+	* @example
+	* ```typescript
+	* const mapper = new CoordinateMapper();
+	* const temple = VITAL_POINTS_DATA.find(vp => vp.id === "head_temple");
+	* const worldPos = mapper.vitalPointToWorld3D(temple);
+	* ```
+	*/
+	vitalPointToWorld3D(vitalPoint) {
+		const region = this.inferRegionFromId(vitalPoint.id);
+		return this.pixel2DToWorld3D(vitalPoint.position, region);
+	}
+	/**
+	* Infers the anatomical region from a vital point ID.
+	* 
+	* **Korean**: 급소 ID에서 영역 추론
+	* 
+	* @param vitalPointId - Vital point ID (e.g., "head_temple", "torso_solar_plexus")
+	* @returns Anatomical region
+	* 
+	* @private
+	*/
+	inferRegionFromId(vitalPointId) {
+		if (vitalPointId.startsWith("head_")) return "head";
+		if (vitalPointId.startsWith("neck_")) return "neck";
+		if (vitalPointId.startsWith("torso_")) return "torso";
+		if (vitalPointId.startsWith("arm_")) return "arms";
+		if (vitalPointId.startsWith("leg_")) return "legs";
+		return "torso";
+	}
+	/**
+	* Calculates the distance between a 3D point and a vital point's 3D position.
+	* 
+	* **Korean**: 거리 계산
+	* 
+	* @param point3D - Point in 3D world space
+	* @param vitalPoint - Vital point to measure distance to
+	* @returns Distance in meters
+	* 
+	* @example
+	* ```typescript
+	* const mapper = new CoordinateMapper();
+	* const attackPoint = { x: 0, y: 1.5, z: 0.1 };
+	* const temple = VITAL_POINTS_DATA.find(vp => vp.id === "head_temple");
+	* const distance = mapper.distanceToVitalPoint(attackPoint, temple);
+	* ```
+	*/
+	distanceToVitalPoint(point3D, vitalPoint) {
+		const vitalPoint3D = this.vitalPointToWorld3D(vitalPoint);
+		const dx = point3D.x - vitalPoint3D.x;
+		const dy = point3D.y - vitalPoint3D.y;
+		const dz = point3D.z - vitalPoint3D.z;
+		return Math.sqrt(dx * dx + dy * dy + dz * dz);
+	}
+	/**
+	* Finds the closest vital point to a 3D position within a given region.
+	* 
+	* **Korean**: 가장 가까운 급소 찾기
+	* 
+	* @param point3D - Point in 3D world space
+	* @param vitalPoints - Array of vital points to search
+	* @param region - Optional region filter
+	* @returns Closest vital point and distance, or null if none found
+	* 
+	* @example
+	* ```typescript
+	* const mapper = new CoordinateMapper();
+	* const hitPoint = { x: 0, y: 1.7, z: 0.05 };
+	* const result = mapper.findClosestVitalPoint(hitPoint, VITAL_POINTS_DATA, "head");
+	* if (result) {
+	*   console.log(`Hit ${result.vitalPoint.names.english} at ${result.distance}m`);
+	* }
+	* ```
+	*/
+	findClosestVitalPoint(point3D, vitalPoints, region) {
+		let closestVitalPoint = null;
+		let closestDistance = Infinity;
+		for (const vitalPoint of vitalPoints) {
+			if (region) {
+				if (this.inferRegionFromId(vitalPoint.id) !== region) continue;
+			}
+			const distance = this.distanceToVitalPoint(point3D, vitalPoint);
+			if (distance < closestDistance) {
+				closestDistance = distance;
+				closestVitalPoint = vitalPoint;
+			}
+		}
+		if (closestVitalPoint === null) return null;
+		return {
+			vitalPoint: closestVitalPoint,
+			distance: closestDistance
+		};
+	}
+	/**
+	* Gets the current character model configuration.
+	* 
+	* @returns Current configuration
+	*/
+	getConfig() {
+		return { ...this.config };
+	}
+};
+new CoordinateMapper();
+//#endregion
+export { CoordinateMapper };
+
+//# sourceMappingURL=CoordinateMapper.js.map

package/lib/systems/physics/CoordinateMapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoordinateMapper.js","names":[],"sources":["../../../src/systems/physics/CoordinateMapper.ts"],"sourcesContent":["/**\n * Coordinate Mapper for 2D→3D conversion in Black Trigram.\n * \n * **Korean**: 좌표 변환기 (2D → 3D)\n * \n * Maps 2D pixel coordinates from the vital points data (UI overlay) to 3D world\n * coordinates for physics-based collision detection. This allows the UI-based\n * vital point system to work seamlessly with Three.js 3D collision detection.\n * \n * ## Coordinate Systems\n * \n * - **2D Pixel Space**: Origin (0,0) at top-left, used by vital points UI overlay\n * - **3D World Space**: Origin (0,0,0) at character center, used by collision detection\n * \n * ## Character Model Assumptions\n * \n * - Character height: 1.75m (average adult)\n * - Character width: 0.5m (shoulder width)\n * - Character depth: 0.3m (chest to back)\n * - Standing position: feet at y=0, head at y=1.75\n * \n * ## Mapping Strategy\n * \n * The mapper uses anatomical regions to determine the Z-depth (front-to-back position)\n * of vital points, ensuring physically accurate 3D positions for collision detection.\n * \n * @module systems/physics/CoordinateMapper\n * @category Physics System\n * @korean 좌표변환\n */\n\nimport type { Position } from \"@/types/common\";\nimport type { Position3D, AnatomicalRegionPhysics } from \"@/types/physics\";\nimport type { VitalPoint } from \"../vitalpoint/types\";\n\n/**\n * Configuration for the character model coordinate mapping.\n * \n * **Korean**: 캐릭터 모델 설정\n */\nexport interface CharacterModelConfig {\n  /** Character height in meters (default: 1.75m) */\n  readonly height: number;\n  \n  /** Character shoulder width in meters (default: 0.5m) */\n  readonly width: number;\n  \n  /** Character depth (chest to back) in meters (default: 0.3m) */\n  readonly depth: number;\n  \n  /** UI overlay width in pixels (default: 200px) */\n  readonly overlayWidth: number;\n  \n  /** UI overlay height in pixels (default: 300px) */\n  readonly overlayHeight: number;\n}\n\n/**\n * Average adult standing height used for physics mapping (meters).\n * \n * This value is based on common anthropometric data and provides a\n * reasonable default for a neutral, unarmed character in Black Trigram.\n */\nconst AVERAGE_ADULT_HEIGHT_M = 1.75; // 175cm average adult height\n\n/**\n * Average shoulder width used for frontal collision and UI mapping (meters).\n * \n * This approximates the biacromial (shoulder-to-shoulder) breadth for an\n * adult, which is sufficient for our hitbox and overlay alignment needs.\n */\nconst AVERAGE_SHOULDER_WIDTH_M = 0.5; // 50cm shoulder width\n\n/**\n * Average torso depth (chest to back) used for front/back hit placement (meters).\n */\nconst AVERAGE_TORSO_DEPTH_M = 0.3; // 30cm chest depth\n\n/**\n * Default UI overlay width in pixels.\n * \n * This matches the designed vital-point sprite asset width, ensuring that\n * pixel coordinates from the overlay map consistently to the 3D character.\n */\nconst DEFAULT_OVERLAY_WIDTH_PX = 200; // Standard UI overlay width\n\n/**\n * Default UI overlay height in pixels.\n * \n * This matches the designed vital-point sprite asset height, keeping the\n * 2D→3D mapping resolution-independent but asset-consistent.\n */\nconst DEFAULT_OVERLAY_HEIGHT_PX = 300; // Standard UI overlay height\n\n/**\n * Default character model configuration based on average adult proportions.\n */\nconst DEFAULT_CHARACTER_CONFIG: CharacterModelConfig = {\n  height: AVERAGE_ADULT_HEIGHT_M,\n  width: AVERAGE_SHOULDER_WIDTH_M,\n  depth: AVERAGE_TORSO_DEPTH_M,\n  overlayWidth: DEFAULT_OVERLAY_WIDTH_PX,\n  overlayHeight: DEFAULT_OVERLAY_HEIGHT_PX,\n};\n\n/**\n * Z-depth (front-to-back) offsets for different anatomical regions.\n * \n * Units are **meters in model space**, measured along the character's local Z axis,\n * and are applied relative to the character's center plane (Z = 0) and the\n * configured {@link CharacterModelConfig.depth}. With the default depth of\n * `0.3m`, an offset of `0.05` corresponds to ≈5 cm of forward displacement.\n *\n * These values were chosen as simple, stable approximations based on average\n * adult proportions and validated visually against the default rig:\n *\n * - `head: 0.05` → head center sits slightly in front of the torso plane\n *   (≈1/6 of torso depth) to match typical forward head posture.\n * - `neck: 0.02` → neck base is close to the torso plane but not perfectly\n *   centered, acknowledging slight anterior offset of the trachea/sternum.\n * - `torso: 0.0` → torso vital points lie on the reference center plane that\n *   approximates the mid‑chest / spine midpoint.\n * - `arms: 0.05` → relaxed arms hang slightly in front of the torso plane,\n *   using the same forward offset as the head for consistency.\n * - `legs: 0.0` → leg targets (front of thighs/shins) are modeled on the\n *   center plane; depth variation is instead captured by vertical placement.\n *\n * If you change {@link CharacterModelConfig.depth}, you may keep these absolute\n * meter values (for physical fidelity) or re‑express them as fractions of the\n * new depth, but they should continue to represent small (≈0–5 cm) anatomical\n * offsets from the torso midline.\n */\nconst REGION_DEPTH_OFFSETS: Record<AnatomicalRegionPhysics, number> = {\n  head: 0.05,    // ≈5 cm forward from torso mid-plane to match cranial alignment\n  neck: 0.02,    // ≈2 cm forward; neck base is near, but not exactly on, center\n  torso: 0.0,    // Torso reference plane (mid‑chest / spine midpoint)\n  arms: 0.05,    // ≈5 cm forward; relaxed arms rest slightly in front of torso\n  legs: 0.0,     // Legs aligned to torso center plane; front/back handled elsewhere\n};\n\n/**\n * Coordinate Mapper for converting 2D pixel coordinates to 3D world coordinates.\n * \n * **Korean**: 좌표 변환기\n * \n * Provides bidirectional mapping between the 2D UI overlay coordinate system\n * and the 3D physics world coordinate system.\n * \n * @public\n * @category Physics System\n * @korean 좌표변환기\n */\nexport class CoordinateMapper {\n  private readonly config: CharacterModelConfig;\n  \n  /**\n   * Creates a new CoordinateMapper with optional custom configuration.\n   * \n   * @param config - Optional character model configuration\n   */\n  constructor(config: Partial<CharacterModelConfig> = {}) {\n    this.config = { ...DEFAULT_CHARACTER_CONFIG, ...config };\n  }\n  \n  /**\n   * Converts a 2D pixel position to a 3D world position.\n   * \n   * **Korean**: 2D → 3D 변환\n   * \n   * Maps UI overlay pixel coordinates to 3D world space coordinates suitable\n   * for physics collision detection.\n   * \n   * @param pixel2D - 2D pixel position (origin top-left)\n   * @param region - Anatomical region for Z-depth calculation\n   * @returns 3D world position in meters (origin at character center)\n   * \n   * @example\n   * ```typescript\n   * const mapper = new CoordinateMapper();\n   * const vitalPoint = { position: { x: 100, y: 50 } };\n   * const worldPos = mapper.pixel2DToWorld3D(vitalPoint.position, \"head\");\n   * // worldPos: { x: 0, y: 1.45, z: 0.05 }\n   * ```\n   */\n  pixel2DToWorld3D(pixel2D: Position, region: AnatomicalRegionPhysics): Position3D {\n    // Normalize pixel coordinates to 0-1 range\n    const normalizedX = pixel2D.x / this.config.overlayWidth;\n    const normalizedY = pixel2D.y / this.config.overlayHeight;\n    \n    // Convert to world coordinates\n    // X: Map from pixel space (0 = left, overlayWidth = right) to world space (-width/2 to +width/2)\n    const worldX = (normalizedX - 0.5) * this.config.width;\n    \n    // Y: Map from pixel space (0 = top, overlayHeight = bottom) to world space (height to 0)\n    // Invert Y-axis: pixel 0 = top = character head, pixel overlayHeight = bottom = character feet\n    const worldY = (1 - normalizedY) * this.config.height;\n    \n    // Z: Use anatomical region to determine depth offset\n    const worldZ = REGION_DEPTH_OFFSETS[region];\n    \n    return {\n      x: worldX,\n      y: worldY,\n      z: worldZ,\n    };\n  }\n  \n  /**\n   * Converts a 3D world position to a 2D pixel position.\n   * \n   * **Korean**: 3D → 2D 변환\n   * \n   * Maps 3D world space coordinates back to UI overlay pixel coordinates.\n   * Useful for debugging and visual feedback.\n   * \n   * @param world3D - 3D world position in meters\n   * @returns 2D pixel position (origin top-left)\n   * \n   * @example\n   * ```typescript\n   * const mapper = new CoordinateMapper();\n   * const worldPos = { x: 0, y: 1.45, z: 0.05 };\n   * const pixelPos = mapper.world3DToPixel2D(worldPos);\n   * // pixelPos: { x: 100, y: 50 }\n   * ```\n   */\n  world3DToPixel2D(world3D: Position3D): Position {\n    // Convert world X to normalized 0-1 range\n    const normalizedX = (world3D.x / this.config.width) + 0.5;\n    \n    // Convert world Y to normalized 0-1 range (inverted)\n    const normalizedY = 1 - (world3D.y / this.config.height);\n    \n    // Convert to pixel coordinates\n    return {\n      x: Math.round(normalizedX * this.config.overlayWidth),\n      y: Math.round(normalizedY * this.config.overlayHeight),\n    };\n  }\n  \n  /**\n   * Converts a vital point's 2D position to 3D world position.\n   * \n   * **Korean**: 급소 위치 변환\n   * \n   * Convenience method that extracts position and region from a VitalPoint object.\n   * \n   * @param vitalPoint - Vital point with 2D position\n   * @returns 3D world position\n   * \n   * @example\n   * ```typescript\n   * const mapper = new CoordinateMapper();\n   * const temple = VITAL_POINTS_DATA.find(vp => vp.id === \"head_temple\");\n   * const worldPos = mapper.vitalPointToWorld3D(temple);\n   * ```\n   */\n  vitalPointToWorld3D(vitalPoint: VitalPoint): Position3D {\n    // Infer region from vital point ID prefix\n    const region = this.inferRegionFromId(vitalPoint.id);\n    return this.pixel2DToWorld3D(vitalPoint.position, region);\n  }\n  \n  /**\n   * Infers the anatomical region from a vital point ID.\n   * \n   * **Korean**: 급소 ID에서 영역 추론\n   * \n   * @param vitalPointId - Vital point ID (e.g., \"head_temple\", \"torso_solar_plexus\")\n   * @returns Anatomical region\n   * \n   * @private\n   */\n  private inferRegionFromId(vitalPointId: string): AnatomicalRegionPhysics {\n    if (vitalPointId.startsWith(\"head_\")) return \"head\";\n    if (vitalPointId.startsWith(\"neck_\")) return \"neck\";\n    if (vitalPointId.startsWith(\"torso_\")) return \"torso\";\n    if (vitalPointId.startsWith(\"arm_\")) return \"arms\";\n    if (vitalPointId.startsWith(\"leg_\")) return \"legs\";\n    \n    // Default to torso if no clear region prefix\n    return \"torso\";\n  }\n  \n  /**\n   * Calculates the distance between a 3D point and a vital point's 3D position.\n   * \n   * **Korean**: 거리 계산\n   * \n   * @param point3D - Point in 3D world space\n   * @param vitalPoint - Vital point to measure distance to\n   * @returns Distance in meters\n   * \n   * @example\n   * ```typescript\n   * const mapper = new CoordinateMapper();\n   * const attackPoint = { x: 0, y: 1.5, z: 0.1 };\n   * const temple = VITAL_POINTS_DATA.find(vp => vp.id === \"head_temple\");\n   * const distance = mapper.distanceToVitalPoint(attackPoint, temple);\n   * ```\n   */\n  distanceToVitalPoint(point3D: Position3D, vitalPoint: VitalPoint): number {\n    const vitalPoint3D = this.vitalPointToWorld3D(vitalPoint);\n    \n    const dx = point3D.x - vitalPoint3D.x;\n    const dy = point3D.y - vitalPoint3D.y;\n    const dz = point3D.z - vitalPoint3D.z;\n    \n    return Math.sqrt(dx * dx + dy * dy + dz * dz);\n  }\n  \n  /**\n   * Finds the closest vital point to a 3D position within a given region.\n   * \n   * **Korean**: 가장 가까운 급소 찾기\n   * \n   * @param point3D - Point in 3D world space\n   * @param vitalPoints - Array of vital points to search\n   * @param region - Optional region filter\n   * @returns Closest vital point and distance, or null if none found\n   * \n   * @example\n   * ```typescript\n   * const mapper = new CoordinateMapper();\n   * const hitPoint = { x: 0, y: 1.7, z: 0.05 };\n   * const result = mapper.findClosestVitalPoint(hitPoint, VITAL_POINTS_DATA, \"head\");\n   * if (result) {\n   *   console.log(`Hit ${result.vitalPoint.names.english} at ${result.distance}m`);\n   * }\n   * ```\n   */\n  findClosestVitalPoint(\n    point3D: Position3D,\n    vitalPoints: readonly VitalPoint[],\n    region?: AnatomicalRegionPhysics\n  ): { vitalPoint: VitalPoint; distance: number } | null {\n    let closestVitalPoint: VitalPoint | null = null;\n    let closestDistance = Infinity;\n    \n    for (const vitalPoint of vitalPoints) {\n      // Filter by region if specified\n      if (region) {\n        const vpRegion = this.inferRegionFromId(vitalPoint.id);\n        if (vpRegion !== region) continue;\n      }\n      \n      const distance = this.distanceToVitalPoint(point3D, vitalPoint);\n      \n      if (distance < closestDistance) {\n        closestDistance = distance;\n        closestVitalPoint = vitalPoint;\n      }\n    }\n    \n    if (closestVitalPoint === null) {\n      return null;\n    }\n    \n    return {\n      vitalPoint: closestVitalPoint,\n      distance: closestDistance,\n    };\n  }\n  \n  /**\n   * Gets the current character model configuration.\n   * \n   * @returns Current configuration\n   */\n  getConfig(): CharacterModelConfig {\n    return { ...this.config };\n  }\n}\n\n/**\n * Default singleton instance for convenient access.\n * \n * **Korean**: 기본 인스턴스\n * \n * @example\n * ```typescript\n * import { defaultCoordinateMapper } from './CoordinateMapper';\n * \n * const worldPos = defaultCoordinateMapper.pixel2DToWorld3D({ x: 100, y: 50 }, \"head\");\n * ```\n */\nexport const defaultCoordinateMapper = new CoordinateMapper();\n"],"mappings":";;;;AAiGA,IAAM,2BAAiD;CACrD,QAnC6B;CAoC7B,OA5B+B;CA6B/B,OAxB4B;CAyB5B,cAjB+B;CAkB/B,eAVgC;CAWjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BD,IAAM,uBAAgE;CACpE,MAAM;CACN,MAAM;CACN,OAAO;CACP,MAAM;CACN,MAAM;CACP;;;;;;;;;;;;;AAcD,IAAa,mBAAb,MAA8B;CAC5B;;;;;;CAOA,YAAY,SAAwC,EAAE,EAAE;AACtD,OAAK,SAAS;GAAE,GAAG;GAA0B,GAAG;GAAQ;;;;;;;;;;;;;;;;;;;;;;CAuB1D,iBAAiB,SAAmB,QAA6C;EAE/E,MAAM,cAAc,QAAQ,IAAI,KAAK,OAAO;EAC5C,MAAM,cAAc,QAAQ,IAAI,KAAK,OAAO;AAa5C,SAAO;GACL,IAVc,cAAc,MAAO,KAAK,OAAO;GAW/C,IAPc,IAAI,eAAe,KAAK,OAAO;GAQ7C,GALa,qBAAqB;GAMnC;;;;;;;;;;;;;;;;;;;;;CAsBH,iBAAiB,SAA+B;EAE9C,MAAM,cAAe,QAAQ,IAAI,KAAK,OAAO,QAAS;EAGtD,MAAM,cAAc,IAAK,QAAQ,IAAI,KAAK,OAAO;AAGjD,SAAO;GACL,GAAG,KAAK,MAAM,cAAc,KAAK,OAAO,aAAa;GACrD,GAAG,KAAK,MAAM,cAAc,KAAK,OAAO,cAAc;GACvD;;;;;;;;;;;;;;;;;;;CAoBH,oBAAoB,YAAoC;EAEtD,MAAM,SAAS,KAAK,kBAAkB,WAAW,GAAG;AACpD,SAAO,KAAK,iBAAiB,WAAW,UAAU,OAAO;;;;;;;;;;;;CAa3D,kBAA0B,cAA+C;AACvE,MAAI,aAAa,WAAW,QAAQ,CAAE,QAAO;AAC7C,MAAI,aAAa,WAAW,QAAQ,CAAE,QAAO;AAC7C,MAAI,aAAa,WAAW,SAAS,CAAE,QAAO;AAC9C,MAAI,aAAa,WAAW,OAAO,CAAE,QAAO;AAC5C,MAAI,aAAa,WAAW,OAAO,CAAE,QAAO;AAG5C,SAAO;;;;;;;;;;;;;;;;;;;CAoBT,qBAAqB,SAAqB,YAAgC;EACxE,MAAM,eAAe,KAAK,oBAAoB,WAAW;EAEzD,MAAM,KAAK,QAAQ,IAAI,aAAa;EACpC,MAAM,KAAK,QAAQ,IAAI,aAAa;EACpC,MAAM,KAAK,QAAQ,IAAI,aAAa;AAEpC,SAAO,KAAK,KAAK,KAAK,KAAK,KAAK,KAAK,KAAK,GAAG;;;;;;;;;;;;;;;;;;;;;;CAuB/C,sBACE,SACA,aACA,QACqD;EACrD,IAAI,oBAAuC;EAC3C,IAAI,kBAAkB;AAEtB,OAAK,MAAM,cAAc,aAAa;AAEpC,OAAI;QACe,KAAK,kBAAkB,WAAW,GAAG,KACrC,OAAQ;;GAG3B,MAAM,WAAW,KAAK,qBAAqB,SAAS,WAAW;AAE/D,OAAI,WAAW,iBAAiB;AAC9B,sBAAkB;AAClB,wBAAoB;;;AAIxB,MAAI,sBAAsB,KACxB,QAAO;AAGT,SAAO;GACL,YAAY;GACZ,UAAU;GACX;;;;;;;CAQH,YAAkC;AAChC,SAAO,EAAE,GAAG,KAAK,QAAQ;;;AAgBU,IAAI,kBAAkB"}