blacktrigram 0.7.2

package/lib/components/shared/three/optimization/AdaptiveQuality.js

@@ -0,0 +1,197 @@
+import { useEffect, useRef, useState } from "react";
+import { useFrame } from "@react-three/fiber";
+//#region src/components/shared/three/optimization/AdaptiveQuality.ts
+/**
+* AdaptiveQuality - Dynamic quality adjustment system for mobile performance
+*
+* Monitors real-time FPS and automatically adjusts rendering quality to maintain
+* 55fps target on mobile devices. Provides quality presets and smooth transitions.
+*
+* Features:
+* - Real-time FPS monitoring
+* - Automatic quality adjustment (high/medium/low)
+* - Debounced quality changes to prevent thrashing
+* - Mobile-optimized thresholds
+* - React hook integration
+*
+* @module components/shared/three/optimization/AdaptiveQuality
+* @category Performance Optimization
+* @korean 적응형품질시스템
+*/
+/**
+* Default thresholds for mobile optimization
+*/
+var DEFAULT_MOBILE_THRESHOLDS = {
+	downgradeThreshold: 45,
+	upgradeThreshold: 58,
+	debounceTime: 2e3,
+	sampleSize: 60
+};
+/**
+* Quality presets optimized for mobile performance
+*/
+var QUALITY_PRESETS = {
+	high: {
+		level: "high",
+		shadowMapSize: 1536,
+		maxParticles: 60,
+		postProcessing: false,
+		effectsQuality: 1
+	},
+	medium: {
+		level: "medium",
+		shadowMapSize: 1024,
+		maxParticles: 40,
+		postProcessing: false,
+		effectsQuality: .75
+	},
+	low: {
+		level: "low",
+		shadowMapSize: 512,
+		maxParticles: 20,
+		postProcessing: false,
+		effectsQuality: .5
+	}
+};
+/**
+* Adaptive quality system class
+*/
+var AdaptiveQualitySystem = class {
+	currentQuality = "high";
+	fpsHistory = [];
+	lastQualityChange = 0;
+	thresholds;
+	constructor(thresholds = {}) {
+		this.thresholds = {
+			...DEFAULT_MOBILE_THRESHOLDS,
+			...thresholds
+		};
+	}
+	/**
+	* Update system with current FPS
+	* Returns new quality level if changed, null otherwise
+	*/
+	update(currentFps) {
+		const now = performance.now();
+		this.fpsHistory.push(currentFps);
+		if (this.fpsHistory.length > this.thresholds.sampleSize) this.fpsHistory.shift();
+		if (this.fpsHistory.length < this.thresholds.sampleSize) return null;
+		if (now - this.lastQualityChange < this.thresholds.debounceTime) return null;
+		const avgFps = this.fpsHistory.reduce((a, b) => a + b, 0) / this.fpsHistory.length;
+		let newQuality = null;
+		if (avgFps < this.thresholds.downgradeThreshold && this.currentQuality !== "low") {
+			if (this.currentQuality === "high") newQuality = "medium";
+			else if (this.currentQuality === "medium") newQuality = "low";
+		} else if (avgFps > this.thresholds.upgradeThreshold && this.currentQuality !== "high") {
+			if (this.currentQuality === "low") newQuality = "medium";
+			else if (this.currentQuality === "medium") newQuality = "high";
+		}
+		if (newQuality !== null) {
+			this.currentQuality = newQuality;
+			this.lastQualityChange = now;
+			this.fpsHistory = [];
+			return newQuality;
+		}
+		return null;
+	}
+	/**
+	* Get current quality level
+	*/
+	getCurrentQuality() {
+		return this.currentQuality;
+	}
+	/**
+	* Get settings for current quality level
+	*/
+	getCurrentSettings() {
+		return QUALITY_PRESETS[this.currentQuality];
+	}
+	/**
+	* Manually set quality level
+	*/
+	setQuality(quality) {
+		this.currentQuality = quality;
+		this.lastQualityChange = performance.now();
+		this.fpsHistory = [];
+	}
+	/**
+	* Reset the system
+	*/
+	reset() {
+		this.fpsHistory = [];
+		this.lastQualityChange = 0;
+	}
+};
+/**
+* React hook for adaptive quality management
+*
+* Automatically monitors FPS and adjusts quality settings.
+* Returns current quality level and settings.
+*
+* @param enabled - Whether adaptive quality is enabled
+* @param isMobile - Whether device is mobile (stricter thresholds)
+* @param onQualityChange - Callback when quality level changes
+* @returns Current quality settings
+*
+* @example
+* ```tsx
+* function CombatScene({ isMobile }) {
+*   const quality = useAdaptiveQuality(true, isMobile, (level) => {
+*     console.log(`Quality changed to ${level}`);
+*   });
+*
+*   return (
+*     <Canvas shadowMap={{ size: quality.shadowMapSize }}>
+*       <ParticleSystem maxParticles={quality.maxParticles} />
+*     </Canvas>
+*   );
+* }
+* ```
+*/
+function useAdaptiveQuality(enabled = true, isMobile = false, onQualityChange) {
+	const initialQuality = isMobile ? "medium" : "high";
+	const [currentQuality, setCurrentQuality] = useState(initialQuality);
+	const systemRef = useRef(null);
+	useEffect(() => {
+		systemRef.current = new AdaptiveQualitySystem(isMobile ? {
+			downgradeThreshold: 45,
+			upgradeThreshold: 58,
+			debounceTime: 2e3,
+			sampleSize: 60
+		} : {
+			downgradeThreshold: 50,
+			upgradeThreshold: 59,
+			debounceTime: 3e3,
+			sampleSize: 90
+		});
+		systemRef.current.setQuality(initialQuality);
+	}, [isMobile, initialQuality]);
+	const lastTimeRef = useRef(0);
+	const frameCountRef = useRef(0);
+	const initializedRef = useRef(false);
+	useFrame(() => {
+		if (!enabled || !systemRef.current) return;
+		const now = performance.now();
+		if (!initializedRef.current) {
+			lastTimeRef.current = now;
+			initializedRef.current = true;
+			return;
+		}
+		const delta = now - lastTimeRef.current;
+		if (delta > 0) {
+			const fps = 1e3 / delta;
+			frameCountRef.current++;
+			const newQuality = systemRef.current.update(fps);
+			if (newQuality !== null) {
+				setCurrentQuality(newQuality);
+				onQualityChange?.(newQuality);
+			}
+		}
+		lastTimeRef.current = now;
+	});
+	return QUALITY_PRESETS[currentQuality];
+}
+//#endregion
+export { AdaptiveQualitySystem, QUALITY_PRESETS, useAdaptiveQuality };
+
+//# sourceMappingURL=AdaptiveQuality.js.map

