@almadar/ui 2.14.0 → 2.15.1

package/dist/components/organisms/game/types/effects.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Canvas Effect Types
+ *
+ * Type definitions for the canvas-based particle, sequence, and overlay
+ * effect system. Used by canvasEffects engine and combat presets.
+ *
+ * Ported from trait-wars and generalized for any almadar-ui client.
+ */
+/**
+ * A single particle in flight — rendered as a tinted sprite each frame.
+ */
+export interface CanvasParticle {
+    /** Sprite URL (white-on-transparent particle) */
+    spriteUrl: string;
+    /** Current position in screen pixels */
+    x: number;
+    y: number;
+    /** Velocity in pixels per second */
+    vx: number;
+    vy: number;
+    /** Downward acceleration in px/s² (positive = down) */
+    gravity: number;
+    /** Current rotation in radians */
+    rotation: number;
+    /** Rotation speed in radians per second */
+    rotationSpeed: number;
+    /** Current scale (1.0 = original size) */
+    scale: number;
+    /** Scale change per second (negative = shrink) */
+    scaleSpeed: number;
+    /** Current alpha (0-1) */
+    alpha: number;
+    /** Alpha change per second (negative = fade out) */
+    fadeRate: number;
+    /** RGB tint color (applied via offscreen canvas compositing) */
+    tint: {
+        r: number;
+        g: number;
+        b: number;
+    };
+    /** Canvas blend mode */
+    blendMode: GlobalCompositeOperation;
+    /** Time this particle was spawned (ms) */
+    spawnTime: number;
+    /** Maximum lifetime in ms (particle removed after) */
+    lifetime: number;
+}
+/**
+ * Configuration for spawning a burst of particles.
+ */
+export interface ParticleEmitterConfig {
+    /** Array of sprite URLs to randomly pick from */
+    spriteUrls: string[];
+    /** Number of particles to spawn */
+    count: number;
+    /** Spawn origin in screen pixels */
+    originX: number;
+    originY: number;
+    /** Random spread radius from origin (px) */
+    spread: number;
+    /** Velocity range (px/s) */
+    velocityMin: number;
+    velocityMax: number;
+    /** Emission angle range (radians, 0 = right, PI/2 = down) */
+    angleMin: number;
+    angleMax: number;
+    /** Gravity (px/s²) */
+    gravity: number;
+    /** RGB tint */
+    tint: {
+        r: number;
+        g: number;
+        b: number;
+    };
+    /** Scale range */
+    scaleMin: number;
+    scaleMax: number;
+    /** Scale speed (per second) */
+    scaleSpeed?: number;
+    /** Particle lifetime range (ms) */
+    lifetimeMin: number;
+    lifetimeMax: number;
+    /** Fade rate (alpha per second, negative = fade out) */
+    fadeRate?: number;
+    /** Starting alpha */
+    alpha?: number;
+    /** Canvas blend mode */
+    blendMode?: GlobalCompositeOperation;
+    /** Rotation speed range (radians/s) */
+    rotationSpeedMin?: number;
+    rotationSpeedMax?: number;
+}
+/**
+ * A frame-sequence animation (e.g., explosion, smoke puff).
+ */
+export interface CanvasSequence {
+    /** Ordered array of frame sprite URLs */
+    frameUrls: string[];
+    /** Position in screen pixels (top-left of sprite) */
+    x: number;
+    y: number;
+    /** Duration per frame in ms */
+    frameDuration: number;
+    /** Time this sequence started (ms) */
+    startTime: number;
+    /** Whether to loop the animation */
+    loop: boolean;
+    /** Render scale */
+    scale: number;
+    /** RGB tint (null = no tinting) */
+    tint: {
+        r: number;
+        g: number;
+        b: number;
+    } | null;
+    /** Alpha (0-1) */
+    alpha: number;
+    /** Canvas blend mode */
+    blendMode: GlobalCompositeOperation;
+}
+/**
+ * Configuration for spawning a frame sequence.
+ */
+export interface SequenceConfig {
+    frameUrls: string[];
+    originX: number;
+    originY: number;
+    frameDuration: number;
+    loop?: boolean;
+    scale?: number;
+    tint?: {
+        r: number;
+        g: number;
+        b: number;
+    } | null;
+    alpha?: number;
+    blendMode?: GlobalCompositeOperation;
+}
+/**
+ * A static/fading overlay image (e.g., ground scorch mark, shield circle).
+ */
+export interface CanvasOverlay {
+    /** Sprite URL */
+    spriteUrl: string;
+    /** Center position in screen pixels */
+    x: number;
+    y: number;
+    /** Current alpha (0-1) */
+    alpha: number;
+    /** Alpha change per second (negative = fade out) */
+    fadeRate: number;
+    /** Pulse amplitude (0 = no pulse, 0.3 = alpha oscillates ±0.3) */
+    pulseAmplitude: number;
+    /** Pulse frequency in Hz */
+    pulseFrequency: number;
+    /** Render scale */
+    scale: number;
+    /** Canvas blend mode */
+    blendMode: GlobalCompositeOperation;
+    /** Time this overlay was spawned (ms) */
+    spawnTime: number;
+    /** Maximum lifetime in ms */
+    lifetime: number;
+}
+/**
+ * Configuration for spawning an overlay.
+ */
+export interface OverlayConfig {
+    spriteUrl: string;
+    originX: number;
+    originY: number;
+    alpha?: number;
+    fadeRate?: number;
+    pulseAmplitude?: number;
+    pulseFrequency?: number;
+    scale?: number;
+    blendMode?: GlobalCompositeOperation;
+    lifetime?: number;
+}
+/**
+ * Full state of all active effects on the canvas.
+ */
+export interface CanvasEffectState {
+    particles: CanvasParticle[];
+    sequences: CanvasSequence[];
+    overlays: CanvasOverlay[];
+}
+/**
+ * Combat action types that map to effect compositions.
+ * Superset of trait-wars types + almadar-ui originals.
+ */
+export type CombatActionType = 'melee' | 'ranged' | 'magic' | 'heal' | 'defend' | 'hit' | 'death' | 'buff' | 'debuff' | 'shield' | 'aoe' | 'critical';
+/**
+ * A combat preset composes multiple effect layers.
+ */
+export interface CombatPreset {
+    /** Particle emitter configs to spawn */
+    particles: ParticleEmitterConfig[];
+    /** Sequence configs to spawn */
+    sequences: SequenceConfig[];
+    /** Overlay configs to spawn */
+    overlays: OverlayConfig[];
+    /** Screen shake intensity in pixels (0 = none) */
+    screenShake: number;
+    /** Screen flash color and duration */
+    screenFlash: {
+        r: number;
+        g: number;
+        b: number;
+        duration: number;
+    } | null;
+}
+/**
+ * Effect asset manifest — the sprites and animation frames available for
+ * the particle engine. This is the `assetManifest.effects` section.
+ */
+export interface EffectAssetManifest {
+    /** Base URL for all asset paths */
+    baseUrl: string;
+    /** Particle sprite groups (white-on-transparent, tinted at runtime) */
+    particles?: {
+        slash?: string[];
+        magic?: string[];
+        fire?: string[];
+        flame?: string[];
+        smoke?: string[];
+        scorch?: string[];
+        circle?: string[];
+        flare?: string;
+        spark?: string[];
+        muzzle?: string[];
+        star?: string[];
+        trace?: string[];
+        twirl?: string[];
+        light?: string[];
+        dirt?: string[];
+        scratch?: string[];
+        symbol?: string[];
+    };
+    /** Frame-sequence animations (array of frame image paths) */
+    animations?: {
+        explosion?: string[];
+        smokePuff?: string[];
+        flash?: string[];
+        blackSmoke?: string[];
+        gasSmoke?: string[];
+        smokeExplosion?: string[];
+    };
+}
+/**
+ * Empty effect state constant.
+ */
+export declare const EMPTY_EFFECT_STATE: CanvasEffectState;

