blacktrigram 0.7.2

package/lib/utils/arenaWorldDimensions.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Arena world dimension calculations for physics-first coordinate system.
+ *
+ * Determines the physical size of the combat arena in meters based on
+ * screen **resolution** (not device type), ensuring appropriate gameplay
+ * space for different display capabilities.
+ *
+ * **Important**: Arena size is determined by RESOLUTION, not device type.
+ * A mobile device with a 4K screen gets a larger arena than a desktop with
+ * 1080p resolution, because arena size should match display capability.
+ *
+ * **4:3 Aspect Ratio Philosophy**:
+ * All arenas use 4:3 aspect ratio (width > height) for optimal screen usage.
+ * Width sizes: 6m, 8m, 10m, 12m, 14m based on resolution.
+ * Height is calculated as width × 0.75 (3/4).
+ * This ensures:
+ * - Efficient use of horizontal screen space
+ * - Consistent physics across all devices
+ * - Traditional fighting game proportions
+ *
+ * **Korean**: 경기장세계크기 (Arena World Size)
+ *
+ * @module utils/arenaWorldDimensions
+ * @category Physics
+ */
+/**
+ * Screen size category based on RESOLUTION (width in pixels).
+ *
+ * **Korean**: 화면크기범주 (Screen Size Category)
+ *
+ * @public
+ */
+export type ScreenSizeCategory = "small" | "medium" | "large" | "xlarge" | "ultra";
+/**
+ * Standard arena widths in meters.
+ * Arenas use 4:3 aspect ratio (height = width × 0.75).
+ *
+ * @public
+ */
+export declare const ARENA_SIZES: {
+    /** Small arena for compact screens (6m × 4.5m) */
+    readonly SMALL: 6;
+    /** Medium arena for tablets and small laptops (8m × 6m) */
+    readonly MEDIUM: 8;
+    /** Large arena for standard desktops (10m × 7.5m) */
+    readonly LARGE: 10;
+    /** Extra-large arena for high-res displays (12m × 9m) */
+    readonly XLARGE: 12;
+    /** Ultra arena for 4K+ displays (14m × 10.5m) */
+    readonly ULTRA: 14;
+};
+/**
+ * Resolution breakpoints for arena size determination.
+ * Based on common display widths.
+ *
+ * @public
+ */
+export declare const RESOLUTION_BREAKPOINTS: {
+    /** Small screens: < 768px (phones, small tablets) */
+    readonly SMALL_MAX: 768;
+    /** Medium screens: 768-1199px (tablets, small laptops) */
+    readonly MEDIUM_MAX: 1200;
+    /** Large screens: 1200-1919px (laptops, standard monitors) */
+    readonly LARGE_MAX: 1920;
+    /** XLarge screens: 1920-2559px (large monitors, some 4K) */
+    readonly XLARGE_MAX: 2560;
+};
+/**
+ * World dimensions for an arena in meters.
+ *
+ * **Korean**: 세계크기 (World Dimensions)
+ *
+ * @public
+ */
+export interface WorldDimensions {
+    /** Arena width in meters */
+    readonly widthMeters: number;
+    /** Arena depth in meters (height = width × 0.75 for 4:3 ratio) */
+    readonly depthMeters: number;
+    /** Arena width in meters (same as widthMeters, for convenience) */
+    readonly sizeMeters: number;
+    /** Screen category used to determine arena size */
+    readonly screenCategory: ScreenSizeCategory;
+}
+/**
+ * Complete arena configuration including pixel and meter dimensions.
+ *
+ * @public
+ */
+export interface ArenaConfiguration {
+    /** Arena position X in pixels */
+    readonly x: number;
+    /** Arena position Y in pixels */
+    readonly y: number;
+    /** Arena width in pixels */
+    readonly width: number;
+    /** Arena height in pixels */
+    readonly height: number;
+    /** Arena world width in meters */
+    readonly worldWidthMeters: number;
+    /** Arena world depth in meters */
+    readonly worldDepthMeters: number;
+    /** Pixels per meter ratio for this arena */
+    readonly pixelsPerMeter: number;
+    /** Scale factor (1.0 = reference desktop, <1.0 = smaller screens) */
+    readonly scale: number;
+}
+/**
+ * Categorize screen based on resolution (width in pixels).
+ *
+ * This is used for arena sizing. Device type (mobile/desktop) is determined
+ * separately for UI controls only.
+ *
+ * **Korean**: 화면크기범주결정 (Determine Screen Size Category)
+ *
+ * @param screenWidth - Screen width in pixels
+ * @returns Screen size category for arena dimensions
+ *
+ * @example
+ * ```typescript
+ * getScreenSizeCategory(640);   // "small" - small phone
+ * getScreenSizeCategory(1200);  // "large" - standard laptop
+ * getScreenSizeCategory(3840);  // "ultra" - 4K display
+ * ```
+ *
+ * @public
+ */
+export declare function getScreenSizeCategory(screenWidth: number): ScreenSizeCategory;
+/**
+ * Get arena size in meters for a given screen category.
+ *
+ * @param category - Screen size category
+ * @returns Arena size in meters (square dimension)
+ *
+ * @public
+ */
+export declare function getArenaSizeForCategory(category: ScreenSizeCategory): number;
+/**
+ * Calculate appropriate arena world dimensions based on screen resolution.
+ *
+ * Larger resolution displays get larger arenas for better gameplay, while
+ * maintaining the same physical combat mechanics. Movement speed in m/s
+ * remains constant, but larger arenas provide more tactical space.
+ *
+ * **Arenas use 4:3 aspect ratio** (width > depth):
+ * - < 768px: 6m × 4.5m (compact, fast-paced combat)
+ * - 768-1199px: 8m × 6m (balanced gameplay)
+ * - 1200-1919px: 10m × 7.5m (tactical combat)
+ * - 1920-2559px: 12m × 9m (advanced positioning)
+ * - ≥ 2560px: 14m × 10.5m (maximum tactical space)
+ *
+ * **Korean**: 경기장크기계산 (Calculate Arena Size)
+ *
+ * @param screenWidth - Screen width in pixels (resolution, not device type)
+ * @returns World dimensions in meters (4:3 aspect ratio)
+ *
+ * @example
+ * ```typescript
+ * // Mobile phone 640px width
+ * const smallPhone = calculateArenaWorldDimensions(640);
+ * // Result: { widthMeters: 6, depthMeters: 4.5, sizeMeters: 6, screenCategory: "small" }
+ *
+ * // Desktop 1920×1080
+ * const desktop = calculateArenaWorldDimensions(1920);
+ * // Result: { widthMeters: 12, depthMeters: 9, sizeMeters: 12, screenCategory: "xlarge" }
+ * ```
+ *
+ * @public
+ */
+export declare function calculateArenaWorldDimensions(screenWidth: number): WorldDimensions;
+/**
+ * Calculate complete arena configuration including pixel and meter dimensions.
+ *
+ * This is the primary function for setting up arena bounds. It calculates:
+ * - Pixel dimensions based on available screen space
+ * - Meter dimensions based on screen resolution category
+ * - Pixels-per-meter ratio for physics conversion
+ *
+ * @param screenWidth - Screen width in pixels
+ * @param screenHeight - Screen height in pixels
+ * @param topOffset - Pixels reserved at top (HUD, headers)
+ * @param bottomOffset - Pixels reserved at bottom (controls, footer)
+ * @param horizontalMargin - Pixels to leave on sides (as ratio 0-1)
+ * @returns Complete arena configuration
+ *
+ * @public
+ */
+export declare function calculateArenaConfiguration(screenWidth: number, screenHeight: number, topOffset: number, bottomOffset: number, horizontalMargin?: number): ArenaConfiguration;
+/**
+ * Calculate pixels-per-meter ratio from arena dimensions.
+ *
+ * @param arenaWidthPixels - Arena width in pixels
+ * @param arenaWidthMeters - Arena width in meters
+ * @returns Pixels per meter ratio
+ *
+ * @public
+ */
+export declare function calculatePixelsPerMeter(arenaWidthPixels: number, arenaWidthMeters: number): number;
+/**
+ * Get player height in meters from archetype physical attributes.
+ *
+ * Converts archetype totalHeight (in centimeters) to meters for physics calculations.
+ *
+ * **Korean**: 플레이어키 (Player Height)
+ *
+ * @param archetypeHeightCm - Player height in centimeters from PhysicalAttributes
+ * @returns Height in meters
+ *
+ * @example
+ * ```typescript
+ * // Musa archetype: 180cm
+ * const height = getPlayerHeightMeters(180);
+ * // Result: 1.8 meters
+ * ```
+ *
+ * @public
+ */
+export declare function getPlayerHeightMeters(archetypeHeightCm: number): number;
+//# sourceMappingURL=arenaWorldDimensions.d.ts.map

