cubeforge 0.2.1 → 0.3.0

package/README.md

@@ -0,0 +1,86 @@
+# cubeforge
+
+**Build browser games with React.**
+
+```tsx
+<Game width={800} height={500} gravity={980}>
+  <World background="#1a1a2e">
+    <Camera2D followEntity="player" smoothing={0.85} />
+    <Entity id="player" tags={['player']}>
+      <Transform x={100} y={300} />
+      <Sprite width={32} height={48} color="#4fc3f7" />
+      <RigidBody />
+      <BoxCollider width={32} height={48} />
+      <Script update={playerUpdate} />
+    </Entity>
+    <Entity tags={['ground']}>
+      <Transform x={400} y={480} />
+      <Sprite width={800} height={32} color="#37474f" />
+      <RigidBody isStatic />
+      <BoxCollider width={800} height={32} />
+    </Entity>
+  </World>
+</Game>
+```
+
+## Install
+
+```bash
+npm install cubeforge react react-dom
+```
+
+## What's included
+
+- **ECS** — archetype-based entity-component-system with query caching
+- **Physics** — two-pass AABB, capsule colliders, kinematic bodies, one-way platforms, 60 Hz fixed timestep
+- **Renderer** — WebGL2 instanced renderer by default; Canvas2D opt-in via `renderer={Canvas2DRenderSystem}`
+- **Input** — keyboard, mouse, gamepad, per-player input maps, input contexts, recording/playback
+- **Audio** — Web Audio API with volume groups, fade, crossfade, ducking (`useSound`)
+- **Gameplay hooks** — `usePlatformerController`, `useTopDownMovement`, `useHealth`, `useSave`, `useGameStateMachine`, `useLevelTransition`, `usePathfinding`, `useAISteering`, and more
+- **DevTools** — time-travel frame scrubber and entity inspector (`<Game devtools>`)
+- **Deterministic mode** — seeded RNG for reproducible simulations (`<Game deterministic seed={n}>`)
+
+## Quick example
+
+```tsx
+import {
+  Game, World, Entity, Transform, Sprite,
+  RigidBody, BoxCollider, Script,
+  usePlatformerController, useHealth, useSound,
+} from 'cubeforge'
+
+function Player() {
+  const id = useEntity()
+  usePlatformerController(id, { speed: 220, jumpForce: -520, maxJumps: 2 })
+  const { hp, takeDamage } = useHealth(5, { onDeath: () => console.log('dead') })
+  const jump = useSound('/jump.wav', { group: 'sfx' })
+  return null
+}
+
+export default function MyGame() {
+  return (
+    <Game width={800} height={500} gravity={980}>
+      <World background="#1a1a2e">
+        <Camera2D followEntity="player" smoothing={0.87} />
+        <Entity id="player" tags={['player']}>
+          <Transform x={100} y={300} />
+          <Sprite src="/player.png" width={32} height={48} />
+          <RigidBody />
+          <BoxCollider width={30} height={48} />
+          <Player />
+        </Entity>
+      </World>
+    </Game>
+  )
+}
+```
+
+## Links
+
+- [Documentation](https://cubeforge.dev)
+- [Examples](https://github.com/1homsi/cubeforge-examples) — 10 runnable games
+- [GitHub](https://github.com/1homsi/cubeforge)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -10,8 +10,9 @@ export { EngineState, useCircleEnter, useCircleExit, useCircleStay, useCollision
 export { AISteering, AnimationClip, AnimationControllerResult, BindingControls, GameState as GameStateDefinition, GameStateMachineResult, HealthControls, HealthOptions, KinematicBodyControls, LevelTransitionControls, PathfindingControls, PlatformerControllerOptions, RestartControls, SaveControls, SaveOptions, TopDownMovementOptions, TransitionOptions, TransitionType, useAISteering, useAnimationController, useDamageZone, useDropThrough, useGameStateMachine, useHealth, useKinematicBody, useLevelTransition, usePathfinding, usePersistedBindings, usePlatformerController, useRestart, useSave, useTopDownMovement } from '@cubeforge/gameplay';
 export { AudioGroup, SoundControls, duck, getGroupVolume, setGroupMute, setGroupVolume, setMasterVolume, stopGroup, useSound } from '@cubeforge/audio';
 export { DevToolsHandle } from '@cubeforge/devtools';
+export { AnimationStateComponent, RenderSystem as Canvas2DRenderSystem, ParallaxLayerComponent, Particle, ParticlePoolComponent, SpriteComponent, SquashStretchComponent, TextComponent, TrailComponent, createSprite } from '@cubeforge/renderer';
+export { WebGLRenderSystem } from '@cubeforge/webgl-renderer';
 export { BoxColliderComponent, CapsuleColliderComponent, CircleColliderComponent, RaycastHit, RigidBodyComponent, overlapBox, overlapCircle, raycast, raycastAll, sweepBox } from '@cubeforge/physics';
-export { AnimationStateComponent, ParallaxLayerComponent, Particle, ParticlePoolComponent, SpriteComponent, SquashStretchComponent, TextComponent, TrailComponent, createSprite } from '@cubeforge/renderer';
 
 interface GameControls {
     pause(): void;
@@ -50,13 +51,12 @@ interface GameProps {
     /** Custom plugins to register after core systems. Each plugin's systems run after Render. */
     plugins?: Plugin[];
     /**
-     * Custom render system constructor. Must implement the System interface and accept
-     * `(canvas: HTMLCanvasElement, entityIds: Map<string, EntityId>)`.
-     *
-     * Defaults to the built-in Canvas2D RenderSystem.
-     * Example: `import { WebGLRenderSystem } from '@cubeforge/webgl-renderer'`
+     * Renderer to use (default: WebGL2).
+     * - omit or undefined — WebGL2 instanced renderer (default)
+     * - 'canvas2d' — Canvas2D renderer (opt-in for compatibility or pixel art)
+     * - CustomClass — any class implementing System with (canvas, entityIds) constructor
      */
-    renderer?: new (canvas: HTMLCanvasElement, entityIds: Map<string, EntityId>) => System;
+    renderer?: 'canvas2d' | (new (canvas: HTMLCanvasElement, entityIds: Map<string, EntityId>) => System);
     style?: CSSProperties;
     className?: string;
     children?: React__default.ReactNode;

package/dist/index.js

@@ -2795,6 +2795,7 @@ var DebugSystem = class {
   fps = 0;
   update(world, dt) {
     const { ctx, canvas } = this.renderer;
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
     this.frameCount++;
     this.lastFpsTime += dt;
     if (this.lastFpsTime >= 0.5) {
@@ -2887,6 +2888,816 @@ var DebugSystem = class {
   }
 };
 
+// ../../packages/webgl-renderer/src/shaders.ts
+var VERT_SRC = `#version 300 es
+layout(location = 0) in vec2 a_quadPos;
+layout(location = 1) in vec2 a_uv;
+
+layout(location = 2) in vec2  i_pos;
+layout(location = 3) in vec2  i_size;
+layout(location = 4) in float i_rot;
+layout(location = 5) in vec2  i_anchor;
+layout(location = 6) in vec2  i_offset;
+layout(location = 7) in float i_flipX;
+layout(location = 8) in vec4  i_color;
+layout(location = 9) in vec4  i_uvRect;
+
+uniform vec2  u_camPos;
+uniform float u_zoom;
+uniform vec2  u_canvasSize;
+uniform vec2  u_shake;
+
+out vec2 v_uv;
+out vec4 v_color;
+
+void main() {
+  // Local position: map quad corner (-0.5..0.5) to draw rect, applying anchor
+  vec2 local = (a_quadPos - vec2(i_anchor.x - 0.5, i_anchor.y - 0.5)) * i_size + i_offset;
+
+  // Horizontal flip
+  if (i_flipX > 0.5) local.x = -local.x;
+
+  // Rotate around local origin
+  float c = cos(i_rot);
+  float s = sin(i_rot);
+  local = vec2(c * local.x - s * local.y, s * local.x + c * local.y);
+
+  // World position
+  vec2 world = i_pos + local;
+
+  // Camera \u2192 NDC clip space (Y is flipped: canvas Y down, WebGL Y up)
+  // Equivalent to Canvas2D: translate(W/2 - camX*zoom + shakeX, H/2 - camY*zoom + shakeY); scale(zoom,zoom)
+  float cx = 2.0 * u_zoom / u_canvasSize.x * (world.x - u_camPos.x) + 2.0 * u_shake.x / u_canvasSize.x;
+  float cy = -2.0 * u_zoom / u_canvasSize.y * (world.y - u_camPos.y) - 2.0 * u_shake.y / u_canvasSize.y;
+
+  gl_Position = vec4(cx, cy, 0.0, 1.0);
+
+  // Remap UV [0,1] to the sub-rect defined by i_uvRect
+  v_uv    = i_uvRect.xy + a_uv * i_uvRect.zw;
+  v_color = i_color;
+}
+`;
+var FRAG_SRC = `#version 300 es
+precision mediump float;
+
+in vec2 v_uv;
+in vec4 v_color;
+
+uniform sampler2D u_texture;
+uniform int       u_useTexture;
+
+out vec4 fragColor;
+
+void main() {
+  if (u_useTexture == 1) {
+    fragColor = texture(u_texture, v_uv) * v_color;
+  } else {
+    fragColor = v_color;
+  }
+}
+`;
+var PARALLAX_VERT_SRC = `#version 300 es
+layout(location = 0) in vec2 a_pos;
+
+out vec2 v_fragCoord;
+
+void main() {
+  gl_Position = vec4(a_pos, 0.0, 1.0);
+  // Convert NDC (-1..1) to canvas pixel coords (0..canvasSize) in the frag shader
+  v_fragCoord = a_pos * 0.5 + 0.5; // 0..1 normalized screen coord
+}
+`;
+var PARALLAX_FRAG_SRC = `#version 300 es
+precision mediump float;
+
+in vec2 v_fragCoord;
+
+uniform sampler2D u_texture;
+uniform vec2      u_uvOffset;
+uniform vec2      u_texSize;   // texture size in pixels
+uniform vec2      u_canvasSize; // canvas size in pixels
+
+out vec4 fragColor;
+
+void main() {
+  // Screen pixel position
+  vec2 screenPx = v_fragCoord * u_canvasSize;
+  // Tile: offset by uvOffset and wrap
+  vec2 uv = mod((screenPx / u_texSize + u_uvOffset), 1.0);
+  // Y must be flipped because WebGL origin is bottom-left but canvas is top-left
+  uv.y = 1.0 - uv.y;
+  fragColor = texture(u_texture, uv);
+}
+`;
+
+// ../../packages/webgl-renderer/src/colorParser.ts
+var cache = /* @__PURE__ */ new Map();
+function parseCSSColor(css) {
+  const hit = cache.get(css);
+  if (hit) return hit;
+  let result = [1, 1, 1, 1];
+  if (css.startsWith("#")) {
+    const h = css.slice(1);
+    if (h.length === 3 || h.length === 4) {
+      const r = parseInt(h[0] + h[0], 16) / 255;
+      const g = parseInt(h[1] + h[1], 16) / 255;
+      const b = parseInt(h[2] + h[2], 16) / 255;
+      const a = h.length === 4 ? parseInt(h[3] + h[3], 16) / 255 : 1;
+      result = [r, g, b, a];
+    } else if (h.length === 6 || h.length === 8) {
+      const r = parseInt(h.slice(0, 2), 16) / 255;
+      const g = parseInt(h.slice(2, 4), 16) / 255;
+      const b = parseInt(h.slice(4, 6), 16) / 255;
+      const a = h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1;
+      result = [r, g, b, a];
+    }
+  } else {
+    const m = css.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)(?:\s*,\s*([\d.]+))?\s*\)/);
+    if (m) {
+      result = [
+        parseInt(m[1]) / 255,
+        parseInt(m[2]) / 255,
+        parseInt(m[3]) / 255,
+        m[4] !== void 0 ? parseFloat(m[4]) : 1
+      ];
+    }
+  }
+  cache.set(css, result);
+  return result;
+}
+
+// ../../packages/webgl-renderer/src/webglRenderSystem.ts
+var FLOATS_PER_INSTANCE = 18;
+var MAX_INSTANCES = 8192;
+var MAX_TEXT_CACHE = 200;
+function compileShader(gl, type, src) {
+  const shader = gl.createShader(type);
+  gl.shaderSource(shader, src);
+  gl.compileShader(shader);
+  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+    throw new Error(`[WebGLRenderer] Shader compile error:
+${gl.getShaderInfoLog(shader)}`);
+  }
+  return shader;
+}
+function createProgram(gl, vertSrc, fragSrc) {
+  const vert = compileShader(gl, gl.VERTEX_SHADER, vertSrc);
+  const frag = compileShader(gl, gl.FRAGMENT_SHADER, fragSrc);
+  const prog = gl.createProgram();
+  gl.attachShader(prog, vert);
+  gl.attachShader(prog, frag);
+  gl.linkProgram(prog);
+  if (!gl.getProgramParameter(prog, gl.LINK_STATUS)) {
+    throw new Error(`[WebGLRenderer] Program link error:
+${gl.getProgramInfoLog(prog)}`);
+  }
+  gl.deleteShader(vert);
+  gl.deleteShader(frag);
+  return prog;
+}
+function createWhiteTexture(gl) {
+  const tex = gl.createTexture();
+  gl.bindTexture(gl.TEXTURE_2D, tex);
+  gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, 1, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, new Uint8Array([255, 255, 255, 255]));
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+  return tex;
+}
+function getTextureKey(sprite) {
+  if (sprite.image?.src) return sprite.image.src;
+  if (sprite.src) return sprite.src;
+  return `__color__:${sprite.color}`;
+}
+function getUVRect(sprite) {
+  if (!sprite.image || sprite.image.naturalWidth === 0) return [0, 0, 1, 1];
+  const iw = sprite.image.naturalWidth;
+  const ih = sprite.image.naturalHeight;
+  if (sprite.frameWidth && sprite.frameHeight) {
+    const cols = sprite.frameColumns ?? Math.floor(iw / sprite.frameWidth);
+    const col = sprite.frameIndex % cols;
+    const row = Math.floor(sprite.frameIndex / cols);
+    return [
+      col * sprite.frameWidth / iw,
+      row * sprite.frameHeight / ih,
+      sprite.frameWidth / iw,
+      sprite.frameHeight / ih
+    ];
+  }
+  if (sprite.frame) {
+    const { sx, sy, sw, sh } = sprite.frame;
+    return [sx / iw, sy / ih, sw / iw, sh / ih];
+  }
+  return [0, 0, 1, 1];
+}
+var WebGLRenderSystem = class {
+  constructor(canvas, entityIds) {
+    this.canvas = canvas;
+    this.entityIds = entityIds;
+    const gl = canvas.getContext("webgl2", { alpha: false, antialias: false, premultipliedAlpha: false });
+    if (!gl) throw new Error("[WebGLRenderer] WebGL2 is not supported in this browser");
+    this.gl = gl;
+    this.program = createProgram(gl, VERT_SRC, FRAG_SRC);
+    const quadVerts = new Float32Array([
+      -0.5,
+      -0.5,
+      0,
+      0,
+      0.5,
+      -0.5,
+      1,
+      0,
+      -0.5,
+      0.5,
+      0,
+      1,
+      0.5,
+      -0.5,
+      1,
+      0,
+      0.5,
+      0.5,
+      1,
+      1,
+      -0.5,
+      0.5,
+      0,
+      1
+    ]);
+    this.quadVAO = gl.createVertexArray();
+    gl.bindVertexArray(this.quadVAO);
+    const quadBuf = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, quadBuf);
+    gl.bufferData(gl.ARRAY_BUFFER, quadVerts, gl.STATIC_DRAW);
+    const qStride = 4 * 4;
+    gl.enableVertexAttribArray(0);
+    gl.vertexAttribPointer(0, 2, gl.FLOAT, false, qStride, 0);
+    gl.enableVertexAttribArray(1);
+    gl.vertexAttribPointer(1, 2, gl.FLOAT, false, qStride, 2 * 4);
+    this.instanceData = new Float32Array(MAX_INSTANCES * FLOATS_PER_INSTANCE);
+    this.instanceBuffer = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, this.instanceBuffer);
+    gl.bufferData(gl.ARRAY_BUFFER, this.instanceData.byteLength, gl.DYNAMIC_DRAW);
+    const iStride = FLOATS_PER_INSTANCE * 4;
+    let byteOffset = 0;
+    const addAttr = (loc, size) => {
+      gl.enableVertexAttribArray(loc);
+      gl.vertexAttribPointer(loc, size, gl.FLOAT, false, iStride, byteOffset);
+      gl.vertexAttribDivisor(loc, 1);
+      byteOffset += size * 4;
+    };
+    addAttr(2, 2);
+    addAttr(3, 2);
+    addAttr(4, 1);
+    addAttr(5, 2);
+    addAttr(6, 2);
+    addAttr(7, 1);
+    addAttr(8, 4);
+    addAttr(9, 4);
+    gl.bindVertexArray(null);
+    gl.useProgram(this.program);
+    this.uCamPos = gl.getUniformLocation(this.program, "u_camPos");
+    this.uZoom = gl.getUniformLocation(this.program, "u_zoom");
+    this.uCanvasSize = gl.getUniformLocation(this.program, "u_canvasSize");
+    this.uShake = gl.getUniformLocation(this.program, "u_shake");
+    this.uTexture = gl.getUniformLocation(this.program, "u_texture");
+    this.uUseTexture = gl.getUniformLocation(this.program, "u_useTexture");
+    this.whiteTexture = createWhiteTexture(gl);
+    this.parallaxProgram = createProgram(gl, PARALLAX_VERT_SRC, PARALLAX_FRAG_SRC);
+    const fsVerts = new Float32Array([
+      -1,
+      -1,
+      1,
+      -1,
+      -1,
+      1,
+      1,
+      -1,
+      1,
+      1,
+      -1,
+      1
+    ]);
+    this.parallaxVAO = gl.createVertexArray();
+    gl.bindVertexArray(this.parallaxVAO);
+    const fsBuf = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, fsBuf);
+    gl.bufferData(gl.ARRAY_BUFFER, fsVerts, gl.STATIC_DRAW);
+    gl.enableVertexAttribArray(0);
+    gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 8, 0);
+    gl.bindVertexArray(null);
+    gl.useProgram(this.parallaxProgram);
+    this.pUTexture = gl.getUniformLocation(this.parallaxProgram, "u_texture");
+    this.pUUvOffset = gl.getUniformLocation(this.parallaxProgram, "u_uvOffset");
+    this.pUTexSize = gl.getUniformLocation(this.parallaxProgram, "u_texSize");
+    this.pUCanvasSize = gl.getUniformLocation(this.parallaxProgram, "u_canvasSize");
+    gl.enable(gl.BLEND);
+    gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+  }
+  gl;
+  program;
+  quadVAO;
+  instanceBuffer;
+  instanceData;
+  whiteTexture;
+  textures = /* @__PURE__ */ new Map();
+  imageCache = /* @__PURE__ */ new Map();
+  // Cached uniform locations — sprite program
+  uCamPos;
+  uZoom;
+  uCanvasSize;
+  uShake;
+  uTexture;
+  uUseTexture;
+  // ── Parallax program ──────────────────────────────────────────────────────
+  parallaxProgram;
+  parallaxVAO;
+  parallaxTextures = /* @__PURE__ */ new Map();
+  parallaxImageCache = /* @__PURE__ */ new Map();
+  // Cached uniform locations — parallax program
+  pUTexture;
+  pUUvOffset;
+  pUTexSize;
+  pUCanvasSize;
+  // ── Text texture cache ────────────────────────────────────────────────────
+  textureCache = /* @__PURE__ */ new Map();
+  /** Insertion-order key list for LRU-style eviction. */
+  textureCacheKeys = [];
+  // ── Texture management (sprite textures — CLAMP_TO_EDGE) ──────────────────
+  loadTexture(src) {
+    const cached = this.textures.get(src);
+    if (cached) return cached;
+    let img = this.imageCache.get(src);
+    if (!img) {
+      img = new Image();
+      img.src = src;
+      img.onload = () => {
+        const tex = this.gl.createTexture();
+        this.gl.bindTexture(this.gl.TEXTURE_2D, tex);
+        this.gl.texImage2D(this.gl.TEXTURE_2D, 0, this.gl.RGBA, this.gl.RGBA, this.gl.UNSIGNED_BYTE, img);
+        this.gl.generateMipmap(this.gl.TEXTURE_2D);
+        this.gl.texParameteri(this.gl.TEXTURE_2D, this.gl.TEXTURE_MIN_FILTER, this.gl.LINEAR_MIPMAP_LINEAR);
+        this.gl.texParameteri(this.gl.TEXTURE_2D, this.gl.TEXTURE_MAG_FILTER, this.gl.LINEAR);
+        this.textures.set(src, tex);
+      };
+      this.imageCache.set(src, img);
+    }
+    return this.whiteTexture;
+  }
+  // ── Parallax texture management (REPEAT wrap mode) ────────────────────────
+  loadParallaxTexture(src) {
+    const cached = this.parallaxTextures.get(src);
+    if (cached) return cached;
+    let img = this.parallaxImageCache.get(src);
+    if (!img) {
+      img = new Image();
+      img.src = src;
+      img.onload = () => {
+        const gl = this.gl;
+        const tex = gl.createTexture();
+        gl.bindTexture(gl.TEXTURE_2D, tex);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img);
+        gl.generateMipmap(gl.TEXTURE_2D);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.REPEAT);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.REPEAT);
+        this.parallaxTextures.set(src, tex);
+      };
+      this.parallaxImageCache.set(src, img);
+    }
+    return null;
+  }
+  // ── Text texture management ───────────────────────────────────────────────
+  getTextTextureKey(text) {
+    return `${text.text}|${text.fontSize ?? 16}|${text.fontFamily ?? "monospace"}|${text.color ?? "#ffffff"}`;
+  }
+  getOrCreateTextTexture(text) {
+    const key = this.getTextTextureKey(text);
+    const cached = this.textureCache.get(key);
+    if (cached) return cached;
+    if (this.textureCache.size >= MAX_TEXT_CACHE) {
+      const oldest = this.textureCacheKeys.shift();
+      if (oldest) {
+        const old = this.textureCache.get(oldest);
+        if (old) this.gl.deleteTexture(old.tex);
+        this.textureCache.delete(oldest);
+      }
+    }
+    const offscreen = document.createElement("canvas");
+    const ctx2d = offscreen.getContext("2d");
+    const font = `${text.fontSize ?? 16}px ${text.fontFamily ?? "monospace"}`;
+    ctx2d.font = font;
+    const metrics = ctx2d.measureText(text.text);
+    const textW = Math.ceil(metrics.width) + 4;
+    const textH = Math.ceil((text.fontSize ?? 16) * 1.5) + 4;
+    offscreen.width = textW;
+    offscreen.height = textH;
+    ctx2d.font = font;
+    ctx2d.fillStyle = text.color ?? "#ffffff";
+    ctx2d.textAlign = "left";
+    ctx2d.textBaseline = "top";
+    ctx2d.fillText(text.text, 2, 2, text.maxWidth);
+    const gl = this.gl;
+    const tex = gl.createTexture();
+    gl.bindTexture(gl.TEXTURE_2D, tex);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, offscreen);
+    gl.generateMipmap(gl.TEXTURE_2D);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    const entry = { tex, w: textW, h: textH };
+    this.textureCache.set(key, entry);
+    this.textureCacheKeys.push(key);
+    return entry;
+  }
+  // ── Instanced draw call ────────────────────────────────────────────────────
+  flush(count, textureKey) {
+    if (count === 0) return;
+    const { gl } = this;
+    const isColor = textureKey.startsWith("__color__");
+    const tex = isColor ? this.whiteTexture : this.loadTexture(textureKey);
+    gl.bindTexture(gl.TEXTURE_2D, tex);
+    gl.uniform1i(this.uUseTexture, isColor ? 0 : 1);
+    gl.bindVertexArray(this.quadVAO);
+    gl.bindBuffer(gl.ARRAY_BUFFER, this.instanceBuffer);
+    gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.instanceData, 0, count * FLOATS_PER_INSTANCE);
+    gl.drawArraysInstanced(gl.TRIANGLES, 0, 6, count);
+  }
+  flushWithTex(count, tex, useTexture) {
+    if (count === 0) return;
+    const { gl } = this;
+    gl.bindTexture(gl.TEXTURE_2D, tex);
+    gl.uniform1i(this.uUseTexture, useTexture ? 1 : 0);
+    gl.bindVertexArray(this.quadVAO);
+    gl.bindBuffer(gl.ARRAY_BUFFER, this.instanceBuffer);
+    gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.instanceData, 0, count * FLOATS_PER_INSTANCE);
+    gl.drawArraysInstanced(gl.TRIANGLES, 0, 6, count);
+  }
+  // ── Write one sprite instance into instanceData ───────────────────────────
+  writeInstance(base, x, y, w, h, rot, anchorX, anchorY, offsetX, offsetY, flipX, r, g, b, a, u, v, uw, vh) {
+    const d = this.instanceData;
+    d[base + 0] = x;
+    d[base + 1] = y;
+    d[base + 2] = w;
+    d[base + 3] = h;
+    d[base + 4] = rot;
+    d[base + 5] = anchorX;
+    d[base + 6] = anchorY;
+    d[base + 7] = offsetX;
+    d[base + 8] = offsetY;
+    d[base + 9] = flipX ? 1 : 0;
+    d[base + 10] = r;
+    d[base + 11] = g;
+    d[base + 12] = b;
+    d[base + 13] = a;
+    d[base + 14] = u;
+    d[base + 15] = v;
+    d[base + 16] = uw;
+    d[base + 17] = vh;
+  }
+  // ── Main update loop ───────────────────────────────────────────────────────
+  update(world, dt) {
+    const { gl, canvas } = this;
+    const W = canvas.width;
+    const H = canvas.height;
+    let camX = 0, camY = 0, zoom = 1;
+    let background = "#000000";
+    let shakeX = 0, shakeY = 0;
+    const camId = world.queryOne("Camera2D");
+    if (camId !== void 0) {
+      const cam = world.getComponent(camId, "Camera2D");
+      background = cam.background;
+      if (cam.followEntityId) {
+        const targetId = this.entityIds.get(cam.followEntityId);
+        if (targetId !== void 0) {
+          const t = world.getComponent(targetId, "Transform");
+          if (t) {
+            if (cam.deadZone) {
+              const halfW = cam.deadZone.w / 2;
+              const halfH = cam.deadZone.h / 2;
+              const dx = t.x - cam.x, dy = t.y - cam.y;
+              if (dx > halfW) cam.x = t.x - halfW;
+              else if (dx < -halfW) cam.x = t.x + halfW;
+              if (dy > halfH) cam.y = t.y - halfH;
+              else if (dy < -halfH) cam.y = t.y + halfH;
+            } else if (cam.smoothing > 0) {
+              cam.x += (t.x - cam.x) * (1 - cam.smoothing);
+              cam.y += (t.y - cam.y) * (1 - cam.smoothing);
+            } else {
+              cam.x = t.x;
+              cam.y = t.y;
+            }
+          }
+        }
+      }
+      if (cam.bounds) {
+        const halfW = W / (2 * cam.zoom);
+        const halfH = H / (2 * cam.zoom);
+        cam.x = Math.max(cam.bounds.x + halfW, Math.min(cam.bounds.x + cam.bounds.width - halfW, cam.x));
+        cam.y = Math.max(cam.bounds.y + halfH, Math.min(cam.bounds.y + cam.bounds.height - halfH, cam.y));
+      }
+      if (cam.shakeTimer > 0) {
+        cam.shakeTimer -= dt;
+        if (cam.shakeTimer < 0) cam.shakeTimer = 0;
+        const progress = cam.shakeDuration > 0 ? cam.shakeTimer / cam.shakeDuration : 0;
+        shakeX = (world.rng() * 2 - 1) * cam.shakeIntensity * progress;
+        shakeY = (world.rng() * 2 - 1) * cam.shakeIntensity * progress;
+      }
+      camX = cam.x;
+      camY = cam.y;
+      zoom = cam.zoom;
+    }
+    for (const id of world.query("AnimationState", "Sprite")) {
+      const anim = world.getComponent(id, "AnimationState");
+      const sprite = world.getComponent(id, "Sprite");
+      if (!anim.playing || anim.frames.length === 0) continue;
+      anim.timer += dt;
+      const frameDuration = 1 / anim.fps;
+      while (anim.timer >= frameDuration) {
+        anim.timer -= frameDuration;
+        anim.currentIndex++;
+        if (anim.currentIndex >= anim.frames.length) {
+          anim.currentIndex = anim.loop ? 0 : anim.frames.length - 1;
+        }
+      }
+      sprite.frameIndex = anim.frames[anim.currentIndex];
+    }
+    for (const id of world.query("SquashStretch", "RigidBody")) {
+      const ss = world.getComponent(id, "SquashStretch");
+      const rb = world.getComponent(id, "RigidBody");
+      const spd = Math.sqrt(rb.vx * rb.vx + rb.vy * rb.vy);
+      const tScX = rb.vy < -100 ? 1 + ss.intensity * 0.4 : spd > 50 ? 1 - ss.intensity * 0.3 : 1;
+      const tScY = rb.vy < -100 ? 1 - ss.intensity * 0.4 : spd > 50 ? 1 + ss.intensity * 0.3 : 1;
+      ss.currentScaleX += (tScX - ss.currentScaleX) * ss.recovery * dt;
+      ss.currentScaleY += (tScY - ss.currentScaleY) * ss.recovery * dt;
+    }
+    const [br, bg, bb] = parseCSSColor(background);
+    gl.viewport(0, 0, W, H);
+    gl.clearColor(br, bg, bb, 1);
+    gl.clear(gl.COLOR_BUFFER_BIT);
+    const parallaxEntities = world.query("ParallaxLayer");
+    if (parallaxEntities.length > 0) {
+      parallaxEntities.sort((a, b) => {
+        const za = world.getComponent(a, "ParallaxLayer").zIndex;
+        const zb = world.getComponent(b, "ParallaxLayer").zIndex;
+        return za - zb;
+      });
+      gl.useProgram(this.parallaxProgram);
+      gl.uniform2f(this.pUCanvasSize, W, H);
+      gl.uniform1i(this.pUTexture, 0);
+      gl.activeTexture(gl.TEXTURE0);
+      gl.bindVertexArray(this.parallaxVAO);
+      for (const id of parallaxEntities) {
+        const layer = world.getComponent(id, "ParallaxLayer");
+        let img = this.parallaxImageCache.get(layer.src);
+        if (!img) {
+          this.loadParallaxTexture(layer.src);
+          continue;
+        }
+        if (!img.complete || img.naturalWidth === 0) continue;
+        if (layer.imageWidth === 0) layer.imageWidth = img.naturalWidth;
+        if (layer.imageHeight === 0) layer.imageHeight = img.naturalHeight;
+        const tex = this.parallaxTextures.get(layer.src);
+        if (!tex) continue;
+        const imgW = layer.imageWidth;
+        const imgH = layer.imageHeight;
+        const drawX = layer.offsetX - camX * layer.speedX;
+        const drawY = layer.offsetY - camY * layer.speedY;
+        const uvOffsetX = (drawX / imgW % 1 + 1) % 1;
+        const uvOffsetY = (drawY / imgH % 1 + 1) % 1;
+        gl.bindTexture(gl.TEXTURE_2D, tex);
+        gl.uniform2f(this.pUUvOffset, uvOffsetX, uvOffsetY);
+        gl.uniform2f(this.pUTexSize, imgW, imgH);
+        gl.drawArrays(gl.TRIANGLES, 0, 6);
+      }
+    }
+    gl.useProgram(this.program);
+    gl.uniform2f(this.uCamPos, camX, camY);
+    gl.uniform1f(this.uZoom, zoom);
+    gl.uniform2f(this.uCanvasSize, W, H);
+    gl.uniform2f(this.uShake, shakeX, shakeY);
+    gl.uniform1i(this.uTexture, 0);
+    gl.activeTexture(gl.TEXTURE0);
+    const renderables = world.query("Transform", "Sprite");
+    renderables.sort((a, b) => {
+      const sa = world.getComponent(a, "Sprite");
+      const sb = world.getComponent(b, "Sprite");
+      const zd = sa.zIndex - sb.zIndex;
+      if (zd !== 0) return zd;
+      const ka = getTextureKey(sa), kb = getTextureKey(sb);
+      return ka < kb ? -1 : ka > kb ? 1 : 0;
+    });
+    let batchCount = 0;
+    let batchKey = "";
+    for (let i = 0; i <= renderables.length; i++) {
+      if (i === renderables.length) {
+        this.flush(batchCount, batchKey);
+        break;
+      }
+      const id = renderables[i];
+      const transform = world.getComponent(id, "Transform");
+      const sprite = world.getComponent(id, "Sprite");
+      if (!sprite.visible) continue;
+      if (sprite.src && !sprite.image) {
+        let img = this.imageCache.get(sprite.src);
+        if (!img) {
+          img = new Image();
+          img.src = sprite.src;
+          this.imageCache.set(sprite.src, img);
+          img.onload = () => {
+            const tex = this.gl.createTexture();
+            this.gl.bindTexture(this.gl.TEXTURE_2D, tex);
+            this.gl.texImage2D(this.gl.TEXTURE_2D, 0, this.gl.RGBA, this.gl.RGBA, this.gl.UNSIGNED_BYTE, img);
+            this.gl.generateMipmap(this.gl.TEXTURE_2D);
+            this.gl.texParameteri(this.gl.TEXTURE_2D, this.gl.TEXTURE_MIN_FILTER, this.gl.LINEAR_MIPMAP_LINEAR);
+            this.gl.texParameteri(this.gl.TEXTURE_2D, this.gl.TEXTURE_MAG_FILTER, this.gl.LINEAR);
+            this.textures.set(sprite.src, tex);
+          };
+        }
+        sprite.image = img;
+      }
+      const key = getTextureKey(sprite);
+      if (key !== batchKey && batchCount > 0 || batchCount >= MAX_INSTANCES) {
+        this.flush(batchCount, batchKey);
+        batchCount = 0;
+      }
+      batchKey = key;
+      const ss = world.getComponent(id, "SquashStretch");
+      const scaleXMod = ss ? ss.currentScaleX : 1;
+      const scaleYMod = ss ? ss.currentScaleY : 1;
+      const [r, g, b, a] = parseCSSColor(sprite.color);
+      const uv = getUVRect(sprite);
+      this.writeInstance(
+        batchCount * FLOATS_PER_INSTANCE,
+        transform.x,
+        transform.y,
+        sprite.width * transform.scaleX * scaleXMod,
+        sprite.height * transform.scaleY * scaleYMod,
+        transform.rotation,
+        sprite.anchorX,
+        sprite.anchorY,
+        sprite.offsetX,
+        sprite.offsetY,
+        sprite.flipX,
+        r,
+        g,
+        b,
+        a,
+        uv[0],
+        uv[1],
+        uv[2],
+        uv[3]
+      );
+      batchCount++;
+    }
+    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;
+      const entry = this.getOrCreateTextTexture(text);
+      if (!entry) continue;
+      this.flush(batchCount, batchKey);
+      batchCount = 0;
+      batchKey = "";
+      this.writeInstance(
+        0,
+        transform.x + text.offsetX,
+        transform.y + text.offsetY,
+        entry.w,
+        entry.h,
+        transform.rotation,
+        0,
+        0,
+        // anchor top-left
+        0,
+        0,
+        false,
+        1,
+        1,
+        1,
+        1,
+        // white tint — color baked into texture
+        0,
+        0,
+        1,
+        1
+      );
+      this.flushWithTex(1, entry.tex, true);
+    }
+    for (const id of world.query("Transform", "ParticlePool")) {
+      const t = world.getComponent(id, "Transform");
+      const pool = world.getComponent(id, "ParticlePool");
+      pool.particles = pool.particles.filter((p) => {
+        p.life -= dt;
+        p.x += p.vx * dt;
+        p.y += p.vy * dt;
+        p.vy += p.gravity * dt;
+        return p.life > 0;
+      });
+      if (pool.active && pool.particles.length < pool.maxParticles) {
+        pool.timer += dt;
+        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 + (world.rng() - 0.5) * pool.spread;
+          const speed = pool.speed * (0.5 + world.rng() * 0.5);
+          pool.particles.push({
+            x: t.x,
+            y: t.y,
+            vx: Math.cos(angle) * speed,
+            vy: Math.sin(angle) * speed,
+            life: pool.particleLife,
+            maxLife: pool.particleLife,
+            size: pool.particleSize,
+            color: pool.color,
+            gravity: pool.gravity
+          });
+        }
+      }
+      let pCount = 0;
+      const pKey = `__color__`;
+      for (const p of pool.particles) {
+        if (pCount >= MAX_INSTANCES) {
+          this.flush(pCount, pKey);
+          pCount = 0;
+        }
+        const alpha = p.life / p.maxLife;
+        const [r, g, b] = parseCSSColor(p.color);
+        this.writeInstance(
+          pCount * FLOATS_PER_INSTANCE,
+          p.x,
+          p.y,
+          p.size,
+          p.size,
+          0,
+          0.5,
+          0.5,
+          0,
+          0,
+          false,
+          r,
+          g,
+          b,
+          alpha,
+          0,
+          0,
+          1,
+          1
+        );
+        pCount++;
+      }
+      if (pCount > 0) this.flush(pCount, pKey);
+    }
+    for (const id of world.query("Transform", "Trail")) {
+      const t = world.getComponent(id, "Transform");
+      const trail = world.getComponent(id, "Trail");
+      trail.points.unshift({ x: t.x, y: t.y });
+      if (trail.points.length > trail.length) trail.points.length = trail.length;
+      if (trail.points.length < 1) continue;
+      const [tr, tg, tb] = parseCSSColor(trail.color);
+      const trailW = trail.width > 0 ? trail.width : 1;
+      let tCount = 0;
+      for (let i = 0; i < trail.points.length; i++) {
+        if (tCount >= MAX_INSTANCES) {
+          this.flush(tCount, "__color__");
+          tCount = 0;
+        }
+        const alpha = 1 - i / trail.points.length;
+        this.writeInstance(
+          tCount * FLOATS_PER_INSTANCE,
+          trail.points[i].x,
+          trail.points[i].y,
+          trailW,
+          trailW,
+          0,
+          0.5,
+          0.5,
+          0,
+          0,
+          false,
+          tr,
+          tg,
+          tb,
+          alpha,
+          0,
+          0,
+          1,
+          1
+        );
+        tCount++;
+      }
+      if (tCount > 0) this.flush(tCount, "__color__");
+    }
+  }
+};
+
 // src/components/Game.tsx
 import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
 function timedSystem(name, system, timings) {
@@ -2916,6 +3727,7 @@ function Game({
   children
 }) {
   const canvasRef = useRef3(null);
+  const debugCanvasRef = useRef3(null);
   const wrapperRef = useRef3(null);
   const [engine, setEngine] = useState2(null);
   const [assetsReady, setAssetsReady] = useState2(asyncAssets);
@@ -2932,14 +3744,34 @@ function Game({
     let canvas2d;
     let builtinRenderSystem;
     let renderSystem;
-    if (CustomRenderer) {
-      renderSystem = new CustomRenderer(canvas, entityIds);
-    } else {
+    let activeRenderSystem;
+    if (CustomRenderer === "canvas2d") {
       canvas2d = new Canvas2DRenderer(canvas);
       builtinRenderSystem = new RenderSystem(canvas2d, entityIds);
       renderSystem = builtinRenderSystem;
+    } else if (CustomRenderer) {
+      renderSystem = new CustomRenderer(canvas, entityIds);
+    } else {
+      try {
+        renderSystem = new WebGLRenderSystem(canvas, entityIds);
+      } catch (e) {
+        console.warn("[Cubeforge] WebGL2 unavailable, falling back to Canvas2D:", e);
+        canvas2d = new Canvas2DRenderer(canvas);
+        builtinRenderSystem = new RenderSystem(canvas2d, entityIds);
+        renderSystem = builtinRenderSystem;
+      }
+    }
+    activeRenderSystem = renderSystem;
+    let debugSystem = null;
+    if (debug) {
+      const debugCanvas2dEl = debugCanvasRef.current;
+      if (debugCanvas2dEl) {
+        const debugCanvas2d = new Canvas2DRenderer(debugCanvas2dEl);
+        debugSystem = new DebugSystem(debugCanvas2d);
+      } else if (canvas2d) {
+        debugSystem = new DebugSystem(canvas2d);
+      }
     }
-    const debugSystem = debug && canvas2d ? new DebugSystem(canvas2d) : null;
     const systemTimings = /* @__PURE__ */ new Map();
     ecs.addSystem(timedSystem("ScriptSystem", new ScriptSystem(input), systemTimings));
     ecs.addSystem(timedSystem("PhysicsSystem", physics, systemTimings));
@@ -2960,7 +3792,20 @@ function Game({
         handle.onFrame?.();
       }
     });
-    const state = { ecs, input, renderer: canvas2d, renderSystem: builtinRenderSystem, physics, events, assets, loop, canvas, entityIds, systemTimings };
+    const state = {
+      ecs,
+      input,
+      renderer: canvas2d,
+      renderSystem: builtinRenderSystem,
+      activeRenderSystem,
+      physics,
+      events,
+      assets,
+      loop,
+      canvas,
+      entityIds,
+      systemTimings
+    };
     setEngine(state);
     if (plugins) {
       const pluginNames = new Set(plugins.map((p) => p.name));
@@ -2999,6 +3844,11 @@ function Game({
         const s2 = Math.min(scaleX, scaleY);
         canvas.style.transform = `scale(${s2})`;
         canvas.style.transformOrigin = "top left";
+        const debugEl = debugCanvasRef.current;
+        if (debugEl) {
+          debugEl.style.transform = `scale(${s2})`;
+          debugEl.style.transformOrigin = "top left";
+        }
       };
       updateScale();
       resizeObserver = new ResizeObserver(updateScale);
@@ -3060,6 +3910,15 @@ function Game({
           className
         }
       ),
+      debug && /* @__PURE__ */ jsx2(
+        "canvas",
+        {
+          ref: debugCanvasRef,
+          width,
+          height,
+          style: { position: "absolute", top: 0, left: 0, pointerEvents: "none" }
+        }
+      ),
       !assetsReady && /* @__PURE__ */ jsxs2("div", { style: {
         position: "absolute",
         inset: 0,
@@ -4313,7 +5172,13 @@ function useCamera() {
   const engine = useGame();
   return useMemo(() => ({
     shake(intensity, duration) {
-      engine.renderSystem?.triggerShake(intensity, duration);
+      const cams = engine.ecs.query("Camera2D");
+      if (cams.length === 0) return;
+      const cam = engine.ecs.getComponent(cams[0], "Camera2D");
+      if (!cam) return;
+      cam.shakeIntensity = intensity;
+      cam.shakeDuration = duration;
+      cam.shakeTimer = duration;
     },
     setFollowOffset(x, y) {
       const camId = engine.ecs.queryOne("Camera2D");
@@ -5224,6 +6089,7 @@ export {
   BoxCollider,
   Camera2D,
   CameraZone,
+  RenderSystem as Canvas2DRenderSystem,
   CapsuleCollider,
   Checkpoint,
   CircleCollider,
@@ -5243,6 +6109,7 @@ export {
   Trail,
   Transform,
   VirtualJoystick,
+  WebGLRenderSystem,
   World,
   arrive,
   createAtlas,

package/package.json

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