@almadar/ui 2.13.3 → 2.15.0

package/dist/components/organisms/game/three/loaders/AssetLoader.d.ts

@@ -0,0 +1,80 @@
+/**
+ * AssetLoader
+ *
+ * Three.js asset loading manager for 3D models and textures.
+ * Supports GLB/GLTF (primary), OBJ (fallback), and texture loading.
+ * Implements caching for performance.
+ *
+ * @packageDocumentation
+ */
+import * as THREE from 'three';
+export interface LoadedModel {
+    scene: THREE.Group;
+    animations: THREE.AnimationClip[];
+}
+export declare class AssetLoader {
+    private objLoader;
+    private textureLoader;
+    private modelCache;
+    private textureCache;
+    private loadingPromises;
+    constructor();
+    /**
+     * Load a GLB/GLTF model
+     * @param url - URL to the .glb or .gltf file
+     * @returns Promise with loaded model scene and animations
+     */
+    loadModel(url: string): Promise<LoadedModel>;
+    /**
+     * Load an OBJ model (fallback for non-GLB assets)
+     * @param url - URL to the .obj file
+     * @returns Promise with loaded object group
+     */
+    loadOBJ(url: string): Promise<THREE.Group>;
+    /**
+     * Load a texture
+     * @param url - URL to the texture image
+     * @returns Promise with loaded texture
+     */
+    loadTexture(url: string): Promise<THREE.Texture>;
+    /**
+     * Preload multiple assets
+     * @param urls - Array of asset URLs to preload
+     * @returns Promise that resolves when all assets are loaded
+     */
+    preload(urls: string[]): Promise<void>;
+    /**
+     * Check if a model is cached
+     * @param url - Model URL
+     */
+    hasModel(url: string): boolean;
+    /**
+     * Check if a texture is cached
+     * @param url - Texture URL
+     */
+    hasTexture(url: string): boolean;
+    /**
+     * Get cached model (throws if not cached)
+     * @param url - Model URL
+     */
+    getModel(url: string): LoadedModel;
+    /**
+     * Get cached texture (throws if not cached)
+     * @param url - Texture URL
+     */
+    getTexture(url: string): THREE.Texture;
+    /**
+     * Clear all caches
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        models: number;
+        textures: number;
+        loading: number;
+    };
+}
+export declare const assetLoader: AssetLoader;
+export default AssetLoader;

package/dist/components/organisms/game/three/renderers/FeatureRenderer.d.ts

@@ -0,0 +1,44 @@
+/**
+ * FeatureRenderer
+ *
+ * Renders static features (trees, rocks, buildings) in the 3D scene.
+ * Supports different feature types and selection states.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import type { IsometricFeature } from '../../types/isometric';
+export interface FeatureRendererProps {
+    /** Array of features to render */
+    features: IsometricFeature[];
+    /** Grid cell size */
+    cellSize?: number;
+    /** Grid offset X */
+    offsetX?: number;
+    /** Grid offset Z */
+    offsetZ?: number;
+    /** Called when feature is clicked */
+    onFeatureClick?: (feature: IsometricFeature) => void;
+    /** Called when feature is hovered */
+    onFeatureHover?: (feature: IsometricFeature | null) => void;
+    /** Selected feature IDs */
+    selectedFeatureIds?: string[];
+    /** Feature color overrides */
+    featureColors?: Record<string, string>;
+}
+/**
+ * FeatureRenderer Component
+ *
+ * Renders all features in the scene.
+ *
+ * @example
+ * ```tsx
+ * <FeatureRenderer
+ *     features={features}
+ *     cellSize={1}
+ *     onFeatureClick={handleFeatureClick}
+ * />
+ * ```
+ */
+export declare function FeatureRenderer({ features, cellSize, offsetX, offsetZ, onFeatureClick, onFeatureHover, selectedFeatureIds, featureColors, }: FeatureRendererProps): React.JSX.Element;
+export default FeatureRenderer;

package/dist/components/organisms/game/three/renderers/FeatureRenderer3D.d.ts