package/lib/components/shared/three/optimization/AdaptiveQuality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdaptiveQuality.js","names":[],"sources":["../../../../../src/components/shared/three/optimization/AdaptiveQuality.ts"],"sourcesContent":["/**\n * AdaptiveQuality - Dynamic quality adjustment system for mobile performance\n *\n * Monitors real-time FPS and automatically adjusts rendering quality to maintain\n * 55fps target on mobile devices. Provides quality presets and smooth transitions.\n *\n * Features:\n * - Real-time FPS monitoring\n * - Automatic quality adjustment (high/medium/low)\n * - Debounced quality changes to prevent thrashing\n * - Mobile-optimized thresholds\n * - React hook integration\n *\n * @module components/shared/three/optimization/AdaptiveQuality\n * @category Performance Optimization\n * @korean 적응형품질시스템\n */\n\nimport { useFrame } from \"@react-three/fiber\";\nimport { useEffect, useRef, useState } from \"react\";\n\n/**\n * Quality levels for adaptive rendering\n */\nexport type QualityLevel = \"high\" | \"medium\" | \"low\";\n\n/**\n * Quality settings for each level\n */\nexport interface QualitySettings {\n  readonly level: QualityLevel;\n  readonly shadowMapSize: number;\n  readonly maxParticles: number;\n  readonly postProcessing: boolean;\n  readonly effectsQuality: number; // 0.0-1.0 multiplier\n}\n\n/**\n * FPS thresholds for quality adjustment\n */\nexport interface AdaptiveQualityThresholds {\n  /** FPS threshold to downgrade quality */\n  readonly downgradeThreshold: number;\n  /** FPS threshold to upgrade quality */\n  readonly upgradeThreshold: number;\n  /** Minimum time between quality changes (ms) */\n  readonly debounceTime: number;\n  /** Number of frames to average for stability */\n  readonly sampleSize: number;\n}\n\n/**\n * Default thresholds for mobile optimization\n */\nconst DEFAULT_MOBILE_THRESHOLDS: AdaptiveQualityThresholds = {\n  downgradeThreshold: 45, // Downgrade if fps drops below 45\n  upgradeThreshold: 58, // Upgrade if fps consistently above 58\n  debounceTime: 2000, // 2 seconds between changes\n  sampleSize: 60, // Average over 60 frames (~1 second at 60fps)\n};\n\n/**\n * Quality presets optimized for mobile performance\n */\nexport const QUALITY_PRESETS: Record<QualityLevel, QualitySettings> = {\n  high: {\n    level: \"high\",\n    shadowMapSize: 1536,\n    maxParticles: 60,\n    postProcessing: false, // Keep disabled on mobile\n    effectsQuality: 1.0,\n  },\n  medium: {\n    level: \"medium\",\n    shadowMapSize: 1024,\n    maxParticles: 40,\n    postProcessing: false,\n    effectsQuality: 0.75,\n  },\n  low: {\n    level: \"low\",\n    shadowMapSize: 512,\n    maxParticles: 20,\n    postProcessing: false,\n    effectsQuality: 0.5,\n  },\n} as const;\n\n/**\n * Adaptive quality system class\n */\nexport class AdaptiveQualitySystem {\n  private currentQuality: QualityLevel = \"high\";\n  private fpsHistory: number[] = [];\n  private lastQualityChange = 0;\n  private readonly thresholds: AdaptiveQualityThresholds;\n\n  constructor(thresholds: Partial<AdaptiveQualityThresholds> = {}) {\n    this.thresholds = { ...DEFAULT_MOBILE_THRESHOLDS, ...thresholds };\n  }\n\n  /**\n   * Update system with current FPS\n   * Returns new quality level if changed, null otherwise\n   */\n  update(currentFps: number): QualityLevel | null {\n    const now = performance.now();\n\n    // Add to history\n    this.fpsHistory.push(currentFps);\n    if (this.fpsHistory.length > this.thresholds.sampleSize) {\n      this.fpsHistory.shift();\n    }\n\n    // Need enough samples before adjusting\n    if (this.fpsHistory.length < this.thresholds.sampleSize) {\n      return null;\n    }\n\n    // Check debounce time\n    if (now - this.lastQualityChange < this.thresholds.debounceTime) {\n      return null;\n    }\n\n    // Calculate average FPS\n    const avgFps =\n      this.fpsHistory.reduce((a, b) => a + b, 0) / this.fpsHistory.length;\n\n    // Determine if quality should change\n    let newQuality: QualityLevel | null = null;\n\n    if (\n      avgFps < this.thresholds.downgradeThreshold &&\n      this.currentQuality !== \"low\"\n    ) {\n      // Downgrade quality\n      if (this.currentQuality === \"high\") {\n        newQuality = \"medium\";\n      } else if (this.currentQuality === \"medium\") {\n        newQuality = \"low\";\n      }\n    } else if (\n      avgFps > this.thresholds.upgradeThreshold &&\n      this.currentQuality !== \"high\"\n    ) {\n      // Upgrade quality\n      if (this.currentQuality === \"low\") {\n        newQuality = \"medium\";\n      } else if (this.currentQuality === \"medium\") {\n        newQuality = \"high\";\n      }\n    }\n\n    if (newQuality !== null) {\n      this.currentQuality = newQuality;\n      this.lastQualityChange = now;\n      this.fpsHistory = []; // Reset history after change\n\n      if (import.meta.env.DEV) {\n        console.log(\n          `[AdaptiveQuality] Quality changed to ${newQuality} (avg fps: ${avgFps.toFixed(1)})`,\n        );\n      }\n\n      return newQuality;\n    }\n\n    return null;\n  }\n\n  /**\n   * Get current quality level\n   */\n  getCurrentQuality(): QualityLevel {\n    return this.currentQuality;\n  }\n\n  /**\n   * Get settings for current quality level\n   */\n  getCurrentSettings(): QualitySettings {\n    return QUALITY_PRESETS[this.currentQuality];\n  }\n\n  /**\n   * Manually set quality level\n   */\n  setQuality(quality: QualityLevel): void {\n    this.currentQuality = quality;\n    this.lastQualityChange = performance.now();\n    this.fpsHistory = [];\n  }\n\n  /**\n   * Reset the system\n   */\n  reset(): void {\n    this.fpsHistory = [];\n    this.lastQualityChange = 0;\n  }\n}\n\n/**\n * React hook for adaptive quality management\n *\n * Automatically monitors FPS and adjusts quality settings.\n * Returns current quality level and settings.\n *\n * @param enabled - Whether adaptive quality is enabled\n * @param isMobile - Whether device is mobile (stricter thresholds)\n * @param onQualityChange - Callback when quality level changes\n * @returns Current quality settings\n *\n * @example\n * ```tsx\n * function CombatScene({ isMobile }) {\n *   const quality = useAdaptiveQuality(true, isMobile, (level) => {\n *     console.log(`Quality changed to ${level}`);\n *   });\n *\n *   return (\n *     <Canvas shadowMap={{ size: quality.shadowMapSize }}>\n *       <ParticleSystem maxParticles={quality.maxParticles} />\n *     </Canvas>\n *   );\n * }\n * ```\n */\nexport function useAdaptiveQuality(\n  enabled: boolean = true,\n  isMobile: boolean = false,\n  onQualityChange?: (quality: QualityLevel) => void,\n): QualitySettings {\n  // Initialize with appropriate starting quality\n  const initialQuality: QualityLevel = isMobile ? \"medium\" : \"high\";\n\n  const [currentQuality, setCurrentQuality] =\n    useState<QualityLevel>(initialQuality);\n\n  // Create system instance\n  const systemRef = useRef<AdaptiveQualitySystem | null>(null);\n\n  useEffect(() => {\n    // Create system with mobile-optimized thresholds\n    const thresholds = isMobile\n      ? {\n          downgradeThreshold: 45, // More aggressive on mobile\n          upgradeThreshold: 58,\n          debounceTime: 2000,\n          sampleSize: 60,\n        }\n      : {\n          downgradeThreshold: 50,\n          upgradeThreshold: 59,\n          debounceTime: 3000,\n          sampleSize: 90,\n        };\n\n    systemRef.current = new AdaptiveQualitySystem(thresholds);\n    systemRef.current.setQuality(initialQuality);\n  }, [isMobile, initialQuality]);\n\n  // FPS tracking - Initialize with 0, will be set on first frame\n  const lastTimeRef = useRef(0);\n  const frameCountRef = useRef(0);\n  const initializedRef = useRef(false);\n\n  useFrame(() => {\n    if (!enabled || !systemRef.current) return;\n\n    // Calculate FPS\n    const now = performance.now();\n\n    // Initialize on first frame\n    if (!initializedRef.current) {\n      lastTimeRef.current = now;\n      initializedRef.current = true;\n      return;\n    }\n\n    const delta = now - lastTimeRef.current;\n\n    if (delta > 0) {\n      const fps = 1000 / delta;\n      frameCountRef.current++;\n\n      // Update every frame for smooth monitoring\n      const newQuality = systemRef.current.update(fps);\n\n      if (newQuality !== null) {\n        setCurrentQuality(newQuality);\n        onQualityChange?.(newQuality);\n      }\n    }\n\n    lastTimeRef.current = now;\n  });\n\n  return QUALITY_PRESETS[currentQuality];\n}\n"],"mappings":"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"}

