Hilo3D runs one renderer over WebGPU and WebGL 2

One renderer over two graphics APIs

Hilo3D is described as a modern Web graphics engine for production 2D and 3D experiences, and the mechanism behind it is stated in the README's own summary: a portable RHI, validated Render Graph, and Scriptable Render Pipeline power one shared renderer for WebGPU and WebGL 2.

The reason that matters is that the two graphics APIs are not close relatives. WebGPU is an explicit, bind-group based API with compute support, and WebGL 2 is the older immediate-mode-ish pipeline that most browsers still support. Writing an engine twice is the usual answer and it doubles the maintenance. The RHI, the render abstraction interface, is the layer that makes one engine serve both.

The backend selection is explicit and the README is careful about it. The auto backend prefers compatible WebGPU and uses WebGL 2 when WebGPU is unavailable, and explicit backend requests never change silently. So an application can ask for webgpu or webgl2 and know it gets what it asked for, rather than discovering at runtime that it was downgraded.

The package is hilo3d on npm, the type field is module, and the description calls it a TypeScript-first 3D engine with explicit WebGL 2 and WebGPU backends. The website is hilo3d.js.org, with the examples gallery, the documentation and the API reference all hosted there.

Installing the 2.0 prerelease

The install is one command, and the channel and the flag both matter.

npm install --save-exact hilo3d@next

The README explains both parts. The next tag selects the 2.0 prerelease, and --save-exact pins the resolved version. That second part is not decoration: with a prerelease on a moving tag, an unpinned dependency can change underneath you between installs, and the README warns separately that the unqualified latest channel may still select 1.x.

The package version in package.json is 2.0.0-alpha.9, so the 2.0 line is an alpha with numbered prereleases, and the README adds a warning at the top of the file. Hilo3D 2.0 is currently in alpha, existing projects should review the breaking changes in CHANGELOG.md before upgrading, and the repository and website documentation may include Unreleased APIs, so you should match the version boundaries documented in documentation/VERSIONS.md to the installed package.

That last point is the one to internalise. This is a project where the docs on the website can describe code that is not in the version you have installed, so the version boundary document is the thing that tells you which API surface you actually have.

There is also a constraint on the platform target. Hilo3D is ESM-only, and it targets modern browsers with WebGPU or WebGL 2. WebGL 1 and legacy global builds are outside the 2.0 contract, which means an application that has to support a WebGL 1 browser cannot use 2.0 at all.

Creating a first scene, and why the stage is async

The README's first scene is short enough to read in one pass, and it shows the shape of the API.

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
});

Stage.create() is asynchronous because backend selection and GPU initialization are asynchronous, and the README says to use backend: 'webgpu' or backend: 'webgl2' when an application requires a specific backend.

That await is the interesting part of the API. The container element and the canvas sizing are passed in, and the camera is created before the stage exists, which means the camera is a plain object the stage then adopts. The stage is the thing that owns the GPU resources, and it is created after the browser has told you which backend it will get.

The rest of the example is the usual scene assembly: a Mesh with a BoxGeometry and a PBRMaterial, an AmbientLight with an amount of 1, a DirectionalLight with an amount of 3 and a direction vector, and then a Ticker at 60 frames per second with the stage added as a tick and started. The ticker rather than a requestAnimationFrame loop is the engine's own frame driver.

What the 2.0 renderer is trying to be

The feature list in the README is long, and it is worth separating the portable renderer from the opt-in high-end profile, because they are different things.

The portable renderer covers modern materials and output, with glTF 2.0, layered PBR, HDR lighting, Bloom, automatic exposure, filmic tone mapping, transmission, volume, iridescence, clearcoat and anisotropy. It covers 2D and 3D together, with a scene graph, meshes, animation, cameras, lights, shadows, sprites, text, batching, picking and layered multi-camera composition.

Then there is the WebGPU high-end profile, which is opt-in and built on the same Scene, Material, Render Graph and RHI contracts. It adds GPU-driven rendering: instancing and multi-pass rendering across both backends, plus a WebGPU profile with GPU Scene culling and LOD, Hi-Z, indirect buckets and Clustered Forward+.

The lighting list for that profile is ambitious: TAA and TAAU, dynamic resolution, GTAO, SSR, SSGI, froxel volumetrics, physical atmosphere, temporal clouds, cloud shadows and eye adaptation.

Two design details in the README are worth noting because they affect what you can rely on. Unsupported devices fail capability checks before the runtime is created, so a device that cannot do the high-end profile gets a clear failure rather than a broken frame. And compatible meshes that are outside the native GPU Scene slice remain on the shared Forward path and compose into the same linear HDR frame, which means the fallback is a real path rather than a degraded one.

The render graph and the production lifecycle

Two of the features are about the shape of the frame rather than about what is in it.

The validated Render Graph and scriptable render pipeline are described as the way a frame can be shaped, and they coordinate shadows, scene passes, post-processing, render targets, readback and presentation. The word validated is doing work there: a render graph that is checked is a render graph where a missing dependency is a startup error rather than a corrupted frame.

