@almadar/ui 5.79.1 → 5.80.0

package/dist/components/game/shared/hooks/useUnitSpriteAtlas.d.ts

@@ -0,0 +1,24 @@
+import type { IsometricUnit } from '../isometricTypes';
+import type { ResolvedFrame } from '../spriteAnimationTypes';
+/**
+ * Resolve the sprite-sheet atlas-JSON URL for a unit.
+ *
+ * A unit has an atlas iff `unit.spriteSheet.url` is set (explicit metadata wins).
+ * No filename-pattern matching — a unit without a `spriteSheet` Asset keeps its static draw.
+ */
+export declare function unitAtlasUrl(unit: Pick<IsometricUnit, 'spriteSheet'>): string | null;
+export interface UseUnitSpriteAtlasResult {
+    /** Atlas-JSON URLs successfully loaded — feed these to no one; sheet PNGs are returned below. */
+    sheetUrls: string[];
+    /** Resolve the current single-frame rect for a unit, or null if its atlas isn't loaded. */
+    resolveUnitFrame: (unitId: string) => ResolvedFrame | null;
+    /** Whether any atlas is still loading (drives isLoading / keeps RAF alive). */
+    pendingCount: number;
+}
+/**
+ * Load per-unit sprite atlases and expose a pure frame resolver.
+ * Frame is computed from each unit's own `animation` + `frame` props — no internal clock.
+ *
+ * @param units - Units whose atlases should be loaded.
+ */
+export declare function useUnitSpriteAtlas(units: IsometricUnit[]): UseUnitSpriteAtlasResult;

package/dist/components/game/shared/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Game Shared (dimension-agnostic)
+ *
+ * Render DTO types, pure projection/animation utils, and the shared image cache hook.
+ *
+ * @packageDocumentation
+ */
+export type { IsometricTile, IsometricUnit, IsometricFeature, CameraState, } from './isometricTypes';
+export type { AnimationName, FacingDirection, SpriteDirection, ResolvedFrame, UnitAnimationState, SpriteFrameDims, SpriteSheetUrls, AnimationDef, } from './spriteAnimationTypes';
+export { createInitialGameState, calculateValidMoves, calculateAttackTargets, } from './game';
+export type { Position, GameUnit, UnitTrait, BoardTile, GamePhase, GameState, GameAction, } from './game';
+export * from './effects';
+export * from './boardEntity';
+export * from './makeAsset';
+export { useImageCache } from './useImageCache';
+export { isoToScreen, screenToIso, TILE_WIDTH, TILE_HEIGHT, FLOOR_HEIGHT, DIAMOND_TOP_Y, FEATURE_COLORS, } from './isometric';
+export type { TileLayout } from './isometric';
+export { inferDirection, resolveSheetDirection, getCurrentFrame, resolveFrame, createUnitAnimationState, transitionAnimation, tickAnimationState, } from './spriteAnimation';
+export { SPRITE_SHEET_LAYOUT, SHEET_COLUMNS } from './spriteSheetConstants';
+export * from './combatPresets';
+export * from './canvasEffects';