package/lib/components/shared/three/optimization/InstancedGeometry.d.ts

@@ -0,0 +1,189 @@
+/**
+ * InstancedGeometry - Reusable instancing utilities for optimized rendering
+ *
+ * Provides helpers and components for GPU instancing to reduce draw calls.
+ * Especially useful for particles, repeated geometry, and effects.
+ *
+ * Features:
+ * - Instanced particle systems
+ * - Batch rendering utilities
+ * - Position/rotation/scale management
+ * - Color variations per instance
+ * - Korean-themed effects optimization
+ *
+ * Performance Impact:
+ * - Reduces draw calls from N to 1 per geometry type
+ * - 50%+ performance improvement for particle-heavy scenes
+ * - Target: <100 draw calls per frame
+ *
+ * @module components/shared/three/optimization/InstancedGeometry
+ * @category Performance Optimization
+ * @korean 인스턴스기하학
+ */
+import React from "react";
+import * as THREE from "three";
+/**
+ * Instance data for a single object
+ */
+export interface InstanceData {
+    readonly position: THREE.Vector3 | [number, number, number];
+    readonly rotation?: THREE.Euler | [number, number, number];
+    readonly scale?: number | [number, number, number];
+    readonly color?: THREE.ColorRepresentation;
+}
+/**
+ * Props for InstancableSpheres component
+ */
+export interface InstancableSpheresProps {
+    /** Array of instance data */
+    readonly instances: readonly InstanceData[];
+    /** Sphere radius */
+    readonly radius?: number;
+    /** Sphere segments (lower = better performance) */
+    readonly segments?: number;
+    /** Base material color */
+    readonly color?: THREE.ColorRepresentation;
+    /** Material properties */
+    readonly materialProps?: Partial<THREE.MeshBasicMaterialParameters>;
+}
+/**
+ * Instanced spheres component
+ *
+ * Renders multiple spheres with a single draw call.
+ * Ideal for particles, projectiles, effects.
+ *
+ * **Important**: The instances array should be stable (use useMemo).
+ * Array indices are used as React keys, so adding/removing/reordering
+ * instances during component lifecycle may cause incorrect rendering.
+ * If instances need to be dynamic, consider using unique identifiers as keys.
+ *
+ * @example
+ * ```tsx
+ * const particles = useMemo(() =>
+ *   Array.from({ length: 50 }, (_, i) => ({
+ *     position: [Math.random() * 10 - 5, Math.random() * 10, Math.random() * 10 - 5],
+ *     color: i % 2 === 0 ? 0x00ffff : 0xffd700,
+ *   })),
+ *   []
+ * );
+ *
+ * <InstancableSpheres
+ *   instances={particles}
+ *   radius={0.1}
+ *   segments={8}
+ * />
+ * ```
+ */
+export declare const InstancableSpheres: React.FC<InstancableSpheresProps>;
+/**
+ * Props for InstancableBoxes component
+ */
+export interface InstancableBoxesProps {
+    /** Array of instance data */
+    readonly instances: readonly InstanceData[];
+    /** Box dimensions [width, height, depth] */
+    readonly size?: [number, number, number];
+    /** Base material color */
+    readonly color?: THREE.ColorRepresentation;
+    /** Material properties */
+    readonly materialProps?: Partial<THREE.MeshStandardMaterialParameters>;
+}
+/**
+ * Instanced boxes component
+ *
+ * Renders multiple boxes with a single draw call.
+ * Useful for environment objects, obstacles, UI elements.
+ *
+ * **Important**: The instances array should be stable (use useMemo).
+ * Array indices are used as React keys, so adding/removing/reordering
+ * instances during component lifecycle may cause incorrect rendering.
+ * If instances need to be dynamic, consider using unique identifiers as keys.
+ *
+ * @example
+ * ```tsx
+ * <InstancableBoxes
+ *   instances={[
+ *     { position: [0, 0, 0], scale: 1 },
+ *     { position: [2, 0, 0], scale: 1.5 },
+ *   ]}
+ *   size={[1, 1, 1]}
+ *   color={0x404040}
+ * />
+ * ```
+ */
+export declare const InstancableBoxes: React.FC<InstancableBoxesProps>;
+/**
+ * Props for InstancableParticles component
+ */
+export interface InstancableParticlesProps {
+    /** Particle positions */
+    readonly positions: readonly (THREE.Vector3 | [number, number, number])[];
+    /** Particle colors (optional) */
+    readonly colors?: readonly THREE.ColorRepresentation[];
+    /** Particle size */
+    readonly size?: number;
+    /** Quality level affects particle complexity */
+    readonly quality?: "high" | "medium" | "low";
+    /** Base particle color */
+    readonly baseColor?: THREE.ColorRepresentation;
+}
+/**
+ * Optimized instanced particles
+ *
+ * High-performance particle system using instancing.
+ * Quality parameter adjusts geometry complexity.
+ *
+ * **Important**: The positions array should be stable (use useMemo).
+ * Array indices are used as React keys, so adding/removing/reordering
+ * particles during component lifecycle may cause incorrect rendering.
+ * If particles need to be dynamic, consider using unique identifiers as keys.
+ *
+ * @example
+ * ```tsx
+ * const positions = useMemo(() =>
+ *   Array.from({ length: 100 }, () => [
+ *     Math.random() * 10 - 5,
+ *     Math.random() * 5,
+ *     Math.random() * 10 - 5,
+ *   ]),
+ *   []
+ * );
+ *
+ * <InstancableParticles
+ *   positions={positions}
+ *   size={0.1}
+ *   quality="medium"
+ *   baseColor={0x00ffff}
+ * />
+ * ```
+ */
+export declare const InstancableParticles: React.FC<InstancableParticlesProps>;
+/**
+ * Calculate optimal instance limit based on performance tier
+ *
+ * @param baseLimit - Ideal instance count
+ * @param isMobile - Whether device is mobile
+ * @returns Adjusted instance limit
+ */
+export declare function getOptimalInstanceLimit(baseLimit: number, isMobile: boolean): number;
+/**
+ * Batch instance data into chunks for efficient rendering
+ *
+ * @param instances - Array of instance data
+ * @param batchSize - Maximum instances per batch
+ * @returns Array of batched instances
+ */
+export declare function batchInstances<T>(instances: readonly T[], batchSize: number): T[][];
+/**
+ * Create instance data from positions array
+ *
+ * @param positions - Array of positions
+ * @param options - Optional instance properties
+ * @returns Array of instance data
+ */
+export declare function createInstancesFromPositions(positions: readonly (THREE.Vector3 | [number, number, number])[], options?: {
+    color?: THREE.ColorRepresentation;
+    scale?: number | [number, number, number];
+    rotation?: THREE.Euler | [number, number, number];
+}): InstanceData[];
+//# sourceMappingURL=InstancedGeometry.d.ts.map