@@ -0,0 +1,44 @@
+/**
+ * FeatureRenderer3D
+ *
+ * Renders 3D features with GLB model loading from CDN.
+ * Supports assetUrl property on features for external model loading.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import type { IsometricFeature } from '../../types/isometric';
+export interface FeatureRenderer3DProps {
+    /** Array of features to render */
+    features: IsometricFeature[];
+    /** Grid cell size */
+    cellSize?: number;
+    /** Grid offset X */
+    offsetX?: number;
+    /** Grid offset Z */
+    offsetZ?: number;
+    /** Called when feature is clicked */
+    onFeatureClick?: (feature: IsometricFeature) => void;
+    /** Called when feature is hovered */
+    onFeatureHover?: (feature: IsometricFeature | null) => void;
+    /** Selected feature IDs */
+    selectedFeatureIds?: string[];
+}
+/**
+ * FeatureRenderer3D Component
+ *
+ * Renders 3D features with GLB model loading support.
+ *
+ * @example
+ * ```tsx
+ * <FeatureRenderer3D
+ *     features={[
+ *         { id: 'gate', x: 0, y: 0, type: 'gate', assetUrl: 'https://.../gate.glb' }
+ *     ]}
+ *     cellSize={1}
+ * />
+ * ```
+ */
+export declare function FeatureRenderer3D({ features, cellSize, offsetX, offsetZ, onFeatureClick, onFeatureHover, selectedFeatureIds, }: FeatureRenderer3DProps): React.JSX.Element;
+export default FeatureRenderer3D;
+export declare function preloadFeatures(urls: string[]): void;

package/dist/components/organisms/game/three/renderers/TileRenderer.d.ts

@@ -0,0 +1,57 @@
+/**
+ * TileRenderer
+ *
+ * Renders isometric tiles using Three.js InstancedMesh for performance.
+ * Supports texture mapping and custom tile geometries.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import type { IsometricTile } from '../../types/isometric';
+export interface TileRendererProps {
+    /** Array of tiles to render */
+    tiles: IsometricTile[];
+    /** Grid cell size */
+    cellSize?: number;
+    /** Grid offset X */
+    offsetX?: number;
+    /** Grid offset Z */
+    offsetZ?: number;
+    /** Use instancing for performance */
+    useInstancing?: boolean;
+    /** Terrain color mapping */
+    terrainColors?: Record<string, string>;
+    /** Called when tile is clicked */
+    onTileClick?: (tile: IsometricTile) => void;
+    /** Called when tile is hovered */
+    onTileHover?: (tile: IsometricTile | null) => void;
+    /** Selected tile IDs */
+    selectedTileIds?: string[];
+    /** Valid move tile coordinates */
+    validMoves?: Array<{
+        x: number;
+        z: number;
+    }>;
+    /** Attack target coordinates */
+    attackTargets?: Array<{
+        x: number;
+        z: number;
+    }>;
+}
+/**
+ * TileRenderer Component
+ *
+ * Renders grid tiles with instancing for optimal performance.
+ *
+ * @example
+ * ```tsx
+ * <TileRenderer
+ *     tiles={tiles}
+ *     cellSize={1}
+ *     onTileClick={handleTileClick}
+ *     validMoves={[{ x: 1, z: 1 }]}
+ * />
+ * ```
+ */
+export declare function TileRenderer({ tiles, cellSize, offsetX, offsetZ, useInstancing, terrainColors, onTileClick, onTileHover, selectedTileIds, validMoves, attackTargets, }: TileRendererProps): React.JSX.Element;
+export default TileRenderer;

package/dist/components/organisms/game/three/renderers/UnitRenderer.d.ts

