cubeforge 0.0.5 → 0.0.6

package/dist/components/DevTools.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+import type { WorldSnapshot } from '@cubeforge/core';
+import type { ECSWorld, GameLoop } from '@cubeforge/core';
+export declare const MAX_DEVTOOLS_FRAMES = 600;
+export interface DevToolsHandle {
+    buffer: WorldSnapshot[];
+    onFrame?: () => void;
+}
+interface DevToolsProps {
+    handle: DevToolsHandle;
+    loop: GameLoop;
+    ecs: ECSWorld;
+}
+export declare function DevToolsOverlay({ handle, loop, ecs }: DevToolsProps): React.ReactPortal;
+export {};

package/dist/components/Game.d.ts

@@ -21,11 +21,17 @@ interface GameProps {
     scale?: 'none' | 'contain' | 'pixel';
     /** Called once the engine is ready — receives pause/resume/reset controls */
     onReady?: (controls: GameControls) => void;
+    /** Enable time-travel debugging overlay (frame scrubber + entity inspector). */
+    devtools?: boolean;
+    /** Run the simulation in deterministic mode using a seeded RNG. */
+    deterministic?: boolean;
+    /** Seed for the deterministic RNG (default 0). Only used when deterministic=true. */
+    seed?: number;
     /** Custom plugins to register after core systems. Each plugin's systems run after Render. */
     plugins?: Plugin[];
     style?: CSSProperties;
     className?: string;
     children?: React.ReactNode;
 }
