cubeforge 0.3.13 → 0.3.15

package/README.md

@@ -32,8 +32,8 @@ npm install cubeforge react react-dom
 ## What's included
 
 - **ECS** — archetype-based entity-component-system with query caching
-- **Physics** — two-pass AABB, capsule colliders, kinematic bodies, one-way platforms, 60 Hz fixed timestep
-- **Renderer** — WebGL2 instanced renderer by default; Canvas2D opt-in via `renderer={Canvas2DRenderSystem}`
+- **Physics** — two-pass AABB, kinematic bodies, one-way platforms, 60 Hz fixed timestep
+- **Renderer** — WebGL2 instanced renderer by default
 - **Input** — keyboard, mouse, gamepad, per-player input maps, input contexts, recording/playback
 - **Audio** — Web Audio API with volume groups, fade, crossfade, ducking (`useSound`)
 - **Gameplay hooks** — `usePlatformerController`, `useTopDownMovement`, `useHealth`, `useSave`, `useGameStateMachine`, `useLevelTransition`, `usePathfinding`, `useAISteering`, and more

package/dist/index.d.ts

@@ -1,17 +1,18 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
-import React__default, { CSSProperties, ReactNode } from 'react';
+import React__default, { CSSProperties, ReactNode, ReactElement } from 'react';
 import { Plugin, EntityId, ECSWorld, ScriptUpdateFn, NavGrid, WorldSnapshot, EventBus } from '@cubeforge/core';
-export { AssetProgress, Component, ECSWorld, Ease, EntityId, GameTimer, HotReloadablePlugin, NavGrid, Plugin, PreloadManifest, ScriptUpdateFn, TransformComponent, TweenHandle, Vec2Like, WorldSnapshot, arrive, createTag, createTimer, createTransform, definePlugin, findByTag, flee, hotReloadPlugin, patrol, preloadManifest, seek, tween, wander } from '@cubeforge/core';
-import { Sampling } from '@cubeforge/renderer';
-export { AnimationStateComponent, MagFilterValue, NineSliceComponent, ParallaxLayerComponent, Particle, ParticlePoolComponent, RenderSystem, Sampling, SpriteComponent, SquashStretchComponent, TextComponent, TextureFilter, TextureFilterValue, TrailComponent, createNineSlice, createSprite } from '@cubeforge/renderer';
+export { AssetProgress, Component, ECSWorld, Ease, EntityId, GameTimer, HotReloadablePlugin, MergedRect, NavGrid, Plugin, PreloadManifest, ScriptUpdateFn, TimelineEntry, TransformComponent, TweenHandle, TweenTimeline, Vec2Like, WorldSnapshot, arrive, createTag, createTimeline, createTimer, createTransform, definePlugin, findByTag, flee, hotReloadPlugin, mergeTileColliders, patrol, preloadManifest, seek, tween, wander } from '@cubeforge/core';
+import { Sampling, BlendMode, PostProcessEffect } from '@cubeforge/renderer';
+export { AnimationStateComponent, BlendMode, MagFilterValue, NineSliceComponent, ParallaxLayerComponent, Particle, ParticlePoolComponent, PostProcessEffect, PostProcessStack, RenderLayer, RenderLayerManager, RenderSystem, Sampling, SpriteComponent, SquashStretchComponent, TextComponent, TextureFilter, TextureFilterValue, TrailComponent, chromaticAberrationEffect, createNineSlice, createPostProcessStack, createRenderLayerManager, createSprite, defaultLayers, scanlineEffect, vignetteEffect } from '@cubeforge/renderer';
 import { ColliderShape } from '@cubeforge/physics';
 export { BoxColliderComponent, CapsuleColliderComponent, CircleColliderComponent, ColliderShape, CompoundColliderComponent, RaycastHit, RigidBodyComponent, createCompoundCollider, overlapBox, overlapCircle, raycast, raycastAll, sweepBox } from '@cubeforge/physics';
 import { InputManager, ActionBindings, InputContextName, PlayerInput, InputRecorderControls } from '@cubeforge/input';
 export { ActionBindings, AxisBinding, InputContextName, InputManager, InputMap, InputRecorderControls, InputRecording, InputRecording as InputRecordingData, PlayerInput, createInputMap, createInputRecorder, createPlayerInput, globalInputContext } from '@cubeforge/input';