@@ -0,0 +1,46 @@
+/**
+ * UnitRenderer
+ *
+ * Renders animated units in the 3D scene.
+ * Supports skeletal animations, health bars, and selection indicators.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import type { IsometricUnit } from '../../types/isometric';
+export type UnitAnimationState = 'idle' | 'walk' | 'attack' | 'hurt' | 'die';
+export interface UnitRendererProps {
+    /** Array of units to render */
+    units: IsometricUnit[];
+    /** Grid cell size */
+    cellSize?: number;
+    /** Grid offset X */
+    offsetX?: number;
+    /** Grid offset Z */
+    offsetZ?: number;
+    /** Currently selected unit ID */
+    selectedUnitId?: string | null;
+    /** Called when unit is clicked */
+    onUnitClick?: (unit: IsometricUnit) => void;
+    /** Called when unit animation state changes */
+    onAnimationStateChange?: (unitId: string, state: UnitAnimationState) => void;
+    /** Animation speed multiplier */
+    animationSpeed?: number;
+}
+/**
+ * UnitRenderer Component
+ *
+ * Renders all units in the scene.
+ *
+ * @example
+ * ```tsx
+ * <UnitRenderer
+ *     units={units}
+ *     cellSize={1}
+ *     selectedUnitId="unit-1"
+ *     onUnitClick={handleUnitClick}
+ * />
+ * ```
+ */
+export declare function UnitRenderer({ units, cellSize, offsetX, offsetZ, selectedUnitId, onUnitClick, onAnimationStateChange, animationSpeed, }: UnitRendererProps): React.JSX.Element;
+export default UnitRenderer;

package/dist/components/organisms/game/three/renderers/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 3D Renderers
+ *
+ * Specialized renderers for tiles, units, and features in the 3D scene.
+ *
+ * @packageDocumentation
+ */
+export { TileRenderer, type TileRendererProps, } from './TileRenderer';
+export { UnitRenderer, type UnitRendererProps, type UnitAnimationState, } from './UnitRenderer';
+export { FeatureRenderer, type FeatureRendererProps, } from './FeatureRenderer';
+export { FeatureRenderer3D, preloadFeatures, type FeatureRenderer3DProps, } from './FeatureRenderer3D';

