cubeforge 0.5.2 → 0.6.0

package/dist/index.d.ts

@@ -503,7 +503,48 @@ interface SquashStretchProps {
 }
 declare function SquashStretch({ intensity, recovery }: SquashStretchProps): null;
 
-type ParticlePreset = 'explosion' | 'spark' | 'smoke' | 'coinPickup' | 'jumpDust';
+type ParticlePreset = 'explosion' | 'spark' | 'smoke' | 'coinPickup' | 'jumpDust' | 'fire' | 'magic' | 'rain' | 'snow' | 'confetti' | 'sparkle' | 'heal' | 'damage' | 'pickup' | 'fountain' | 'trail';
+interface ParticleEmitterConfig {
+    rate?: number;
+    speed?: number;
+    spread?: number;
+    angle?: number;
+    particleLife?: number;
+    particleSize?: number;
+    color?: string;
+    gravity?: number;
+    maxParticles?: number;
+    /** Colors to interpolate through over particle lifetime. */
+    colorOverLife?: string[];
+    /** Start/end size ratios for per-particle size curve (end is multiplier of particleSize). */
+    sizeOverLife?: {
+        start: number;
+        end: number;
+    };
+    /** Blend mode for the emitter (additive for glows, normal for solid). */
+    blendMode?: 'normal' | 'additive';
+    /** Particle shape: 'soft' gradient, 'circle' hard disc, 'square' quad. */
+    particleShape?: 'soft' | 'circle' | 'square';
+}
+/**
+ * Ready-made particle configurations. Pass via the `preset` prop on
+ * `<ParticleEmitter>`:
+ *
+ * ```tsx
+ * <ParticleEmitter preset="fire" />
+ * <ParticleEmitter preset="explosion" color="#8bc34a" />  // overrides
+ * ```
+ *
+ * Individual props always override preset values — presets are defaults.
+ *
+ * ## Catalog
+ *
+ * Action / combat: `explosion`, `spark`, `damage`, `heal`, `magic`
+ * Environment:     `fire`, `smoke`, `rain`, `snow`, `fountain`
+ * UI / reward:     `coinPickup`, `pickup`, `sparkle`, `confetti`
+ * Character:       `jumpDust`, `trail`
+ */
+declare const PARTICLE_PRESETS: Record<ParticlePreset, ParticleEmitterConfig>;
 
 interface ParticleEmitterProps {
     active?: boolean;
@@ -3100,6 +3141,143 @@ declare function deleteSavedScene(key: string): boolean;
  */
 declare function listSavedScenes(prefix?: string): string[];
 
+type HUDPosition = 'topLeft' | 'topCenter' | 'topRight' | 'centerLeft' | 'center' | 'centerRight' | 'bottomLeft' | 'bottomCenter' | 'bottomRight';
+interface HUDProps {
+    /**
+     * Whether the HUD fades out during scene transitions. Default true. When a
+     * `SceneTransitionOverlay` is active or `usePause` is paused, the HUD will
+     * dim to `dimmedOpacity` to get out of the way.
+     */
+    dimDuringTransitions?: boolean;
+    /** Opacity when dimmed. Default 0.25. */
+    dimmedOpacity?: number;
+    /** Whether the HUD is currently visible. Default true. */
+    visible?: boolean;
+    /** Whether to apply CSS `env(safe-area-inset-*)` padding. Default true on touch. */
+    safeArea?: boolean;
+    /** Extra padding around all zones in CSS pixels. Default 12. */
+    padding?: number;
+    /** Additional style for the HUD root. */
+    style?: CSSProperties;
+    /** Additional CSS class. */
+    className?: string;
+    children?: ReactNode;
+}
+/**
+ * Heads-up-display root. Positions a full-screen overlay over the game canvas
+ * and provides layout zones via {@link HUDZone}. Integrates automatically with
+ * CubeForge primitives:
+ *
+ * - Fades out during scene transitions (via `dimDuringTransitions`)
+ * - Respects `prefers-reduced-motion` for fade timing
+ * - Honors mobile safe-area insets when `safeArea` is on
+ *
+ * @example
+ * ```tsx
+ * <Stage>
+ *   <HUD>
+ *     <HUDZone position="topLeft">
+ *       <HUDBar value={hp} max={100} label="HP" color="#ef5350" />
+ *     </HUDZone>
+ *     <HUDZone position="topRight">
+ *       <span>Score: {score}</span>
+ *     </HUDZone>
+ *     <HUDZone position="bottomCenter">
+ *       <button onClick={onJump}>Jump</button>
+ *     </HUDZone>
+ *   </HUD>
+ * </Stage>
+ * ```
+ */
+declare function HUD({ dimDuringTransitions, dimmedOpacity, visible, safeArea, padding, style, className, children, }: HUDProps): react_jsx_runtime.JSX.Element;
+interface HUDZoneProps {
+    /** Where to anchor this zone. Default 'topLeft'. */
+    position?: HUDPosition;
+    /** Direction children lay out. Default 'row' for top/bottom, 'column' for left/right/center. */
+    direction?: 'row' | 'column';
+    /** Gap between children in CSS pixels. Default 8. */
+    gap?: number;
+    /** Allow pointer events on zone contents (buttons, sliders). Default true for this zone. */
+    interactive?: boolean;
+    /** Override style for the zone. */
+    style?: CSSProperties;
+    /** Additional CSS class. */
+    className?: string;
+    children?: ReactNode;
+}
+/**
+ * Positioned content zone inside a {@link HUD}. Nine anchors available
+ * (topLeft, topCenter, topRight, centerLeft, center, centerRight, bottomLeft,
+ * bottomCenter, bottomRight). Honors the parent HUD's padding and safe-area.
+ */
+declare function HUDZone({ position, direction, gap, interactive, style, className, children, }: HUDZoneProps): react_jsx_runtime.JSX.Element;
+interface HUDBarProps {
+    /** Current value. */
+    value: number;
+    /** Maximum value. */
+    max: number;
+    /** Optional label shown on top of the bar. */
+    label?: string;
+    /** Bar color. Default '#4fc3f7'. */
+    color?: string;
+    /** Track (empty) color. Default 'rgba(255,255,255,0.08)'. */
+    trackColor?: string;
+    /** Bar width in CSS pixels. Default 180. */
+    width?: number;
+    /** Bar height in CSS pixels. Default 14. */
+    height?: number;
+    /** Show numeric value as "value / max". Default true. */
+    showValue?: boolean;
+    /** Reverse direction: fills right→left. Default false. */
+    rtl?: boolean;
+    /** Round the bar corners. Default true. */
+    rounded?: boolean;
+    /** Smooth transition when value changes. Default true. */
+    animated?: boolean;
+    /** Additional style. */
+    style?: CSSProperties;
+}
+/**
+ * A simple value bar for HP, stamina, XP, progress, etc. Meant to be dropped
+ * inside a {@link HUDZone} without any extra styling. Animates smoothly by
+ * default; respects `prefers-reduced-motion` transparently via CSS.
+ *
+ * @example
+ * ```tsx
+ * <HUDZone position="topLeft">
+ *   <HUDBar value={hp} max={100} label="HP" color="#ef5350" />
+ *   <HUDBar value={mana} max={50} label="MP" color="#4fc3f7" />
+ * </HUDZone>
+ * ```
+ */
+declare function HUDBar({ value, max, label, color, trackColor, width, height, showValue, rtl, rounded, animated, style, }: HUDBarProps): react_jsx_runtime.JSX.Element;
+interface HUDCounterProps {
+    /** Numeric value to display. */
+    value: number;
+    /** Optional icon or emoji shown before the value. */
+    icon?: ReactNode;
+    /** Optional label shown after the value. */
+    label?: string;
+    /** Flash briefly when the value changes. Default true. */
+    pulse?: boolean;
+    /** Value color. Default '#fff'. */
+    color?: string;
+    /** Font size in CSS pixels. Default 18. */
+    fontSize?: number;
+    style?: CSSProperties;
+}
+/**
+ * A numeric counter widget for score, coins, ammo, etc.
+ *
+ * @example
+ * ```tsx
+ * <HUDZone position="topRight">
+ *   <HUDCounter icon="🪙" value={coins} />
+ * </HUDZone>
+ * ```
+ */
+declare function HUDCounter({ value, icon, label, pulse, color, fontSize, style, }: HUDCounterProps): react_jsx_runtime.JSX.Element;
+
 declare function playClip(world: ECSWorld, entityId: EntityId, clipName: string): void;
 declare function setAnimationState(world: ECSWorld, entityId: EntityId, stateName: string): void;
 declare function setAnimatorParam(world: ECSWorld, entityId: EntityId, name: string, value: AnimatorParamValue): void;
@@ -3206,4 +3384,4 @@ declare function useRemotePlayer(config: {
     opts?: RemotePlayerOptions;
 }): RemotePlayerControls;
 
-export { A11yNode, type A11yNodeProps, type AccessibilityControls, AnimatedSprite, type AnimatedSpriteProps, Animation, type AnimationSet, Animator, AssetLoader, type BoundInputMap, BoxCollider, Camera2D, type CameraControls, type CameraLookaheadOptions, CameraZone, CapsuleCollider, Checkpoint, Circle, CircleCollider, type ComboDetectorResult, CompoundCollider, ConvexCollider, type CoordinateHelpers, type CoroutineControls, type CoroutineFactory, type CoroutineYield, type DraggableControls, type DraggableOptions, type DroppableControls, type DroppableOptions, EditableText, type EditableTextProps, Entity, type ExportOptions, FocusRing, type FocusRingProps, type FocusableOptions, Game, type GameControls, type GamepadState, type GestureHandlers, type GestureOptions, Gradient, type GridCell, type GridControls, type GridOptions, type HMRControls, HalfSpaceCollider, HeightFieldCollider, type HistoryControls, type HistoryOptions, type HoverableControls, type HoverableOptions, type InputContextControls, Joint, type KeyboardFocusControls, Line, Mask, MovingPlatform, type NetworkSyncOptions, NineSlice, ParallaxLayer, ParticleEmitter, type ParticlePreset, type PauseControls, type PinchEvent, Polygon, type PreloadState, type ProfilerData, type RemotePlayerControls, type RemotePlayerOptions, RigidBody, type SceneManagerControls, type SceneSaveOptions, type SceneTransitionControls, SceneTransitionOverlay, ScreenFlash, type ScreenFlashHandle, Script, SegmentCollider, type SelectOptions, Selection, type SelectionControls, type SelectionProps, type SnapControls, type SnapOptions, type SnapResult, type SnapshotControls, Sprite, type SpriteAtlas, SquashStretch, type SquashStretchControls, Stage, type SwipeEvent, Text, type TiledLayer, type TiledObject, Tilemap, type TimerControls, type TouchControls, Trail, Transform, TransformHandles, type TransformHandlesProps, type TransitionEffect, TriMeshCollider, TriangleCollider, type TurnSystemControls, type TurnSystemOptions, VectorPath, type VectorPathProps, type VirtualInputState, VirtualJoystick, type VirtualJoystickProps, type Waypoint, World, createAtlas, defineAnimations, definePrefab, deleteSavedScene, downloadCanvas, exportToBlob, exportToDataURL, listSavedScenes, loadScene, loadSceneFromLocalStorage, playClip, saveScene, saveSceneToLocalStorage, setAnimationState, setAnimatorParam, useAccessibility, useAudioListener, useCamera, useCameraLookahead, useComboDetector, useCoordinates, useCoroutine, useDestroyEntity, useDraggable, useDroppable, useEntity, useEvent, useEvents, useFocusable, useGame, useGamepad, useGamepadHaptics, useGestures, useGrid, useHMR, useHistory, useHitstop, useHoverable, useInput, useInputBuffer, useInputContext, useInputMap, useInputRecorder, useKeyboardFocus, useLocalMultiplayer, useNetworkSync, useParent, usePause, usePlayerInput, usePostProcess, usePreload, useProfiler, useRemotePlayer, useSceneManager, useSceneTransition, useSelection, useSnap, useSnapshot, useSquashStretch, useTimer, useTouch, useTurnSystem, useVirtualInput, useWebGLPostProcess, useWorldQuery, wait, waitFrames, waitUntil };
+export { A11yNode, type A11yNodeProps, type AccessibilityControls, AnimatedSprite, type AnimatedSpriteProps, Animation, type AnimationSet, Animator, AssetLoader, type BoundInputMap, BoxCollider, Camera2D, type CameraControls, type CameraLookaheadOptions, CameraZone, CapsuleCollider, Checkpoint, Circle, CircleCollider, type ComboDetectorResult, CompoundCollider, ConvexCollider, type CoordinateHelpers, type CoroutineControls, type CoroutineFactory, type CoroutineYield, type DraggableControls, type DraggableOptions, type DroppableControls, type DroppableOptions, EditableText, type EditableTextProps, Entity, type ExportOptions, FocusRing, type FocusRingProps, type FocusableOptions, Game, type GameControls, type GamepadState, type GestureHandlers, type GestureOptions, Gradient, type GridCell, type GridControls, type GridOptions, type HMRControls, HUD, HUDBar, type HUDBarProps, HUDCounter, type HUDCounterProps, type HUDPosition, type HUDProps, HUDZone, type HUDZoneProps, HalfSpaceCollider, HeightFieldCollider, type HistoryControls, type HistoryOptions, type HoverableControls, type HoverableOptions, type InputContextControls, Joint, type KeyboardFocusControls, Line, Mask, MovingPlatform, type NetworkSyncOptions, NineSlice, PARTICLE_PRESETS, ParallaxLayer, ParticleEmitter, type ParticleEmitterConfig, type ParticlePreset, type PauseControls, type PinchEvent, Polygon, type PreloadState, type ProfilerData, type RemotePlayerControls, type RemotePlayerOptions, RigidBody, type SceneManagerControls, type SceneSaveOptions, type SceneTransitionControls, SceneTransitionOverlay, ScreenFlash, type ScreenFlashHandle, Script, SegmentCollider, type SelectOptions, Selection, type SelectionControls, type SelectionProps, type SnapControls, type SnapOptions, type SnapResult, type SnapshotControls, Sprite, type SpriteAtlas, SquashStretch, type SquashStretchControls, Stage, type SwipeEvent, Text, type TiledLayer, type TiledObject, Tilemap, type TimerControls, type TouchControls, Trail, Transform, TransformHandles, type TransformHandlesProps, type TransitionEffect, TriMeshCollider, TriangleCollider, type TurnSystemControls, type TurnSystemOptions, VectorPath, type VectorPathProps, type VirtualInputState, VirtualJoystick, type VirtualJoystickProps, type Waypoint, World, createAtlas, defineAnimations, definePrefab, deleteSavedScene, downloadCanvas, exportToBlob, exportToDataURL, listSavedScenes, loadScene, loadSceneFromLocalStorage, playClip, saveScene, saveSceneToLocalStorage, setAnimationState, setAnimatorParam, useAccessibility, useAudioListener, useCamera, useCameraLookahead, useComboDetector, useCoordinates, useCoroutine, useDestroyEntity, useDraggable, useDroppable, useEntity, useEvent, useEvents, useFocusable, useGame, useGamepad, useGamepadHaptics, useGestures, useGrid, useHMR, useHistory, useHitstop, useHoverable, useInput, useInputBuffer, useInputContext, useInputMap, useInputRecorder, useKeyboardFocus, useLocalMultiplayer, useNetworkSync, useParent, usePause, usePlayerInput, usePostProcess, usePreload, useProfiler, useRemotePlayer, useSceneManager, useSceneTransition, useSelection, useSnap, useSnapshot, useSquashStretch, useTimer, useTouch, useTurnSystem, useVirtualInput, useWebGLPostProcess, useWorldQuery, wait, waitFrames, waitUntil };

package/dist/index.js

@@ -7829,6 +7829,7 @@ import { useEffect as useEffect28, useContext as useContext19 } from "react";
 
 // src/components/particlePresets.ts
 var PARTICLE_PRESETS = {
+  // ── Action / combat ──
   explosion: {
     rate: 60,
     speed: 200,
@@ -7837,8 +7838,12 @@ var PARTICLE_PRESETS = {
     particleLife: 0.5,
     particleSize: 6,
     color: "#ff6b35",
+    colorOverLife: ["#fff3b0", "#ff6b35", "#6d4c41"],
+    sizeOverLife: { start: 1.4, end: 0 },
     gravity: 300,
-    maxParticles: 80
+    maxParticles: 80,
+    blendMode: "additive",
+    particleShape: "soft"
   },
   spark: {
     rate: 40,
@@ -7849,7 +7854,70 @@ var PARTICLE_PRESETS = {
     particleSize: 3,
     color: "#ffd54f",
     gravity: 400,
-    maxParticles: 50
+    maxParticles: 50,
+    blendMode: "additive",
+    particleShape: "soft"
+  },
+  damage: {
+    rate: 45,
+    speed: 120,
+    spread: Math.PI * 2,
+    angle: 0,
+    particleLife: 0.35,
+    particleSize: 4,
+    color: "#ef5350",
+    colorOverLife: ["#ffab91", "#ef5350", "#4a148c"],
+    sizeOverLife: { start: 1, end: 0.2 },
+    gravity: 150,
+    maxParticles: 40,
+    blendMode: "normal",
+    particleShape: "circle"
+  },
+  heal: {
+    rate: 22,
+    speed: 50,
+    spread: Math.PI / 2,
+    angle: -Math.PI / 2,
+    particleLife: 0.9,
+    particleSize: 5,
+    color: "#8bc34a",
+    colorOverLife: ["#e8f5e9", "#8bc34a"],
+    sizeOverLife: { start: 0.5, end: 1.2 },
+    gravity: -60,
+    maxParticles: 30,
+    blendMode: "additive",
+    particleShape: "soft"
+  },
+  magic: {
+    rate: 32,
+    speed: 80,
+    spread: Math.PI * 2,
+    angle: 0,
+    particleLife: 1.1,
+    particleSize: 5,
+    color: "#ba68c8",
+    colorOverLife: ["#e1bee7", "#ba68c8", "#4a148c"],
+    sizeOverLife: { start: 1, end: 0 },
+    gravity: -20,
+    maxParticles: 60,
+    blendMode: "additive",
+    particleShape: "soft"
+  },
+  // ── Environment ──
+  fire: {
+    rate: 40,
+    speed: 60,
+    spread: 0.6,
+    angle: -Math.PI / 2,
+    particleLife: 0.7,
+    particleSize: 7,
+    color: "#ff9800",
+    colorOverLife: ["#ffe082", "#ff9800", "#6d4c41", "#37474f"],
+    sizeOverLife: { start: 1.2, end: 0.3 },
+    gravity: -120,
+    maxParticles: 70,
+    blendMode: "additive",
+    particleShape: "soft"
   },
   smoke: {
     rate: 15,
@@ -7859,9 +7927,54 @@ var PARTICLE_PRESETS = {
     particleLife: 1.2,
     particleSize: 10,
     color: "#90a4ae",
+    colorOverLife: ["#90a4ae", "rgba(55,71,79,0)"],
+    sizeOverLife: { start: 0.5, end: 1.8 },
     gravity: -20,
-    maxParticles: 40
+    maxParticles: 40,
+    blendMode: "normal",
+    particleShape: "soft"
+  },
+  rain: {
+    rate: 80,
+    speed: 350,
+    spread: 0.05,
+    angle: Math.PI / 2,
+    particleLife: 0.8,
+    particleSize: 2,
+    color: "#81d4fa",
+    gravity: 900,
+    maxParticles: 300,
+    blendMode: "normal",
+    particleShape: "square"
+  },
+  snow: {
+    rate: 20,
+    speed: 40,
+    spread: 0.4,
+    angle: Math.PI / 2,
+    particleLife: 4,
+    particleSize: 3,
+    color: "#ffffff",
+    gravity: 20,
+    maxParticles: 150,
+    blendMode: "normal",
+    particleShape: "circle"
+  },
+  fountain: {
+    rate: 50,
+    speed: 300,
+    spread: 0.3,
+    angle: -Math.PI / 2,
+    particleLife: 1.5,
+    particleSize: 4,
+    color: "#4fc3f7",
+    colorOverLife: ["#b3e5fc", "#4fc3f7", "#0277bd"],
+    gravity: 500,
+    maxParticles: 200,
+    blendMode: "additive",
+    particleShape: "soft"
   },
+  // ── UI / reward ──
   coinPickup: {
     rate: 30,
     speed: 80,
@@ -7871,8 +7984,54 @@ var PARTICLE_PRESETS = {
     particleSize: 4,
     color: "#ffd700",
     gravity: 200,
-    maxParticles: 20
+    maxParticles: 20,
+    blendMode: "additive",
+    particleShape: "soft"
+  },
+  pickup: {
+    rate: 35,
+    speed: 70,
+    spread: Math.PI * 2,
+    angle: 0,
+    particleLife: 0.5,
+    particleSize: 5,
+    color: "#4fc3f7",
+    colorOverLife: ["#ffffff", "#4fc3f7"],
+    sizeOverLife: { start: 1, end: 0 },
+    gravity: -80,
+    maxParticles: 24,
+    blendMode: "additive",
+    particleShape: "soft"
+  },
+  sparkle: {
+    rate: 14,
+    speed: 40,
+    spread: Math.PI * 2,
+    angle: 0,
+    particleLife: 0.8,
+    particleSize: 3,
+    color: "#fffde7",
+    sizeOverLife: { start: 0, end: 1 },
+    gravity: 0,
+    maxParticles: 30,
+    blendMode: "additive",
+    particleShape: "soft"
   },
+  confetti: {
+    rate: 70,
+    speed: 280,
+    spread: Math.PI / 3,
+    angle: -Math.PI / 2,
+    particleLife: 2.2,
+    particleSize: 5,
+    color: "#ffc107",
+    colorOverLife: ["#f44336", "#ffc107", "#4caf50", "#2196f3", "#9c27b0"],
+    gravity: 400,
+    maxParticles: 150,
+    blendMode: "normal",
+    particleShape: "square"
+  },
+  // ── Character ──
   jumpDust: {
     rate: 25,
     speed: 60,
@@ -7882,7 +8041,23 @@ var PARTICLE_PRESETS = {
     particleSize: 5,
     color: "#b0bec5",
     gravity: 80,
-    maxParticles: 20
+    maxParticles: 20,
+    blendMode: "normal",
+    particleShape: "soft"
+  },
+  trail: {
+    rate: 30,
+    speed: 8,
+    spread: 0.2,
+    angle: Math.PI / 2,
+    particleLife: 0.5,
+    particleSize: 4,
+    color: "#4fc3f7",
+    sizeOverLife: { start: 1, end: 0 },
+    gravity: 0,
+    maxParticles: 40,
+    blendMode: "additive",
+    particleShape: "soft"
   }
 };
 
@@ -7928,6 +8103,10 @@ function ParticleEmitter({
   const resolvedColor = color ?? presetConfig.color ?? "#ffffff";
   const resolvedGravity = gravity ?? presetConfig.gravity ?? 200;
   const resolvedMaxParticles = maxParticles ?? presetConfig.maxParticles ?? 100;
+  const resolvedBlendMode = blendMode ?? presetConfig.blendMode;
+  const resolvedParticleShape = particleShape ?? presetConfig.particleShape;
+  const resolvedColorOverLife = colorOverLife ?? presetConfig.colorOverLife;
+  const resolvedSizeOverLife = sizeOverLife ?? presetConfig.sizeOverLife;
   const engine = useContext19(EngineContext);
   const entityId = useContext19(EntityContext);
   useEffect28(() => {
@@ -7953,15 +8132,15 @@ function ParticleEmitter({
       textureSrc,
       enableRotation,
       rotationSpeedRange,
-      sizeOverLife,
+      sizeOverLife: resolvedSizeOverLife,
       attractors,
-      colorOverLife,
-      blendMode,
+      colorOverLife: resolvedColorOverLife,
+      blendMode: resolvedBlendMode,
       mode,
       formationPoints,
       seekStrength,
       colorTransitionDuration,
-      particleShape
+      particleShape: resolvedParticleShape
     });
     return () => engine.ecs.removeComponent(entityId, "ParticlePool");
   }, []);
@@ -7973,9 +8152,9 @@ function ParticleEmitter({
   useEffect28(() => {
     const pool = engine.ecs.getComponent(entityId, "ParticlePool");
     if (!pool) return;
-    pool.blendMode = blendMode;
-    pool.particleShape = particleShape;
-  }, [blendMode, particleShape, engine, entityId]);
+    pool.blendMode = resolvedBlendMode;
+    pool.particleShape = resolvedParticleShape;
+  }, [resolvedBlendMode, resolvedParticleShape, engine, entityId]);
   useEffect28(() => {
     const pool = engine.ecs.getComponent(entityId, "ParticlePool");
     if (!pool) return;
@@ -13358,6 +13537,164 @@ function createAtlas(names, _columns) {
   return atlas;
 }
 
+// src/components/HUD.tsx
+import { createContext as createContext3, useContext as useContext78, useMemo as useMemo19 } from "react";
+import { jsx as jsx22, jsxs as jsxs11 } from "react/jsx-runtime";
+var HUDContextRef = createContext3(null);
+function HUD({
+  dimDuringTransitions = true,
+  dimmedOpacity = 0.25,
+  visible = true,
+  safeArea = true,
+  padding = 12,
+  style,
+  className,
+  children
+}) {
+  const ctx = useMemo19(() => ({ padding, safeArea }), [padding, safeArea]);
+  const rootStyle = {
+    position: "absolute",
+    inset: 0,
+    pointerEvents: "none",
+    zIndex: 100,
+    opacity: visible ? 1 : 0,
+    transition: "opacity 180ms ease-out",
+    userSelect: "none",
+    ...style
+  };
+  void dimDuringTransitions;
+  void dimmedOpacity;
+  return /* @__PURE__ */ jsx22(HUDContextRef.Provider, { value: ctx, children: /* @__PURE__ */ jsx22("div", { className, style: rootStyle, "data-cubeforge-hud": "true", children }) });
+}
+function useHUD() {
+  return useContext78(HUDContextRef) ?? { padding: 12, safeArea: false };
+}
+function HUDZone({
+  position = "topLeft",
+  direction,
+  gap = 8,
+  interactive = true,
+  style,
+  className,
+  children
+}) {
+  const { padding, safeArea } = useHUD();
+  const isTop = position.startsWith("top");
+  const isBottom = position.startsWith("bottom");
+  const isCenter = position.startsWith("center");
+  const isLeft = position.endsWith("Left") || position === "centerLeft";
+  const isRight = position.endsWith("Right") || position === "centerRight";
+  const isHCenter = position.endsWith("Center") || position === "center";
+  const flexDirection = direction ?? (isTop || isBottom ? "row" : "column");
+  const sa = (side) => safeArea ? `max(${padding}px, env(safe-area-inset-${side}))` : `${padding}px`;
+  const zoneStyle = {
+    position: "absolute",
+    display: "flex",
+    flexDirection,
+    gap,
+    pointerEvents: interactive ? "auto" : "none",
+    ...isTop && { top: sa("top") },
+    ...isBottom && { bottom: sa("bottom") },
+    ...isLeft && { left: sa("left") },
+    ...isRight && { right: sa("right") },
+    ...isCenter && !isHCenter && { top: "50%", transform: "translateY(-50%)" },
+    ...isHCenter && !isCenter && { left: "50%", transform: "translateX(-50%)" },
+    ...position === "center" && { top: "50%", left: "50%", transform: "translate(-50%, -50%)" },
+    ...isHCenter && !isCenter && isTop && { top: sa("top") },
+    ...isHCenter && !isCenter && isBottom && { bottom: sa("bottom") },
+    alignItems: isHCenter ? "center" : isRight ? "flex-end" : "flex-start",
+    ...style
+  };
+  return /* @__PURE__ */ jsx22("div", { className, style: zoneStyle, children });
+}
+function HUDBar({
+  value,
+  max,
+  label,
+  color = "#4fc3f7",
+  trackColor = "rgba(255,255,255,0.08)",
+  width = 180,
+  height = 14,
+  showValue = true,
+  rtl = false,
+  rounded = true,
+  animated = true,
+  style
+}) {
+  const pct = max > 0 ? Math.max(0, Math.min(1, value / max)) : 0;
+  const fillStyle = {
+    width: `${pct * 100}%`,
+    height: "100%",
+    background: color,
+    borderRadius: rounded ? height / 2 : 0,
+    transition: animated ? "width 160ms ease-out" : void 0,
+    ...rtl && { marginLeft: "auto" }
+  };
+  const trackStyle = {
+    width,
+    height,
+    background: trackColor,
+    borderRadius: rounded ? height / 2 : 0,
+    overflow: "hidden",
+    position: "relative",
+    display: "flex",
+    flexDirection: rtl ? "row-reverse" : "row"
+  };
+  const labelStyle = {
+    fontFamily: "system-ui, sans-serif",
+    fontSize: 11,
+    letterSpacing: 0.5,
+    textTransform: "uppercase",
+    color: "#e0e7f1",
+    opacity: 0.85,
+    display: "flex",
+    justifyContent: "space-between",
+    marginBottom: 4
+  };
+  return /* @__PURE__ */ jsxs11("div", { style: { display: "flex", flexDirection: "column", ...style }, "aria-label": label, children: [
+    (label || showValue) && /* @__PURE__ */ jsxs11("div", { style: labelStyle, children: [
+      label && /* @__PURE__ */ jsx22("span", { children: label }),
+      showValue && /* @__PURE__ */ jsxs11("span", { style: { fontVariantNumeric: "tabular-nums" }, children: [
+        Math.round(value),
+        " / ",
+        max
+      ] })
+    ] }),
+    /* @__PURE__ */ jsx22("div", { style: trackStyle, role: "progressbar", "aria-valuenow": value, "aria-valuemin": 0, "aria-valuemax": max, children: /* @__PURE__ */ jsx22("div", { style: fillStyle }) })
+  ] });
+}
+function HUDCounter({
+  value,
+  icon,
+  label,
+  pulse = true,
+  color = "#fff",
+  fontSize = 18,
+  style
+}) {
+  void pulse;
+  return /* @__PURE__ */ jsxs11(
+    "div",
+    {
+      style: {
+        display: "flex",
+        alignItems: "center",
+        gap: 6,
+        fontFamily: "system-ui, sans-serif",
+        fontSize,
+        color,
+        fontVariantNumeric: "tabular-nums",
+        ...style
+      },
+      children: [
+        icon && /* @__PURE__ */ jsx22("span", { style: { fontSize: fontSize * 1.1 }, children: icon }),
+        /* @__PURE__ */ jsx22("span", { children: value }),
+        label && /* @__PURE__ */ jsx22("span", { style: { opacity: 0.7, fontSize: fontSize * 0.75 }, children: label })
+      ]
+    }
+  );
+}
+
 // src/utils/animationHelpers.ts
 function playClip(world, entityId, clipName) {
   const anim = world.getComponent(entityId, "AnimationState");
@@ -14056,6 +14393,10 @@ export {
   FocusRing,
   Game,
   Gradient,
+  HUD,
+  HUDBar,
+  HUDCounter,
+  HUDZone,
   HalfSpaceCollider,
   HeightFieldCollider,
   HierarchySystem,
@@ -14066,6 +14407,7 @@ export {
   Mask,
   MovingPlatform,
   NineSlice,
+  PARTICLE_PRESETS,
   ParallaxLayer,
   ParticleEmitter,
   Polygon,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cubeforge",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "React-first 2D browser game engine",
   "type": "module",
   "main": "./dist/index.js",