+import { AnimationClip } from '@cubeforge/gameplay';
+export { AISteering, AnimationClip, AnimationControllerResult, BindingControls, CutsceneControls, CutsceneStep, DialogueControls, DialogueLine, DialogueScript, GameState as GameStateDefinition, GameStateMachineResult, HealthControls, HealthOptions, KinematicBodyControls, LevelTransitionControls, ObjectPool, PathfindingControls, PlatformerControllerOptions, RestartControls, SaveControls, SaveOptions, TopDownMovementOptions, TransitionOptions, TransitionType, TweenControls, useAISteering, useAnimationController, useCutscene, useDamageZone, useDialogue, useDropThrough, useGameStateMachine, useGameStore, useHealth, useKinematicBody, useLevelTransition, useObjectPool, usePathfinding, usePersistedBindings, usePlatformerController, useRestart, useSave, useTopDownMovement, useTween } from '@cubeforge/gameplay';
 import { EngineState } from '@cubeforge/context';
-export { EngineState, useCircleEnter, useCircleExit, useCircleStay, useCollisionEnter, useCollisionExit, useCollisionStay, useTriggerEnter, useTriggerExit, useTriggerStay } from '@cubeforge/context';
-export { AISteering, AnimationClip, AnimationControllerResult, BindingControls, CutsceneControls, CutsceneStep, DialogueControls, DialogueLine, DialogueScript, GameState as GameStateDefinition, GameStateMachineResult, HealthControls, HealthOptions, KinematicBodyControls, LevelTransitionControls, PathfindingControls, PlatformerControllerOptions, RestartControls, SaveControls, SaveOptions, TopDownMovementOptions, TransitionOptions, TransitionType, useAISteering, useAnimationController, useCutscene, useDamageZone, useDialogue, useDropThrough, useGameStateMachine, useGameStore, useHealth, useKinematicBody, useLevelTransition, usePathfinding, usePersistedBindings, usePlatformerController, useRestart, useSave, useTopDownMovement } from '@cubeforge/gameplay';
+export { EngineState, useCircleEnter, useCircleExit, useCircleStay, useCollidingWith, useCollisionEnter, useCollisionExit, useCollisionStay, useTriggerEnter, useTriggerExit, useTriggerStay } from '@cubeforge/context';
 export { AudioGroup, SoundControls, duck, getGroupVolume, setGroupMute, setGroupVolume, setMasterVolume, stopGroup, useSound } from '@cubeforge/audio';
 export { DevToolsHandle } from '@cubeforge/devtools';
 