package/lib/components/shared/three/optimization/InstancedGeometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InstancedGeometry.d.ts","sourceRoot":"","sources":["../../../../../src/components/shared/three/optimization/InstancedGeometry.tsx"],"names":[],"mappings":"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"}

package/lib/components/shared/three/optimization/InstancedGeometry.js

@@ -0,0 +1,3 @@
+import "react";
+import "react/jsx-runtime";
+import "@react-three/drei";

package/lib/components/shared/three/optimization/LODSystem.d.ts

@@ -0,0 +1,126 @@
+/**
+ * LODSystem - Level of Detail optimization for Three.js objects
+ *
+ * Reduces polygon count and detail based on distance from camera.
+ * Implements 3-tier LOD system (high/medium/low) for optimal performance.
+ *
+ * Features:
+ * - Distance-based detail switching
+ * - Smooth transitions between LOD levels
+ * - Configurable distance thresholds
+ * - Works with any Three.js component
+ * - Korean martial arts character optimization
+ *
+ * Performance Impact:
+ * - Reduces polygon count by 50-75% for distant objects
+ * - Maintains visual quality for near objects
+ * - Target: <100 draw calls per frame
+ *
+ * @module components/shared/three/optimization/LODSystem
+ * @category Performance Optimization
+ * @korean LOD시스템
+ */
+import React from "react";
+/**
+ * LOD distance thresholds (in Three.js units)
+ */
+export interface LODDistances {
+    /** Distance for high detail (closest) */
+    readonly high: number;
+    /** Distance for medium detail */
+    readonly medium: number;
+}
+/**
+ * Default LOD distances optimized for Black Trigram combat
+ * Arena is approximately 16x8 units, camera at [0, 5, 10]
+ */
+export declare const DEFAULT_LOD_DISTANCES: LODDistances;
+/**
+ * Mobile LOD distances (more aggressive)
+ */
+export declare const MOBILE_LOD_DISTANCES: LODDistances;
+/**
+ * Props for LODCharacter component
+ */
+export interface LODCharacterProps {
+    /** High detail component (0-high distance) */
+    readonly highDetail: React.ReactNode;
+    /** Medium detail component (high-medium distance) */
+    readonly mediumDetail: React.ReactNode;
+    /** Low detail component (beyond medium distance) */
+    readonly lowDetail: React.ReactNode;
+    /** Custom LOD distances (optional) */
+    readonly distances?: LODDistances;
+    /** Whether to use mobile-optimized distances */
+    readonly isMobile?: boolean;
+}
+/**
+ * LOD-enabled character component
+ *
+ * Automatically switches between detail levels based on camera distance.
+ * Uses @react-three/drei's Detailed component for smooth transitions.
+ *
+ * @example
+ * ```tsx
+ * <LODCharacter
+ *   highDetail={<Player3DHighDetail />}
+ *   mediumDetail={<Player3DMediumDetail />}
+ *   lowDetail={<Player3DLowDetail />}
+ *   isMobile={isMobile}
+ * />
+ * ```
+ */
+export declare const LODCharacter: React.FC<LODCharacterProps>;
+/**
+ * Props for LODEffect component
+ */
+export interface LODEffectProps {
+    /** Effect to render at different detail levels */
+    readonly children: (detailLevel: "high" | "medium" | "low") => React.ReactNode;
+    /** Custom LOD distances (optional) */
+    readonly distances?: LODDistances;
+    /** Whether to use mobile-optimized distances */
+    readonly isMobile?: boolean;
+}
+/**
+ * LOD-enabled effect component
+ *
+ * Allows render function to adjust effect quality based on distance.
+ * Useful for particle effects, visual effects, etc.
+ *
+ * @example
+ * ```tsx
+ * <LODEffect isMobile={isMobile}>
+ *   {(detail) => (
+ *     <ParticleSystem
+ *       particleCount={detail === 'high' ? 100 : detail === 'medium' ? 50 : 20}
+ *     />
+ *   )}
+ * </LODEffect>
+ * ```
+ */
+export declare const LODEffect: React.FC<LODEffectProps>;
+/**
+ * Calculate appropriate LOD distances based on arena size
+ *
+ * @param arenaWidth - Arena width in units
+ * @param arenaDepth - Arena depth in units
+ * @returns Calculated LOD distances
+ */
+export declare function calculateLODDistances(arenaWidth: number, arenaDepth: number): LODDistances;
+/**
+ * Get recommended particle count based on LOD level
+ *
+ * @param baseCount - Base particle count at high detail
+ * @param detailLevel - Current LOD level
+ * @returns Adjusted particle count
+ */
+export declare function getLODParticleCount(baseCount: number, detailLevel: "high" | "medium" | "low"): number;
+/**
+ * Get recommended shadow quality based on LOD level
+ *
+ * @param detailLevel - Current LOD level
+ * @returns Shadow map size
+ */
+export declare function getLODShadowQuality(detailLevel: "high" | "medium" | "low"): number;
+//# sourceMappingURL=LODSystem.d.ts.map