package/dist/components/game/shared/isometric.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Isometric Coordinate Utilities
+ *
+ * Pure functions for 2:1 diamond isometric coordinate conversion.
+ * No React dependencies — usable in any context.
+ *
+ * @packageDocumentation
+ */
+/** Base tile width in pixels (before scale) */
+export declare const TILE_WIDTH = 256;
+/** Base tile height in pixels (before scale) — full sprite image height (Kenney 256×512) */
+export declare const TILE_HEIGHT = 512;
+/** Floor diamond height — the "walkable surface" portion of the tile (TILE_WIDTH / 2 for 2:1 ratio) */
+export declare const FLOOR_HEIGHT = 128;
+/**
+ * Measured Y offset from sprite top to the diamond top vertex within a Kenney
+ * 256×512 tile sprite.  The code previously assumed `TILE_HEIGHT - FLOOR_HEIGHT = 384`,
+ * but the actual diamond (dirt_E.png) begins at y = 374 because the 3D side walls
+ * occupy 10 extra pixels above the pure 128 px diamond.
+ *
+ * Use `DIAMOND_TOP_Y * scale` for highlight positioning, unit groundY, feature
+ * placement, and hit-testing — NOT `(TILE_HEIGHT - FLOOR_HEIGHT) * scale`.
+ * `FLOOR_HEIGHT` remains 128 for the isoToScreen spacing formula (2:1 ratio).
+ */
+export declare const DIAMOND_TOP_Y = 374;
+/**
+ * Feature type → fallback color mapping (when sprites not loaded).
+ */
+export declare const FEATURE_COLORS: Record<string, string>;
+/**
+ * Tile layout mode. 'isometric' = 2:1 diamond projection (default).
+ * 'hex' = pointy-top offset-row hex grid.
+ * 'flat' = orthographic top-down square grid (sokoban/tanks/sports/etc.).
+ *
+ * Hex constants (at scale=1):
+ *   w = TILE_WIDTH (256)   — horizontal cell width
+ *   h = FLOOR_HEIGHT (128) — vertical row stride (= w/2; hex row-to-row = h*0.75 = 96)
+ * Forward:  screenX = col*w + (row&1)*(w/2) + baseOffsetX
+ *           screenY = row * (h * 0.75)
+ * Inverse: row = round(screenY / (h*0.75)); col = round((screenX - (row&1)*(w/2) - baseOffsetX) / w)
+ *
+ * Flat constants (at scale=1):
+ *   cellW = TILE_WIDTH (256) — horizontal cell pitch
+ *   cellH = FLOOR_HEIGHT (128) — vertical cell pitch (= cellW/2; keeps same visual scale as hex rows)
+ * Forward:  screenX = col*cellW + baseOffsetX
+ *           screenY = row * cellH
+ * Inverse:  col = round((screenX - baseOffsetX) / cellW); row = round(screenY / cellH)
+ */
+export type TileLayout = 'isometric' | 'hex' | 'flat';
+/**
+ * Convert tile grid coordinates to screen pixel coordinates.
+ *
+ * For 'isometric' (default): 2:1 diamond projection.
+ * For 'hex': pointy-top offset-row projection (odd rows shifted right by w/2).
+ * For 'flat': orthographic top-down square grid; col maps to X, row maps to Y.
+ *
+ * @param tileX - Grid X (col) coordinate
+ * @param tileY - Grid Y (row) coordinate
+ * @param scale - Render scale factor
+ * @param baseOffsetX - Horizontal offset to center the grid
+ * @param layout - Tile layout mode (default: 'isometric')
+ * @returns Screen position { x, y } of the tile's top-left corner
+ */
+export declare function isoToScreen(tileX: number, tileY: number, scale: number, baseOffsetX: number, layout?: TileLayout): {
+    x: number;
+    y: number;
+};
+/**
+ * Convert screen pixel coordinates back to tile grid coordinates.
+ *
+ * Inverse of isoToScreen. Snaps to nearest integer tile position.
+ *
+ * @param screenX - Screen X in pixels
+ * @param screenY - Screen Y in pixels
+ * @param scale - Render scale factor
+ * @param baseOffsetX - Horizontal offset used in isoToScreen
+ * @param layout - Tile layout mode (default: 'isometric')
+ * @returns Snapped grid position { x, y }
+ */
+export declare function screenToIso(screenX: number, screenY: number, scale: number, baseOffsetX: number, layout?: TileLayout): {
+    x: number;
+    y: number;
+};

package/dist/components/game/shared/isometricTypes.d.ts