@@ -109,6 +110,7 @@ interface SpriteProps {
     zIndex?: number;
     visible?: boolean;
     flipX?: boolean;
+    flipY?: boolean;
     anchorX?: number;
     anchorY?: number;
     frameIndex?: number;
@@ -123,8 +125,12 @@ interface SpriteProps {
     tileSizeY?: number;
     /** Texture sampling mode — controls filtering when the sprite is scaled */
     sampling?: Sampling;
+    /** Blend mode used when drawing this sprite */
+    blendMode?: BlendMode;
+    /** Render layer name — sprites are sorted by layer order first, then zIndex */
+    layer?: string;
 }
-declare function Sprite({ width, height, color, src, offsetX, offsetY, zIndex, visible, flipX, anchorX, anchorY, frameIndex, frameWidth, frameHeight, frameColumns, atlas, frame, tileX, tileY, tileSizeX, tileSizeY, sampling, }: SpriteProps): null;
+declare function Sprite({ width, height, color, src, offsetX, offsetY, zIndex, visible, flipX, flipY, anchorX, anchorY, frameIndex, frameWidth, frameHeight, frameColumns, atlas, frame, tileX, tileY, tileSizeX, tileSizeY, sampling, blendMode, layer, }: SpriteProps): null;
 
 interface TextProps {
     text: string;
@@ -153,8 +159,16 @@ interface RigidBodyProps {
     lockX?: boolean;
     /** Prevent any vertical movement — velocity.y is zeroed every frame (disables gravity) */
     lockY?: boolean;
+    /** Enable continuous collision detection to prevent tunneling through thin colliders */
+    ccd?: boolean;
+    /** Angular velocity in radians per second */
+    angularVelocity?: number;
+    /** Angular damping (0–1): fraction of angular velocity removed each fixed step */
+    angularDamping?: number;
+    /** Linear damping (0–1): velocity reduction applied every fixed step (air resistance) */
+    linearDamping?: number;
 }
-declare function RigidBody({ mass, gravityScale, isStatic, bounce, friction, vx, vy, lockX, lockY, }: RigidBodyProps): null;
+declare function RigidBody({ mass, gravityScale, isStatic, bounce, friction, vx, vy, lockX, lockY, ccd, angularVelocity, angularDamping, linearDamping, }: RigidBodyProps): null;
 
 interface BoxColliderProps {
     width: number;
@@ -261,6 +275,107 @@ interface AnimationProps {
 }
 declare function Animation({ frames, fps, loop, playing, onComplete, frameEvents }: AnimationProps): null;
 
+/** Shared sprite props used by both API forms */
+interface SpriteOptions {
+    width: number;
+    height: number;
+    src: string;
+    color?: string;
+    offsetX?: number;
+    offsetY?: number;
+    zIndex?: number;
+    visible?: boolean;
+    flipX?: boolean;
+    flipY?: boolean;
+    anchorX?: number;
+    anchorY?: number;
+    frameWidth?: number;
+    frameHeight?: number;
+    frameColumns?: number;
+    atlas?: SpriteAtlas;
+    frame?: string;
+    tileX?: boolean;
+    tileY?: boolean;
+    tileSizeX?: number;
+    tileSizeY?: number;
+    sampling?: Sampling;
+    blendMode?: BlendMode;
+}
+/** Simple form — single animation clip (like Sprite + Animation) */
+interface SimpleAnimatedSpriteProps extends SpriteOptions {
+    frames: number[];
+    fps?: number;
+    loop?: boolean;
+    playing?: boolean;
+    onComplete?: () => void;
+    frameEvents?: Record<number, () => void>;
+    animations?: never;
+    current?: never;
+}
+/** Multi-clip form — named animation states with typed clip names */
+interface MultiAnimatedSpriteProps<S extends string = string> extends SpriteOptions {
+    /** Map of named animation clips (use `defineAnimations()` for type-safe names) */
+    animations: AnimationSet<S>;
+    /** Which animation clip is currently playing — typed to the clip names */
+    current: S;
+    frames?: never;
+    fps?: never;
+    loop?: never;
+    playing?: never;
+    onComplete?: never;
+    frameEvents?: never;
+}
+type AnimatedSpriteProps<S extends string = string> = SimpleAnimatedSpriteProps | MultiAnimatedSpriteProps<S>;
+/** A typed set of animation clips. Created by `defineAnimations()`. */
+type AnimationSet<S extends string = string> = Record<S, AnimationClip>;
+/**
+ * Define a reusable, type-safe set of animation clips.
+ *
+ * The returned object can be shared across components and provides
+ * autocomplete on `current` when used with `<AnimatedSprite>`.
+ *
+ * @example
+ * ```tsx
+ * const playerAnims = defineAnimations({
+ *   idle:   { frames: [0],          fps: 1  },
+ *   walk:   { frames: [1, 2, 3, 4], fps: 10 },
+ *   run:    { frames: [5, 6, 7, 8], fps: 14 },
+ *   jump:   { frames: [9],          fps: 1, loop: false },
+ *   attack: { frames: [10, 11, 12], fps: 16, loop: false, next: 'idle' },
+ * })
+ *
+ * // `current` is typed as 'idle' | 'walk' | 'run' | 'jump' | 'attack'
+ * <AnimatedSprite animations={playerAnims} current={state} ... />
+ * ```
+ */
+declare function defineAnimations<S extends string>(clips: Record<S, AnimationClip>): AnimationSet<S>;
+/**
+ * Convenience wrapper that combines `<Sprite>` and `<Animation>` into a
+ * single component. Must be placed inside an `<Entity>`.
+ *
+ * Supports two API forms:
+ *
+ * **Simple** — single clip:
+ * ```tsx
+ * <AnimatedSprite src="/hero.png" width={32} height={32}
+ *   frameWidth={32} frameHeight={32} frameColumns={8}
+ *   frames={[0, 1, 2, 3]} fps={10} />
+ * ```
+ *
+ * **Multi-clip** — named animation states, switch via `current`:
+ * ```tsx
+ * const anims = defineAnimations({
+ *   idle: { frames: [0], fps: 1 },
+ *   walk: { frames: [1, 2, 3, 4], fps: 10 },
+ * })
+ *
+ * <AnimatedSprite src="/hero.png" width={32} height={48}
+ *   frameWidth={32} frameHeight={48} frameColumns={8}
+ *   animations={anims} current={state} />
+ * ```
+ */
+declare function AnimatedSprite<S extends string>(props: AnimatedSpriteProps<S>): ReactElement;
+
 interface SquashStretchProps {
     /** How much to squash/stretch (default 0.2) */
     intensity?: number;
@@ -293,8 +408,18 @@ interface ParticleEmitterProps {
     gravity?: number;
     /** Maximum live particles, default 100 */
     maxParticles?: number;
+    /** Emit this many particles in one frame then deactivate (one-shot burst) */
+    burstCount?: number;
+    /** Emission shape: 'point' (default), 'circle', or 'box' */
+    emitShape?: 'point' | 'circle' | 'box';
+    /** Radius for 'circle' emission shape */
+    emitRadius?: number;
+    /** Width for 'box' emission shape */
+    emitWidth?: number;
+    /** Height for 'box' emission shape */
+    emitHeight?: number;
 }
-declare function ParticleEmitter({ active, preset, rate, speed, spread, angle, particleLife, particleSize, color, gravity, maxParticles, }: ParticleEmitterProps): null;
+declare function ParticleEmitter({ active, preset, rate, speed, spread, angle, particleLife, particleSize, color, gravity, maxParticles, burstCount, emitShape, emitRadius, emitWidth, emitHeight, }: ParticleEmitterProps): null;
 
 interface VirtualJoystickProps {
     /** Diameter of the joystick base in pixels (default 120) */
@@ -435,8 +560,15 @@ interface TilemapProps {
      * can filter them by `layer.name === spawnLayer` inside the callback.
      */
     spawnLayer?: string;
+    /**
+     * When true (default), adjacent solid tiles in collision/trigger layers
+     * are merged into larger rectangles using a 2D greedy algorithm, reducing
+     * the number of collider entities. Set to false to create one collider per
+     * row-run (legacy behaviour).
+     */
+    mergeColliders?: boolean;
 }
-declare function Tilemap({ src, onSpawnObject, layerFilter, zIndex, collisionLayer, triggerLayer: triggerLayerName, onTileProperty, navGrid, }: TilemapProps): React__default.ReactElement | null;
+declare function Tilemap({ src, onSpawnObject, layerFilter, zIndex, collisionLayer, triggerLayer: triggerLayerName, onTileProperty, navGrid, mergeColliders, }: TilemapProps): React__default.ReactElement | null;
 
 interface ParallaxLayerProps {
     /** Image URL to use as the background layer */
@@ -960,4 +1092,59 @@ interface PauseControls {
  */
 declare function usePause(): PauseControls;
 
-export { Animation, AssetLoader, type BoundInputMap, BoxCollider, Camera2D, type CameraControls, CameraZone, CapsuleCollider, Checkpoint, CircleCollider, CompoundCollider, type CoordinateHelpers, Entity, Game, type GameControls, type GamepadState, type InputContextControls, MovingPlatform, NineSlice, ParallaxLayer, ParticleEmitter, type ParticlePreset, type PauseControls, type PreloadState, RigidBody, ScreenFlash, type ScreenFlashHandle, Script, type SnapshotControls, Sprite, type SpriteAtlas, SquashStretch, Text, type TiledLayer, type TiledObject, Tilemap, Trail, Transform, type VirtualInputState, VirtualJoystick, type VirtualJoystickProps, World, createAtlas, useCamera, useCoordinates, useDestroyEntity, useEntity, useEvent, useEvents, useGame, useGamepad, useInput, useInputContext, useInputMap, useInputRecorder, useLocalMultiplayer, usePause, usePlayerInput, usePreload, useSnapshot, useVirtualInput };
+interface ProfilerData {
+    fps: number;
+    frameTime: number;
+    entityCount: number;
+    systemTimings: Map<string, number>;
+}
+/**
+ * Returns live performance data from the engine: FPS, frame time, entity count,
+ * and per-system timings. Updates at most every 500 ms to avoid excessive re-renders.
+ *
+ * Must be used inside a `<Game>` component.
+ */
+declare function useProfiler(): ProfilerData;
+
+/**
+ * Registers a post-processing effect for the lifetime of the component.
+ * The effect runs in screen space after all scene rendering is complete.
+ *
+ * @example
+ * ```tsx
+ * import { vignetteEffect } from 'cubeforge'
+ *
+ * function Atmosphere() {
+ *   usePostProcess(vignetteEffect(0.5))
+ *   return null
+ * }
+ * ```
+ */
+declare function usePostProcess(effect: PostProcessEffect): void;
+
+/**
+ * Define a reusable entity prefab with default props.
+ *
+ * Returns a memoized React component that merges caller-supplied props
+ * over the provided defaults, so every prop becomes optional at the call site.
+ *
+ * @example
+ * ```tsx
+ * const Crate = definePrefab('Crate', {
+ *   width: 32, height: 32, color: '#8B4513', mass: 1,
+ * }, (props) => (
+ *   <Entity tags={['crate']}>
+ *     <Transform x={0} y={0} />
+ *     <Sprite width={props.width} height={props.height} color={props.color} />
+ *     <RigidBody mass={props.mass} />
+ *     <BoxCollider width={props.width} height={props.height} />
+ *   </Entity>
+ * ))
+ *
+ * // Usage — all defaults applied, override only what you need:
+ * <Crate width={64} />
+ * ```
+ */
+declare function definePrefab<D extends Record<string, unknown>>(name: string, defaults: D, render: (props: D) => ReactElement): React__default.FC<Partial<D>>;
+
+export { AnimatedSprite, type AnimatedSpriteProps, Animation, type AnimationSet, AssetLoader, type BoundInputMap, BoxCollider, Camera2D, type CameraControls, CameraZone, CapsuleCollider, Checkpoint, CircleCollider, CompoundCollider, type CoordinateHelpers, Entity, Game, type GameControls, type GamepadState, type InputContextControls, MovingPlatform, NineSlice, ParallaxLayer, ParticleEmitter, type ParticlePreset, type PauseControls, type PreloadState, type ProfilerData, RigidBody, ScreenFlash, type ScreenFlashHandle, Script, type SnapshotControls, Sprite, type SpriteAtlas, SquashStretch, Text, type TiledLayer, type TiledObject, Tilemap, Trail, Transform, type VirtualInputState, VirtualJoystick, type VirtualJoystickProps, World, createAtlas, defineAnimations, definePrefab, useCamera, useCoordinates, useDestroyEntity, useEntity, useEvent, useEvents, useGame, useGamepad, useInput, useInputContext, useInputMap, useInputRecorder, useLocalMultiplayer, usePause, usePlayerInput, usePostProcess, usePreload, useProfiler, useSnapshot, useVirtualInput };