cubeforge 0.0.7 → 0.0.9

package/dist/components/Animation.js

@@ -0,0 +1,32 @@
+import { useEffect, useContext } from 'react';
+import { EngineContext, EntityContext } from '../context';
+export function Animation({ frames, fps = 12, loop = true, playing = true }) {
+    const engine = useContext(EngineContext);
+    const entityId = useContext(EntityContext);
+    useEffect(() => {
+        const state = {
+            type: 'AnimationState',
+            frames,
+            fps,
+            loop,
+            playing,
+            currentIndex: 0,
+            timer: 0,
+        };
+        engine.ecs.addComponent(entityId, state);
+        return () => {
+            engine.ecs.removeComponent(entityId, 'AnimationState');
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // Sync playing state and animation params
+    useEffect(() => {
+        const anim = engine.ecs.getComponent(entityId, 'AnimationState');
+        if (!anim)
+            return;
+        anim.playing = playing;
+        anim.fps = fps;
+        anim.loop = loop;
+    }, [playing, fps, loop, engine, entityId]);
+    return null;
+}

package/dist/components/BoxCollider.js

@@ -0,0 +1,21 @@
+import { useEffect, useContext } from 'react';
+import { createBoxCollider } from '@cubeforge/physics';
+import { EngineContext, EntityContext } from '../context';
+export function BoxCollider({ width, height, offsetX = 0, offsetY = 0, isTrigger = false, layer = 'default', }) {
+    const engine = useContext(EngineContext);
+    const entityId = useContext(EntityContext);
+    useEffect(() => {
+        engine.ecs.addComponent(entityId, createBoxCollider(width, height, { offsetX, offsetY, isTrigger, layer }));
+        // Defer check so sibling components have had a chance to add their components
+        const checkId = setTimeout(() => {
+            if (engine.ecs.hasEntity(entityId) && !engine.ecs.hasComponent(entityId, 'Transform')) {
+                console.warn(`[Cubeforge] BoxCollider on entity ${entityId} has no Transform. Physics requires Transform.`);
+            }
+        }, 0);
+        return () => {
+            clearTimeout(checkId);
+            engine.ecs.removeComponent(entityId, 'BoxCollider');
+        };
+    }, []); // eslint-disable-line react-hooks/exhaustive-deps
+    return null;
+}

package/dist/components/Camera2D.d.ts

@@ -1,6 +1,10 @@
 interface Camera2DProps {
     /** String ID of entity to follow */
     followEntity?: string;
+    /** Initial camera X position in world space (default 0 = world origin at screen center) */
+    x?: number;
+    /** Initial camera Y position in world space (default 0 = world origin at screen center) */
+    y?: number;
     zoom?: number;
     /** Lerp smoothing factor (0 = instant snap, 0.85 = smooth) */
     smoothing?: number;
@@ -19,5 +23,5 @@ interface Camera2DProps {
     followOffsetX?: number;
     followOffsetY?: number;
 }
-export declare function Camera2D({ followEntity, zoom, smoothing, background, bounds, deadZone, followOffsetX, followOffsetY, }: Camera2DProps): null;
+export declare function Camera2D({ followEntity, x, y, zoom, smoothing, background, bounds, deadZone, followOffsetX, followOffsetY, }: Camera2DProps): null;
 export {};

package/dist/components/Camera2D.js

@@ -0,0 +1,33 @@
+import { useEffect, useContext } from 'react';
+import { createCamera2D } from '@cubeforge/renderer';
+import { EngineContext } from '../context';
+export function Camera2D({ followEntity, zoom = 1, smoothing = 0, background = '#1a1a2e', bounds, deadZone, }) {
+    const engine = useContext(EngineContext);
+    useEffect(() => {
+        const entityId = engine.ecs.createEntity();
+        engine.ecs.addComponent(entityId, createCamera2D({
+            followEntityId: followEntity,
+            zoom,
+            smoothing,
+            background,
+            bounds,
+            deadZone,
+        }));
+        return () => engine.ecs.destroyEntity(entityId);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // Sync prop changes
+    useEffect(() => {
+        const camId = engine.ecs.queryOne('Camera2D');
+        if (camId === undefined)
+            return;
+        const cam = engine.ecs.getComponent(camId, 'Camera2D');
+        cam.followEntityId = followEntity;
+        cam.zoom = zoom;
+        cam.smoothing = smoothing;
+        cam.background = background;
+        cam.bounds = bounds;
+        cam.deadZone = deadZone;
+    }, [followEntity, zoom, smoothing, background, bounds, deadZone, engine]);
+    return null;
+}

package/dist/components/Checkpoint.js

@@ -0,0 +1,36 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Entity } from './Entity';
+import { Transform } from './Transform';
+import { Sprite } from './Sprite';
+import { BoxCollider } from './BoxCollider';
+import { Script } from './Script';
+/**
+ * A trigger zone that fires `onActivate` when the player enters it, then destroys itself.
+ *
+ * @example
+ * <Checkpoint x={800} y={450} onActivate={() => setCheckpoint(800)} />
+ */
+export function Checkpoint({ x, y, width = 24, height = 48, color = '#ffd54f', onActivate, }) {
+    return (_jsxs(Entity, { tags: ['checkpoint'], children: [_jsx(Transform, { x: x, y: y }), _jsx(Sprite, { width: width, height: height, color: color, zIndex: 5 }), _jsx(BoxCollider, { width: width, height: height, isTrigger: true }), _jsx(Script, { init: () => { }, update: (id, world) => {
+                    if (!world.hasEntity(id))
+                        return;
+                    const ct = world.getComponent(id, 'Transform');
+                    if (!ct)
+                        return;
+                    for (const pid of world.query('Tag')) {
+                        const tag = world.getComponent(pid, 'Tag');
+                        if (!tag?.tags.includes('player'))
+                            continue;
+                        const pt = world.getComponent(pid, 'Transform');
+                        if (!pt)
+                            continue;
+                        const dx = Math.abs(pt.x - ct.x);
+                        const dy = Math.abs(pt.y - ct.y);
+                        if (dx < (width / 2 + 16) && dy < (height / 2 + 20)) {
+                            onActivate?.();
+                            world.destroyEntity(id);
+                            return;
+                        }
+                    }
+                } })] }));
+}

package/dist/components/Entity.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useContext, useState } from 'react';
+import { createTag } from '@cubeforge/core';
+import { EngineContext, EntityContext } from '../context';
+export function Entity({ id, tags = [], children }) {
+    const engine = useContext(EngineContext);
+    const [entityId, setEntityId] = useState(null);
+    useEffect(() => {
+        const eid = engine.ecs.createEntity();
+        if (id) {
+            if (engine.entityIds.has(id)) {
+                console.warn(`[Cubeforge] Duplicate entity ID "${id}". Entity IDs must be unique — the previous entity with this ID will be replaced.`);
+            }
+            engine.entityIds.set(id, eid);
+        }
+        if (tags.length > 0)
+            engine.ecs.addComponent(eid, createTag(...tags));
+        setEntityId(eid);
+        return () => {
+            engine.ecs.destroyEntity(eid);
+            if (id)
+                engine.entityIds.delete(id);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    if (entityId === null)
+        return null;
+    return (_jsx(EntityContext.Provider, { value: entityId, children: children }));
+}

package/dist/components/Game.d.ts

@@ -27,6 +27,13 @@ interface GameProps {
     deterministic?: boolean;
     /** Seed for the deterministic RNG (default 0). Only used when deterministic=true. */
     seed?: number;
+    /**
+     * When true, the game loop starts immediately and sprites swap from color → image as
+     * they load in the background. When false (default) the loop is held until every
+     * sprite that is part of the initial scene has finished loading, so the first frame
+     * shown is fully rendered with real assets.
+     */
+    asyncAssets?: boolean;
     /** Custom plugins to register after core systems. Each plugin's systems run after Render. */
     plugins?: Plugin[];
     /**
@@ -41,5 +48,5 @@ interface GameProps {
     className?: string;
     children?: React.ReactNode;
 }
-export declare function Game({ width, height, gravity, debug, devtools, scale, deterministic, seed, onReady, plugins, renderer: CustomRenderer, style, className, children, }: GameProps): import("react/jsx-runtime").JSX.Element;
+export declare function Game({ width, height, gravity, debug, devtools, scale, deterministic, seed, asyncAssets, onReady, plugins, renderer: CustomRenderer, style, className, children, }: GameProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/Game.js

@@ -0,0 +1,93 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { ECSWorld, GameLoop, EventBus, AssetManager, ScriptSystem } from '@cubeforge/core';
+import { InputManager } from '@cubeforge/input';
+import { Canvas2DRenderer, RenderSystem } from '@cubeforge/renderer';
+import { PhysicsSystem } from '@cubeforge/physics';
+import { EngineContext } from '../context';
+import { DebugSystem } from '../systems/debugSystem';
+export function Game({ width = 800, height = 600, gravity = 980, debug = false, scale = 'none', onReady, style, className, children, }) {
+    const canvasRef = useRef(null);
+    const wrapperRef = useRef(null);
+    const [engine, setEngine] = useState(null);
+    useEffect(() => {
+        const canvas = canvasRef.current;
+        const ecs = new ECSWorld();
+        const input = new InputManager();
+        const renderer = new Canvas2DRenderer(canvas);
+        const events = new EventBus();
+        const assets = new AssetManager();
+        const physics = new PhysicsSystem(gravity, events);
+        const entityIds = new Map();
+        const renderSystem = new RenderSystem(renderer, entityIds);
+        const debugSystem = debug ? new DebugSystem(renderer) : null;
+        // System order: scripts → physics → render → (debug)
+        ecs.addSystem(new ScriptSystem(input));
+        ecs.addSystem(physics);
+        ecs.addSystem(renderSystem);
+        if (debugSystem)
+            ecs.addSystem(debugSystem);
+        input.attach(canvas);
+        canvas.setAttribute('tabindex', '0');
+        // Validate dimensions
+        if (width <= 0 || height <= 0) {
+            console.warn(`[Cubeforge] Invalid Game dimensions: ${width}x${height}. Width and height must be positive.`);
+        }
+        const loop = new GameLoop((dt) => {
+            ecs.update(dt);
+            input.flush();
+        });
+        const state = { ecs, input, renderer, physics, events, assets, loop, canvas, entityIds };
+        setEngine(state);
+        loop.start();
+        // Expose controls via onReady callback
+        onReady?.({
+            pause: () => loop.pause(),
+            resume: () => loop.resume(),
+            reset: () => {
+                ecs.clear();
+                loop.stop();
+                loop.start();
+            },
+        });
+        // Handle contain scaling
+        let resizeObserver = null;
+        if (scale === 'contain' && wrapperRef.current) {
+            const wrapper = wrapperRef.current;
+            const updateScale = () => {
+                const parentW = wrapper.parentElement?.clientWidth ?? width;
+                const parentH = wrapper.parentElement?.clientHeight ?? height;
+                const scaleX = parentW / width;
+                const scaleY = parentH / height;
+                const s = Math.min(scaleX, scaleY);
+                canvas.style.transform = `scale(${s})`;
+                canvas.style.transformOrigin = 'top left';
+            };
+            updateScale();
+            resizeObserver = new ResizeObserver(updateScale);
+            if (wrapper.parentElement)
+                resizeObserver.observe(wrapper.parentElement);
+        }
+        return () => {
+            loop.stop();
+            input.detach();
+            ecs.clear();
+            resizeObserver?.disconnect();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // Sync gravity changes
+    useEffect(() => {
+        engine?.physics.setGravity(gravity);
+    }, [gravity, engine]);
+    const canvasStyle = {
+        display: 'block',
+        outline: 'none',
+        imageRendering: scale === 'pixel' ? 'pixelated' : undefined,
+        ...style,
+    };
+    const wrapperStyle = scale === 'contain'
+        ? { position: 'relative', width, height, overflow: 'visible' }
+        : {};
+    return (_jsxs(EngineContext.Provider, { value: engine, children: [_jsx("div", { ref: wrapperRef, style: wrapperStyle, children: _jsx("canvas", { ref: canvasRef, width: width, height: height, style: canvasStyle, className: className }) }), engine && children] }));
+}

package/dist/components/MovingPlatform.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Entity } from './Entity';
+import { Transform } from './Transform';
+import { Sprite } from './Sprite';
+import { RigidBody } from './RigidBody';
+import { BoxCollider } from './BoxCollider';
+import { Script } from './Script';
+const platformPhases = new Map();
+/**
+ * A static platform that oscillates between (x1,y1) and (x2,y2).
+ *
+ * @example
+ * <MovingPlatform x1={200} y1={350} x2={450} y2={350} width={120} duration={2.5} />
+ */
+export function MovingPlatform({ x1, y1, x2, y2, width = 120, height = 18, duration = 3, color = '#37474f', }) {
+    return (_jsxs(Entity, { children: [_jsx(Transform, { x: x1, y: y1 }), _jsx(Sprite, { width: width, height: height, color: color, zIndex: 5 }), _jsx(RigidBody, { isStatic: true }), _jsx(BoxCollider, { width: width, height: height }), _jsx(Script, { init: () => { }, update: (id, world, _input, dt) => {
+                    if (!world.hasEntity(id))
+                        return;
+                    const t = world.getComponent(id, 'Transform');
+                    if (!t)
+                        return;
+                    const phase = (platformPhases.get(id) ?? 0) + dt * (Math.PI * 2) / duration;
+                    platformPhases.set(id, phase);
+                    const alpha = (Math.sin(phase) + 1) / 2; // 0..1
+                    t.x = x1 + (x2 - x1) * alpha;
+                    t.y = y1 + (y2 - y1) * alpha;
+                } })] }));
+}

package/dist/components/ParallaxLayer.js

@@ -0,0 +1,51 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useContext } from 'react';
+import { Entity } from './Entity';
+import { Transform } from './Transform';
+import { EngineContext, EntityContext } from '../context';
+function ParallaxLayerInner({ src, speedX, speedY, repeatX, repeatY, zIndex, offsetX, offsetY, }) {
+    const engine = useContext(EngineContext);
+    const entityId = useContext(EntityContext);
+    useEffect(() => {
+        engine.ecs.addComponent(entityId, {
+            type: 'ParallaxLayer',
+            src,
+            speedX,
+            speedY,
+            repeatX,
+            repeatY,
+            zIndex,
+            offsetX,
+            offsetY,
+            imageWidth: 0,
+            imageHeight: 0,
+        });
+        return () => engine.ecs.removeComponent(entityId, 'ParallaxLayer');
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // Sync prop changes
+    useEffect(() => {
+        const layer = engine.ecs.getComponent(entityId, 'ParallaxLayer');
+        if (!layer)
+            return;
+        layer.src = src;
+        layer.speedX = speedX;
+        layer.speedY = speedY;
+        layer.repeatX = repeatX;
+        layer.repeatY = repeatY;
+        layer.zIndex = zIndex;
+        layer.offsetX = offsetX;
+        layer.offsetY = offsetY;
+    }, [src, speedX, speedY, repeatX, repeatY, zIndex, offsetX, offsetY, engine, entityId]);
+    return null;
+}
+/**
+ * A background layer that scrolls at a fraction of the camera speed to create depth.
+ *
+ * @example
+ * <ParallaxLayer src="/bg/sky.png" speedX={0.2} repeatX />
+ * <ParallaxLayer src="/bg/mountains.png" speedX={0.5} repeatX zIndex={-5} />
+ */
+export function ParallaxLayer({ src, speedX = 0.5, speedY = 0, repeatX = true, repeatY = false, zIndex = -10, offsetX = 0, offsetY = 0, }) {
+    return (_jsxs(Entity, { children: [_jsx(Transform, { x: 0, y: 0 }), _jsx(ParallaxLayerInner, { src: src, speedX: speedX, speedY: speedY, repeatX: repeatX, repeatY: repeatY, zIndex: zIndex, offsetX: offsetX, offsetY: offsetY })] }));
+}

package/dist/components/ParticleEmitter.js

@@ -0,0 +1,44 @@
+import { useEffect, useContext } from 'react';
+import { EngineContext, EntityContext } from '../context';
+import { PARTICLE_PRESETS } from './particlePresets';
+export function ParticleEmitter({ active = true, preset, rate, speed, spread, angle, particleLife, particleSize, color, gravity, maxParticles, }) {
+    const presetConfig = preset ? PARTICLE_PRESETS[preset] : {};
+    const resolvedRate = rate ?? presetConfig.rate ?? 20;
+    const resolvedSpeed = speed ?? presetConfig.speed ?? 80;
+    const resolvedSpread = spread ?? presetConfig.spread ?? Math.PI;
+    const resolvedAngle = angle ?? presetConfig.angle ?? -Math.PI / 2;
+    const resolvedParticleLife = particleLife ?? presetConfig.particleLife ?? 0.8;
+    const resolvedParticleSize = particleSize ?? presetConfig.particleSize ?? 4;
+    const resolvedColor = color ?? presetConfig.color ?? '#ffffff';
+    const resolvedGravity = gravity ?? presetConfig.gravity ?? 200;
+    const resolvedMaxParticles = maxParticles ?? presetConfig.maxParticles ?? 100;
+    const engine = useContext(EngineContext);
+    const entityId = useContext(EntityContext);
+    useEffect(() => {
+        engine.ecs.addComponent(entityId, {
+            type: 'ParticlePool',
+            particles: [],
+            maxParticles: resolvedMaxParticles,
+            active,
+            rate: resolvedRate,
+            timer: 0,
+            speed: resolvedSpeed,
+            spread: resolvedSpread,
+            angle: resolvedAngle,
+            particleLife: resolvedParticleLife,
+            particleSize: resolvedParticleSize,
+            color: resolvedColor,
+            gravity: resolvedGravity,
+        });
+        return () => engine.ecs.removeComponent(entityId, 'ParticlePool');
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // Sync active state
+    useEffect(() => {
+        const pool = engine.ecs.getComponent(entityId, 'ParticlePool');
+        if (!pool)
+            return;
+        pool.active = active;
+    }, [active, engine, entityId]);
+    return null;
+}

package/dist/components/RigidBody.js

@@ -0,0 +1,13 @@
+import { useEffect, useContext } from 'react';
+import { createRigidBody } from '@cubeforge/physics';
+import { EngineContext, EntityContext } from '../context';
+export function RigidBody({ mass = 1, gravityScale = 1, isStatic = false, bounce = 0, friction = 0.85, vx = 0, vy = 0, }) {
+    const engine = useContext(EngineContext);
+    const entityId = useContext(EntityContext);
+    useEffect(() => {
+        engine.ecs.addComponent(entityId, createRigidBody({ mass, gravityScale, isStatic, bounce, friction, vx, vy }));
+        return () => engine.ecs.removeComponent(entityId, 'RigidBody');
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return null;
+}

package/dist/components/ScreenFlash.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef, useImperativeHandle, useRef } from 'react';
+export const ScreenFlash = forwardRef((_, ref) => {
+    const divRef = useRef(null);
+    useImperativeHandle(ref, () => ({
+        flash(color, duration) {
+            const el = divRef.current;
+            if (!el)
+                return;
+            el.style.backgroundColor = color;
+            el.style.opacity = '1';
+            el.style.transition = 'none';
+            const durationMs = duration * 1000;
+            // Next frame: start the fade
+            requestAnimationFrame(() => {
+                requestAnimationFrame(() => {
+                    if (!divRef.current)
+                        return;
+                    divRef.current.style.transition = `opacity ${durationMs}ms linear`;
+                    divRef.current.style.opacity = '0';
+                });
+            });
+        },
+    }));
+    return (_jsx("div", { ref: divRef, style: {
+            position: 'absolute',
+            inset: 0,
+            pointerEvents: 'none',
+            zIndex: 9999,
+            opacity: 0,
+            backgroundColor: 'transparent',
+        } }));
+});
+ScreenFlash.displayName = 'ScreenFlash';

package/dist/components/Script.js

@@ -0,0 +1,20 @@
+import { useEffect, useContext } from 'react';
+import { createScript } from '@cubeforge/core';
+import { EngineContext, EntityContext } from '../context';
+export function Script({ init, update }) {
+    const engine = useContext(EngineContext);
+    const entityId = useContext(EntityContext);
+    useEffect(() => {
+        if (init) {
+            try {
+                init(entityId, engine.ecs);
+            }
+            catch (err) {
+                console.error(`[Cubeforge] Script init error on entity ${entityId}:`, err);
+            }
+        }
+        engine.ecs.addComponent(entityId, createScript(update));
+        return () => engine.ecs.removeComponent(entityId, 'Script');
+    }, []); // eslint-disable-line react-hooks/exhaustive-deps
+    return null;
+}

package/dist/components/Sprite.js

@@ -0,0 +1,49 @@
+import { useEffect, useContext } from 'react';
+import { createSprite } from '@cubeforge/renderer';
+import { EngineContext, EntityContext } from '../context';
+export function Sprite({ width, height, color = '#ffffff', src, offsetX = 0, offsetY = 0, zIndex = 0, visible = true, flipX = false, anchorX = 0.5, anchorY = 0.5, frameIndex = 0, frameWidth, frameHeight, frameColumns, atlas, frame, }) {
+    const resolvedFrameIndex = (atlas && frame != null) ? (atlas[frame] ?? 0) : frameIndex;
+    const engine = useContext(EngineContext);
+    const entityId = useContext(EntityContext);
+    useEffect(() => {
+        const comp = createSprite({
+            width,
+            height,
+            color,
+            src,
+            offsetX,
+            offsetY,
+            zIndex,
+            visible,
+            flipX,
+            anchorX,
+            anchorY,
+            frameIndex: resolvedFrameIndex,
+            frameWidth,
+            frameHeight,
+            frameColumns,
+        });
+        engine.ecs.addComponent(entityId, comp);
+        if (src) {
+            engine.assets.loadImage(src).then((img) => {
+                const c = engine.ecs.getComponent(entityId, 'Sprite');
+                if (c)
+                    c.image = img;
+            }).catch(console.error);
+        }
+        return () => engine.ecs.removeComponent(entityId, 'Sprite');
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // Sync mutable props
+    useEffect(() => {
+        const comp = engine.ecs.getComponent(entityId, 'Sprite');
+        if (!comp)
+            return;
+        comp.color = color;
+        comp.visible = visible;
+        comp.flipX = flipX;
+        comp.zIndex = zIndex;
+        comp.frameIndex = resolvedFrameIndex;
+    }, [color, visible, flipX, zIndex, resolvedFrameIndex, engine, entityId]);
+    return null;
+}

package/dist/components/SquashStretch.js

@@ -0,0 +1,18 @@
+import { useEffect, useContext } from 'react';
+import { EngineContext, EntityContext } from '../context';
+export function SquashStretch({ intensity = 0.2, recovery = 8 }) {
+    const engine = useContext(EngineContext);
+    const entityId = useContext(EntityContext);
+    useEffect(() => {
+        engine.ecs.addComponent(entityId, {
+            type: 'SquashStretch',
+            intensity,
+            recovery,
+            currentScaleX: 1,
+            currentScaleY: 1,
+        });
+        return () => engine.ecs.removeComponent(entityId, 'SquashStretch');
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return null;
+}