@@ -0,0 +1,130 @@
+import type { Asset } from '@almadar/core';
+import type { AnimationName } from './spriteAnimationTypes';
+import type { UnitTrait } from './game';
+/**
+ * Isometric Game Types
+ *
+ * Type definitions for isometric grid rendering: tiles, units, features.
+ * Used by IsometricCanvas and game hooks.
+ *
+ * @packageDocumentation
+ */
+/** An active visual effect on the board. x,y are grid tile coords; ttl = remaining ticks. */
+export interface ActiveEffect {
+    /** Unique key — matched against assetManifest.effects for sprite lookup */
+    key: string;
+    /** Grid x coordinate */
+    x: number;
+    /** Grid y coordinate */
+    y: number;
+    /** Remaining ticks — used as a fade/scale hint (alpha = min(1, ttl/4)) */
+    ttl: number;
+}
+/** A single isometric tile on the grid */
+export interface IsometricTile {
+    /** Optional unique identifier (required for 3D rendering) */
+    id?: string;
+    /** Grid x coordinate */
+    x: number;
+    /** Grid y coordinate (2D) */
+    y: number;
+    /** Grid z coordinate (3D alternative to y) */
+    z?: number;
+    /** Terrain type key (e.g., 'grass', 'stone', 'water') - 2D */
+    terrain?: string;
+    /** Tile type for visual rendering (3D) */
+    type?: string;
+    /** Direct sprite URL override (bypasses getTerrainSprite resolver) */
+    terrainSprite?: Asset;
+    /** Whether units can traverse this tile (default true) */
+    passable?: boolean;
+    /** Movement cost for pathfinding (default 1) */
+    movementCost?: number;
+    /** Optional tile type for visual variants */
+    tileType?: string;
+    /** Elevation offset for 3D rendering */
+    elevation?: number;
+    /** 3D model URL (GLB format) for GameCanvas3D — rendered via ModelLoader with box fallback */
+    modelUrl?: Asset;
+}
+/** A unit positioned on the isometric grid */
+export type IsometricUnit = {
+    /** Unique unit identifier */
+    id: string;
+    /** Current grid position (2D format) */
+    position?: {
+        x: number;
+        y: number;
+    };
+    /** Grid x coordinate (3D format) */
+    x?: number;
+    /** Grid y coordinate (3D format) */
+    y?: number;
+    /** Grid z coordinate (3D format) */
+    z?: number;
+    /** Static sprite URL (used when no sprite sheet animation) */
+    sprite?: Asset;
+    /** Sprite-sheet atlas JSON URL (e.g. `.../guardian-sprite-sheet.json`).
+     *  When set, the canvas loads the atlas and crops/animates a single frame
+     *  by animation state instead of drawing the whole sheet. */
+    spriteSheet?: Asset;
+    /** 3D model URL (GLB format) for GameCanvas3D — rendered via ModelLoader with box fallback */
+    modelUrl?: Asset;
+    /** Unit archetype key for sprite resolution */
+    unitType?: string;
+    /** Hero identifier for sprite sheet lookup */
+    heroId?: string;
+    /** Display name rendered below the unit */
+    name?: string;
+    /** Team affiliation for coloring */
+    team?: 'player' | 'enemy' | 'neutral';
+    /** Faction for 3D rendering (player/enemy/neutral) */
+    faction?: 'player' | 'enemy' | 'neutral';
+    /** Current health */
+    health?: number;
+    /** Maximum health */
+    maxHealth?: number;
+    /** Trait attachments for state display */
+    traits?: UnitTrait[];
+    /** Previous position for movement trail ghost */
+    previousPosition?: {
+        x: number;
+        y: number;
+    };
+    /** Elevation offset for 3D rendering */
+    elevation?: number;
+    /** Animation name — driven by the LOLO state machine; renderer defaults to 'idle' */
+    animation?: AnimationName;
+    /** Frame index within the animation — driven by the LOLO state machine; renderer defaults to 0 */
+    frame?: number;
+};
+/** A map feature (resource, building, portal, etc.) */
+export type IsometricFeature = {
+    /** Optional unique identifier (required for 3D rendering) */
+    id?: string;
+    /** Grid x coordinate */
+    x: number;
+    /** Grid y coordinate (2D) */
+    y: number;
+    /** Grid z coordinate (3D alternative to y) */
+    z?: number;
+    /** Feature type key (e.g., 'goldMine', 'castle', 'portal') */
+    type: string;
+    /** Direct sprite URL override (bypasses getFeatureSprite resolver) */
+    sprite?: Asset;
+    /** 3D model URL (GLB format) for GameCanvas3D */
+    assetUrl?: Asset;
+    /** Color override for 3D rendering */
+    color?: string;
+    /** Elevation offset for 3D rendering */
+    elevation?: number;
+};
+/** Camera state for pan/zoom */
+export interface CameraState {
+    /** Camera X offset in pixels */
+    x: number;
+    /** Camera Y offset in pixels */
+    y: number;
+    /** Zoom level (1.0 = 100%) */
+    zoom: number;
+}

