@almadar/ui 5.111.0 → 5.113.0

package/dist/avl-schema-parser-B8Onmfsu.d.cts

@@ -0,0 +1,393 @@
+import { AnimationName, Asset, JsonObject, JsonValue } from '@almadar/core';
+
+/**
+ * Sprite Sheet Animation Types
+ *
+ * Type definitions for frame-based sprite sheet animation system.
+ * Supports standard 8-column × 5-row character sheets.
+ *
+ * `AnimationName`, `AnimationDef`, and `SpriteDirection` are canonically owned
+ * by `@almadar/core` (they travel with a `spriteSheet`-role `Asset.url`'s
+ * resolved atlas contract) — re-exported here so existing call sites in this
+ * package don't need to change their import path.
+ *
+ * @packageDocumentation
+ */
+
+/** Unit facing direction on screen (4 isometric directions) */
+type FacingDirection = 'se' | 'sw' | 'ne' | 'nw';
+/** A resolved frame ready to draw on canvas */
+interface ResolvedFrame {
+    /** URL of the sprite sheet image */
+    sheetUrl: string;
+    /** Source X in the sheet (pixel offset) */
+    sx: number;
+    /** Source Y in the sheet (pixel offset) */
+    sy: number;
+    /** Source width (frame width) */
+    sw: number;
+    /** Source height (frame height) */
+    sh: number;
+    /** Whether to flip horizontally when drawing (for NE/NW directions) */
+    flipX: boolean;
+    /** When true, canvas should apply sine-bob breathing offset (frozen idle frame) */
+    applyBreathing?: boolean;
+}
+/** Per-unit animation state tracked in the animation system */
+interface UnitAnimationState {
+    /** Unit identifier */
+    unitId: string;
+    /** Current animation playing */
+    animation: AnimationName;
+    /** Current facing direction */
+    direction: FacingDirection;
+    /** Current frame index within the animation */
+    frame: number;
+    /** Elapsed time in current animation (ms) */
+    elapsed: number;
+    /** Animation to play after current one-shot completes (null = idle) */
+    queuedAnimation: AnimationName | null;
+    /** Whether the current one-shot animation has finished its last frame */
+    finished: boolean;
+}
+/** Frame dimensions for a sprite sheet */
+interface SpriteFrameDims {
+    /** Width of a single frame in pixels */
+    width: number;
+    /** Height of a single frame in pixels */
+    height: number;
+}
+/** Sheet URLs for both directions */
+interface SpriteSheetUrls {
+    /** Southeast-facing sheet URL */
+    se: string;
+    /** Southwest-facing sheet URL */
+    sw: string;
+}
+
+/**
+ * Game Types — Generalized
+ *
+ * Core type definitions for tactical game state.
+ * Extracted from Trait Wars and generalized for any game project.
+ */
+interface Position {
+    x: number;
+    y: number;
+}
+interface GameUnit {
+    id: string;
+    name: string;
+    characterType: string;
+    team: 'player' | 'enemy' | 'neutral';
+    position: Position;
+    health: number;
+    maxHealth: number;
+    movement: number;
+    attack: number;
+    defense: number;
+    traits: UnitTrait[];
+}
+interface UnitTrait {
+    name: string;
+    currentState: string;
+    states: string[];
+    cooldown: number;
+}
+interface BoardTile {
+    terrain: string;
+    unitId?: string;
+    isBlocked?: boolean;
+}
+type GamePhase = 'observation' | 'planning' | 'execution' | 'tick';
+interface GameState {
+    board: BoardTile[][];
+    units: Record<string, GameUnit>;
+    currentPhase: GamePhase;
+    currentTurn: number;
+    activeTeam: 'player' | 'enemy' | 'neutral';
+    selectedUnitId?: string;
+    validMoves: Position[];
+    attackTargets: Position[];
+}
+type GameAction = {
+    type: 'SELECT_UNIT';
+    unitId: string;
+} | {
+    type: 'MOVE_UNIT';
+    from: Position;
+    to: Position;
+} | {
+    type: 'ATTACK';
+    attackerId: string;
+    targetId: string;
+} | {
+    type: 'END_TURN';
+} | {
+    type: 'EXECUTE_TRAITS';
+};
+/**
+ * Create the initial game state with board and units.
+ *
+ * @param {number} width - Board width in tiles
+ * @param {number} height - Board height in tiles
+ * @param {GameUnit[]} units - Initial units to place on the board
+ * @param {string} [defaultTerrain] - Default terrain type for empty tiles
+ * @returns {GameState} The initialized game state
+ */
+declare function createInitialGameState(width: number, height: number, units: GameUnit[], defaultTerrain?: string): GameState;
+/**
+ * Calculate valid movement positions for a unit.
+ *
+ * Returns all tiles within the unit's movement range that are
+ * not blocked and don't contain other units.
+ *
+ * @param {GameState} state - Current game state
+ * @param {string} unitId - ID of the unit to calculate moves for
+ * @returns {Position[]} Array of valid move positions
+ */
+declare function calculateValidMoves(state: GameState, unitId: string): Position[];
+/**
+ * Calculate valid attack targets for a unit.
+ *
+ * Returns adjacent positions containing enemy units that can be attacked.
+ *
+ * @param {GameState} state - Current game state
+ * @param {string} unitId - ID of the unit to calculate targets for
+ * @returns {Position[]} Array of valid attack target positions
+ */
+declare function calculateAttackTargets(state: GameState, unitId: string): Position[];
+
+/** A single isometric tile on the grid */
+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;
+    /** Fallback/override fill color (2D + 3D) — bypasses the terrain color map. `.lolo`-computed. */
+    color?: string;
+    /** 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;
+    /** Y-axis rotation in degrees (3D) — orients directional pieces (track corners, road bends) */
+    rotation?: number;
+}
+/** A unit positioned on the isometric grid */
+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';
+    /** Fallback/override tint color (2D + 3D) — bypasses the team/faction color map. `.lolo`-computed. */
+    tint?: string;
+    /** 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;
+    /** Y-axis heading in radians (3D) — travel/facing direction. Orients the unit model and
+     *  drives the `chase` camera (behind + above, looking along heading). Driving boards set this. */
+    heading?: number;
+};
+/** A map feature (resource, building, portal, etc.) */
+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;
+    /** Y-axis rotation in radians (3D) — orients directional features (arches, signs, docks). */
+    rotation?: number;
+};
+/** Camera state for pan/zoom */
+interface CameraState {
+    /** Camera X offset in pixels */
+    x: number;
+    /** Camera Y offset in pixels */
+    y: number;
+    /** Zoom level (1.0 = 100%) */
+    zoom: number;
+}
+
+/**
+ * AVL Schema Parser
+ *
+ * Pure functions that transform an OrbitalSchema into structured data
+ * for each zoom level of the Cosmic Zoom visualization.
+ *
+ * Imports all types from @almadar/core.
+ *
+ * @packageDocumentation
+ */
+
+interface SerializedEffect extends JsonObject {
+    type: string;
+    args: JsonValue[];
+}
+interface ApplicationOrbitalData {
+    name: string;
+    entityName: string;
+    fieldCount: number;
+    persistence: string;
+    traitNames: string[];
+    pageNames: string[];
+    position: {
+        x: number;
+        y: number;
+    };
+}
+interface CrossLink {
+    emitterOrbital: string;
+    listenerOrbital: string;
+    eventName: string;
+    emitterTrait: string;
+    listenerTrait: string;
+}
+interface ApplicationLevelData {
+    orbitals: ApplicationOrbitalData[];
+    crossLinks: CrossLink[];
+}
+interface FieldInfo extends JsonObject {
+    name: string;
+    type: string;
+    required: boolean;
+    hasDefault: boolean;
+}
+interface OrbitalTraitInfo extends JsonObject {
+    name: string;
+    stateCount: number;
+    eventCount: number;
+    transitionCount: number;
+    emits: string[];
+    listens: string[];
+}
+interface OrbitalPageInfo extends JsonObject {
+    name: string;
+    route: string;
+}
+interface ExternalLink extends JsonObject {
+    targetOrbital: string;
+    eventName: string;
+    direction: string;
+    traitName: string;
+}
+interface OrbitalLevelData {
+    name: string;
+    entity: {
+        name: string;
+        fields: FieldInfo[];
+        persistence: string;
+    };
+    traits: OrbitalTraitInfo[];
+    pages: OrbitalPageInfo[];
+    externalLinks: ExternalLink[];
+}
+interface TraitStateInfo extends JsonObject {
+    name: string;
+    isInitial: boolean | null;
+    isTerminal: boolean | null;
+}
+interface TraitTransitionInfo extends JsonObject {
+    from: string;
+    to: string;
+    event: string;
+    guard: JsonValue | null;
+    effects: SerializedEffect[];
+    index: number;
+}
+interface TraitLevelData extends JsonObject {
+    name: string;
+    linkedEntity: string;
+    states: TraitStateInfo[];
+    transitions: TraitTransitionInfo[];
+    emittedEvents: string[];
+    listenedEvents: string[];
+}
+interface ExprTreeNode {
+    label: string;
+    type: 'operator' | 'literal' | 'binding';
+    children?: ExprTreeNode[];
+}
+interface SlotTarget {
+    name: string;
+    pattern: string;
+}
+interface TransitionLevelData {
+    from: string;
+    to: string;
+    event: string;
+    guard: ExprTreeNode | null;
+    effects: ExprTreeNode[];
+    slotTargets: SlotTarget[];
+}
+
+export { type ApplicationLevelData as A, type BoardTile as B, type CameraState as C, type ExternalLink as E, type FacingDirection as F, type GameAction as G, type IsometricTile as I, type OrbitalLevelData as O, type Position as P, type ResolvedFrame as R, type SpriteSheetUrls as S, type TraitLevelData as T, type UnitAnimationState as U, type IsometricUnit as a, type IsometricFeature as b, type TransitionLevelData as c, type SpriteFrameDims as d, type FieldInfo as e, type OrbitalTraitInfo as f, type OrbitalPageInfo as g, type GamePhase as h, type GameState as i, type GameUnit as j, type UnitTrait as k, calculateAttackTargets as l, calculateValidMoves as m, createInitialGameState as n };