package/dist/components/organisms/game/types/game.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Game Types — Generalized
+ *
+ * Core type definitions for tactical game state.
+ * Extracted from Trait Wars and generalized for any game project.
+ */
+export interface Position {
+    x: number;
+    y: number;
+}
+export interface GameUnit {
+    id: string;
+    name: string;
+    characterType: string;
+    team: 'player' | 'enemy';
+    position: Position;
+    health: number;
+    maxHealth: number;
+    movement: number;
+    attack: number;
+    defense: number;
+    traits: UnitTrait[];
+}
+export interface UnitTrait {
+    name: string;
+    currentState: string;
+    states: string[];
+    cooldown: number;
+}
+export interface BoardTile {
+    terrain: string;
+    unitId?: string;
+    isBlocked?: boolean;
+}
+export type GamePhase = 'observation' | 'planning' | 'execution' | 'tick';
+export interface GameState {
+    board: BoardTile[][];
+    units: Record<string, GameUnit>;
+    currentPhase: GamePhase;
+    currentTurn: number;
+    activeTeam: 'player' | 'enemy';
+    selectedUnitId?: string;
+    validMoves: Position[];
+    attackTargets: Position[];
+}
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export declare function calculateAttackTargets(state: GameState, unitId: string): Position[];

package/dist/components/organisms/game/types/isometric.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Isometric Game Types
+ *
+ * Type definitions for isometric grid rendering: tiles, units, features.
+ * Used by IsometricCanvas and game hooks.
+ *
+ * @packageDocumentation
+ */
+/** 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?: 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;
+}
+/** A unit positioned on the isometric grid */
+export interface 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?: string;
+    /** 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?: {
+        name: string;
+        currentState: string;
+        states: string[];
+        cooldown: number;
+    }[];
+    /** Previous position for movement trail ghost */
+    previousPosition?: {
+        x: number;
+        y: number;
+    };
+    /** Elevation offset for 3D rendering */
+    elevation?: number;
+}
+/** A map feature (resource, building, portal, etc.) */
+export interface 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?: string;
+    /** 3D model URL (GLB format) for GameCanvas3D */
+    assetUrl?: string;
+    /** 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/organisms/game/types/spriteAnimation.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Sprite Sheet Animation Types
+ *
+ * Type definitions for frame-based sprite sheet animation system.
+ * Supports standard 8-column × 5-row character sheets.
+ *
+ * @packageDocumentation
+ */
+/** Animation names matching sprite sheet row layout */
+export type AnimationName = 'idle' | 'walk' | 'attack' | 'hit' | 'death';
+/** Sheet file directions (physical PNG files) */
+export type SpriteDirection = 'se' | 'sw';
+/** Unit facing direction on screen (4 isometric directions) */
+export type FacingDirection = 'se' | 'sw' | 'ne' | 'nw';
+/** Definition for a single animation row in the sprite sheet */
+export interface AnimationDef {
+    /** Row index in the sprite sheet (0-4) */
+    row: number;
+    /** Number of frames in this animation */
+    frames: number;
+    /** Frames per second */
+    frameRate: number;
+    /** Whether the animation loops */
+    loop: boolean;
+}
+/** A resolved frame ready to draw on canvas */
+export 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 */
+export 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 */
+export 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 */
+export interface SpriteSheetUrls {
+    /** Southeast-facing sheet URL */
+    se: string;
+    /** Southwest-facing sheet URL */
+    sw: string;
+}