package/lib/utils/arenaWorldDimensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arenaWorldDimensions.d.ts","sourceRoot":"","sources":["../../src/utils/arenaWorldDimensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAC1B,OAAO,GACP,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,OAAO,CAAC;AAEZ;;;;;GAKG;AACH,eAAO,MAAM,WAAW;IACtB,kDAAkD;;IAElD,2DAA2D;;IAE3D,qDAAqD;;IAErD,yDAAyD;;IAEzD,iDAAiD;;CAEzC,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;IACjC,qDAAqD;;IAErD,0DAA0D;;IAE1D,8DAA8D;;IAE9D,4DAA4D;;CAGpD,CAAC;AAEX;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,cAAc,EAAE,kBAAkB,CAAC;CAC7C;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,iCAAiC;IACjC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,kCAAkC;IAClC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,4CAA4C;IAC5C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,CAM7E;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,CAe5E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,MAAM,GAClB,eAAe,CAYjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,gBAAgB,GAAE,MAAY,GAC7B,kBAAkB,CAgCpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,gBAAgB,EAAE,MAAM,EACxB,gBAAgB,EAAE,MAAM,GACvB,MAAM,CAKR;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAEvE"}

package/lib/utils/arenaWorldDimensions.js

@@ -0,0 +1,154 @@
+//#region src/utils/arenaWorldDimensions.ts
+/**
+* Standard arena widths in meters.
+* Arenas use 4:3 aspect ratio (height = width × 0.75).
+*
+* @public
+*/
+var ARENA_SIZES = {
+	SMALL: 6,
+	MEDIUM: 8,
+	LARGE: 10,
+	XLARGE: 12,
+	ULTRA: 14
+};
+/**
+* Resolution breakpoints for arena size determination.
+* Based on common display widths.
+*
+* @public
+*/
+var RESOLUTION_BREAKPOINTS = {
+	SMALL_MAX: 768,
+	MEDIUM_MAX: 1200,
+	LARGE_MAX: 1920,
+	XLARGE_MAX: 2560
+};
+/**
+* Categorize screen based on resolution (width in pixels).
+*
+* This is used for arena sizing. Device type (mobile/desktop) is determined
+* separately for UI controls only.
+*
+* **Korean**: 화면크기범주결정 (Determine Screen Size Category)
+*
+* @param screenWidth - Screen width in pixels
+* @returns Screen size category for arena dimensions
+*
+* @example
+* ```typescript
+* getScreenSizeCategory(640);   // "small" - small phone
+* getScreenSizeCategory(1200);  // "large" - standard laptop
+* getScreenSizeCategory(3840);  // "ultra" - 4K display
+* ```
+*
+* @public
+*/
+function getScreenSizeCategory(screenWidth) {
+	if (screenWidth < RESOLUTION_BREAKPOINTS.SMALL_MAX) return "small";
+	if (screenWidth < RESOLUTION_BREAKPOINTS.MEDIUM_MAX) return "medium";
+	if (screenWidth < RESOLUTION_BREAKPOINTS.LARGE_MAX) return "large";
+	if (screenWidth < RESOLUTION_BREAKPOINTS.XLARGE_MAX) return "xlarge";
+	return "ultra";
+}
+/**
+* Get arena size in meters for a given screen category.
+*
+* @param category - Screen size category
+* @returns Arena size in meters (square dimension)
+*
+* @public
+*/
+function getArenaSizeForCategory(category) {
+	switch (category) {
+		case "small": return ARENA_SIZES.SMALL;
+		case "medium": return ARENA_SIZES.MEDIUM;
+		case "large": return ARENA_SIZES.LARGE;
+		case "xlarge": return ARENA_SIZES.XLARGE;
+		case "ultra": return ARENA_SIZES.ULTRA;
+		default: return ARENA_SIZES.LARGE;
+	}
+}
+/**
+* Calculate appropriate arena world dimensions based on screen resolution.
+*
+* Larger resolution displays get larger arenas for better gameplay, while
+* maintaining the same physical combat mechanics. Movement speed in m/s
+* remains constant, but larger arenas provide more tactical space.
+*
+* **Arenas use 4:3 aspect ratio** (width > depth):
+* - < 768px: 6m × 4.5m (compact, fast-paced combat)
+* - 768-1199px: 8m × 6m (balanced gameplay)
+* - 1200-1919px: 10m × 7.5m (tactical combat)
+* - 1920-2559px: 12m × 9m (advanced positioning)
+* - ≥ 2560px: 14m × 10.5m (maximum tactical space)
+*
+* **Korean**: 경기장크기계산 (Calculate Arena Size)
+*
+* @param screenWidth - Screen width in pixels (resolution, not device type)
+* @returns World dimensions in meters (4:3 aspect ratio)
+*
+* @example
+* ```typescript
+* // Mobile phone 640px width
+* const smallPhone = calculateArenaWorldDimensions(640);
+* // Result: { widthMeters: 6, depthMeters: 4.5, sizeMeters: 6, screenCategory: "small" }
+*
+* // Desktop 1920×1080
+* const desktop = calculateArenaWorldDimensions(1920);
+* // Result: { widthMeters: 12, depthMeters: 9, sizeMeters: 12, screenCategory: "xlarge" }
+* ```
+*
+* @public
+*/
+function calculateArenaWorldDimensions(screenWidth) {
+	const category = getScreenSizeCategory(screenWidth);
+	const sizeMeters = getArenaSizeForCategory(category);
+	return {
+		widthMeters: sizeMeters,
+		depthMeters: sizeMeters * .75,
+		sizeMeters,
+		screenCategory: category
+	};
+}
+/**
+* Calculate complete arena configuration including pixel and meter dimensions.
+*
+* This is the primary function for setting up arena bounds. It calculates:
+* - Pixel dimensions based on available screen space
+* - Meter dimensions based on screen resolution category
+* - Pixels-per-meter ratio for physics conversion
+*
+* @param screenWidth - Screen width in pixels
+* @param screenHeight - Screen height in pixels
+* @param topOffset - Pixels reserved at top (HUD, headers)
+* @param bottomOffset - Pixels reserved at bottom (controls, footer)
+* @param horizontalMargin - Pixels to leave on sides (as ratio 0-1)
+* @returns Complete arena configuration
+*
+* @public
+*/
+function calculateArenaConfiguration(screenWidth, screenHeight, topOffset, bottomOffset, horizontalMargin = .1) {
+	const worldDimensions = calculateArenaWorldDimensions(screenWidth);
+	const availableWidth = screenWidth * (1 - 2 * horizontalMargin);
+	const availableHeight = screenHeight - topOffset - bottomOffset;
+	const arenaSizePixels = Math.min(availableWidth, availableHeight);
+	const arenaX = (screenWidth - arenaSizePixels) / 2;
+	const arenaY = topOffset;
+	const pixelsPerMeter = arenaSizePixels / worldDimensions.sizeMeters;
+	const scale = pixelsPerMeter / 100;
+	return {
+		x: arenaX,
+		y: arenaY,
+		width: arenaSizePixels,
+		height: arenaSizePixels,
+		worldWidthMeters: worldDimensions.widthMeters,
+		worldDepthMeters: worldDimensions.depthMeters,
+		pixelsPerMeter,
+		scale
+	};
+}
+//#endregion
+export { calculateArenaConfiguration, calculateArenaWorldDimensions };
+
+//# sourceMappingURL=arenaWorldDimensions.js.map