package/lib/components/shared/three/optimization/LODSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LODSystem.d.ts","sourceRoot":"","sources":["../../../../../src/components/shared/three/optimization/LODSystem.tsx"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAEzB;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,YAInC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,YAIlC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC;IACrC,qDAAqD;IACrD,QAAQ,CAAC,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC;IACvC,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC;IACpC,sCAAsC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,YAAY,CAAC;IAClC,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CAyBpD,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,CACjB,WAAW,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,KACnC,KAAK,CAAC,SAAS,CAAC;IACrB,sCAAsC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,YAAY,CAAC;IAClC,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC,cAAc,CAiB9C,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,YAAY,CAad;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,GACrC,MAAM,CAWR;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,GACrC,MAAM,CAWR"}

package/lib/components/shared/three/optimization/LODSystem.js

@@ -0,0 +1,3 @@
+import "react";
+import "react/jsx-runtime";
+import "@react-three/drei";

package/lib/components/shared/three/optimization/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Three.js Optimization Module
+ *
+ * Performance optimization utilities for mobile and desktop rendering.
+ * Includes LOD system, instanced geometry, and adaptive quality management.
+ *
+ * @module components/shared/three/optimization
+ * @category Performance Optimization
+ * @korean 최적화모듈
+ */
+export { AdaptiveQualitySystem, useAdaptiveQuality, QUALITY_PRESETS, type QualityLevel, type QualitySettings, type AdaptiveQualityThresholds, } from "./AdaptiveQuality";
+export { LODCharacter, LODEffect, calculateLODDistances, getLODParticleCount, getLODShadowQuality, DEFAULT_LOD_DISTANCES, MOBILE_LOD_DISTANCES, type LODDistances, type LODCharacterProps, type LODEffectProps, } from "./LODSystem";
+export { InstancableSpheres, InstancableBoxes, InstancableParticles, getOptimalInstanceLimit, batchInstances, createInstancesFromPositions, type InstanceData, type InstancableSpheresProps, type InstancableBoxesProps, type InstancableParticlesProps, } from "./InstancedGeometry";
+//# sourceMappingURL=index.d.ts.map