-export declare function Game({ width, height, gravity, debug, scale, onReady, plugins, style, className, children, }: GameProps): import("react/jsx-runtime").JSX.Element;
+export declare function Game({ width, height, gravity, debug, devtools, scale, deterministic, seed, onReady, plugins, style, className, children, }: GameProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/index.d.ts

@@ -27,9 +27,10 @@ export type { SpriteAtlas } from './components/spriteAtlas';
 export { createAtlas } from './components/spriteAtlas';
 export type { EngineState } from './context';
 export type { GameControls } from './components/Game';
+export type { DevToolsHandle } from './components/DevTools';
 export type { PlatformerControllerOptions } from './hooks/usePlatformerController';
 export type { TopDownMovementOptions } from './hooks/useTopDownMovement';
-export type { EntityId, ECSWorld, ScriptUpdateFn, Plugin } from '@cubeforge/core';
+export type { EntityId, ECSWorld, ScriptUpdateFn, Plugin, WorldSnapshot } from '@cubeforge/core';
 export { definePlugin } from '@cubeforge/core';
 export type { InputManager } from '@cubeforge/input';
 export type { TransformComponent } from '@cubeforge/core';

package/dist/index.js

@@ -1,48 +1,94 @@
 // src/components/Game.tsx
-import { useEffect, useRef, useState } from "react";
+import { useEffect as useEffect2, useRef, useState as useState2 } from "react";
 // ../core/src/ecs/world.ts
 class ECSWorld {
   nextId = 0;
-  entities = new Set;
-  components = new Map;
+  componentIndex = new Map;
+  _rngState = 0;
+  _deterministic = false;
+  archetypes = new Map;
+  entityArchetype = new Map;
   systems = [];
   queryCache = new Map;
   dirtyTypes = new Set;
   dirtyAll = false;
+  getOrCreateArchetype(types) {
+    const arr = [...types].sort();
+    const key = arr.join("\x00");
+    let arch = this.archetypes.get(key);
+    if (!arch) {
+      arch = { key, types: new Set(arr), entities: [] };
+      this.archetypes.set(key, arch);
+    }
+    return arch;
+  }
+  moveToArchetype(id, newArch) {
+    const oldKey = this.entityArchetype.get(id);
+    if (oldKey !== undefined) {
+      const oldArch = this.archetypes.get(oldKey);
+      if (oldArch) {
+        const idx = oldArch.entities.indexOf(id);
+        if (idx !== -1)
+          oldArch.entities.splice(idx, 1);
+      }
+    }
+    newArch.entities.push(id);
+    this.entityArchetype.set(id, newArch.key);
+  }
   createEntity() {
     const id = this.nextId++;
-    this.entities.add(id);
-    this.components.set(id, new Map);
+    this.componentIndex.set(id, new Map);
+    const emptyArch = this.getOrCreateArchetype([]);
+    emptyArch.entities.push(id);
+    this.entityArchetype.set(id, emptyArch.key);
     this.dirtyAll = true;
     return id;
   }
   destroyEntity(id) {
-    const comps = this.components.get(id);
+    const comps = this.componentIndex.get(id);
     if (comps) {
-      for (const type of comps.keys()) {
+      for (const type of comps.keys())
         this.dirtyTypes.add(type);
+    }
+    const archKey = this.entityArchetype.get(id);
+    if (archKey !== undefined) {
+      const arch = this.archetypes.get(archKey);
+      if (arch) {
+        const idx = arch.entities.indexOf(id);
+        if (idx !== -1)
+          arch.entities.splice(idx, 1);
       }
     }
-    this.entities.delete(id);
-    this.components.delete(id);
+    this.componentIndex.delete(id);
+    this.entityArchetype.delete(id);
     this.dirtyAll = true;
   }
   hasEntity(id) {
-    return this.entities.has(id);
+    return this.componentIndex.has(id);
   }
   addComponent(id, component) {
-    this.components.get(id)?.set(component.type, component);
+    const comps = this.componentIndex.get(id);
+    if (!comps)
+      return;
+    comps.set(component.type, component);
     this.dirtyTypes.add(component.type);
+    const newArch = this.getOrCreateArchetype(comps.keys());
+    this.moveToArchetype(id, newArch);
   }
   removeComponent(id, type) {
-    this.components.get(id)?.delete(type);
+    const comps = this.componentIndex.get(id);
+    if (!comps)
+      return;
+    comps.delete(type);
     this.dirtyTypes.add(type);
+    const newArch = this.getOrCreateArchetype(comps.keys());
+    this.moveToArchetype(id, newArch);
   }
   getComponent(id, type) {
-    return this.components.get(id)?.get(type);
+    return this.componentIndex.get(id)?.get(type);
   }
   hasComponent(id, type) {
-    return this.components.get(id)?.has(type) ?? false;
+    return this.componentIndex.get(id)?.has(type) ?? false;
   }
   query(...types) {
     const key = types.slice().sort().join("\x00");
@@ -50,36 +96,60 @@ class ECSWorld {
     if (cached)
       return cached;
     const result = [];
-    for (const id of this.entities) {
-      const comps = this.components.get(id);
-      let match = true;
-      for (const t of types) {
-        if (!comps.has(t)) {
-          match = false;
-          break;
-        }
+    for (const arch of this.archetypes.values()) {
+      if (types.every((t) => arch.types.has(t))) {
+        for (const id of arch.entities)
+          result.push(id);
       }
-      if (match)
-        result.push(id);
     }
     this.queryCache.set(key, result);
     return result;
   }
   queryOne(...types) {
-    for (const id of this.entities) {
-      const comps = this.components.get(id);
-      let match = true;
-      for (const t of types) {
-        if (!comps.has(t)) {
-          match = false;
-          break;
-        }
+    for (const arch of this.archetypes.values()) {
+      if (types.every((t) => arch.types.has(t))) {
+        if (arch.entities.length > 0)
+          return arch.entities[0];
       }
-      if (match)
-        return id;
     }
     return;
   }
+  setDeterministicSeed(seed) {
+    this._rngState = seed >>> 0;
+    this._deterministic = true;
+  }
+  rng() {
+    if (!this._deterministic)
+      return Math.random();
+    this._rngState = Math.imul(this._rngState, 1664525) + 1013904223 >>> 0;
+    return this._rngState / 4294967296;
+  }
+  getSnapshot() {
+    const entities = [];
+    for (const [id, comps] of this.componentIndex) {
+      const components = [];
+      for (const comp of comps.values()) {
+        components.push(JSON.parse(JSON.stringify(comp)));
+      }
+      entities.push({ id, components });
+    }
+    return { nextId: this.nextId, rngState: this._rngState, entities };
+  }
+  restoreSnapshot(snapshot) {
+    this.clear();
+    this.nextId = snapshot.nextId;
+    this._rngState = snapshot.rngState;
+    for (const { id, components } of snapshot.entities) {
+      const compMap = new Map;
+      for (const comp of components)
+        compMap.set(comp.type, comp);
+      this.componentIndex.set(id, compMap);
+      const arch = this.getOrCreateArchetype(compMap.keys());
+      arch.entities.push(id);
+      this.entityArchetype.set(id, arch.key);
+    }
+    this.dirtyAll = true;
+  }
   addSystem(system) {
     this.systems.push(system);
   }
@@ -110,15 +180,18 @@ class ECSWorld {
     }
   }
   clear() {
-    this.entities.clear();
-    this.components.clear();
+    this.componentIndex.clear();
+    this.archetypes.clear();
+    this.entityArchetype.clear();
     this.queryCache.clear();
     this.dirtyTypes.clear();
     this.dirtyAll = false;
     this.nextId = 0;
+    this._rngState = 0;
+    this._deterministic = false;
   }
   get entityCount() {
-    return this.entities.size;
+    return this.componentIndex.size;
   }
 }
 // ../core/src/loop/gameLoop.ts
@@ -673,8 +746,8 @@ class RenderSystem {
         if (cam.shakeTimer < 0)
           cam.shakeTimer = 0;
         const progress = cam.shakeDuration > 0 ? cam.shakeTimer / cam.shakeDuration : 0;
-        shakeX = (Math.random() * 2 - 1) * cam.shakeIntensity * progress;
-        shakeY = (Math.random() * 2 - 1) * cam.shakeIntensity * progress;
+        shakeX = (world2.rng() * 2 - 1) * cam.shakeIntensity * progress;
+        shakeY = (world2.rng() * 2 - 1) * cam.shakeIntensity * progress;
       }
       camX = cam.x;
       camY = cam.y;
@@ -755,10 +828,27 @@ class RenderSystem {
     ctx.translate(canvas.width / 2 - camX * zoom + shakeX, canvas.height / 2 - camY * zoom + shakeY);
     ctx.scale(zoom, zoom);
     const renderables = world2.query("Transform", "Sprite");
+    const textureKey = (id) => {
+      const sprite = world2.getComponent(id, "Sprite");
+      if (sprite.image && sprite.image.src)
+        return sprite.image.src;
+      if (sprite.src)
+        return sprite.src;
+      return `__color__:${sprite.color}`;
+    };
     renderables.sort((a, b) => {
-      const za = world2.getComponent(a, "Sprite").zIndex;
-      const zb = world2.getComponent(b, "Sprite").zIndex;
-      return za - zb;
+      const sa = world2.getComponent(a, "Sprite");
+      const sb = world2.getComponent(b, "Sprite");
+      const zDiff = sa.zIndex - sb.zIndex;
+      if (zDiff !== 0)
+        return zDiff;
+      const ka = textureKey(a);
+      const kb = textureKey(b);
+      if (ka < kb)
+        return -1;
+      if (ka > kb)
+        return 1;
+      return 0;
     });
     for (const id of renderables) {
       const transform2 = world2.getComponent(id, "Transform");
@@ -809,8 +899,8 @@ class RenderSystem {
         const spawnCount = Math.floor(pool.timer * pool.rate);
         pool.timer -= spawnCount / pool.rate;
         for (let i = 0;i < spawnCount && pool.particles.length < pool.maxParticles; i++) {
-          const angle = pool.angle + (Math.random() - 0.5) * pool.spread;
-          const speed = pool.speed * (0.5 + Math.random() * 0.5);
+          const angle = pool.angle + (world2.rng() - 0.5) * pool.spread;
+          const speed = pool.speed * (0.5 + world2.rng() * 0.5);
           pool.particles.push({
             x: t.x,
             y: t.y,
@@ -1253,14 +1343,318 @@ class DebugSystem {
   }
 }
 
+// src/components/DevTools.tsx
+import React from "react";
+import { createPortal } from "react-dom";
+import { useState, useEffect, useCallback } from "react";
+import { jsxDEV, Fragment } from "react/jsx-dev-runtime";
+var MAX_DEVTOOLS_FRAMES = 600;
+var css = {
+  overlay: {
+    position: "fixed",
+    bottom: 0,
+    left: 0,
+    right: 0,
+    zIndex: 99999,
+    fontFamily: "'JetBrains Mono', 'Fira Code', 'Courier New', monospace",
+    fontSize: 11,
+    color: "#cdd6f4",
+    userSelect: "none",
+    pointerEvents: "auto"
+  },
+  bar: {
+    background: "rgba(11,13,20,0.97)",
+    borderTop: "1px solid #2a3048",
+    padding: "6px 12px",
+    display: "flex",
+    alignItems: "center",
+    gap: 10,
+    height: 40
+  },
+  badge: {
+    fontSize: 9,
+    fontWeight: 700,
+    letterSpacing: "0.1em",
+    color: "#4fc3f7",
+    background: "rgba(79,195,247,0.1)",
+    border: "1px solid rgba(79,195,247,0.2)",
+    borderRadius: 4,
+    padding: "2px 6px",
+    flexShrink: 0
+  },
+  btn: (active = false, danger = false) => ({
+    background: active ? "rgba(79,195,247,0.15)" : "rgba(255,255,255,0.04)",
+    border: `1px solid ${active ? "rgba(79,195,247,0.3)" : "#2a3048"}`,
+    borderRadius: 4,
+    color: danger ? "#f38ba8" : active ? "#4fc3f7" : "#6b7a9e",
+    cursor: "pointer",
+    padding: "3px 8px",
+    fontSize: 10,
+    fontFamily: "inherit",
+    display: "flex",
+    alignItems: "center",
+    gap: 4,
+    transition: "all 0.1s",
+    flexShrink: 0
+  }),
+  scrubber: {
+    flex: 1,
+    accentColor: "#4fc3f7",
+    cursor: "pointer",
+    height: 4
+  },
+  counter: {
+    color: "#6b7a9e",
+    fontSize: 10,
+    whiteSpace: "nowrap",
+    flexShrink: 0,
+    minWidth: 80,
+    textAlign: "right"
+  },
+  panel: {
+    background: "rgba(11,13,20,0.97)",
+    borderTop: "1px solid #1f2435",
+    maxHeight: 260,
+    overflowY: "auto",
+    padding: "8px 0"
+  },
+  entityRow: (selected) => ({
+    display: "flex",
+    alignItems: "center",
+    gap: 8,
+    padding: "4px 12px",
+    cursor: "pointer",
+    background: selected ? "rgba(79,195,247,0.06)" : "transparent",
+    borderLeft: `2px solid ${selected ? "#4fc3f7" : "transparent"}`
+  }),
+  entityId: {
+    color: "#4fc3f7",
+    minWidth: 28,
+    fontSize: 10
+  },
+  compPill: {
+    fontSize: 9,
+    background: "rgba(79,195,247,0.08)",
+    border: "1px solid rgba(79,195,247,0.12)",
+    borderRadius: 3,
+    padding: "1px 5px",
+    color: "#6b7a9e"
+  },
+  detailPanel: {
+    background: "rgba(18,21,31,0.98)",
+    borderTop: "1px solid #1f2435",
+    padding: "10px 14px",
+    maxHeight: 200,
+    overflowY: "auto"
+  },
+  kv: {
+    display: "grid",
+    gridTemplateColumns: "140px 1fr",
+    gap: "2px 12px",
+    lineHeight: 1.8
+  },
+  key: { color: "#6b7a9e" },
+  val: { color: "#cdd6f4" }
+};
+function DevToolsOverlay({ handle, loop, ecs }) {
+  const [, forceUpdate] = useState(0);
+  const [paused, setPaused] = useState(false);
+  const [selectedIdx, setSelectedIdx] = useState(0);
+  const [panelOpen, setPanelOpen] = useState(false);
+  const [selectedEntity, setSelectedEntity] = useState(null);
+  useEffect(() => {
+    handle.onFrame = () => {
+      if (!paused) {
+        forceUpdate((n) => n + 1);
+        setSelectedIdx(Math.max(0, handle.buffer.length - 1));
+      }
+    };
+    return () => {
+      handle.onFrame = undefined;
+    };
+  }, [handle, paused]);
+  const totalFrames = handle.buffer.length;
+  const currentSnap = handle.buffer[selectedIdx];
+  const handlePauseResume = useCallback(() => {
+    if (paused) {
+      if (currentSnap)
+        ecs.restoreSnapshot(currentSnap);
+      loop.resume();
+      setPaused(false);
+      setSelectedEntity(null);
+    } else {
+      loop.pause();
+      setPaused(true);
+      setSelectedIdx(Math.max(0, handle.buffer.length - 1));
+    }
+  }, [paused, currentSnap, ecs, loop, handle]);
+  const stepBack = useCallback(() => {
+    setSelectedIdx((i) => Math.max(0, i - 1));
+    setSelectedEntity(null);
+  }, []);
+  const stepForward = useCallback(() => {
+    setSelectedIdx((i) => Math.min(handle.buffer.length - 1, i + 1));
+    setSelectedEntity(null);
+  }, [handle]);
+  const frameLabel = totalFrames === 0 ? "0 / 0" : `${selectedIdx + 1} / ${totalFrames}`;
+  const entities = currentSnap?.entities ?? [];
+  const selectedEntityData = selectedEntity !== null ? entities.find((e) => e.id === selectedEntity) : null;
+  return createPortal(/* @__PURE__ */ jsxDEV("div", {
+    style: css.overlay,
+    children: [
+      panelOpen && paused && /* @__PURE__ */ jsxDEV(Fragment, {
+        children: [
+          /* @__PURE__ */ jsxDEV("div", {
+            style: css.panel,
+            children: [
+              entities.length === 0 && /* @__PURE__ */ jsxDEV("div", {
+                style: { padding: "4px 14px", color: "#3d4666" },
+                children: "No entities"
+              }, undefined, false, undefined, this),
+              entities.map((e) => /* @__PURE__ */ jsxDEV("div", {
+                style: css.entityRow(selectedEntity === e.id),
+                onClick: () => setSelectedEntity((s) => s === e.id ? null : e.id),
+                children: [
+                  /* @__PURE__ */ jsxDEV("span", {
+                    style: css.entityId,
+                    children: [
+                      "#",
+                      e.id
+                    ]
+                  }, undefined, true, undefined, this),
+                  /* @__PURE__ */ jsxDEV("div", {
+                    style: { display: "flex", gap: 4, flexWrap: "wrap" },
+                    children: e.components.map((c) => /* @__PURE__ */ jsxDEV("span", {
+                      style: css.compPill,
+                      children: c.type
+                    }, c.type, false, undefined, this))
+                  }, undefined, false, undefined, this)
+                ]
+              }, e.id, true, undefined, this))
+            ]
+          }, undefined, true, undefined, this),
+          selectedEntityData && /* @__PURE__ */ jsxDEV("div", {
+            style: css.detailPanel,
+            children: selectedEntityData.components.map((comp) => /* @__PURE__ */ jsxDEV("div", {
+              style: { marginBottom: 10 },
+              children: [
+                /* @__PURE__ */ jsxDEV("div", {
+                  style: { color: "#4fc3f7", fontSize: 10, fontWeight: 700, marginBottom: 4 },
+                  children: comp.type
+                }, undefined, false, undefined, this),
+                /* @__PURE__ */ jsxDEV("div", {
+                  style: css.kv,
+                  children: Object.entries(comp).filter(([k]) => k !== "type").map(([k, v]) => /* @__PURE__ */ jsxDEV(React.Fragment, {
+                    children: [
+                      /* @__PURE__ */ jsxDEV("span", {
+                        style: css.key,
+                        children: k
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV("span", {
+                        style: css.val,
+                        children: formatValue(v)
+                      }, undefined, false, undefined, this)
+                    ]
+                  }, k, true, undefined, this))
+                }, undefined, false, undefined, this)
+              ]
+            }, comp.type, true, undefined, this))
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV("div", {
+        style: css.bar,
+        children: [
+          /* @__PURE__ */ jsxDEV("span", {
+            style: css.badge,
+            children: "DEVTOOLS"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV("button", {
+            style: css.btn(paused),
+            onClick: handlePauseResume,
+            children: paused ? "▶ Resume" : "⏸ Pause"
+          }, undefined, false, undefined, this),
+          paused && /* @__PURE__ */ jsxDEV(Fragment, {
+            children: [
+              /* @__PURE__ */ jsxDEV("button", {
+                style: css.btn(),
+                onClick: stepBack,
+                children: "◀◀"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV("button", {
+                style: css.btn(),
+                onClick: stepForward,
+                children: "▶▶"
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV("input", {
+            type: "range",
+            min: 0,
+            max: Math.max(0, totalFrames - 1),
+            value: selectedIdx,
+            style: css.scrubber,
+            onChange: (e) => {
+              const idx = Number(e.target.value);
+              setSelectedIdx(idx);
+              setSelectedEntity(null);
+              if (!paused) {
+                loop.pause();
+                setPaused(true);
+              }
+            }
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV("span", {
+            style: css.counter,
+            children: frameLabel
+          }, undefined, false, undefined, this),
+          paused && /* @__PURE__ */ jsxDEV("button", {
+            style: css.btn(panelOpen),
+            onClick: () => setPanelOpen((o) => !o),
+            children: [
+              panelOpen ? "▾" : "▸",
+              " Entities (",
+              entities.length,
+              ")"
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV("button", {
+            style: css.btn(false, true),
+            onClick: () => {
+              handle.buffer.length = 0;
+              setSelectedIdx(0);
+              forceUpdate((n) => n + 1);
+            },
+            children: "Clear"
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this)
+    ]
+  }, undefined, true, undefined, this), document.body);
+}
+function formatValue(v) {
+  if (typeof v === "number")
+    return v.toFixed(2);
+  if (typeof v === "boolean")
+    return v ? "true" : "false";
+  if (v === null || v === undefined)
+    return "—";
+  if (typeof v === "object")
+    return JSON.stringify(v).slice(0, 60);
+  return String(v);
+}
+
 // src/components/Game.tsx
-import { jsxDEV } from "react/jsx-dev-runtime";
+import { jsxDEV as jsxDEV2 } from "react/jsx-dev-runtime";
 function Game({
   width = 800,
   height = 600,
   gravity = 980,
   debug = false,
+  devtools = false,
   scale = "none",
+  deterministic = false,
+  seed = 0,
   onReady,
   plugins,
   style,
@@ -1269,10 +1663,13 @@ function Game({
 }) {
   const canvasRef = useRef(null);
   const wrapperRef = useRef(null);
-  const [engine, setEngine] = useState(null);
-  useEffect(() => {
+  const [engine, setEngine] = useState2(null);
+  const devtoolsHandle = useRef({ buffer: [] });
+  useEffect2(() => {
     const canvas = canvasRef.current;
     const ecs = new ECSWorld;
+    if (deterministic)
+      ecs.setDeterministicSeed(seed);
     const input = new InputManager;
     const renderer = new Canvas2DRenderer(canvas);
     const events = new EventBus;
@@ -1294,6 +1691,13 @@ function Game({
     const loop = new GameLoop((dt) => {
       ecs.update(dt);
       input.flush();
+      if (devtools) {
+        const handle = devtoolsHandle.current;
+        handle.buffer.push(ecs.getSnapshot());
+        if (handle.buffer.length > MAX_DEVTOOLS_FRAMES)
+          handle.buffer.shift();
+        handle.onFrame?.();
+      }
     });
     const state = { ecs, input, renderer, physics, events, assets, loop, canvas, entityIds };
     setEngine(state);
@@ -1339,7 +1743,7 @@ function Game({
       resizeObserver?.disconnect();
     };
   }, []);
-  useEffect(() => {
+  useEffect2(() => {
     engine?.physics.setGravity(gravity);
   }, [gravity, engine]);
   const canvasStyle = {
@@ -1349,13 +1753,13 @@ function Game({
     ...style
   };
   const wrapperStyle = scale === "contain" ? { position: "relative", width, height, overflow: "visible" } : {};
-  return /* @__PURE__ */ jsxDEV(EngineContext.Provider, {
+  return /* @__PURE__ */ jsxDEV2(EngineContext.Provider, {
     value: engine,
     children: [
-      /* @__PURE__ */ jsxDEV("div", {
+      /* @__PURE__ */ jsxDEV2("div", {
         ref: wrapperRef,
         style: wrapperStyle,
-        children: /* @__PURE__ */ jsxDEV("canvas", {
+        children: /* @__PURE__ */ jsxDEV2("canvas", {
           ref: canvasRef,
           width,
           height,
@@ -1363,22 +1767,27 @@ function Game({
           className
         }, undefined, false, undefined, this)
       }, undefined, false, undefined, this),
-      engine && children
+      engine && children,
+      engine && devtools && /* @__PURE__ */ jsxDEV2(DevToolsOverlay, {
+        handle: devtoolsHandle.current,
+        loop: engine.loop,
+        ecs: engine.ecs
+      }, undefined, false, undefined, this)
     ]
   }, undefined, true, undefined, this);
 }
 // src/components/World.tsx
-import { useEffect as useEffect2, useContext } from "react";
-import { jsxDEV as jsxDEV2, Fragment } from "react/jsx-dev-runtime";
+import { useEffect as useEffect3, useContext } from "react";
+import { jsxDEV as jsxDEV3, Fragment as Fragment2 } from "react/jsx-dev-runtime";
 function World({ gravity, background = "#1a1a2e", children }) {
   const engine = useContext(EngineContext);
-  useEffect2(() => {
+  useEffect3(() => {
     if (!engine)
       return;
     if (gravity !== undefined)
       engine.physics.setGravity(gravity);
   }, [gravity, engine]);
-  useEffect2(() => {
+  useEffect3(() => {
     if (!engine)
       return;
     const camId = engine.ecs.queryOne("Camera2D");
@@ -1390,17 +1799,17 @@ function World({ gravity, background = "#1a1a2e", children }) {
       engine.canvas.style.background = background;
     }
   }, [background, engine]);
-  return /* @__PURE__ */ jsxDEV2(Fragment, {
+  return /* @__PURE__ */ jsxDEV3(Fragment2, {
     children
   }, undefined, false, undefined, this);
 }
 // src/components/Entity.tsx
-import { useEffect as useEffect3, useContext as useContext2, useState as useState2 } from "react";
-import { jsxDEV as jsxDEV3 } from "react/jsx-dev-runtime";
+import { useEffect as useEffect4, useContext as useContext2, useState as useState3 } from "react";
+import { jsxDEV as jsxDEV4 } from "react/jsx-dev-runtime";
 function Entity({ id, tags = [], children }) {
   const engine = useContext2(EngineContext);
-  const [entityId, setEntityId] = useState2(null);
-  useEffect3(() => {
+  const [entityId, setEntityId] = useState3(null);
+  useEffect4(() => {
     const eid = engine.ecs.createEntity();
     if (id) {
       if (engine.entityIds.has(id)) {
@@ -1419,21 +1828,21 @@ function Entity({ id, tags = [], children }) {
   }, []);
   if (entityId === null)
     return null;
-  return /* @__PURE__ */ jsxDEV3(EntityContext.Provider, {
+  return /* @__PURE__ */ jsxDEV4(EntityContext.Provider, {
     value: entityId,
     children
   }, undefined, false, undefined, this);
 }
 // src/components/Transform.tsx
-import { useEffect as useEffect4, useContext as useContext3 } from "react";
+import { useEffect as useEffect5, useContext as useContext3 } from "react";
 function Transform({ x = 0, y = 0, rotation = 0, scaleX = 1, scaleY = 1 }) {
   const engine = useContext3(EngineContext);
   const entityId = useContext3(EntityContext);
-  useEffect4(() => {
+  useEffect5(() => {
     engine.ecs.addComponent(entityId, createTransform(x, y, rotation, scaleX, scaleY));
     return () => engine.ecs.removeComponent(entityId, "Transform");
   }, []);
-  useEffect4(() => {
+  useEffect5(() => {
     const comp = engine.ecs.getComponent(entityId, "Transform");
     if (comp) {
       comp.x = x;
@@ -1446,7 +1855,7 @@ function Transform({ x = 0, y = 0, rotation = 0, scaleX = 1, scaleY = 1 }) {
   return null;
 }
 // src/components/Sprite.tsx
-import { useEffect as useEffect5, useContext as useContext4 } from "react";
+import { useEffect as useEffect6, useContext as useContext4 } from "react";
 function Sprite({
   width,
   height,
@@ -1469,7 +1878,7 @@ function Sprite({
   const resolvedFrameIndex = atlas && frame != null ? atlas[frame] ?? 0 : frameIndex;
   const engine = useContext4(EngineContext);
   const entityId = useContext4(EntityContext);
-  useEffect5(() => {
+  useEffect6(() => {
     const comp = createSprite({
       width,
       height,
@@ -1497,7 +1906,7 @@ function Sprite({
     }
     return () => engine.ecs.removeComponent(entityId, "Sprite");
   }, []);
-  useEffect5(() => {
+  useEffect6(() => {
     const comp = engine.ecs.getComponent(entityId, "Sprite");
     if (!comp)
       return;
@@ -1510,7 +1919,7 @@ function Sprite({
   return null;
 }
 // src/components/RigidBody.tsx
-import { useEffect as useEffect6, useContext as useContext5 } from "react";
+import { useEffect as useEffect7, useContext as useContext5 } from "react";
 function RigidBody({
   mass = 1,
   gravityScale = 1,
@@ -1522,14 +1931,14 @@ function RigidBody({
 }) {
   const engine = useContext5(EngineContext);
   const entityId = useContext5(EntityContext);
-  useEffect6(() => {
+  useEffect7(() => {
     engine.ecs.addComponent(entityId, createRigidBody({ mass, gravityScale, isStatic, bounce, friction, vx, vy }));
     return () => engine.ecs.removeComponent(entityId, "RigidBody");
   }, []);
   return null;
 }
 // src/components/BoxCollider.tsx
-import { useEffect as useEffect7, useContext as useContext6 } from "react";
+import { useEffect as useEffect8, useContext as useContext6 } from "react";
 function BoxCollider({
   width,
   height,
@@ -1540,7 +1949,7 @@ function BoxCollider({
 }) {
   const engine = useContext6(EngineContext);
   const entityId = useContext6(EntityContext);
-  useEffect7(() => {
+  useEffect8(() => {
     engine.ecs.addComponent(entityId, createBoxCollider(width, height, { offsetX, offsetY, isTrigger, layer }));
     const checkId = setTimeout(() => {
       if (engine.ecs.hasEntity(entityId) && !engine.ecs.hasComponent(entityId, "Transform")) {
@@ -1555,11 +1964,11 @@ function BoxCollider({
   return null;
 }
 // src/components/Script.tsx
-import { useEffect as useEffect8, useContext as useContext7 } from "react";
+import { useEffect as useEffect9, useContext as useContext7 } from "react";
 function Script({ init, update }) {
   const engine = useContext7(EngineContext);
   const entityId = useContext7(EntityContext);
-  useEffect8(() => {
+  useEffect9(() => {
     if (init) {
       try {
         init(entityId, engine.ecs);
@@ -1573,7 +1982,7 @@ function Script({ init, update }) {
   return null;
 }
 // src/components/Camera2D.tsx
-import { useEffect as useEffect9, useContext as useContext8 } from "react";
+import { useEffect as useEffect10, useContext as useContext8 } from "react";
 function Camera2D({
   followEntity,
   zoom = 1,
@@ -1583,7 +1992,7 @@ function Camera2D({
   deadZone
 }) {
   const engine = useContext8(EngineContext);
-  useEffect9(() => {
+  useEffect10(() => {
     const entityId = engine.ecs.createEntity();
     engine.ecs.addComponent(entityId, createCamera2D({
       followEntityId: followEntity,
@@ -1595,7 +2004,7 @@ function Camera2D({
     }));
     return () => engine.ecs.destroyEntity(entityId);
   }, []);
-  useEffect9(() => {
+  useEffect10(() => {
     const camId = engine.ecs.queryOne("Camera2D");
     if (camId === undefined)
       return;
@@ -1610,11 +2019,11 @@ function Camera2D({
   return null;
 }
 // src/components/Animation.tsx
-import { useEffect as useEffect10, useContext as useContext9 } from "react";
+import { useEffect as useEffect11, useContext as useContext9 } from "react";
 function Animation({ frames, fps = 12, loop = true, playing = true }) {
   const engine = useContext9(EngineContext);
   const entityId = useContext9(EntityContext);
-  useEffect10(() => {
+  useEffect11(() => {
     const state = {
       type: "AnimationState",
       frames,
@@ -1629,7 +2038,7 @@ function Animation({ frames, fps = 12, loop = true, playing = true }) {
       engine.ecs.removeComponent(entityId, "AnimationState");
     };
   }, []);
-  useEffect10(() => {
+  useEffect11(() => {
     const anim = engine.ecs.getComponent(entityId, "AnimationState");
     if (!anim)
       return;
@@ -1640,11 +2049,11 @@ function Animation({ frames, fps = 12, loop = true, playing = true }) {
   return null;
 }
 // src/components/SquashStretch.tsx
-import { useEffect as useEffect11, useContext as useContext10 } from "react";
+import { useEffect as useEffect12, useContext as useContext10 } from "react";
 function SquashStretch({ intensity = 0.2, recovery = 8 }) {
   const engine = useContext10(EngineContext);
   const entityId = useContext10(EntityContext);
-  useEffect11(() => {
+  useEffect12(() => {
     engine.ecs.addComponent(entityId, {
       type: "SquashStretch",
       intensity,
@@ -1657,7 +2066,7 @@ function SquashStretch({ intensity = 0.2, recovery = 8 }) {
   return null;
 }
 // src/components/ParticleEmitter.tsx
-import { useEffect as useEffect12, useContext as useContext11 } from "react";
+import { useEffect as useEffect13, useContext as useContext11 } from "react";
 
 // src/components/particlePresets.ts
 var PARTICLE_PRESETS = {
@@ -1744,7 +2153,7 @@ function ParticleEmitter({
   const resolvedMaxParticles = maxParticles ?? presetConfig.maxParticles ?? 100;
   const engine = useContext11(EngineContext);
   const entityId = useContext11(EntityContext);
-  useEffect12(() => {
+  useEffect13(() => {
     engine.ecs.addComponent(entityId, {
       type: "ParticlePool",
       particles: [],
@@ -1762,7 +2171,7 @@ function ParticleEmitter({
     });
     return () => engine.ecs.removeComponent(entityId, "ParticlePool");
   }, []);
-  useEffect12(() => {
+  useEffect13(() => {
     const pool = engine.ecs.getComponent(entityId, "ParticlePool");
     if (!pool)
       return;
@@ -1771,7 +2180,7 @@ function ParticleEmitter({
   return null;
 }
 // src/components/MovingPlatform.tsx
-import { jsxDEV as jsxDEV4 } from "react/jsx-dev-runtime";
+import { jsxDEV as jsxDEV5 } from "react/jsx-dev-runtime";
 var platformPhases = new Map;
 function MovingPlatform({
   x1,
@@ -1783,26 +2192,26 @@ function MovingPlatform({
   duration = 3,
   color = "#37474f"
 }) {
-  return /* @__PURE__ */ jsxDEV4(Entity, {
+  return /* @__PURE__ */ jsxDEV5(Entity, {
     children: [
-      /* @__PURE__ */ jsxDEV4(Transform, {
+      /* @__PURE__ */ jsxDEV5(Transform, {
         x: x1,
         y: y1
       }, undefined, false, undefined, this),
-      /* @__PURE__ */ jsxDEV4(Sprite, {
+      /* @__PURE__ */ jsxDEV5(Sprite, {
         width,
         height,
         color,
         zIndex: 5
       }, undefined, false, undefined, this),
-      /* @__PURE__ */ jsxDEV4(RigidBody, {
+      /* @__PURE__ */ jsxDEV5(RigidBody, {
         isStatic: true
       }, undefined, false, undefined, this),
-      /* @__PURE__ */ jsxDEV4(BoxCollider, {
+      /* @__PURE__ */ jsxDEV5(BoxCollider, {
         width,
         height
       }, undefined, false, undefined, this),
-      /* @__PURE__ */ jsxDEV4(Script, {
+      /* @__PURE__ */ jsxDEV5(Script, {
         init: () => {},
         update: (id, world2, _input, dt) => {
           if (!world2.hasEntity(id))
@@ -1821,7 +2230,7 @@ function MovingPlatform({
   }, undefined, true, undefined, this);
 }
 // src/components/Checkpoint.tsx
-import { jsxDEV as jsxDEV5 } from "react/jsx-dev-runtime";
+import { jsxDEV as jsxDEV6 } from "react/jsx-dev-runtime";
 function Checkpoint({
   x,
   y,
@@ -1830,25 +2239,25 @@ function Checkpoint({
   color = "#ffd54f",
   onActivate
 }) {
-  return /* @__PURE__ */ jsxDEV5(Entity, {
+  return /* @__PURE__ */ jsxDEV6(Entity, {
     tags: ["checkpoint"],
     children: [
-      /* @__PURE__ */ jsxDEV5(Transform, {
+      /* @__PURE__ */ jsxDEV6(Transform, {
         x,
         y
       }, undefined, false, undefined, this),
-      /* @__PURE__ */ jsxDEV5(Sprite, {
+      /* @__PURE__ */ jsxDEV6(Sprite, {
         width,
         height,
         color,
         zIndex: 5
       }, undefined, false, undefined, this),
-      /* @__PURE__ */ jsxDEV5(BoxCollider, {
+      /* @__PURE__ */ jsxDEV6(BoxCollider, {
         width,
         height,
         isTrigger: true
       }, undefined, false, undefined, this),
-      /* @__PURE__ */ jsxDEV5(Script, {
+      /* @__PURE__ */ jsxDEV6(Script, {
         init: () => {},
         update: (id, world2) => {
           if (!world2.hasEntity(id))
@@ -1877,8 +2286,8 @@ function Checkpoint({
   }, undefined, true, undefined, this);
 }
 // src/components/Tilemap.tsx
-import { useEffect as useEffect13, useState as useState3, useContext as useContext12 } from "react";
-import { jsxDEV as jsxDEV6, Fragment as Fragment2 } from "react/jsx-dev-runtime";
+import { useEffect as useEffect14, useState as useState4, useContext as useContext12 } from "react";
+import { jsxDEV as jsxDEV7, Fragment as Fragment3 } from "react/jsx-dev-runtime";
 var animatedTiles = new Map;
 function getProperty(props, name) {
   return props?.find((p) => p.name === name)?.value;
@@ -1902,8 +2311,8 @@ function Tilemap({
   onTileProperty
 }) {
   const engine = useContext12(EngineContext);
-  const [spawnedNodes, setSpawnedNodes] = useState3([]);
-  useEffect13(() => {
+  const [spawnedNodes, setSpawnedNodes] = useState4([]);
+  useEffect14(() => {
     if (!engine)
       return;
     const createdEntities = [];
@@ -2094,13 +2503,13 @@ function Tilemap({
   }, [src]);
   if (spawnedNodes.length === 0)
     return null;
-  return /* @__PURE__ */ jsxDEV6(Fragment2, {
+  return /* @__PURE__ */ jsxDEV7(Fragment3, {
     children: spawnedNodes
   }, undefined, false, undefined, this);
 }
 // src/components/ParallaxLayer.tsx
-import { useEffect as useEffect14, useContext as useContext13 } from "react";
-import { jsxDEV as jsxDEV7 } from "react/jsx-dev-runtime";
+import { useEffect as useEffect15, useContext as useContext13 } from "react";
+import { jsxDEV as jsxDEV8 } from "react/jsx-dev-runtime";
 function ParallaxLayerInner({
   src,
   speedX,
@@ -2113,7 +2522,7 @@ function ParallaxLayerInner({
 }) {
   const engine = useContext13(EngineContext);
   const entityId = useContext13(EntityContext);
-  useEffect14(() => {
+  useEffect15(() => {
     engine.ecs.addComponent(entityId, {
       type: "ParallaxLayer",
       src,
@@ -2129,7 +2538,7 @@ function ParallaxLayerInner({
     });
     return () => engine.ecs.removeComponent(entityId, "ParallaxLayer");
   }, []);
-  useEffect14(() => {
+  useEffect15(() => {
     const layer = engine.ecs.getComponent(entityId, "ParallaxLayer");
     if (!layer)
       return;
@@ -2154,13 +2563,13 @@ function ParallaxLayer({
   offsetX = 0,
   offsetY = 0
 }) {
-  return /* @__PURE__ */ jsxDEV7(Entity, {
+  return /* @__PURE__ */ jsxDEV8(Entity, {
     children: [
-      /* @__PURE__ */ jsxDEV7(Transform, {
+      /* @__PURE__ */ jsxDEV8(Transform, {
         x: 0,
         y: 0
       }, undefined, false, undefined, this),
-      /* @__PURE__ */ jsxDEV7(ParallaxLayerInner, {
+      /* @__PURE__ */ jsxDEV8(ParallaxLayerInner, {
         src,
         speedX,
         speedY,
@@ -2175,7 +2584,7 @@ function ParallaxLayer({
 }
 // src/components/ScreenFlash.tsx
 import { forwardRef, useImperativeHandle, useRef as useRef2 } from "react";
-import { jsxDEV as jsxDEV8 } from "react/jsx-dev-runtime";
+import { jsxDEV as jsxDEV9 } from "react/jsx-dev-runtime";
 var ScreenFlash = forwardRef((_, ref) => {
   const divRef = useRef2(null);
   useImperativeHandle(ref, () => ({
@@ -2197,7 +2606,7 @@ var ScreenFlash = forwardRef((_, ref) => {
       });
     }
   }));
-  return /* @__PURE__ */ jsxDEV8("div", {
+  return /* @__PURE__ */ jsxDEV9("div", {
     ref: divRef,
     style: {
       position: "absolute",
@@ -2235,7 +2644,7 @@ function useInput() {
   return engine.input;
 }
 // src/hooks/useEvents.ts
-import { useContext as useContext17, useEffect as useEffect15 } from "react";
+import { useContext as useContext17, useEffect as useEffect16 } from "react";
 function useEvents() {
   const engine = useContext17(EngineContext);
   if (!engine)
@@ -2244,12 +2653,12 @@ function useEvents() {
 }
 function useEvent(event, handler) {
   const events = useEvents();
-  useEffect15(() => {
+  useEffect16(() => {
     return events.on(event, handler);
   }, [events, event]);
 }
 // src/hooks/usePlatformerController.ts
-import { useContext as useContext18, useEffect as useEffect16 } from "react";
+import { useContext as useContext18, useEffect as useEffect17 } from "react";
 function usePlatformerController(entityId, opts = {}) {
   const engine = useContext18(EngineContext);
   const {
@@ -2259,7 +2668,7 @@ function usePlatformerController(entityId, opts = {}) {
     coyoteTime = 0.08,
     jumpBuffer = 0.08
   } = opts;
-  useEffect16(() => {
+  useEffect17(() => {
     const state = { coyoteTimer: 0, jumpBuffer: 0, jumpsLeft: maxJumps };
     const updateFn = (id, world2, input, dt) => {
       if (!world2.hasEntity(id))
@@ -2308,11 +2717,11 @@ function usePlatformerController(entityId, opts = {}) {
   }, []);
 }
 // src/hooks/useTopDownMovement.ts
-import { useContext as useContext19, useEffect as useEffect17 } from "react";
+import { useContext as useContext19, useEffect as useEffect18 } from "react";
 function useTopDownMovement(entityId, opts = {}) {
   const engine = useContext19(EngineContext);
   const { speed = 200, normalizeDiagonal = true } = opts;
-  useEffect17(() => {
+  useEffect18(() => {
     const updateFn = (id, world2, input) => {
       if (!world2.hasEntity(id))
         return;

package/package.json

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