README.md

August 29, 2026 · View on GitHub

A modern Web graphics engine for production 2D and 3D experiences.

A portable RHI, validated Render Graph, and Scriptable Render Pipeline
power one shared renderer for WebGPU and WebGL 2.

Website · Examples · Documentation · API · 简体中文

Hilo3D 2.0 is currently in alpha. Existing projects should review the breaking changes before upgrading.

Why Hilo3D

Hilo3D keeps high-level scene authoring and low-level GPU control in the same engine. Applications use one scene, material, render-target, and shader contract while the renderer selects a native WebGPU path or a production WebGL 2 compatibility path.

One renderer, two backends — auto prefers compatible WebGPU and uses WebGL 2 when WebGPU is unavailable. Explicit backend requests never change silently.
Modern materials and output — glTF 2.0, layered PBR, HDR lighting, Bloom, automatic exposure, filmic tone mapping, transmission, volume, iridescence, clearcoat, and anisotropy.
2D and 3D together — scene graph, meshes, animation, cameras, lights, shadows, sprites, text, batching, picking, and layered multi-camera composition.
GPU-driven rendering — instancing and multi-pass rendering across both backends, plus a WebGPU high-end profile with GPU Scene culling/LOD, Hi-Z, indirect buckets, and Clustered Forward+.
Stable high-end lighting — TAA/TAAU, dynamic resolution, GTAO, SSR, SSGI, froxel volumetrics, physical atmosphere, temporal clouds, cloud shadows, and eye adaptation.
A frame you can shape — a validated Render Graph and scriptable render pipeline coordinate shadows, scene passes, post-processing, render targets, readback, and presentation.
Production lifecycle — bounded GPU caches, incremental uploads, explicit resource ownership, and recovery from WebGPU device loss or WebGL context loss.

Install

npm install hilo3d

Hilo3D is ESM-only. It targets modern browsers with WebGPU or WebGL 2; WebGL 1 and legacy global builds are outside the 2.0 contract.

Build games with Codex

The standalone hilo3d-game Agent Skill helps Codex plan, scaffold, implement, debug, and optimize Hilo3D 2D, 3D, and hybrid browser games. It uses the published hilo3d package and is kept outside .agents/skills so it is distributed from this repository without becoming guidance for contributors working on the engine itself.

Create your first scene

import * as Hilo3d from 'hilo3d';

const camera = new Hilo3d.PerspectiveCamera({
    aspect: innerWidth / innerHeight,
    z: 4
});

const stage = await Hilo3d.Stage.create({
    backend: 'auto',
    container: document.querySelector('#app')!,
    camera,
    width: innerWidth,
    height: innerHeight
});

new Hilo3d.Mesh({
    geometry: new Hilo3d.BoxGeometry(),
    material: new Hilo3d.PBRMaterial({
        baseColor: new Hilo3d.Color(0.83, 0.12, 0.09)
    })
}).addTo(stage);

stage.addChild(new Hilo3d.AmbientLight({ amount: 1 }));

const ticker = new Hilo3d.Ticker(60);
ticker.addTick(stage);
ticker.start();

Stage.create() is asynchronous because backend selection and GPU initialization are asynchronous. Use backend: 'webgpu' or backend: 'webgl2' when an application requires a specific backend.

See the engine in motion


HDR Bloom Compute-driven light shaped through the engine post-processing pipeline.	glTF material extensions Layered Khronos assets on the shared WebGPU and WebGL 2 renderer.	Compute path tracing Progressive WebGPU tracing with denoising, caustics, and HDR output.

Browse the complete example gallery →

Modern rendering stack

The opt-in WebGPU high-end profile is built on the same Scene, Material, Render Graph, and RHI contracts as the portable renderer. Unsupported devices fail capability checks before the runtime is created; compatible meshes that are outside the native GPU Scene slice remain on the shared Forward path and compose into the same linear HDR frame.

System	Current production slice
GPU Scene	Dirty object/material databases, previous-frame Hi-Z occlusion, projected-radius LOD, compact visible ranges, and fixed indirect buckets
Clustered Forward+	Depth-driven 3D clusters, bounded deterministic light allocation, storage PBR, shared directional/spot/point shadows, and LTC area lights
Shadow caching	Stable atlas tiles, exact per-slice invalidation, scissored depth clears, transactional reuse, and recovery-aware diagnostics
Temporal rendering	Motion vectors, authored reactive masks, native TAA, 0.5–1.0 TAAU, and timestamp-driven dynamic resolution
Screen-space lighting	Portable GTAO and SSGI on WebGPU/WebGL 2, plus WebGPU Clustered hierarchical SSR
Volumetrics and weather	Froxel height/local fog, directional/point/spot injection, physical atmosphere LUTs, temporal clouds, and cloud shadows
HDR display	GPU histogram exposure, asymmetric eye adaptation, Bloom, and configurable filmic display transforms

Explore the Clustered Sponza lab, Temporal Observatory, Silent Dragon GTAO, Afterimage SSR, Prismatic Vespers SSGI, Neon Reliquary volumetrics, and Stormfront Observatory.

See the modern WebGPU rendering roadmap for the exact completed boundaries, remaining compatibility paths, and future streaming/virtualization work.

Rendering profiles

	Portable profile	WebGPU high-end profile
Backend	WebGPU and WebGL 2	WebGPU
Scene and materials	Shared scene graph, PBR materials, glTF, sprites, text	The same public model with registered PBR buckets and Forward fallback
Frame composition	Render Graph, render targets, MRT, MSAA, post-processing	The same graph with GPU Scene, clustered lighting, and native compute
Lighting and quality	Forward PBR, shadows, GTAO, SSGI, TAA/TAAU, Bloom, Color Uber	Adds Hi-Z SSR, dynamic resolution, froxels, atmosphere/clouds, auto exposure
GPU workloads	Instancing, uniform buffers, incremental resource uploads	Compute, storage buffers/textures, indirect GPU workflows
Shader path	Authored GLSL ES 3.00	Raster GLSL → Naga → WGSL; validated direct WGSL compute
Recovery	WebGL context restoration or WebGPU resource rebuild	WebGPU device reacquisition with submission-aware history rebuild

Unsupported WebGPU-only features fail capability checks on WebGL 2 instead of being partially emulated.

Architecture at a glance

Scene · Materials · 2D · Animation · Lights
                    │
              Shared Renderer
                    │
    Render Graph · Scriptable Render Pipeline
                    │
               Portable RHI
              ┌─────┴─────┐
           WebGPU       WebGL 2

The shared renderer owns scene collection, culling, sorting, instancing, shadows, post-processing, draw preparation, and resource coordination. Production frames flow through the Render Graph and portable RHI; backend code remains responsible only for native API execution.

Raster shaders have one GLSL ES 3.00 source of truth. WebGL 2 compiles that source directly, while the WebGPU path preprocesses it for Naga and produces WGSL. WebGPU-only compute uses the engine's validated ComputeShader contract.

Read the rendering architecture for the complete frame, resource, shader, and recovery contracts.

Documentation

Develop locally

Requires Node.js 20.19.0 or newer and the npm version declared by the repository.

npm ci
npm run dev

Useful commands:

npm run examples:dev  # run the example gallery locally
npm run typecheck     # check maintained TypeScript
npm run test          # run the test suite
npm run validate      # run the full release validation

See the contributing guide before opening a pull request.