package/lib/utils/arenaWorldDimensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arenaWorldDimensions.js","names":[],"sources":["../../src/utils/arenaWorldDimensions.ts"],"sourcesContent":["/**\n * Arena world dimension calculations for physics-first coordinate system.\n *\n * Determines the physical size of the combat arena in meters based on\n * screen **resolution** (not device type), ensuring appropriate gameplay\n * space for different display capabilities.\n *\n * **Important**: Arena size is determined by RESOLUTION, not device type.\n * A mobile device with a 4K screen gets a larger arena than a desktop with\n * 1080p resolution, because arena size should match display capability.\n *\n * **4:3 Aspect Ratio Philosophy**:\n * All arenas use 4:3 aspect ratio (width > height) for optimal screen usage.\n * Width sizes: 6m, 8m, 10m, 12m, 14m based on resolution.\n * Height is calculated as width × 0.75 (3/4).\n * This ensures:\n * - Efficient use of horizontal screen space\n * - Consistent physics across all devices\n * - Traditional fighting game proportions\n *\n * **Korean**: 경기장세계크기 (Arena World Size)\n *\n * @module utils/arenaWorldDimensions\n * @category Physics\n */\n\n/**\n * Screen size category based on RESOLUTION (width in pixels).\n *\n * **Korean**: 화면크기범주 (Screen Size Category)\n *\n * @public\n */\nexport type ScreenSizeCategory =\n  | \"small\"\n  | \"medium\"\n  | \"large\"\n  | \"xlarge\"\n  | \"ultra\";\n\n/**\n * Standard arena widths in meters.\n * Arenas use 4:3 aspect ratio (height = width × 0.75).\n *\n * @public\n */\nexport const ARENA_SIZES = {\n  /** Small arena for compact screens (6m × 4.5m) */\n  SMALL: 6,\n  /** Medium arena for tablets and small laptops (8m × 6m) */\n  MEDIUM: 8,\n  /** Large arena for standard desktops (10m × 7.5m) */\n  LARGE: 10,\n  /** Extra-large arena for high-res displays (12m × 9m) */\n  XLARGE: 12,\n  /** Ultra arena for 4K+ displays (14m × 10.5m) */\n  ULTRA: 14,\n} as const;\n\n/**\n * Resolution breakpoints for arena size determination.\n * Based on common display widths.\n *\n * @public\n */\nexport const RESOLUTION_BREAKPOINTS = {\n  /** Small screens: < 768px (phones, small tablets) */\n  SMALL_MAX: 768,\n  /** Medium screens: 768-1199px (tablets, small laptops) */\n  MEDIUM_MAX: 1200,\n  /** Large screens: 1200-1919px (laptops, standard monitors) */\n  LARGE_MAX: 1920,\n  /** XLarge screens: 1920-2559px (large monitors, some 4K) */\n  XLARGE_MAX: 2560,\n  /** Ultra screens: ≥ 2560px (4K, ultrawide) */\n} as const;\n\n/**\n * World dimensions for an arena in meters.\n *\n * **Korean**: 세계크기 (World Dimensions)\n *\n * @public\n */\nexport interface WorldDimensions {\n  /** Arena width in meters */\n  readonly widthMeters: number;\n  /** Arena depth in meters (height = width × 0.75 for 4:3 ratio) */\n  readonly depthMeters: number;\n  /** Arena width in meters (same as widthMeters, for convenience) */\n  readonly sizeMeters: number;\n  /** Screen category used to determine arena size */\n  readonly screenCategory: ScreenSizeCategory;\n}\n\n/**\n * Complete arena configuration including pixel and meter dimensions.\n *\n * @public\n */\nexport interface ArenaConfiguration {\n  /** Arena position X in pixels */\n  readonly x: number;\n  /** Arena position Y in pixels */\n  readonly y: number;\n  /** Arena width in pixels */\n  readonly width: number;\n  /** Arena height in pixels */\n  readonly height: number;\n  /** Arena world width in meters */\n  readonly worldWidthMeters: number;\n  /** Arena world depth in meters */\n  readonly worldDepthMeters: number;\n  /** Pixels per meter ratio for this arena */\n  readonly pixelsPerMeter: number;\n  /** Scale factor (1.0 = reference desktop, <1.0 = smaller screens) */\n  readonly scale: number;\n}\n\n/**\n * Categorize screen based on resolution (width in pixels).\n *\n * This is used for arena sizing. Device type (mobile/desktop) is determined\n * separately for UI controls only.\n *\n * **Korean**: 화면크기범주결정 (Determine Screen Size Category)\n *\n * @param screenWidth - Screen width in pixels\n * @returns Screen size category for arena dimensions\n *\n * @example\n * ```typescript\n * getScreenSizeCategory(640);   // \"small\" - small phone\n * getScreenSizeCategory(1200);  // \"large\" - standard laptop\n * getScreenSizeCategory(3840);  // \"ultra\" - 4K display\n * ```\n *\n * @public\n */\nexport function getScreenSizeCategory(screenWidth: number): ScreenSizeCategory {\n  if (screenWidth < RESOLUTION_BREAKPOINTS.SMALL_MAX) return \"small\";\n  if (screenWidth < RESOLUTION_BREAKPOINTS.MEDIUM_MAX) return \"medium\";\n  if (screenWidth < RESOLUTION_BREAKPOINTS.LARGE_MAX) return \"large\";\n  if (screenWidth < RESOLUTION_BREAKPOINTS.XLARGE_MAX) return \"xlarge\";\n  return \"ultra\";\n}\n\n/**\n * Get arena size in meters for a given screen category.\n *\n * @param category - Screen size category\n * @returns Arena size in meters (square dimension)\n *\n * @public\n */\nexport function getArenaSizeForCategory(category: ScreenSizeCategory): number {\n  switch (category) {\n    case \"small\":\n      return ARENA_SIZES.SMALL;\n    case \"medium\":\n      return ARENA_SIZES.MEDIUM;\n    case \"large\":\n      return ARENA_SIZES.LARGE;\n    case \"xlarge\":\n      return ARENA_SIZES.XLARGE;\n    case \"ultra\":\n      return ARENA_SIZES.ULTRA;\n    default:\n      return ARENA_SIZES.LARGE;\n  }\n}\n\n/**\n * Calculate appropriate arena world dimensions based on screen resolution.\n *\n * Larger resolution displays get larger arenas for better gameplay, while\n * maintaining the same physical combat mechanics. Movement speed in m/s\n * remains constant, but larger arenas provide more tactical space.\n *\n * **Arenas use 4:3 aspect ratio** (width > depth):\n * - < 768px: 6m × 4.5m (compact, fast-paced combat)\n * - 768-1199px: 8m × 6m (balanced gameplay)\n * - 1200-1919px: 10m × 7.5m (tactical combat)\n * - 1920-2559px: 12m × 9m (advanced positioning)\n * - ≥ 2560px: 14m × 10.5m (maximum tactical space)\n *\n * **Korean**: 경기장크기계산 (Calculate Arena Size)\n *\n * @param screenWidth - Screen width in pixels (resolution, not device type)\n * @returns World dimensions in meters (4:3 aspect ratio)\n *\n * @example\n * ```typescript\n * // Mobile phone 640px width\n * const smallPhone = calculateArenaWorldDimensions(640);\n * // Result: { widthMeters: 6, depthMeters: 4.5, sizeMeters: 6, screenCategory: \"small\" }\n *\n * // Desktop 1920×1080\n * const desktop = calculateArenaWorldDimensions(1920);\n * // Result: { widthMeters: 12, depthMeters: 9, sizeMeters: 12, screenCategory: \"xlarge\" }\n * ```\n *\n * @public\n */\nexport function calculateArenaWorldDimensions(\n  screenWidth: number,\n): WorldDimensions {\n  const category = getScreenSizeCategory(screenWidth);\n  const sizeMeters = getArenaSizeForCategory(category);\n  // 4:3 aspect ratio: depth = width × 0.75\n  const depthMeters = sizeMeters * 0.75;\n\n  return {\n    widthMeters: sizeMeters,\n    depthMeters,\n    sizeMeters,\n    screenCategory: category,\n  };\n}\n\n/**\n * Calculate complete arena configuration including pixel and meter dimensions.\n *\n * This is the primary function for setting up arena bounds. It calculates:\n * - Pixel dimensions based on available screen space\n * - Meter dimensions based on screen resolution category\n * - Pixels-per-meter ratio for physics conversion\n *\n * @param screenWidth - Screen width in pixels\n * @param screenHeight - Screen height in pixels\n * @param topOffset - Pixels reserved at top (HUD, headers)\n * @param bottomOffset - Pixels reserved at bottom (controls, footer)\n * @param horizontalMargin - Pixels to leave on sides (as ratio 0-1)\n * @returns Complete arena configuration\n *\n * @public\n */\nexport function calculateArenaConfiguration(\n  screenWidth: number,\n  screenHeight: number,\n  topOffset: number,\n  bottomOffset: number,\n  horizontalMargin: number = 0.1,\n): ArenaConfiguration {\n  // Get world dimensions based on resolution\n  const worldDimensions = calculateArenaWorldDimensions(screenWidth);\n\n  // Calculate available pixel space\n  const availableWidth = screenWidth * (1 - 2 * horizontalMargin);\n  const availableHeight = screenHeight - topOffset - bottomOffset;\n\n  // Use the smaller dimension to ensure square arena fits\n  const arenaSizePixels = Math.min(availableWidth, availableHeight);\n\n  // Calculate arena position (centered horizontally)\n  const arenaX = (screenWidth - arenaSizePixels) / 2;\n  const arenaY = topOffset;\n\n  // Calculate pixels per meter for this configuration\n  const pixelsPerMeter = arenaSizePixels / worldDimensions.sizeMeters;\n\n  // Calculate scale relative to reference (1000px / 10m = 100 px/m)\n  const referencePixelsPerMeter = 100;\n  const scale = pixelsPerMeter / referencePixelsPerMeter;\n\n  return {\n    x: arenaX,\n    y: arenaY,\n    width: arenaSizePixels,\n    height: arenaSizePixels,\n    worldWidthMeters: worldDimensions.widthMeters,\n    worldDepthMeters: worldDimensions.depthMeters,\n    pixelsPerMeter,\n    scale,\n  };\n}\n\n/**\n * Calculate pixels-per-meter ratio from arena dimensions.\n *\n * @param arenaWidthPixels - Arena width in pixels\n * @param arenaWidthMeters - Arena width in meters\n * @returns Pixels per meter ratio\n *\n * @public\n */\nexport function calculatePixelsPerMeter(\n  arenaWidthPixels: number,\n  arenaWidthMeters: number,\n): number {\n  if (arenaWidthMeters <= 0) {\n    throw new Error(`arenaWidthMeters must be positive: ${arenaWidthMeters}`);\n  }\n  return arenaWidthPixels / arenaWidthMeters;\n}\n\n/**\n * Get player height in meters from archetype physical attributes.\n *\n * Converts archetype totalHeight (in centimeters) to meters for physics calculations.\n *\n * **Korean**: 플레이어키 (Player Height)\n *\n * @param archetypeHeightCm - Player height in centimeters from PhysicalAttributes\n * @returns Height in meters\n *\n * @example\n * ```typescript\n * // Musa archetype: 180cm\n * const height = getPlayerHeightMeters(180);\n * // Result: 1.8 meters\n * ```\n *\n * @public\n */\nexport function getPlayerHeightMeters(archetypeHeightCm: number): number {\n  return archetypeHeightCm / 100;\n}\n"],"mappings":";;;;;;;AA8CA,IAAa,cAAc;CAEzB,OAAO;CAEP,QAAQ;CAER,OAAO;CAEP,QAAQ;CAER,OAAO;CACR;;;;;;;AAQD,IAAa,yBAAyB;CAEpC,WAAW;CAEX,YAAY;CAEZ,WAAW;CAEX,YAAY;CAEb;;;;;;;;;;;;;;;;;;;;;AAgED,SAAgB,sBAAsB,aAAyC;AAC7E,KAAI,cAAc,uBAAuB,UAAW,QAAO;AAC3D,KAAI,cAAc,uBAAuB,WAAY,QAAO;AAC5D,KAAI,cAAc,uBAAuB,UAAW,QAAO;AAC3D,KAAI,cAAc,uBAAuB,WAAY,QAAO;AAC5D,QAAO;;;;;;;;;;AAWT,SAAgB,wBAAwB,UAAsC;AAC5E,SAAQ,UAAR;EACE,KAAK,QACH,QAAO,YAAY;EACrB,KAAK,SACH,QAAO,YAAY;EACrB,KAAK,QACH,QAAO,YAAY;EACrB,KAAK,SACH,QAAO,YAAY;EACrB,KAAK,QACH,QAAO,YAAY;EACrB,QACE,QAAO,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCzB,SAAgB,8BACd,aACiB;CACjB,MAAM,WAAW,sBAAsB,YAAY;CACnD,MAAM,aAAa,wBAAwB,SAAS;AAIpD,QAAO;EACL,aAAa;EACb,aAJkB,aAAa;EAK/B;EACA,gBAAgB;EACjB;;;;;;;;;;;;;;;;;;;AAoBH,SAAgB,4BACd,aACA,cACA,WACA,cACA,mBAA2B,IACP;CAEpB,MAAM,kBAAkB,8BAA8B,YAAY;CAGlE,MAAM,iBAAiB,eAAe,IAAI,IAAI;CAC9C,MAAM,kBAAkB,eAAe,YAAY;CAGnD,MAAM,kBAAkB,KAAK,IAAI,gBAAgB,gBAAgB;CAGjE,MAAM,UAAU,cAAc,mBAAmB;CACjD,MAAM,SAAS;CAGf,MAAM,iBAAiB,kBAAkB,gBAAgB;CAIzD,MAAM,QAAQ,iBADkB;AAGhC,QAAO;EACL,GAAG;EACH,GAAG;EACH,OAAO;EACP,QAAQ;EACR,kBAAkB,gBAAgB;EAClC,kBAAkB,gBAAgB;EAClC;EACA;EACD"}

