cubeforge 0.0.1

package/dist/hooks/usePlatformerController.d.ts

@@ -0,0 +1,32 @@
+import type { EntityId } from '@cubeforge/core';
+export interface PlatformerControllerOptions {
+    /** Horizontal move speed in px/s (default 200) */
+    speed?: number;
+    /** Upward impulse on jump (default -500) */
+    jumpForce?: number;
+    /** Max consecutive jumps, e.g. 2 for double jump (default 1) */
+    maxJumps?: number;
+    /** Seconds after leaving ground the player can still jump (default 0.08) */
+    coyoteTime?: number;
+    /** Seconds to buffer a jump input before landing (default 0.08) */
+    jumpBuffer?: number;
+}
+/**
+ * Attaches platformer movement (WASD/Arrows + Space/Up to jump) to an entity.
+ * The entity must already have a RigidBody component.
+ *
+ * @example
+ * function Player() {
+ *   const id = useEntity()
+ *   usePlatformerController(id, { speed: 220, maxJumps: 2 })
+ *   return (
+ *     <Entity id="player">
+ *       <Transform x={100} y={300} />
+ *       <Sprite width={28} height={40} color="#4fc3f7" />
+ *       <RigidBody />
+ *       <BoxCollider width={26} height={40} />
+ *     </Entity>
+ *   )
+ * }
+ */
+export declare function usePlatformerController(entityId: EntityId, opts?: PlatformerControllerOptions): void;

package/dist/hooks/usePlatformerController.js

