@giraphics/gravix-engine

ECS-based 3D rendering library for map and point-cloud visualisation, built on bitECS with a pluggable render backend.

Live demo · Lorenz attractor · WebGL2

GitHub’s README cannot run WebGPU, so the demo is that link, not an embedded canvas. Use a browser with WebGPU (Chrome/Edge). If it is blank, open the WebGL2 link.

Install

npm install @giraphics/gravix-engine
# plus a backend, if you want to render to a canvas:
npm install @babylonjs/core

Requires Node 20+.

Usage

import { GravixEngine } from '@giraphics/gravix-engine';
import { BabylonBackend } from '@giraphics/gravix-engine/babylon';

const engine = await GravixEngine.create(new BabylonBackend(), { canvas });
engine.start();

Headless (no browser, no GPU): pass NullBackend from the root entry instead. Polygon tessellation lives on a third entry so consumers that never draw a polygon never download earcut:

import { tessellatePolygon } from '@giraphics/gravix-engine/geo';

| Subpath | What it is for | |---|---| | @giraphics/gravix-engine | Engine, ECS, geometry, UTM, NullBackend | | @giraphics/gravix-engine/babylon | Babylon.js backend (@babylonjs/core peer) | | @giraphics/gravix-engine/geo | Polygon tessellation (earcut) |

Design

• ECS core over bitECS. Components are created per world, never as module-scope singletons, so two worlds in one process cannot alias each other's storage.
• Backend seam. The public API exposes API-neutral enums (PrimitiveTopology, PolygonMode, CullMode) and opaque resource handles. Babylon.js is one implementation of IRenderBackend; a headless NullBackend runs the same systems in Node with no browser and no GPU.
• Babylon is an optional peer dependency and is never bundled. Applications choose and construct a backend; the library never imports one.
• Scene graph. Parent/child via ChildOf, world transforms composed T * Rx * Ry * Rz * S, visibility cascading through ancestors, and disposal that tears children down with their parent.

Development

npm install
npm run typecheck
npm test
npm run build
npm run verify:pack

Smoke canvases (not published): npm -w apps/test-gravix run dev

GitHub Pages

Push main. The workflow builds the library, then the smoke app, and deploys it. Once, in the GitHub repo: Settings → Pages → Source: GitHub Actions. After the first green run the live demo URL above works.

Roadmap

• PLAN.md — how the library was built, Phases 0–6. Complete.
• MAP-VIEWER-PLAN.md — Map Viewer capabilities: spatial indexing, A* navigation, grouped draw calls, viewport streaming with LOD, crowd simulation, procedural sky. M1–M7 landed.

License

MIT