The production lifecycle feature is the other one, and it lists bounded GPU caches, incremental uploads, explicit resource ownership, and recovery from WebGPU device loss or WebGL context loss. That last item is the one that matters most in practice, because a lost GPU device on a long-running WebGPU application is a real event rather than an edge case, and a renderer that cannot recover from it turns a recoverable situation into a page reload.

Bounded GPU caches are the quiet one. A cache that grows without limit is a memory leak that shows up as a slow degradation over hours, which is the hardest kind of bug to attribute. Bounding them and saying so is a sign the engine is aimed at applications that run for a long time.

The repository layout backs up that production orientation. There is an editor/ directory, a benchmarks/ directory, an api-extractor.json for the public API surface, a typedoc.json for the API documentation, and a llms.txt file, and the whole thing is built with Vite across several configurations, with vite.config.ts for the library, vite.editor.config.ts, vite.examples.config.ts and vite.player.config.ts. The test setup is unusually broad, with separate vitest configurations for the editor, the node side of the editor, the player, the native RHI, the RHI, the surface renderer and the editor renderer, plus Playwright configurations for the editor pages, the player and the general case.

Addons, the game skill and the wider repository

The engine is one workspace among several, and the addons are separate packages.

The package.json declares five workspaces: addon-particle, addon-physics, addon-live2d, addon-assets and addon-audio. They are built and cleaned individually by the npm scripts, and the clean:build script lists each one's cache and dist directory, so they are first class packages rather than folders inside the core.

The addon set tells you what the core deliberately does not do. Particle effects, physics, Live2D, asset loading and audio are all separate, which keeps the core renderer small and lets an application take only what it needs.

There is also a Codex angle worth mentioning, since it is unusual in an engine repository. 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 it is kept outside .agents/skills so that it is distributed from the repository without becoming guidance for contributors working on the engine itself. That separation is deliberate and documented: the skill is for users of the engine, the .agents directory would be for people changing it.

The examples directory is extensive and split by topic, with 2D examples for sprite animation, sprite batching, text layout, UI buttons and sorting, then 3D examples for animation, area lights, asset streaming and multi-sampled renderbuffers. The engine website has a full example gallery, and the README highlights three that show the range: HDR Bloom as compute-driven light shaped through the post-processing pipeline, glTF material extensions with layered Khronos assets on the shared renderer, and compute path tracing as progressive WebGPU tracing with denoising, caustics and HDR output.

Where Hilo3D fits, and where it stops

The comparison worth making is with the other two options for a 3D engine in the browser: a WebGL 2 only engine, and a native WebGPU engine.

Against a WebGL 2 only engine, the difference is that you keep the fallback without writing two codebases. A WebGL 2 engine reaches a wider range of devices today, because WebGPU is still not everywhere, but the moment you want a WebGPU feature you are on your own. Hilo3D's bet is that the RHI abstraction is worth the indirection, so the fallback is free and the high-end path is available where the hardware supports it.

Against a native WebGPU engine, the difference is the reach. A WebGPU-only engine gets compute path tracing and GPU Scene culling everywhere it runs, and it does not run anywhere WebGPU is missing. Hilo3D gives you the same contract on both, at the cost of an abstraction layer that limits how directly you can express the newest API features.

The limits are visible in the record. The 2.0 line is alpha, with the version at 2.0.0-alpha.9 and an explicit warning to review the breaking changes before upgrading. The npm latest channel may still resolve to 1.x, and the tagged releases in the repository history are 1.19.0 from 2023-05-05, 1.18.0 from 2023-01-30 and 1.17.0 from 2022-12-19, so the 1.x line is what has stable tags and 2.0 is the prerelease line. The last push was on 2026-10-21 and the repository is not archived, so the work is current even though the tagged 1.x history is not.

The other constraint is WebGL 1, which the README puts outside the 2.0 contract entirely, alongside legacy global builds. An application that has to reach a WebGL 1 browser is on 1.x.

For a team that wants the modern features and can accept an alpha dependency with a pinned prerelease tag, the RHI and the render graph are the substance here. The render targets, the tiers and the build tooling are the cost of that.

Editorial conclusion

Hilo3D suits a browser team that wants GPU-driven rendering features such as compute path tracing, Clustered Forward+ and GPU Scene culling without writing two backends, since the RHI and the render graph sit between the application and the API. It is the wrong tool for a project on WebGL 1 or for a stable 1.x application, because 2.0 is ESM-only and in alpha with breaking changes, and the unqualified latest channel may still select 1.x. Before adopting it, install with npm install --save-exact hilo3d@next so the prerelease is pinned, read the breaking changes in CHANGELOG.md, and check the version boundaries against the installed package.

Frequently asked questions

Official sources

1. hiloteam/Hilo3d on GitHub
2. License: MIT
3. Project website
4. README
5. Releases