package/lib/components/shared/three/optimization/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/components/shared/three/optimization/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EACf,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,yBAAyB,GAC/B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,YAAY,EACZ,SAAS,EACT,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,cAAc,EACd,4BAA4B,EAC5B,KAAK,YAAY,EACjB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,GAC/B,MAAM,qBAAqB,CAAC"}

package/lib/components/shared/three/optimization/index.js

@@ -0,0 +1,3 @@
+import "./AdaptiveQuality.js";
+import "./LODSystem.js";
+import "./InstancedGeometry.js";

package/lib/components/shared/three/scene/AtmosphericParticles3D.d.ts

@@ -0,0 +1,31 @@
+/**
+ * AtmosphericParticles3D - Three.js 3D atmospheric particle effects
+ *
+ * Renders rain/mist particles for environmental depth in the combat arena
+ * Creates an immersive cyberpunk urban night atmosphere
+ */
+import React from "react";
+/**
+ * Props for the AtmosphericParticles3D component.
+ */
+export interface AtmosphericParticles3DProps {
+    /** Number of particles to render. Defaults to 500 */
+    readonly count?: number;
+    /** Scale factor for particle spread (1.0 = desktop, <1.0 = mobile). Defaults to 1.0 */
+    readonly scale?: number;
+    /** Particle fall speed. Defaults to 2 */
+    readonly speed?: number;
+}
+/**
+ * AtmosphericParticles3D Component
+ * Creates rain/mist particle effects for atmospheric depth
+ *
+ * Performance optimized with:
+ * - BufferGeometry for efficient rendering
+ * - Additive blending for transparent particles
+ * - Configurable particle count for mobile optimization
+ * - Deterministic position generation (no Math.random in render)
+ */
+export declare const AtmosphericParticles3D: React.FC<AtmosphericParticles3DProps>;
+export default AtmosphericParticles3D;
+//# sourceMappingURL=AtmosphericParticles3D.d.ts.map

package/lib/components/shared/three/scene/AtmosphericParticles3D.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AtmosphericParticles3D.d.ts","sourceRoot":"","sources":["../../../../../src/components/shared/three/scene/AtmosphericParticles3D.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAsC,MAAM,OAAO,CAAC;AAG3D;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,qDAAqD;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,uFAAuF;IACvF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAgCD;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAE,KAAK,CAAC,EAAE,CAC3C,2BAA2B,CA4D5B,CAAC;AAEF,eAAe,sBAAsB,CAAC"}