package/lib/utils/assetConfig.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Asset path configuration for Black Trigram library consumers.
+ *
+ * By default, all asset URLs are root-relative (e.g. /assets/audio/*).
+ * Library consumers who host assets at a different path can call
+ * {@link setAssetBasePath} to prefix all asset URLs.
+ *
+ * @example
+ * ```ts
+ * import { setAssetBasePath } from 'blacktrigram';
+ * // Serve assets from a CDN
+ * setAssetBasePath('https://cdn.example.com');
+ * ```
+ *
+ * @module utils
+ * @category Utilities
+ */
+/**
+ * Set the base path for all game assets.
+ * Call this before initializing any game components.
+ *
+ * @param basePath - The base URL/path prefix (e.g. `"https://cdn.example.com"` or `"/my-app"`)
+ */
+export declare function setAssetBasePath(basePath: string): void;
+/**
+ * Get the current asset base path.
+ */
+export declare function getAssetBasePath(): string;
+/**
+ * Resolve an asset path by prepending the configured base path.
+ *
+ * Accepts paths with or without a leading slash — both are normalized
+ * to root-relative before the base path (if any) is prepended.
+ *
+ * @param path - Asset path, e.g. /assets/audio/music/intro_theme.mp3 or assets/audio/music/intro_theme.mp3
+ * @returns The resolved URL with the configured base path prepended
+ */
+export declare function resolveAssetPath(path: string): string;
+//# sourceMappingURL=assetConfig.d.ts.map

package/lib/utils/assetConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assetConfig.d.ts","sourceRoot":"","sources":["../../src/utils/assetConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAGvD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQrD"}

package/lib/utils/assetConfig.js

@@ -0,0 +1,52 @@
+//#region src/utils/assetConfig.ts
+/**
+* Asset path configuration for Black Trigram library consumers.
+*
+* By default, all asset URLs are root-relative (e.g. /assets/audio/*).
+* Library consumers who host assets at a different path can call
+* {@link setAssetBasePath} to prefix all asset URLs.
+*
+* @example
+* ```ts
+* import { setAssetBasePath } from 'blacktrigram';
+* // Serve assets from a CDN
+* setAssetBasePath('https://cdn.example.com');
+* ```
+*
+* @module utils
+* @category Utilities
+*/
+var assetBasePath = "";
+/**
+* Set the base path for all game assets.
+* Call this before initializing any game components.
+*
+* @param basePath - The base URL/path prefix (e.g. `"https://cdn.example.com"` or `"/my-app"`)
+*/
+function setAssetBasePath(basePath) {
+	assetBasePath = basePath.replace(/\/+$/, "");
+}
+/**
+* Get the current asset base path.
+*/
+function getAssetBasePath() {
+	return assetBasePath;
+}
+/**
+* Resolve an asset path by prepending the configured base path.
+*
+* Accepts paths with or without a leading slash — both are normalized
+* to root-relative before the base path (if any) is prepended.
+*
+* @param path - Asset path, e.g. /assets/audio/music/intro_theme.mp3 or assets/audio/music/intro_theme.mp3
+* @returns The resolved URL with the configured base path prepended
+*/
+function resolveAssetPath(path) {
+	const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+	if (!assetBasePath) return normalizedPath;
+	return `${assetBasePath}${normalizedPath}`;
+}
+//#endregion
+export { getAssetBasePath, resolveAssetPath, setAssetBasePath };
+
+//# sourceMappingURL=assetConfig.js.map

package/lib/utils/assetConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assetConfig.js","names":[],"sources":["../../src/utils/assetConfig.ts"],"sourcesContent":["/**\n * Asset path configuration for Black Trigram library consumers.\n *\n * By default, all asset URLs are root-relative (e.g. /assets/audio/*).\n * Library consumers who host assets at a different path can call\n * {@link setAssetBasePath} to prefix all asset URLs.\n *\n * @example\n * ```ts\n * import { setAssetBasePath } from 'blacktrigram';\n * // Serve assets from a CDN\n * setAssetBasePath('https://cdn.example.com');\n * ```\n *\n * @module utils\n * @category Utilities\n */\n\nlet assetBasePath = \"\";\n\n/**\n * Set the base path for all game assets.\n * Call this before initializing any game components.\n *\n * @param basePath - The base URL/path prefix (e.g. `\"https://cdn.example.com\"` or `\"/my-app\"`)\n */\nexport function setAssetBasePath(basePath: string): void {\n  // Remove trailing slash for consistency\n  assetBasePath = basePath.replace(/\\/+$/, \"\");\n}\n\n/**\n * Get the current asset base path.\n */\nexport function getAssetBasePath(): string {\n  return assetBasePath;\n}\n\n/**\n * Resolve an asset path by prepending the configured base path.\n *\n * Accepts paths with or without a leading slash — both are normalized\n * to root-relative before the base path (if any) is prepended.\n *\n * @param path - Asset path, e.g. /assets/audio/music/intro_theme.mp3 or assets/audio/music/intro_theme.mp3\n * @returns The resolved URL with the configured base path prepended\n */\nexport function resolveAssetPath(path: string): string {\n  // Ensure path starts with / for correct concatenation\n  const normalizedPath = path.startsWith(\"/\") ? path : `/${path}`;\n\n  if (!assetBasePath) {\n    return normalizedPath;\n  }\n  return `${assetBasePath}${normalizedPath}`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAkBA,IAAI,gBAAgB;;;;;;;AAQpB,SAAgB,iBAAiB,UAAwB;AAEvD,iBAAgB,SAAS,QAAQ,QAAQ,GAAG;;;;;AAM9C,SAAgB,mBAA2B;AACzC,QAAO;;;;;;;;;;;AAYT,SAAgB,iBAAiB,MAAsB;CAErD,MAAM,iBAAiB,KAAK,WAAW,IAAI,GAAG,OAAO,IAAI;AAEzD,KAAI,CAAC,cACH,QAAO;AAET,QAAO,GAAG,gBAAgB"}