package/dist/components/organisms/game/useCanvasEffects.d.ts

@@ -0,0 +1,26 @@
+import type { CombatActionType, EffectAssetManifest } from './types/effects';
+export interface UseCanvasEffectsOptions {
+    /** Effect asset manifest (baseUrl + particles + animations) */
+    manifest: EffectAssetManifest;
+}
+export interface UseCanvasEffectsResult {
+    /** All effect sprite URLs for preloading via useImageCache */
+    effectSpriteUrls: string[];
+    /** Spawn a combat effect at the given screen position */
+    spawnEffect: (type: CombatActionType, screenX: number, screenY: number) => void;
+    /** Draw all active effects — call inside draw() after units, before ctx.restore() */
+    drawEffects: (ctx: CanvasRenderingContext2D, animTime: number, getImage: (url: string) => HTMLImageElement | undefined) => void;
+    /** Whether there are active effects (keeps RAF alive) */
+    hasActiveEffects: boolean;
+    /** Screen shake offset to apply to container transform */
+    screenShake: {
+        x: number;
+        y: number;
+    };
+    /** Screen flash overlay (null = no flash) */
+    screenFlash: {
+        color: string;
+        alpha: number;
+    } | null;
+}
+export declare function useCanvasEffects({ manifest, }: UseCanvasEffectsOptions): UseCanvasEffectsResult;