package/dist/components/organisms/game/three/utils/culling.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Culling Utilities
+ *
+ * Frustum culling and LOD (Level of Detail) management for 3D scene optimization.
+ *
+ * @packageDocumentation
+ */
+import * as THREE from 'three';
+export interface CullingOptions {
+    /** Camera frustum for culling */
+    camera: THREE.Camera;
+    /** Optional padding around frustum */
+    padding?: number;
+}
+export interface LODLevel {
+    /** Distance threshold for this LOD level */
+    distance: number;
+    /** Geometry or mesh for this level */
+    geometry?: THREE.BufferGeometry;
+    /** Scale multiplier for this level */
+    scale?: number;
+    /** Whether to use simplified material */
+    simpleMaterial?: boolean;
+}
+export interface LODConfig {
+    /** LOD levels from closest to farthest */
+    levels: LODLevel[];
+    /** Transition smoothness (0-1) */
+    transitionSmoothness?: number;
+}
+/**
+ * Frustum culling check for a position
+ * @param position - World position to check
+ * @param camera - Camera to check against
+ * @param padding - Optional padding in world units
+ * @returns Whether the position is within the frustum
+ */
+export declare function isInFrustum(position: THREE.Vector3, camera: THREE.Camera, padding?: number): boolean;
+/**
+ * Filter an array of positions to only those within the frustum
+ * @param positions - Array of world positions
+ * @param camera - Camera to check against
+ * @param padding - Optional padding in world units
+ * @returns Array of positions within frustum
+ */
+export declare function filterByFrustum(positions: THREE.Vector3[], camera: THREE.Camera, padding?: number): THREE.Vector3[];
+/**
+ * Get indices of visible items from an array
+ * @param positions - Array of world positions
+ * @param camera - Camera to check against
+ * @param padding - Optional padding in world units
+ * @returns Set of visible indices
+ */
+export declare function getVisibleIndices(positions: THREE.Vector3[], camera: THREE.Camera, padding?: number): Set<number>;
+/**
+ * Calculate LOD level based on distance from camera
+ * @param position - Object position
+ * @param camera - Camera position
+ * @param lodLevels - Array of distance thresholds (sorted closest to farthest)
+ * @returns Index of the LOD level to use
+ */
+export declare function calculateLODLevel(position: THREE.Vector3, camera: THREE.Camera, lodLevels: number[]): number;
+/**
+ * Create a distance-based LOD system for an instanced mesh
+ * @param instancedMesh - The instanced mesh to manage
+ * @param positions - Array of instance positions
+ * @param camera - Camera to calculate distances from
+ * @param lodDistances - Distance thresholds for LOD levels
+ * @returns Array of LOD indices for each instance
+ */
+export declare function updateInstanceLOD(instancedMesh: THREE.InstancedMesh, positions: THREE.Vector3[], camera: THREE.Camera, lodDistances: number[]): Uint8Array;
+/**
+ * Create visibility data for instanced mesh culling
+ * Updates the instance matrix to hide/show instances
+ * @param instancedMesh - The instanced mesh
+ * @param positions - Array of instance positions
+ * @param visibleIndices - Set of visible indices
+ * @returns Updated count of visible instances
+ */
+export declare function cullInstancedMesh(instancedMesh: THREE.InstancedMesh, positions: THREE.Vector3[], visibleIndices: Set<number>): number;
+/**
+ * Spatial hash grid for efficient object queries
+ */
+export declare class SpatialHashGrid {
+    private cellSize;
+    private cells;
+    private objectPositions;
+    constructor(cellSize?: number);
+    /**
+     * Get cell key for a position
+     */
+    private getCellKey;
+    /**
+     * Insert an object into the grid
+     */
+    insert(id: string, position: THREE.Vector3): void;
+    /**
+     * Remove an object from the grid
+     */
+    remove(id: string): void;
+    /**
+     * Update an object's position
+     */
+    update(id: string, newPosition: THREE.Vector3): void;
+    /**
+     * Query objects within a radius of a position
+     */
+    queryRadius(center: THREE.Vector3, radius: number): string[];
+    /**
+     * Query objects within a bounding box
+     */
+    queryBox(minX: number, maxX: number, minZ: number, maxZ: number): string[];
+    /**
+     * Clear all objects from the grid
+     */
+    clear(): void;
+    /**
+     * Get statistics about the grid
+     */
+    getStats(): {
+        objects: number;
+        cells: number;
+    };
+}
+declare const _default: {
+    isInFrustum: typeof isInFrustum;
+    filterByFrustum: typeof filterByFrustum;
+    getVisibleIndices: typeof getVisibleIndices;
+    calculateLODLevel: typeof calculateLODLevel;
+    updateInstanceLOD: typeof updateInstanceLOD;
+    cullInstancedMesh: typeof cullInstancedMesh;
+    SpatialHashGrid: typeof SpatialHashGrid;
+};
+export default _default;