package/dist/components/game/shared/lib/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/game/shared/lib/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/game/shared/lib/editorUtils.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Shared Map Editor Utilities
+ *
+ * Reusable editor components for Storybook-based map editing.
+ * All composed from @almadar/ui atoms (Box, VStack, HStack, Typography, Button, Badge).
+ *
+ * NOTE: These are Storybook editor controls, NOT Orbital templates.
+ * They use native HTML inputs wrapped in Box for lightweight editor UX.
+ */
+import React from 'react';
+import type { Asset } from '@almadar/core';
+export type EditorMode = 'select' | 'paint' | 'unit' | 'feature' | 'erase';
+export declare const TERRAIN_COLORS: Record<string, string>;
+export declare const FEATURE_TYPES: readonly ["goldMine", "resonanceCrystal", "traitCache", "salvageYard", "portal", "battleMarker", "treasure", "castle"];
+export interface CollapsibleSectionProps {
+    title: string;
+    expanded: boolean;
+    onToggle: () => void;
+    children: React.ReactNode;
+    /** Optional per-semantic-key asset overrides for icons (expand/collapse). */
+    assetManifest?: {
+        ui?: Record<string, Asset>;
+    };
+    className?: string;
+}
+export declare function CollapsibleSection({ title, expanded, onToggle, children, assetManifest, className }: CollapsibleSectionProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace CollapsibleSection {
+    var displayName: string;
+}
+export interface EditorSliderProps {
+    label: string;
+    value: number;
+    min: number;
+    max: number;
+    step?: number;
+    onChange: (value: number) => void;
+    className?: string;
+}
+export declare function EditorSlider({ label, value, min, max, step, onChange, className }: EditorSliderProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace EditorSlider {
+    var displayName: string;
+}
+export interface EditorSelectProps {
+    label: string;
+    value: string;
+    options: Array<{
+        value: string;
+        label: string;
+    }>;
+    onChange: (value: string) => void;
+    className?: string;
+}
+export declare function EditorSelect({ label, value, options, onChange, className }: EditorSelectProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace EditorSelect {
+    var displayName: string;
+}
+export interface EditorCheckboxProps {
+    label: string;
+    checked: boolean;
+    onChange: (checked: boolean) => void;
+    className?: string;
+}
+export declare function EditorCheckbox({ label, checked, onChange, className }: EditorCheckboxProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace EditorCheckbox {
+    var displayName: string;
+}
+export interface EditorTextInputProps {
+    label: string;
+    value: string;
+    onChange: (value: string) => void;
+    placeholder?: string;
+    className?: string;
+}
+export declare function EditorTextInput({ label, value, onChange, placeholder, className }: EditorTextInputProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace EditorTextInput {
+    var displayName: string;
+}
+export interface StatusBarProps {
+    hoveredTile: {
+        x: number;
+        y: number;
+    } | null;
+    mode: EditorMode;
+    gridSize?: {
+        width: number;
+        height: number;
+    };
+    unitCount?: number;
+    featureCount?: number;
+    className?: string;
+}
+export declare function StatusBar({ hoveredTile, mode, gridSize, unitCount, featureCount, className }: StatusBarProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace StatusBar {
+    var displayName: string;
+}
+export interface TerrainPaletteProps {
+    terrains: string[];
+    selectedTerrain: string;
+    onSelect: (terrain: string) => void;
+    className?: string;
+}
+export declare function TerrainPalette({ terrains, selectedTerrain, onSelect, className }: TerrainPaletteProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace TerrainPalette {
+    var displayName: string;
+}
+export interface EditorToolbarProps {
+    mode: EditorMode;
+    onModeChange: (mode: EditorMode) => void;
+    className?: string;
+}
+export declare function EditorToolbar({ mode, onModeChange, className }: EditorToolbarProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace EditorToolbar {
+    var displayName: string;
+}

package/dist/components/game/shared/lib/game3dAssetManifest.d.ts

@@ -0,0 +1,48 @@
+/**
+ * game3dAssetManifest — shared, asset-URL-free helpers for the 3D game-canvas
+ * templates (battle / castle / world-map).
+ *
+ * Every GLB model URL lives in the lolo `assetManifest` config and arrives via
+ * props; these helpers resolve a tile's / feature's `modelUrl` from that manifest
+ * by terrain/feature key. NO asset URLs are declared here — the templates and this
+ * module stay pure, exactly like the `GameCanvas3D` molecule.
+ *
+ * @packageDocumentation
+ */
+import type { Asset, EntityRow } from '@almadar/core';
+import type { IsometricTile, IsometricFeature } from '../isometricTypes';
+/** GLB model assets for a 3D board, keyed by terrain "kind" and (optionally) feature type. */
+export interface Game3DAssetManifest {
+    /** Floor model assets by terrain kind ('wall' | 'dirt' | 'open'). */
+    models?: Record<string, Asset>;
+    /** Feature/structure model assets by feature type ('gold_mine', 'portal', …). */
+    features?: Record<string, Asset>;
+}
+/** Layout-only tile (no model URL): position + terrain kind. */
+export interface Tile3DLayout {
+    id?: string;
+    x: number;
+    y: number;
+    z?: number;
+    type: string;
+    passable?: boolean;
+    /** Terrain kind that maps into `assetManifest.models` (wall | dirt | open). */
+    kind: string;
+}
+/**
+ * Resolve a layout tile array into render-ready `IsometricTile[]`, attaching each
+ * tile's `modelUrl` from `assetManifest.models` by terrain kind. Pure: URLs come
+ * only from the manifest.
+ */
+export declare function resolveTilesWithModels(layout: readonly Tile3DLayout[], manifest: Game3DAssetManifest | undefined): IsometricTile[];
+/**
+ * Map prop `IsometricTile[]` (which already carry `type`/`passable` but no model)
+ * into render-ready tiles with manifest-resolved model URLs.
+ */
+export declare function resolvePropTiles(tiles: readonly IsometricTile[], manifest: Game3DAssetManifest | undefined): IsometricTile[];
+/** Read entity-carried tile rows into render-ready `IsometricTile[]` with manifest-resolved models. */
+export declare function resolveEntityTiles(entity: EntityRow | readonly EntityRow[] | undefined, manifest: Game3DAssetManifest | undefined): IsometricTile[];
+/** Resolve feature model URLs from `assetManifest.features` by feature type. */
+export declare function resolveFeaturesWithModels(features: readonly IsometricFeature[], manifest: Game3DAssetManifest | undefined): IsometricFeature[];
+/** Read entity-carried feature rows into render-ready `IsometricFeature[]` with manifest models. */
+export declare function resolveEntityFeatures(entity: EntityRow | readonly EntityRow[] | undefined, manifest: Game3DAssetManifest | undefined): IsometricFeature[];