package/lib/utils/cameraShake.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Camera shake utilities for explosive impact feedback
+ *
+ * Provides camera shake effects for Jin (Thunder) trigram techniques
+ * with configurable intensity and duration.
+ *
+ * **Korean Martial Arts Context:**
+ * - 진괘 (Jin): Thunder trigram impact visualization
+ * - 카메라 진동 (Camera Shake): Visual impact feedback
+ * - 충격 효과 (Impact Effect): Explosive force sensation
+ *
+ * @module utils/cameraShake
+ * @korean 카메라진동
+ */
+import * as THREE from "three";
+/**
+ * Camera shake configuration
+ */
+export interface CameraShakeConfig {
+    /** Shake intensity (0-1) */
+    readonly intensity: number;
+    /** Duration in milliseconds */
+    readonly duration: number;
+    /** Frequency of shake oscillation (Hz) */
+    readonly frequency?: number;
+    /** Decay rate (0-1, higher = faster decay) */
+    readonly decay?: number;
+}
+/**
+ * Camera shake manager for Three.js cameras
+ */
+export declare class CameraShakeManager {
+    private shakeState;
+    private camera;
+    private tempVector;
+    /**
+     * Attach the shake manager to a camera
+     */
+    attachCamera(camera: THREE.Camera): void;
+    /**
+     * Detach from current camera
+     */
+    detachCamera(): void;
+    /**
+     * Trigger a camera shake effect
+     */
+    shake(config: CameraShakeConfig): void;
+    /**
+     * Update camera shake (call in animation loop)
+     */
+    update(): void;
+    /**
+     * Check if shake is currently active
+     */
+    isShaking(): boolean;
+    /**
+     * Stop current shake immediately
+     */
+    stop(): void;
+}
+/**
+ * Predefined shake profiles for Jin techniques
+ */
+export declare const JIN_SHAKE_PROFILES: {
+    /** Light shake for quick strikes */
+    readonly light: {
+        readonly intensity: 0.3;
+        readonly duration: 200;
+        readonly frequency: 20;
+        readonly decay: 0.95;
+    };
+    /** Medium shake for standard impacts */
+    readonly medium: {
+        readonly intensity: 0.5;
+        readonly duration: 300;
+        readonly frequency: 15;
+        readonly decay: 0.92;
+    };
+    /** Heavy shake for powerful techniques */
+    readonly heavy: {
+        readonly intensity: 0.7;
+        readonly duration: 400;
+        readonly frequency: 12;
+        readonly decay: 0.9;
+    };
+    /** Explosive shake for maximum impact */
+    readonly explosive: {
+        readonly intensity: 1;
+        readonly duration: 500;
+        readonly frequency: 10;
+        readonly decay: 0.88;
+    };
+};
+/**
+ * React hook for camera shake in @react-three/fiber
+ */
+export declare const useCameraShake: () => {
+    /**
+     * Trigger camera shake with configuration
+     */
+    shake: (config: CameraShakeConfig) => void;
+    /**
+     * Trigger camera shake using predefined profile
+     */
+    shakeProfile: (profile: keyof typeof JIN_SHAKE_PROFILES) => void;
+    /**
+     * Get the shake manager instance
+     */
+    getManager: () => CameraShakeManager;
+};
+/**
+ * Calculate shake intensity from Jin technique properties
+ */
+export declare const calculateJinShakeIntensity: (techniqueIntensity: number, explosivePower: number) => number;
+//# sourceMappingURL=cameraShake.d.ts.map

package/lib/utils/cameraShake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cameraShake.d.ts","sourceRoot":"","sources":["../../src/utils/cameraShake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+BAA+B;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAgBD;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,UAAU,CAAiC;IACnD,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,UAAU,CAA8B;IAEhD;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI;IAIxC;;OAEG;IACH,YAAY,IAAI,IAAI;IASpB;;OAEG;IACH,KAAK,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAyBtC;;OAEG;IACH,MAAM,IAAI,IAAI;IAuCd;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,IAAI,IAAI,IAAI;CAMb;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB;IAC7B,oCAAoC;;;;;;;IAOpC,wCAAwC;;;;;;;IAOxC,0CAA0C;;;;;;;IAO1C,yCAAyC;;;;;;;CAOjC,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,cAAc;IAmBvB;;OAEG;oBAfM,iBAAiB;IAkB1B;;OAEG;4BAfO,MAAM,OAAO,kBAAkB;IAkBzC;;OAEG;;CAGN,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,0BAA0B,GACrC,oBAAoB,MAAM,EAC1B,gBAAgB,MAAM,KACrB,MAEF,CAAC"}