package/dist/components/organisms/game/three/utils/grid3D.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Grid 3D Utilities
+ *
+ * Utility functions for 3D grid coordinate transformations,
+ * raycasting, and spatial calculations for GameCanvas3D.
+ *
+ * @packageDocumentation
+ */
+import * as THREE from 'three';
+export interface Grid3DConfig {
+    /** Size of each grid cell */
+    cellSize: number;
+    /** Grid offset X */
+    offsetX?: number;
+    /** Grid offset Z */
+    offsetZ?: number;
+    /** Grid Y height (elevation) */
+    elevation?: number;
+}
+export interface GridCoordinate {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * Convert grid coordinates to world position
+ * @param gridX - Grid X coordinate
+ * @param gridZ - Grid Z coordinate
+ * @param config - Grid configuration
+ * @returns World position vector
+ */
+export declare function gridToWorld(gridX: number, gridZ: number, config?: Grid3DConfig): THREE.Vector3;
+/**
+ * Convert world position to grid coordinates
+ * @param worldX - World X position
+ * @param worldZ - World Z position
+ * @param config - Grid configuration
+ * @returns Grid coordinates
+ */
+export declare function worldToGrid(worldX: number, worldZ: number, config?: Grid3DConfig): {
+    x: number;
+    z: number;
+};
+/**
+ * Raycast from camera through mouse position to find grid intersection
+ * @param camera - Three.js camera
+ * @param mouseX - Mouse X position (normalized -1 to 1)
+ * @param mouseY - Mouse Y position (normalized -1 to 1)
+ * @param planeY - Y height of the intersection plane (default: 0)
+ * @returns Intersection point or null
+ */
+export declare function raycastToPlane(camera: THREE.Camera, mouseX: number, mouseY: number, planeY?: number): THREE.Vector3 | null;
+/**
+ * Raycast from camera through mouse position against a set of objects
+ * @param camera - Three.js camera
+ * @param mouseX - Mouse X position (normalized -1 to 1)
+ * @param mouseY - Mouse Y position (normalized -1 to 1)
+ * @param objects - Array of objects to test
+ * @returns First intersection or null
+ */
+export declare function raycastToObjects(camera: THREE.Camera, mouseX: number, mouseY: number, objects: THREE.Object3D[]): THREE.Intersection | null;
+/**
+ * Calculate distance between two grid coordinates
+ * @param a - First grid coordinate
+ * @param b - Second grid coordinate
+ * @returns Distance in grid units
+ */
+export declare function gridDistance(a: {
+    x: number;
+    z: number;
+}, b: {
+    x: number;
+    z: number;
+}): number;
+/**
+ * Calculate Manhattan distance between two grid coordinates
+ * @param a - First grid coordinate
+ * @param b - Second grid coordinate
+ * @returns Manhattan distance
+ */
+export declare function gridManhattanDistance(a: {
+    x: number;
+    z: number;
+}, b: {
+    x: number;
+    z: number;
+}): number;
+/**
+ * Get neighboring grid cells
+ * @param x - Center X coordinate
+ * @param z - Center Z coordinate
+ * @param includeDiagonal - Whether to include diagonal neighbors
+ * @returns Array of neighbor coordinates
+ */
+export declare function getNeighbors(x: number, z: number, includeDiagonal?: boolean): {
+    x: number;
+    z: number;
+}[];
+/**
+ * Check if a grid coordinate is within bounds
+ * @param x - X coordinate
+ * @param z - Z coordinate
+ * @param bounds - Bounds object
+ * @returns Whether the coordinate is within bounds
+ */
+export declare function isInBounds(x: number, z: number, bounds: {
+    minX: number;
+    maxX: number;
+    minZ: number;
+    maxZ: number;
+}): boolean;
+/**
+ * Get all grid cells within a circular radius
+ * @param centerX - Center X coordinate
+ * @param centerZ - Center Z coordinate
+ * @param radius - Radius in grid units
+ * @returns Array of coordinates within radius
+ */
+export declare function getCellsInRadius(centerX: number, centerZ: number, radius: number): {
+    x: number;
+    z: number;
+}[];
+/**
+ * Create a highlight mesh for grid cells
+ * @param color - Highlight color
+ * @param opacity - Opacity (0-1)
+ * @returns Mesh that can be positioned at grid cells
+ */
+export declare function createGridHighlight(color?: number, opacity?: number): THREE.Mesh;
+/**
+ * Normalize mouse coordinates to NDC (-1 to 1)
+ * @param clientX - Mouse client X
+ * @param clientY - Mouse client Y
+ * @param element - Canvas element
+ * @returns Normalized coordinates
+ */
+export declare function normalizeMouseCoordinates(clientX: number, clientY: number, element: HTMLElement): {
+    x: number;
+    y: number;
+};
+declare const _default: {
+    gridToWorld: typeof gridToWorld;
+    worldToGrid: typeof worldToGrid;
+    raycastToPlane: typeof raycastToPlane;
+    raycastToObjects: typeof raycastToObjects;
+    gridDistance: typeof gridDistance;
+    gridManhattanDistance: typeof gridManhattanDistance;
+    getNeighbors: typeof getNeighbors;
+    isInBounds: typeof isInBounds;
+    getCellsInRadius: typeof getCellsInRadius;
+    createGridHighlight: typeof createGridHighlight;
+    normalizeMouseCoordinates: typeof normalizeMouseCoordinates;
+};
+export default _default;