cubeforge 0.1.5 → 0.1.7

package/dist/index.d.mts

@@ -6,7 +6,7 @@ export { Component, ECSWorld, Ease, EntityId, Plugin, ScriptUpdateFn, TransformC
 import { InputManager, ActionBindings } from '@cubeforge/input';
 export { ActionBindings, InputManager, InputMap, createInputMap } from '@cubeforge/input';
 import { Canvas2DRenderer, RenderSystem } from '@cubeforge/renderer';
-export { AnimationStateComponent, ParallaxLayerComponent, Particle, ParticlePoolComponent, SpriteComponent, SquashStretchComponent, createSprite } from '@cubeforge/renderer';
+export { AnimationStateComponent, ParallaxLayerComponent, Particle, ParticlePoolComponent, SpriteComponent, SquashStretchComponent, TextComponent, createSprite } from '@cubeforge/renderer';
 import { PhysicsSystem } from '@cubeforge/physics';
 export { BoxColliderComponent, CircleColliderComponent, RaycastHit, RigidBodyComponent, overlapBox, raycast } from '@cubeforge/physics';
 
@@ -114,8 +114,25 @@ interface SpriteProps {
     frameColumns?: number;
     atlas?: SpriteAtlas;
     frame?: string;
+    tileX?: boolean;
+    tileY?: boolean;
 }
-declare function Sprite({ width, height, color, src, offsetX, offsetY, zIndex, visible, flipX, anchorX, anchorY, frameIndex, frameWidth, frameHeight, frameColumns, atlas, frame, }: SpriteProps): null;
+declare function Sprite({ width, height, color, src, offsetX, offsetY, zIndex, visible, flipX, anchorX, anchorY, frameIndex, frameWidth, frameHeight, frameColumns, atlas, frame, tileX, tileY, }: SpriteProps): null;
+
+interface TextProps {
+    text: string;
+    fontSize?: number;
+    fontFamily?: string;
+    color?: string;
+    align?: CanvasTextAlign;
+    baseline?: CanvasTextBaseline;
+    zIndex?: number;
+    visible?: boolean;
+    maxWidth?: number;
+    offsetX?: number;
+    offsetY?: number;
+}
+declare function Text({ text, fontSize, fontFamily, color, align, baseline, zIndex, visible, maxWidth, offsetX, offsetY, }: TextProps): null;
 
 interface RigidBodyProps {
     mass?: number;
@@ -512,9 +529,28 @@ interface PlatformerControllerOptions {
     coyoteTime?: number;
     /** Seconds to buffer a jump input before landing (default 0.08) */
     jumpBuffer?: number;
+    /**
+     * Minimum seconds between jumps — prevents multi-jump spam when holding the
+     * jump key with double-jump enabled (default 0.18)
+     */
+    jumpCooldown?: number;
+    /**
+     * Override the default key bindings. Each action accepts a single key code
+     * or an array of key codes.
+     *
+     * Defaults:
+     *   left:  ['ArrowLeft', 'KeyA', 'a']
+     *   right: ['ArrowRight', 'KeyD', 'd']
+     *   jump:  ['Space', 'ArrowUp', 'KeyW', 'w']
+     */
+    bindings?: {
+        left?: string | string[];
+        right?: string | string[];
+        jump?: string | string[];
+    };
 }
 /**
- * Attaches platformer movement (WASD/Arrows + Space/Up to jump) to an entity.
+ * Attaches platformer movement (customisable keys + Space/Up to jump) to an entity.
  * The entity must already have a RigidBody component.
  *
  * @example
@@ -555,6 +591,116 @@ interface TopDownMovementOptions {
  */
 declare function useTopDownMovement(entityId: EntityId, opts?: TopDownMovementOptions): void;
 
+interface SoundControls {
+    /** Start playing. If already playing and loop=false, restarts from the beginning. */
+    play(): void;
+    /** Stop the current playback. */
+    stop(): void;
+    /** Change the volume (0–1). */
+    setVolume(v: number): void;
+}
+/**
+ * Loads and plays an audio file via the Web Audio API.
+ *
+ * The AudioContext is created lazily — the first call to `play()` resumes it
+ * if the browser suspended it before a user gesture.
+ *
+ * @example
+ * function JumpSfx() {
+ *   const { play } = useSound('/jump.wav')
+ *   // call play() on jump event
+ * }
+ */
+declare function useSound(src: string, opts?: {
+    volume?: number;
+    loop?: boolean;
+}): SoundControls;
+
+/**
+ * A lightweight game-loop timer for use inside Script update functions.
+ *
+ * @example
+ * // Create once outside the update function (e.g. in playerInit):
+ * const invincibleTimer = createTimer(2.0, () => { state.isInvincible = false })
+ *
+ * // Call update(dt) inside the Script update function each frame:
+ * function playerUpdate(id, world, input, dt) {
+ *   invincibleTimer.update(dt)
+ *   if (someHitCondition) {
+ *     state.isInvincible = true
+ *     invincibleTimer.restart()
+ *   }
+ * }
+ */
+interface GameTimer {
+    /** Advance the timer by dt seconds. Calls onComplete when it reaches zero. */
+    update(dt: number): void;
+    /** Start (or resume) counting down. */
+    start(): void;
+    /** Pause counting without resetting. */
+    stop(): void;
+    /** Reset elapsed time to 0 and stop. Optionally change the duration. */
+    reset(newDuration?: number): void;
+    /** Reset elapsed time to 0 and immediately start. */
+    restart(): void;
+    /** Whether the timer is currently counting. */
+    readonly running: boolean;
+    /** Elapsed seconds since last reset/restart. */
+    readonly elapsed: number;
+    /** Remaining seconds (clamped to 0). */
+    readonly remaining: number;
+    /** Progress from 0 (just started) to 1 (complete). */
+    readonly progress: number;
+}
+declare function createTimer(duration: number, onComplete?: () => void, autoStart?: boolean): GameTimer;
+
+interface GamepadState {
+    /** Whether a gamepad is connected at this player index. */
+    connected: boolean;
+    /**
+     * Normalised axis values (typically −1 to +1).
+     * Index 0 = left stick X, 1 = left stick Y, 2 = right stick X, 3 = right stick Y
+     * (varies by browser / controller).
+     */
+    axes: readonly number[];
+    /**
+     * Button pressed states.
+     * Standard mapping: 0=A/Cross, 1=B/Circle, 2=X/Square, 3=Y/Triangle,
+     * 4=LB, 5=RB, 12=DPad-Up, 13=DPad-Down, 14=DPad-Left, 15=DPad-Right
+     */
+    buttons: readonly boolean[];
+}
+/**
+ * Polls the Gamepad API every frame and returns the current state.
+ *
+ * @param playerIndex - Which gamepad slot to read (0–3). Default 0.
+ *
+ * @example
+ * function MoveWithGamepad() {
+ *   const gp = useGamepad()
+ *   // gp.axes[0] = left stick horizontal
+ *   // gp.buttons[0] = A button
+ * }
+ */
+declare function useGamepad(playerIndex?: number): GamepadState;
+
+interface PauseControls {
+    paused: boolean;
+    pause(): void;
+    resume(): void;
+    toggle(): void;
+}
+/**
+ * Controls the game loop pause state from inside a `<Game>` tree.
+ *
+ * @example
+ * function PauseButton() {
+ *   const { paused, toggle } = usePause()
+ *   return <button onClick={toggle}>{paused ? 'Resume' : 'Pause'}</button>
+ * }
+ */
+declare function usePause(): PauseControls;
+
 interface ContactOpts {
     /** Only fire if the other entity has this tag */
     tag?: string;
@@ -616,4 +762,4 @@ interface DevToolsHandle {
     onFrame?: () => void;
 }
 
-export { Animation, type BoundInputMap, BoxCollider, Camera2D, type CameraControls, Checkpoint, CircleCollider, type DevToolsHandle, type EngineState, Entity, Game, type GameControls, MovingPlatform, ParallaxLayer, ParticleEmitter, type ParticlePreset, type PlatformerControllerOptions, RigidBody, ScreenFlash, type ScreenFlashHandle, Script, type SnapshotControls, Sprite, type SpriteAtlas, SquashStretch, type TiledLayer, type TiledObject, Tilemap, type TopDownMovementOptions, Transform, World, createAtlas, useCamera, useCircleEnter, useCircleExit, useCollisionEnter, useCollisionExit, useEntity, useEvent, useEvents, useGame, useInput, useInputMap, usePlatformerController, useSnapshot, useTopDownMovement, useTriggerEnter, useTriggerExit };
+export { Animation, type BoundInputMap, BoxCollider, Camera2D, type CameraControls, Checkpoint, CircleCollider, type DevToolsHandle, type EngineState, Entity, Game, type GameControls, type GameTimer, type GamepadState, MovingPlatform, ParallaxLayer, ParticleEmitter, type ParticlePreset, type PauseControls, type PlatformerControllerOptions, RigidBody, ScreenFlash, type ScreenFlashHandle, Script, type SnapshotControls, type SoundControls, Sprite, type SpriteAtlas, SquashStretch, Text, type TiledLayer, type TiledObject, Tilemap, type TopDownMovementOptions, Transform, World, createAtlas, createTimer, useCamera, useCircleEnter, useCircleExit, useCollisionEnter, useCollisionExit, useEntity, useEvent, useEvents, useGame, useGamepad, useInput, useInputMap, usePause, usePlatformerController, useSnapshot, useSound, useTopDownMovement, useTriggerEnter, useTriggerExit };

package/dist/index.js

@@ -961,6 +961,14 @@ var RenderSystem = class {
         } else if (sprite.frame) {
           const { sx, sy, sw, sh } = sprite.frame;
           ctx.drawImage(sprite.image, sx, sy, sw, sh, drawX, drawY, sprite.width, sprite.height);
+        } else if (sprite.tileX || sprite.tileY) {
+          const repeat = sprite.tileX && sprite.tileY ? "repeat" : sprite.tileX ? "repeat-x" : "repeat-y";
+          const pat = ctx.createPattern(sprite.image, repeat);
+          if (pat) {
+            pat.setTransform(new DOMMatrix().translate(drawX, drawY));
+            ctx.fillStyle = pat;
+            ctx.fillRect(drawX, drawY, sprite.width, sprite.height);
+          }
         } else {
           ctx.drawImage(sprite.image, drawX, drawY, sprite.width, sprite.height);
         }
@@ -970,6 +978,26 @@ var RenderSystem = class {
       }
       ctx.restore();
     }
+    const textEntities = world.query("Transform", "Text");
+    textEntities.sort((a, b) => {
+      const ta = world.getComponent(a, "Text");
+      const tb = world.getComponent(b, "Text");
+      return ta.zIndex - tb.zIndex;
+    });
+    for (const id of textEntities) {
+      const transform = world.getComponent(id, "Transform");
+      const text = world.getComponent(id, "Text");
+      if (!text.visible) continue;
+      ctx.save();
+      ctx.translate(transform.x + text.offsetX, transform.y + text.offsetY);
+      ctx.rotate(transform.rotation);
+      ctx.font = `${text.fontSize}px ${text.fontFamily}`;
+      ctx.fillStyle = text.color;
+      ctx.textAlign = text.align;
+      ctx.textBaseline = text.baseline;
+      ctx.fillText(text.text, 0, 0, text.maxWidth);
+      ctx.restore();
+    }
     for (const id of world.query("Transform", "ParticlePool")) {
       const t = world.getComponent(id, "Transform");
       const pool = world.getComponent(id, "ParticlePool");
@@ -2201,7 +2229,9 @@ function Sprite({
   frameHeight,
   frameColumns,
   atlas,
-  frame
+  frame,
+  tileX,
+  tileY
 }) {
   const resolvedFrameIndex = atlas && frame != null ? atlas[frame] ?? 0 : frameIndex;
   const engine = useContext4(EngineContext);
@@ -2222,7 +2252,9 @@ function Sprite({
       frameIndex: resolvedFrameIndex,
       frameWidth,
       frameHeight,
-      frameColumns
+      frameColumns,
+      tileX,
+      tileY
     });
     engine.ecs.addComponent(entityId, comp);
     if (src) {
@@ -2248,8 +2280,54 @@ function Sprite({
   return null;
 }
 
-// src/components/RigidBody.tsx
+// src/components/Text.tsx
 import { useEffect as useEffect7, useContext as useContext5 } from "react";
+function Text({
+  text,
+  fontSize = 16,
+  fontFamily = "monospace",
+  color = "#ffffff",
+  align = "center",
+  baseline = "middle",
+  zIndex = 10,
+  visible = true,
+  maxWidth,
+  offsetX = 0,
+  offsetY = 0
+}) {
+  const engine = useContext5(EngineContext);
+  const entityId = useContext5(EntityContext);
+  useEffect7(() => {
+    const comp = {
+      type: "Text",
+      text,
+      fontSize,
+      fontFamily,
+      color,
+      align,
+      baseline,
+      zIndex,
+      visible,
+      maxWidth,
+      offsetX,
+      offsetY
+    };
+    engine.ecs.addComponent(entityId, comp);
+    return () => engine.ecs.removeComponent(entityId, "Text");
+  }, []);
+  useEffect7(() => {
+    const comp = engine.ecs.getComponent(entityId, "Text");
+    if (!comp) return;
+    comp.text = text;
+    comp.color = color;
+    comp.visible = visible;
+    comp.zIndex = zIndex;
+  }, [text, color, visible, zIndex, engine, entityId]);
+  return null;
+}
+
+// src/components/RigidBody.tsx
+import { useEffect as useEffect8, useContext as useContext6 } from "react";
 function RigidBody({
   mass = 1,
   gravityScale = 1,
@@ -2261,9 +2339,9 @@ function RigidBody({
   lockX = false,
   lockY = false
 }) {
-  const engine = useContext5(EngineContext);
-  const entityId = useContext5(EntityContext);
-  useEffect7(() => {
+  const engine = useContext6(EngineContext);
+  const entityId = useContext6(EntityContext);
+  useEffect8(() => {
     engine.ecs.addComponent(entityId, createRigidBody({ mass, gravityScale, isStatic, bounce, friction, vx, vy, lockX, lockY }));
     return () => engine.ecs.removeComponent(entityId, "RigidBody");
   }, []);
@@ -2271,7 +2349,7 @@ function RigidBody({
 }
 
 // src/components/BoxCollider.tsx
-import { useEffect as useEffect8, useContext as useContext6 } from "react";
+import { useEffect as useEffect9, useContext as useContext7 } from "react";
 function BoxCollider({
   width,
   height,
@@ -2282,9 +2360,9 @@ function BoxCollider({
   mask = "*",
   oneWay = false
 }) {
-  const engine = useContext6(EngineContext);
-  const entityId = useContext6(EntityContext);
-  useEffect8(() => {
+  const engine = useContext7(EngineContext);
+  const entityId = useContext7(EntityContext);
+  useEffect9(() => {
     engine.ecs.addComponent(entityId, createBoxCollider(width, height, { offsetX, offsetY, isTrigger, layer, mask, oneWay }));
     const checkId = setTimeout(() => {
       if (engine.ecs.hasEntity(entityId) && !engine.ecs.hasComponent(entityId, "Transform")) {
@@ -2300,7 +2378,7 @@ function BoxCollider({
 }
 
 // src/components/CircleCollider.tsx
-import { useEffect as useEffect9, useContext as useContext7 } from "react";
+import { useEffect as useEffect10, useContext as useContext8 } from "react";
 function CircleCollider({
   radius,
   offsetX = 0,
@@ -2309,9 +2387,9 @@ function CircleCollider({
   layer = "default",
   mask = "*"
 }) {
-  const engine = useContext7(EngineContext);
-  const entityId = useContext7(EntityContext);
-  useEffect9(() => {
+  const engine = useContext8(EngineContext);
+  const entityId = useContext8(EntityContext);
+  useEffect10(() => {
     engine.ecs.addComponent(entityId, createCircleCollider(radius, { offsetX, offsetY, isTrigger, layer, mask }));
     return () => engine.ecs.removeComponent(entityId, "CircleCollider");
   }, []);
@@ -2319,11 +2397,11 @@ function CircleCollider({
 }
 
 // src/components/Script.tsx
-import { useEffect as useEffect10, useContext as useContext8 } from "react";
+import { useEffect as useEffect11, useContext as useContext9 } from "react";
 function Script({ init, update }) {
-  const engine = useContext8(EngineContext);
-  const entityId = useContext8(EntityContext);
-  useEffect10(() => {
+  const engine = useContext9(EngineContext);
+  const entityId = useContext9(EntityContext);
+  useEffect11(() => {
     if (init) {
       try {
         init(entityId, engine.ecs);
@@ -2338,7 +2416,7 @@ function Script({ init, update }) {
 }
 
 // src/components/Camera2D.tsx
-import { useEffect as useEffect11, useContext as useContext9 } from "react";
+import { useEffect as useEffect12, useContext as useContext10 } from "react";
 function Camera2D({
   followEntity,
   x = 0,
@@ -2351,8 +2429,8 @@ function Camera2D({
   followOffsetX = 0,
   followOffsetY = 0
 }) {
-  const engine = useContext9(EngineContext);
-  useEffect11(() => {
+  const engine = useContext10(EngineContext);
+  useEffect12(() => {
     const entityId = engine.ecs.createEntity();
     engine.ecs.addComponent(entityId, createCamera2D({
       followEntityId: followEntity,
@@ -2368,7 +2446,7 @@ function Camera2D({
     }));
     return () => engine.ecs.destroyEntity(entityId);
   }, []);
-  useEffect11(() => {
+  useEffect12(() => {
     const camId = engine.ecs.queryOne("Camera2D");
     if (camId === void 0) return;
     const cam = engine.ecs.getComponent(camId, "Camera2D");
@@ -2385,11 +2463,11 @@ function Camera2D({
 }
 
 // src/components/Animation.tsx
-import { useEffect as useEffect12, useContext as useContext10 } from "react";
+import { useEffect as useEffect13, useContext as useContext11 } from "react";
 function Animation({ frames, fps = 12, loop = true, playing = true, onComplete }) {
-  const engine = useContext10(EngineContext);
-  const entityId = useContext10(EntityContext);
-  useEffect12(() => {
+  const engine = useContext11(EngineContext);
+  const entityId = useContext11(EntityContext);
+  useEffect13(() => {
     const state = {
       type: "AnimationState",
       frames,
@@ -2406,7 +2484,7 @@ function Animation({ frames, fps = 12, loop = true, playing = true, onComplete }
       engine.ecs.removeComponent(entityId, "AnimationState");
     };
   }, []);
-  useEffect12(() => {
+  useEffect13(() => {
     const anim = engine.ecs.getComponent(entityId, "AnimationState");
     if (!anim) return;
     const wasFramesChanged = anim.frames !== frames;
@@ -2425,11 +2503,11 @@ function Animation({ frames, fps = 12, loop = true, playing = true, onComplete }
 }
 
 // src/components/SquashStretch.tsx
-import { useEffect as useEffect13, useContext as useContext11 } from "react";
+import { useEffect as useEffect14, useContext as useContext12 } from "react";
 function SquashStretch({ intensity = 0.2, recovery = 8 }) {
-  const engine = useContext11(EngineContext);
-  const entityId = useContext11(EntityContext);
-  useEffect13(() => {
+  const engine = useContext12(EngineContext);
+  const entityId = useContext12(EntityContext);
+  useEffect14(() => {
     engine.ecs.addComponent(entityId, {
       type: "SquashStretch",
       intensity,
@@ -2443,7 +2521,7 @@ function SquashStretch({ intensity = 0.2, recovery = 8 }) {
 }
 
 // src/components/ParticleEmitter.tsx
-import { useEffect as useEffect14, useContext as useContext12 } from "react";
+import { useEffect as useEffect15, useContext as useContext13 } from "react";
 
 // src/components/particlePresets.ts
 var PARTICLE_PRESETS = {
@@ -2528,9 +2606,9 @@ function ParticleEmitter({
   const resolvedColor = color ?? presetConfig.color ?? "#ffffff";
   const resolvedGravity = gravity ?? presetConfig.gravity ?? 200;
   const resolvedMaxParticles = maxParticles ?? presetConfig.maxParticles ?? 100;
-  const engine = useContext12(EngineContext);
-  const entityId = useContext12(EntityContext);
-  useEffect14(() => {
+  const engine = useContext13(EngineContext);
+  const entityId = useContext13(EntityContext);
+  useEffect15(() => {
     engine.ecs.addComponent(entityId, {
       type: "ParticlePool",
       particles: [],
@@ -2548,7 +2626,7 @@ function ParticleEmitter({
     });
     return () => engine.ecs.removeComponent(entityId, "ParticlePool");
   }, []);
-  useEffect14(() => {
+  useEffect15(() => {
     const pool = engine.ecs.getComponent(entityId, "ParticlePool");
     if (!pool) return;
     pool.active = active;
@@ -2598,13 +2676,13 @@ function MovingPlatform({
 import { useState as useState4 } from "react";
 
 // src/hooks/useContact.ts
-import { useContext as useContext13, useEffect as useEffect15 } from "react";
+import { useContext as useContext14, useEffect as useEffect16 } from "react";
 function useContactEvent(eventName, handler, opts) {
-  const engine = useContext13(EngineContext);
-  const entityId = useContext13(EntityContext);
+  const engine = useContext14(EngineContext);
+  const entityId = useContext14(EntityContext);
   if (!engine) throw new Error(`${eventName} hook must be used inside <Game>`);
   if (entityId === null) throw new Error(`${eventName} hook must be used inside <Entity>`);
-  useEffect15(() => {
+  useEffect16(() => {
     return engine.events.on(eventName, ({ a, b }) => {
       const isA = a === entityId;
       const isB = b === entityId;
@@ -2669,7 +2747,7 @@ function Checkpoint({
 }
 
 // src/components/Tilemap.tsx
-import { useEffect as useEffect16, useState as useState5, useContext as useContext14 } from "react";
+import { useEffect as useEffect17, useState as useState5, useContext as useContext15 } from "react";
 import { Fragment as Fragment3, jsx as jsx7 } from "react/jsx-runtime";
 var animatedTiles = /* @__PURE__ */ new Map();
 function getProperty(props, name) {
@@ -2693,9 +2771,9 @@ function Tilemap({
   triggerLayer: triggerLayerName = "triggers",
   onTileProperty
 }) {
-  const engine = useContext14(EngineContext);
+  const engine = useContext15(EngineContext);
   const [spawnedNodes, setSpawnedNodes] = useState5([]);
-  useEffect16(() => {
+  useEffect17(() => {
     if (!engine) return;
     const createdEntities = [];
     async function load() {
@@ -2878,7 +2956,7 @@ function Tilemap({
 }
 
 // src/components/ParallaxLayer.tsx
-import { useEffect as useEffect17, useContext as useContext15 } from "react";
+import { useEffect as useEffect18, useContext as useContext16 } from "react";
 import { jsx as jsx8, jsxs as jsxs5 } from "react/jsx-runtime";
 function ParallaxLayerInner({
   src,
@@ -2890,9 +2968,9 @@ function ParallaxLayerInner({
   offsetX,
   offsetY
 }) {
-  const engine = useContext15(EngineContext);
-  const entityId = useContext15(EntityContext);
-  useEffect17(() => {
+  const engine = useContext16(EngineContext);
+  const entityId = useContext16(EntityContext);
+  useEffect18(() => {
     engine.ecs.addComponent(entityId, {
       type: "ParallaxLayer",
       src,
@@ -2908,7 +2986,7 @@ function ParallaxLayerInner({
     });
     return () => engine.ecs.removeComponent(entityId, "ParallaxLayer");
   }, []);
-  useEffect17(() => {
+  useEffect18(() => {
     const layer = engine.ecs.getComponent(entityId, "ParallaxLayer");
     if (!layer) return;
     layer.src = src;
@@ -2990,9 +3068,9 @@ var ScreenFlash = forwardRef((_, ref) => {
 ScreenFlash.displayName = "ScreenFlash";
 
 // src/hooks/useGame.ts
-import { useContext as useContext16 } from "react";
+import { useContext as useContext17 } from "react";
 function useGame() {
-  const engine = useContext16(EngineContext);
+  const engine = useContext17(EngineContext);
   if (!engine) throw new Error("useGame must be used inside <Game>");
   return engine;
 }
@@ -3043,17 +3121,17 @@ function useSnapshot() {
 }
 
 // src/hooks/useEntity.ts
-import { useContext as useContext17 } from "react";
+import { useContext as useContext18 } from "react";
 function useEntity() {
-  const id = useContext17(EntityContext);
+  const id = useContext18(EntityContext);
   if (id === null) throw new Error("useEntity must be used inside <Entity>");
   return id;
 }
 
 // src/hooks/useInput.ts
-import { useContext as useContext18 } from "react";
+import { useContext as useContext19 } from "react";
 function useInput() {
-  const engine = useContext18(EngineContext);
+  const engine = useContext19(EngineContext);
   if (!engine) throw new Error("useInput must be used inside <Game>");
   return engine.input;
 }
@@ -3077,32 +3155,46 @@ function useInputMap(bindings) {
 }
 
 // src/hooks/useEvents.ts
-import { useContext as useContext19, useEffect as useEffect18 } from "react";
+import { useContext as useContext20, useEffect as useEffect19 } from "react";
 function useEvents() {
-  const engine = useContext19(EngineContext);
+  const engine = useContext20(EngineContext);
   if (!engine) throw new Error("useEvents must be used inside <Game>");
   return engine.events;
 }
 function useEvent(event, handler) {
   const events = useEvents();
-  useEffect18(() => {
+  useEffect19(() => {
     return events.on(event, handler);
   }, [events, event]);
 }
 
 // src/hooks/usePlatformerController.ts
-import { useContext as useContext20, useEffect as useEffect19 } from "react";
+import { useContext as useContext21, useEffect as useEffect20 } from "react";
+function normalizeKeys(val, defaults) {
+  if (!val) return defaults;
+  return Array.isArray(val) ? val : [val];
+}
 function usePlatformerController(entityId, opts = {}) {
-  const engine = useContext20(EngineContext);
+  const engine = useContext21(EngineContext);
   const {
     speed = 200,
     jumpForce = -500,
     maxJumps = 1,
     coyoteTime = 0.08,
-    jumpBuffer = 0.08
+    jumpBuffer = 0.08,
+    jumpCooldown = 0.18,
+    bindings
   } = opts;
-  useEffect19(() => {
-    const state = { coyoteTimer: 0, jumpBuffer: 0, jumpsLeft: maxJumps };
+  const leftKeys = normalizeKeys(bindings?.left, ["ArrowLeft", "KeyA", "a"]);
+  const rightKeys = normalizeKeys(bindings?.right, ["ArrowRight", "KeyD", "d"]);
+  const jumpKeys = normalizeKeys(bindings?.jump, ["Space", "ArrowUp", "KeyW", "w"]);
+  useEffect20(() => {
+    const state = {
+      coyoteTimer: 0,
+      jumpBuffer: 0,
+      jumpCooldown: 0,
+      jumpsLeft: maxJumps
+    };
     const updateFn = (id, world, input, dt) => {
       if (!world.hasEntity(id)) return;
       const rb = world.getComponent(id, "RigidBody");
@@ -3111,11 +3203,12 @@ function usePlatformerController(entityId, opts = {}) {
         state.coyoteTimer = coyoteTime;
         state.jumpsLeft = maxJumps;
       } else state.coyoteTimer = Math.max(0, state.coyoteTimer - dt);
-      const jumpPressed = input.isPressed("Space") || input.isPressed("ArrowUp") || input.isPressed("KeyW") || input.isPressed("w");
-      if (jumpPressed) state.jumpBuffer = jumpBuffer;
-      else state.jumpBuffer = Math.max(0, state.jumpBuffer - dt);
-      const left = input.isDown("ArrowLeft") || input.isDown("KeyA") || input.isDown("a");
-      const right = input.isDown("ArrowRight") || input.isDown("KeyD") || input.isDown("d");
+      state.jumpCooldown = Math.max(0, state.jumpCooldown - dt);
+      const jumpPressed = jumpKeys.some((k) => input.isPressed(k));
+      if (jumpPressed && state.jumpCooldown === 0) state.jumpBuffer = jumpBuffer;
+      else if (!jumpKeys.some((k) => input.isDown(k))) state.jumpBuffer = Math.max(0, state.jumpBuffer - dt);
+      const left = leftKeys.some((k) => input.isDown(k));
+      const right = rightKeys.some((k) => input.isDown(k));
       if (left) rb.vx = -speed;
       else if (right) rb.vx = speed;
       else rb.vx *= rb.onGround ? 0.6 : 0.92;
@@ -3130,8 +3223,9 @@ function usePlatformerController(entityId, opts = {}) {
         state.jumpsLeft = Math.max(0, state.jumpsLeft - 1);
         state.coyoteTimer = 0;
         state.jumpBuffer = 0;
+        state.jumpCooldown = jumpCooldown;
       }
-      const jumpHeld = input.isDown("Space") || input.isDown("ArrowUp") || input.isDown("KeyW") || input.isDown("w");
+      const jumpHeld = jumpKeys.some((k) => input.isDown(k));
       if (!jumpHeld && rb.vy < -120) rb.vy += 800 * dt;
     };
     engine.ecs.addComponent(entityId, createScript(updateFn));
@@ -3140,11 +3234,11 @@ function usePlatformerController(entityId, opts = {}) {
 }
 
 // src/hooks/useTopDownMovement.ts
-import { useContext as useContext21, useEffect as useEffect20 } from "react";
+import { useContext as useContext22, useEffect as useEffect21 } from "react";
 function useTopDownMovement(entityId, opts = {}) {
-  const engine = useContext21(EngineContext);
+  const engine = useContext22(EngineContext);
   const { speed = 200, normalizeDiagonal = true } = opts;
-  useEffect20(() => {
+  useEffect21(() => {
     const updateFn = (id, world, input) => {
       if (!world.hasEntity(id)) return;
       const rb = world.getComponent(id, "RigidBody");
@@ -3168,6 +3262,166 @@ function useTopDownMovement(entityId, opts = {}) {
   }, []);
 }
 
+// src/hooks/useSound.ts
+import { useEffect as useEffect22, useRef as useRef3 } from "react";
+var _audioCtx = null;
+function getAudioCtx() {
+  if (!_audioCtx) _audioCtx = new AudioContext();
+  return _audioCtx;
+}
+var bufferCache = /* @__PURE__ */ new Map();
+async function loadBuffer(src) {
+  const cached = bufferCache.get(src);
+  if (cached) return cached;
+  const res = await fetch(src);
+  const data = await res.arrayBuffer();
+  const buf = await getAudioCtx().decodeAudioData(data);
+  bufferCache.set(src, buf);
+  return buf;
+}
+function useSound(src, opts = {}) {
+  const bufferRef = useRef3(null);
+  const sourceRef = useRef3(null);
+  const gainRef = useRef3(null);
+  const volRef = useRef3(opts.volume ?? 1);
+  const loopRef = useRef3(opts.loop ?? false);
+  useEffect22(() => {
+    loadBuffer(src).then((buf) => {
+      bufferRef.current = buf;
+    }).catch(console.error);
+  }, [src]);
+  const play = () => {
+    if (!bufferRef.current) return;
+    const ctx = getAudioCtx();
+    if (ctx.state === "suspended") ctx.resume();
+    if (sourceRef.current) {
+      try {
+        sourceRef.current.stop();
+      } catch {
+      }
+      sourceRef.current = null;
+    }
+    const gain = ctx.createGain();
+    gain.gain.value = volRef.current;
+    gain.connect(ctx.destination);
+    gainRef.current = gain;
+    const source = ctx.createBufferSource();
+    source.buffer = bufferRef.current;
+    source.loop = loopRef.current;
+    source.connect(gain);
+    source.start();
+    source.onended = () => {
+      sourceRef.current = null;
+    };
+    sourceRef.current = source;
+  };
+  const stop = () => {
+    if (sourceRef.current) {
+      try {
+        sourceRef.current.stop();
+      } catch {
+      }
+      sourceRef.current = null;
+    }
+  };
+  const setVolume = (v) => {
+    volRef.current = v;
+    if (gainRef.current) gainRef.current.gain.value = v;
+  };
+  return { play, stop, setVolume };
+}
+
+// src/hooks/useTimer.ts
+function createTimer(duration, onComplete, autoStart = false) {
+  let _duration = duration;
+  let _elapsed = 0;
+  let _running = autoStart;
+  return {
+    update(dt) {
+      if (!_running) return;
+      _elapsed += dt;
+      if (_elapsed >= _duration) {
+        _elapsed = _duration;
+        _running = false;
+        onComplete?.();
+      }
+    },
+    start() {
+      _running = true;
+    },
+    stop() {
+      _running = false;
+    },
+    reset(d) {
+      _elapsed = 0;
+      _running = false;
+      if (d !== void 0) _duration = d;
+    },
+    restart() {
+      _elapsed = 0;
+      _running = true;
+    },
+    get running() {
+      return _running;
+    },
+    get elapsed() {
+      return _elapsed;
+    },
+    get remaining() {
+      return Math.max(0, _duration - _elapsed);
+    },
+    get progress() {
+      return _duration > 0 ? Math.min(1, _elapsed / _duration) : 1;
+    }
+  };
+}
+
+// src/hooks/useGamepad.ts
+import { useEffect as useEffect23, useRef as useRef4, useState as useState6 } from "react";
+var EMPTY_STATE = { connected: false, axes: [], buttons: [] };
+function useGamepad(playerIndex = 0) {
+  const [state, setState] = useState6(EMPTY_STATE);
+  const rafRef = useRef4(0);
+  useEffect23(() => {
+    const poll = () => {
+      const gp = navigator.getGamepads()[playerIndex];
+      if (gp) {
+        setState({
+          connected: true,
+          axes: Array.from(gp.axes),
+          buttons: Array.from(gp.buttons).map((b) => b.pressed)
+        });
+      } else {
+        setState((s) => s.connected ? EMPTY_STATE : s);
+      }
+      rafRef.current = requestAnimationFrame(poll);
+    };
+    rafRef.current = requestAnimationFrame(poll);
+    return () => cancelAnimationFrame(rafRef.current);
+  }, [playerIndex]);
+  return state;
+}
+
+// src/hooks/usePause.ts
+import { useContext as useContext23, useState as useState7, useCallback as useCallback2 } from "react";
+function usePause() {
+  const engine = useContext23(EngineContext);
+  const [paused, setPaused] = useState7(false);
+  const pause = useCallback2(() => {
+    engine.loop.pause();
+    setPaused(true);
+  }, [engine]);
+  const resume = useCallback2(() => {
+    engine.loop.resume();
+    setPaused(false);
+  }, [engine]);
+  const toggle = useCallback2(() => {
+    if (engine.loop.isPaused) resume();
+    else pause();
+  }, [engine, pause, resume]);
+  return { paused, pause, resume, toggle };
+}
+
 // src/components/spriteAtlas.ts
 function createAtlas(names, _columns) {
   const atlas = {};
@@ -3193,6 +3447,7 @@ export {
   Script,
   Sprite,
   SquashStretch,
+  Text,
   Tilemap,
   Transform,
   World,
@@ -3200,6 +3455,7 @@ export {
   createInputMap,
   createSprite,
   createTag,
+  createTimer,
   createTransform,
   definePlugin,
   findByTag,
@@ -3215,10 +3471,13 @@ export {
   useEvent,
   useEvents,
   useGame,
+  useGamepad,
   useInput,
   useInputMap,
+  usePause,
   usePlatformerController,
   useSnapshot,
+  useSound,
   useTopDownMovement,
   useTriggerEnter,
   useTriggerExit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cubeforge",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "React-first 2D browser game engine",
   "main": "./dist/index.js",
   "scripts": {