@@ -0,0 +1,82 @@
+import { useContext, useEffect } from 'react';
+import { createScript } from '@cubeforge/core';
+import { EngineContext } from '../context';
+/**
+ * Attaches platformer movement (WASD/Arrows + Space/Up to jump) to an entity.
+ * The entity must already have a RigidBody component.
+ *
+ * @example
+ * function Player() {
+ *   const id = useEntity()
+ *   usePlatformerController(id, { speed: 220, maxJumps: 2 })
+ *   return (
+ *     <Entity id="player">
+ *       <Transform x={100} y={300} />
+ *       <Sprite width={28} height={40} color="#4fc3f7" />
+ *       <RigidBody />
+ *       <BoxCollider width={26} height={40} />
+ *     </Entity>
+ *   )
+ * }
+ */
+export function usePlatformerController(entityId, opts = {}) {
+    const engine = useContext(EngineContext);
+    const { speed = 200, jumpForce = -500, maxJumps = 1, coyoteTime = 0.08, jumpBuffer = 0.08, } = opts;
+    useEffect(() => {
+        const state = { coyoteTimer: 0, jumpBuffer: 0, jumpsLeft: maxJumps };
+        const updateFn = (id, world, input, dt) => {
+            if (!world.hasEntity(id))
+                return;
+            const rb = world.getComponent(id, 'RigidBody');
+            if (!rb)
+                return;
+            // Ground tracking
+            if (rb.onGround) {
+                state.coyoteTimer = coyoteTime;
+                state.jumpsLeft = maxJumps;
+            }
+            else
+                state.coyoteTimer = Math.max(0, state.coyoteTimer - dt);
+            // Jump buffer
+            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);
+            // Horizontal movement
+            const left = input.isDown('ArrowLeft') || input.isDown('KeyA') || input.isDown('a');
+            const right = input.isDown('ArrowRight') || input.isDown('KeyD') || input.isDown('d');
+            if (left)
+                rb.vx = -speed;
+            else if (right)
+                rb.vx = speed;
+            else
+                rb.vx *= rb.onGround ? 0.6 : 0.92;
+            // Sprite flip
+            const sprite = world.getComponent(id, 'Sprite');
+            if (sprite) {
+                if (left)
+                    sprite.flipX = true;
+                if (right)
+                    sprite.flipX = false;
+            }
+            // Jump
+            const canJump = state.coyoteTimer > 0 || state.jumpsLeft > 0;
+            if (state.jumpBuffer > 0 && canJump) {
+                rb.vy = jumpForce;
+                state.jumpsLeft = Math.max(0, state.jumpsLeft - 1);
+                state.coyoteTimer = 0;
+                state.jumpBuffer = 0;
+            }
+            // Variable jump height — release early to cut arc
+            const jumpHeld = input.isDown('Space') || input.isDown('ArrowUp') ||
+                input.isDown('KeyW') || input.isDown('w');
+            if (!jumpHeld && rb.vy < -120)
+                rb.vy += 800 * dt;
+        };
+        engine.ecs.addComponent(entityId, createScript(updateFn));
+        return () => engine.ecs.removeComponent(entityId, 'Script');
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+}

package/dist/hooks/useTopDownMovement.d.ts

@@ -0,0 +1,22 @@
+import type { EntityId } from '@cubeforge/core';
+export interface TopDownMovementOptions {
+    /** Movement speed in px/s (default 200) */
+    speed?: number;
+    /** Normalize diagonal movement to avoid faster diagonal movement (default true) */
+    normalizeDiagonal?: boolean;
+}
+/**
+ * Attaches 4-directional top-down movement (WASD/Arrows) to an entity.
+ * The entity must have a RigidBody with gravityScale=0 for top-down games.
+ *
+ * @example
+ * <Entity id="player">
+ *   <Transform x={100} y={100} />
+ *   <Sprite width={24} height={24} color="#4fc3f7" />
+ *   <RigidBody gravityScale={0} />
+ *   <BoxCollider width={24} height={24} />
+ * </Entity>
+ * // In a Script or parent component:
+ * useTopDownMovement(playerId, { speed: 180 })
+ */
+export declare function useTopDownMovement(entityId: EntityId, opts?: TopDownMovementOptions): void;

package/dist/hooks/useTopDownMovement.js

@@ -0,0 +1,46 @@
+import { useContext, useEffect } from 'react';
+import { createScript } from '@cubeforge/core';
+import { EngineContext } from '../context';
+/**
+ * Attaches 4-directional top-down movement (WASD/Arrows) to an entity.
+ * The entity must have a RigidBody with gravityScale=0 for top-down games.
+ *
+ * @example
+ * <Entity id="player">
+ *   <Transform x={100} y={100} />
+ *   <Sprite width={24} height={24} color="#4fc3f7" />
+ *   <RigidBody gravityScale={0} />
+ *   <BoxCollider width={24} height={24} />
+ * </Entity>
+ * // In a Script or parent component:
+ * useTopDownMovement(playerId, { speed: 180 })
+ */
+export function useTopDownMovement(entityId, opts = {}) {
+    const engine = useContext(EngineContext);
+    const { speed = 200, normalizeDiagonal = true } = opts;
+    useEffect(() => {
+        const updateFn = (id, world, input) => {
+            if (!world.hasEntity(id))
+                return;
+            const rb = world.getComponent(id, 'RigidBody');
+            if (!rb)
+                return;
+            const left = (input.isDown('ArrowLeft') || input.isDown('KeyA') || input.isDown('a')) ? -1 : 0;
+            const right = (input.isDown('ArrowRight') || input.isDown('KeyD') || input.isDown('d')) ? 1 : 0;
+            const up = (input.isDown('ArrowUp') || input.isDown('KeyW') || input.isDown('w')) ? -1 : 0;
+            const down = (input.isDown('ArrowDown') || input.isDown('KeyS') || input.isDown('s')) ? 1 : 0;
+            let dx = left + right;
+            let dy = up + down;
+            if (normalizeDiagonal && dx !== 0 && dy !== 0) {
+                const len = Math.sqrt(dx * dx + dy * dy);
+                dx /= len;
+                dy /= len;
+            }
+            rb.vx = dx * speed;
+            rb.vy = dy * speed;
+        };
+        engine.ecs.addComponent(entityId, createScript(updateFn));
+        return () => engine.ecs.removeComponent(entityId, 'Script');
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+}

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+export { Game } from './components/Game';
+export { World } from './components/World';
+export { Entity } from './components/Entity';
+export { Transform } from './components/Transform';
+export { Sprite } from './components/Sprite';
+export { RigidBody } from './components/RigidBody';
+export { BoxCollider } from './components/BoxCollider';
+export { Script } from './components/Script';
+export { Camera2D } from './components/Camera2D';
+export { Animation } from './components/Animation';
+export { SquashStretch } from './components/SquashStretch';
+export { ParticleEmitter } from './components/ParticleEmitter';
+export { MovingPlatform } from './components/MovingPlatform';
+export { Checkpoint } from './components/Checkpoint';
+export { Tilemap } from './components/Tilemap';
+export { ParallaxLayer } from './components/ParallaxLayer';
+export { ScreenFlash } from './components/ScreenFlash';
+export type { ScreenFlashHandle } from './components/ScreenFlash';
+export type { TiledObject, TiledLayer } from './components/Tilemap';
+export { useGame } from './hooks/useGame';
+export { useEntity } from './hooks/useEntity';
+export { useInput } from './hooks/useInput';
+export { useEvents, useEvent } from './hooks/useEvents';
+export { usePlatformerController } from './hooks/usePlatformerController';
+export { useTopDownMovement } from './hooks/useTopDownMovement';
+export type { SpriteAtlas } from './components/spriteAtlas';
+export { createAtlas } from './components/spriteAtlas';
+export type { EngineState } from './context';
+export type { GameControls } from './components/Game';
+export type { PlatformerControllerOptions } from './hooks/usePlatformerController';
+export type { TopDownMovementOptions } from './hooks/useTopDownMovement';
+export type { EntityId, ECSWorld, ScriptUpdateFn } from '@cubeforge/core';
+export type { InputManager } from '@cubeforge/input';
+export type { TransformComponent } from '@cubeforge/core';
+export type { RigidBodyComponent } from '@cubeforge/physics';
+export type { BoxColliderComponent } from '@cubeforge/physics';
+export type { SpriteComponent } from '@cubeforge/renderer';
+export type { AnimationStateComponent } from '@cubeforge/renderer';
+export type { SquashStretchComponent } from '@cubeforge/renderer';
+export type { ParticlePoolComponent, Particle } from '@cubeforge/renderer';
+export type { ParallaxLayerComponent } from '@cubeforge/renderer';
+export type { TweenHandle } from '@cubeforge/core';
+export { Ease, tween } from '@cubeforge/core';
+export type { ParticlePreset } from './components/particlePresets';

package/dist/index.js

@@ -0,0 +1,27 @@
+// Components
+export { Game } from './components/Game';
+export { World } from './components/World';
+export { Entity } from './components/Entity';
+export { Transform } from './components/Transform';
+export { Sprite } from './components/Sprite';
+export { RigidBody } from './components/RigidBody';
+export { BoxCollider } from './components/BoxCollider';
+export { Script } from './components/Script';
+export { Camera2D } from './components/Camera2D';
+export { Animation } from './components/Animation';
+export { SquashStretch } from './components/SquashStretch';
+export { ParticleEmitter } from './components/ParticleEmitter';
+export { MovingPlatform } from './components/MovingPlatform';
+export { Checkpoint } from './components/Checkpoint';
+export { Tilemap } from './components/Tilemap';
+export { ParallaxLayer } from './components/ParallaxLayer';
+export { ScreenFlash } from './components/ScreenFlash';
+// Hooks
+export { useGame } from './hooks/useGame';
+export { useEntity } from './hooks/useEntity';
+export { useInput } from './hooks/useInput';
+export { useEvents, useEvent } from './hooks/useEvents';
+export { usePlatformerController } from './hooks/usePlatformerController';
+export { useTopDownMovement } from './hooks/useTopDownMovement';
+export { createAtlas } from './components/spriteAtlas';
+export { Ease, tween } from '@cubeforge/core';

package/dist/systems/debugSystem.d.ts

@@ -0,0 +1,10 @@
+import type { System, ECSWorld } from '@cubeforge/core';
+import type { Canvas2DRenderer } from '@cubeforge/renderer';
+export declare class DebugSystem implements System {
+    private readonly renderer;
+    private frameCount;
+    private lastFpsTime;
+    private fps;
+    constructor(renderer: Canvas2DRenderer);
+    update(world: ECSWorld, dt: number): void;
+}

package/dist/systems/debugSystem.js

@@ -0,0 +1,104 @@
+export class DebugSystem {
+    renderer;
+    frameCount = 0;
+    lastFpsTime = 0;
+    fps = 0;
+    constructor(renderer) {
+        this.renderer = renderer;
+    }
+    update(world, dt) {
+        const { ctx, canvas } = this.renderer;
+        // FPS tracking
+        this.frameCount++;
+        this.lastFpsTime += dt;
+        if (this.lastFpsTime >= 0.5) {
+            this.fps = Math.round(this.frameCount / this.lastFpsTime);
+            this.frameCount = 0;
+            this.lastFpsTime = 0;
+        }
+        // Get camera for world-space drawing
+        const camId = world.queryOne('Camera2D');
+        let camX = 0, camY = 0, zoom = 1;
+        if (camId !== undefined) {
+            const cam = world.getComponent(camId, 'Camera2D');
+            camX = cam.x;
+            camY = cam.y;
+            zoom = cam.zoom;
+        }
+        // Draw collider wireframes in world space
+        ctx.save();
+        ctx.translate(canvas.width / 2 - camX * zoom, canvas.height / 2 - camY * zoom);
+        ctx.scale(zoom, zoom);
+        const lw = 1 / zoom;
+        for (const id of world.query('Transform', 'BoxCollider')) {
+            const t = world.getComponent(id, 'Transform');
+            const c = world.getComponent(id, 'BoxCollider');
+            ctx.strokeStyle = c.isTrigger ? 'rgba(255,200,0,0.85)' : 'rgba(0,255,120,0.85)';
+            ctx.lineWidth = lw;
+            ctx.strokeRect(t.x + c.offsetX - c.width / 2, t.y + c.offsetY - c.height / 2, c.width, c.height);
+            // Entity ID label
+            ctx.fillStyle = 'rgba(255,255,255,0.5)';
+            ctx.font = `${10 / zoom}px monospace`;
+            ctx.fillText(String(id), t.x + c.offsetX - c.width / 2 + lw, t.y + c.offsetY - c.height / 2 - lw * 2);
+        }
+        // Camera bounds visualization (drawn in same world-space context)
+        if (camId !== undefined) {
+            const camFull = world.getComponent(camId, 'Camera2D');
+            if (camFull.bounds) {
+                const b = camFull.bounds;
+                ctx.strokeStyle = 'rgba(0, 255, 255, 0.4)';
+                ctx.lineWidth = 1 / zoom;
+                ctx.setLineDash([8 / zoom, 4 / zoom]);
+                ctx.strokeRect(b.x, b.y, b.width, b.height);
+                ctx.setLineDash([]);
+            }
+        }
+        ctx.restore();
+        // Physics grid visualization (128px spatial broadphase grid)
+        const GRID_SIZE = 128;
+        ctx.save();
+        ctx.strokeStyle = 'rgba(255, 255, 255, 0.04)';
+        ctx.lineWidth = 1;
+        ctx.setLineDash([]);
+        // Compute visible world-space range
+        const offsetX = camX - canvas.width / (2 * zoom);
+        const offsetY = camY - canvas.height / (2 * zoom);
+        const visibleW = canvas.width / zoom;
+        const visibleH = canvas.height / zoom;
+        const startCol = Math.floor(offsetX / GRID_SIZE);
+        const endCol = Math.ceil((offsetX + visibleW) / GRID_SIZE);
+        const startRow = Math.floor(offsetY / GRID_SIZE);
+        const endRow = Math.ceil((offsetY + visibleH) / GRID_SIZE);
+        ctx.translate(canvas.width / 2 - camX * zoom, canvas.height / 2 - camY * zoom);
+        ctx.scale(zoom, zoom);
+        for (let col = startCol; col <= endCol; col++) {
+            const wx = col * GRID_SIZE;
+            ctx.beginPath();
+            ctx.moveTo(wx, startRow * GRID_SIZE);
+            ctx.lineTo(wx, endRow * GRID_SIZE);
+            ctx.stroke();
+        }
+        for (let row = startRow; row <= endRow; row++) {
+            const wy = row * GRID_SIZE;
+            ctx.beginPath();
+            ctx.moveTo(startCol * GRID_SIZE, wy);
+            ctx.lineTo(endCol * GRID_SIZE, wy);
+            ctx.stroke();
+        }
+        ctx.restore();
+        // Screen-space HUD
+        const entityCount = world.entityCount;
+        const physicsCount = world.query('RigidBody', 'BoxCollider').length;
+        const renderCount = world.query('Transform', 'Sprite').length;
+        ctx.save();
+        ctx.fillStyle = 'rgba(0,0,0,0.65)';
+        ctx.fillRect(8, 8, 184, 84);
+        ctx.fillStyle = '#00ff88';
+        ctx.font = '11px monospace';
+        ctx.fillText(`FPS         ${this.fps}`, 16, 26);
+        ctx.fillText(`Entities    ${entityCount}`, 16, 42);
+        ctx.fillText(`Physics     ${physicsCount}`, 16, 58);
+        ctx.fillText(`Renderables ${renderCount}`, 16, 74);
+        ctx.restore();
+    }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "cubeforge",
+  "version": "0.0.1",
+  "description": "React-first 2D browser game engine",
+  "main": "./src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc"
+  },
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "import": "./dist/index.js",
+        "types": "./dist/index.d.ts"
+      }
+    }
+  },
+  "files": ["dist"],
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "dependencies": {
+    "@cubeforge/core": "workspace:*",
+    "@cubeforge/input": "workspace:*",
+    "@cubeforge/renderer": "workspace:*",
+    "@cubeforge/physics": "workspace:*"
+  },
+  "keywords": ["game-engine", "react", "2d", "browser-game", "cubeforge"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/1homsi/cubeforge"
+  }
+}