package/dist/components/organisms/game/utils/canvasEffects.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Canvas Effect Engine
+ *
+ * Pure functions for spawning, updating, and drawing canvas effects.
+ * No React dependencies — called from the RAF loop via useCanvasEffects hook.
+ *
+ * Ported from trait-wars and generalized for any almadar-ui client.
+ */
+import type { CanvasParticle, CanvasSequence, CanvasOverlay, CanvasEffectState, ParticleEmitterConfig, SequenceConfig, OverlayConfig } from '../types/effects';
+/**
+ * Draw a sprite tinted with an RGB color onto the main canvas.
+ * Uses offscreen canvas with `source-atop` compositing to recolor
+ * white-on-transparent sprites.
+ */
+export declare function drawTintedImage(ctx: CanvasRenderingContext2D, img: HTMLImageElement | ImageBitmap, x: number, y: number, w: number, h: number, tint: {
+    r: number;
+    g: number;
+    b: number;
+}, alpha: number, blendMode?: GlobalCompositeOperation): void;
+/**
+ * Spawn a burst of particles from an emitter config.
+ */
+export declare function spawnParticles(config: ParticleEmitterConfig, animTime: number): CanvasParticle[];
+/**
+ * Spawn a frame sequence animation.
+ */
+export declare function spawnSequence(config: SequenceConfig, animTime: number): CanvasSequence;
+/**
+ * Spawn an overlay effect.
+ */
+export declare function spawnOverlay(config: OverlayConfig, animTime: number): CanvasOverlay;
+/**
+ * Advance effect state by one frame. Returns new state with expired effects removed.
+ */
+export declare function updateEffectState(state: CanvasEffectState, animTime: number, deltaMs: number): CanvasEffectState;
+type GetImageFn = (url: string) => HTMLImageElement | undefined;
+/**
+ * Draw all active effects onto the canvas.
+ */
+export declare function drawEffectState(ctx: CanvasRenderingContext2D, state: CanvasEffectState, animTime: number, getImage: GetImageFn): void;
+export declare function hasActiveEffects(state: CanvasEffectState): boolean;
+/**
+ * Collect all sprite URLs from an EffectAssetManifest for preloading.
+ */
+export declare function getAllEffectSpriteUrls(manifest: {
+    baseUrl: string;
+    particles?: Record<string, string[] | string | undefined>;
+    animations?: Record<string, string[] | undefined>;
+}): string[];
+export {};

package/dist/components/organisms/game/utils/combatEffects.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Combat Effects Utility
+ *
+ * CSS animation utilities and effect triggers for combat visualization.
+ * Extracted from Trait Wars design-system.
+ */
+export declare const combatAnimations: {
+    shake: string;
+    flash: string;
+    pulseRed: string;
+    healGlow: string;
+};
+export declare const combatClasses: {
+    shake: string;
+    flash: string;
+    pulseRed: string;
+    healGlow: string;
+    hit: string;
+    defend: string;
+    critical: string;
+};
+export interface CombatEffect {
+    className: string;
+    duration: number;
+    sound?: string;
+}
+export declare const combatEffects: Record<string, CombatEffect>;
+/**
+ * Apply a temporary combat effect to an HTML element.
+ *
+ * Adds the effect's CSS class to the element and removes it after
+ * the effect duration completes.
+ *
+ * @param {HTMLElement} element - The DOM element to apply the effect to
+ * @param {CombatEffect} effect - The combat effect to apply
+ * @param {() => void} [onComplete] - Optional callback when effect completes
+ */
+export declare function applyTemporaryEffect(element: HTMLElement, effect: CombatEffect, onComplete?: () => void): void;
+export interface DamageResult {
+    baseDamage: number;
+    finalDamage: number;
+    isCritical: boolean;
+    isBlocked: boolean;
+    damageReduction: number;
+}
+/**
+ * Calculate combat damage with defense and critical hit mechanics.
+ *
+ * @param {number} attack - Attacker's attack power
+ * @param {number} defense - Defender's defense power
+ * @param {boolean} [isDefending] - Whether defender is in defend stance (doubles defense)
+ * @param {number} [criticalChance] - Probability of critical hit (0-1, default 0.1)
+ * @returns {DamageResult} Calculated damage with critical/block info
+ */
+export declare function calculateDamage(attack: number, defense: number, isDefending?: boolean, criticalChance?: number): DamageResult;
+export type CombatEventType = 'attack' | 'critical' | 'defend' | 'heal' | 'defeat' | 'level_up' | 'state_change';
+export interface CombatEventData {
+    type: CombatEventType;
+    sourceId: string;
+    targetId?: string;
+    value?: number;
+    message: string;
+}
+export declare function generateCombatMessage(event: CombatEventData): string;

package/dist/components/organisms/game/utils/combatPresets.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Combat Presets
+ *
+ * Maps combat actions to composed effect layers (particles + sequences + overlays).
+ * Each preset factory takes a screen-space origin and returns a CombatPreset.
+ *
+ * Generalized from trait-wars: uses EffectAssetManifest instead of TraitWarsAssetManifest.
+ */
+import type { CombatActionType, CombatPreset, EffectAssetManifest } from '../types/effects';
+type PresetFactory = (originX: number, originY: number) => CombatPreset;
+/**
+ * Create combat preset factories from an effect asset manifest.
+ */
+export declare function createCombatPresets(manifest: EffectAssetManifest): Record<CombatActionType, PresetFactory>;
+export {};