Demeter 2D Engine

Demeter is a web-first 2D game engine and editor. It is built for creators who need a browser-based tool to make 2D games, not as a single game project.

Current Scope

• Web studio interface
• GPU-accelerated 2D viewport through WebGL2
• Scene, layer, and object model
• Rect, circle, and text objects
• Object selection, dragging, duplication, deletion, and property editing
• Automatic shape recognition and project-wide shape expansion
• Undo and redo
• Project save and load as JSON
• Chunked project save and load for large scenes
• Spatial index, collision layers, ECS data storage, sprite atlas helpers, static-layer cache, and worker-based logic helpers
• Adaptive virtual-load shield with 10B primary, 50B reserve, and 100B insurance tiers
• Runtime performance readout
• Public browser API exposed as window.Demeter

Install

npm install demeter-2d-engine

import {
  DemeterEngine,
  createDefaultProject,
  createObject,
  createMillionObjectWorld,
  createTenBillionVirtualWorld,
  createFiftyBillionVirtualWorld,
  createHundredBillionVirtualWorld,
  createVirtualLoadShield,
  scaleProjectShapes,
  SpatialIndex,
  CollisionWorld,
  createDefaultECS,
  TextureAtlas
} from "demeter-2d-engine";

Run Locally

npm run dev

Open:

http://127.0.0.1:5176

Verify

npm run check

Renderer Load Test

Run the local server, then open:

http://127.0.0.1:5176/benchmarks/load-test.html

The load test measures visible 2D quad rendering in the browser GPU path and reports smooth and usable object-count limits for the current machine.

Latest local benchmark notes are in docs/BENCHMARK.md.

For the million-object logic target, open:

http://127.0.0.1:5176/benchmarks/million-logic-test.html

The current typed-array LogicWorld path has been measured with 1,000,000 lightweight logic objects, quality 100%, and 60 FPS target passing on the local benchmark machine.

For the 10-billion-object virtual world target, open:

http://127.0.0.1:5176/benchmarks/ten-billion-virtual-test.html

This path uses a procedural indexed world: 10,000,000,000 objects are addressable and queryable, while only camera-visible objects are materialized and rendered each frame.

The latest local run passed the 60 FPS target with 12,030 visible objects, quality 100%, and 2.3 MB virtual-world memory.

Project Files

Demeter project files use readable JSON with the .demeter.json suffix. Large scenes can also be saved as chunked JSON with the .demeterchunks.json suffix, splitting object data into chunks so loading, diffing, and future streaming are easier.

Both formats can be loaded from the studio through the same Load JSON button.

Optimization Systems

• SpatialIndex skips broad full-scene scans for large object sets.
• CollisionWorld adds layer/mask-based broadphase collision checks.
• ECSWorld stores gameplay data in typed arrays for lower memory pressure.
• TextureAtlas and SpriteBatch prepare sprite batching by texture.
• StaticLayerCache stores stable layer results with bounded LRU cleanup.
• LogicWorkerClient moves heavy logic stepping into a Web Worker.
• VirtualLoadShield protects huge virtual worlds with a 10B primary tier, a 50B reserve tier, and a 100B insurance tier that lowers visible workload before FPS enters a dangerous range.
• detectWebGPU() probes WebGPU support while WebGL2 remains the current production renderer.

Virtual Load Shield

Demeter does not store 10B, 50B, or 100B full JavaScript objects in memory. It keeps those worlds virtual and only materializes what the camera can see. The load shield adds a second safety half around that model: if the current tier cannot keep FPS safe, it lowers the visible workload and moves from the 10B primary tier to the 50B reserve tier, then to the 100B insurance tier.

import {
  DemeterEngine,
  createHundredBillionVirtualWorld,
  createVirtualLoadShield
} from "demeter-2d-engine";

const shield = createVirtualLoadShield();
const world = createHundredBillionVirtualWorld();
const engine = new DemeterEngine({ canvas, overlayCanvas, loadShield: shield });

function frame() {
  world.update(1 / 60);
  const stats = engine.renderVirtualWorld(world);
  console.log(stats.loadShield.tier, stats.qualityPercent);
  requestAnimationFrame(frame);
}

Shape Expansion

The engine can automatically recognize common 2D shapes and enlarge them in one pass. The scaler handles built-in rect, circle, and text objects, plus custom objects that expose dimensions, radii, or point lists.

import { scaleProjectShapes } from "demeter-2d-engine";

const summary = scaleProjectShapes(project, { factor: 2 });
console.log(summary.scaled);

In Demeter Studio, use Expand x2 in the Objects panel to double the current scene's shapes and scene bounds.

Commercial Direction

Demeter is intended as a web engine and editor that other people can use to create games. The current implementation avoids game-specific content so the product remains focused on engine authoring, project editing, and runtime foundations.