Orillusion: a WebGPU-only 3D engine for the browser

The gap Orillusion fills: no WebGL fallback, no abstraction tax

Most browser 3D engines were written for WebGL and later grew a WebGPU backend, which means their internals are shaped by a stateful API and their shader story is GLSL first. Orillusion takes the opposite route. The description is explicit: it is a pure Web3D rendering engine fully developed on the WebGPU standard. There is no WebGL2 path to fall back to, and no translation layer between your code and the GPU API.

That has a direct consequence. If a browser does not expose WebGPU, the engine has nothing to run on. The README lists Chrome 113+ and Edge 113+ for Windows, Mac and Linux, and puts Android behind the enable-unsafe-webgpu flag on Chrome Canary 113+ and Edge Canary 113+. Safari is not listed at all. So the audience is narrow by construction: developers building desktop-class scenes, technical demos, or internal tools where the browser is known in advance, and who would rather write WGSL than GLSL.

The second audience is people who want to read a WebGPU engine rather than only use one. The repository is TypeScript, MIT licensed, and organised as a monorepo with a packages/ directory holding optional modules for physics, media, stats, particle, graphic and geometry. The topics list confirms the stack: typescript, webgpu, wgsl, 3d, html5, javascript.

How the engine is put together: one core package, optional modules, per-instance engines

The published package is @orillusion/core, and package.json exposes three entry points. The default export resolves to dist/orillusion.es.js for import and dist/orillusion.umd.js for require, with types at dist/types/index.d.ts. A second subpath, ./dev, maps to orillusion.es.max.js and orillusion.umd.max.js, which is the unminified build you would want while debugging into engine internals. The files field ships only dist, so anything you want from the source tree you read on GitHub rather than from node_modules.

The root build script chains tsc against tsconfig.build.json, then vite build, then declaration emission, then minification. The build:packages script fans out into the six subpackages, each with its own build command run from its own directory. That layout tells you the core is meant to stand alone and the extras are opt-in: you do not pull in Rapier physics or the particle system unless you import those packages.

The runtime model is worth noting because it differs from the singleton pattern many engines use. The README states that Engine3D.init() returns an independent instance on each call, so multiple engines can run side by side in the same page. For a demo site that renders several scenes in one document, or for a comparison harness, that removes a class of global-state bugs. It also means you carry the memory of each instance separately, which is a cost, not a free win.

Installing @orillusion/core and rendering a first canvas

The README recommends a front-end build tool such as Vite or Webpack, and the repository's own dev script is vite, so the maintainers practise what they suggest. Install the core package with npm:

npm install @orillusion/core --save

Then import only what you need. The README gives both an on-demand form and a namespace form:

import { Engine3D, Camera3D } from '@orillusion/core'

If you would rather skip a bundler, the README documents three CDN routes through unpkg. The global build attaches everything to an Orillusion global; the ES module build is the one the README recommends for development. The ES module form looks like this:

<script type="module">
  import { Engine3D, Camera3D } from "https://unpkg.com/@orillusion/core/dist/orillusion.es.js"
</script>

For a real page you will usually want your own canvas rather than the full-window one the engine creates by default. The README shows a canvas element with an id and a fixed size, then passing it in through canvasConfig:

import { Engine3D } from '@orillusion/core';
let canvas = document.getElementById('canvas')

const engine = await Engine3D.init({
    canvasConfig: { canvas }
})

Because init() is asynchronous, the README recommends async/await over the promise chain. What you should see after this step is an engine instance bound to your canvas, ready for a scene, camera and render loop. The README stops there and points to the documentation site for the rest, so expect to read the guide before you have pixels. The samples/ directory in the repository is the other place to look: it is split by topic into alpha, animation, audio, base, benchmark, compute, geometry, gi, graphic, lights, loader, material, navemesh, octree, particle, physics, physics-rapier, pick, post, render, sky, sprite and utils.

The beta warning is the real constraint, not the feature list

The README carries a short section titled Need to know. It reads: beta version, not recommended for any commercial application. That is the maintainers' own assessment, and it should govern any adoption decision more than the rendering features shown in the sample GIFs.

There is evidence in the release history that the API is still moving. The jump from v0.8.4 in November 2024 to v0.9.2 in July 2026 is a minor-version step, and minor steps in a pre-1.0 project are where breaking changes usually land. Anyone who built against the 0.8 line should assume migration work rather than a drop-in upgrade, and the CHANGELOG.md at the repository root is where that work would be documented.

The platform story is the second hard limit. Android support requires the enable-unsafe-webgpu flag and a Canary browser, which is not a configuration you can ship to end users. The README lists no support for Safari or Firefox. If your product has to work on phones today, this engine is the wrong tool, and no amount of rendering quality changes that.

A third constraint is documentation depth. The README is a quick-start document. It covers install, engine creation, canvas configuration and platform support, then defers to the guide site for everything else. There is no rollback story, no compatibility matrix beyond the browser list, and no performance guidance in the README itself.

Where Orillusion sits against Three.js and PlayCanvas

Three.js is the default choice for browser 3D, and the difference is architectural rather than cosmetic. Three.js abstracts over multiple backends and has a decade of loaders, exporters and community examples behind it. Orillusion commits to one API and one shading language. You get closer to the metal and pay for it with a much smaller ecosystem and no fallback when WebGPU is missing. If your project needs to load a dozen legacy model formats or run on whatever browser the user happens to have, Three.js is the safer pick, and the search interest in comparing the two reflects exactly this trade-off.

PlayCanvas takes a third position: an editor-first workflow with a hosted toolchain. If your team wants a visual scene editor and a publishing pipeline rather than a code-first rendering library, PlayCanvas addresses a problem Orillusion does not attempt to solve. Orillusion has no editor in the README; it is a library you import.

There is also a lower-level option worth naming: writing against the WebGPU API directly, or against a thin wrapper such as wgpuEngine. That gives you full control and no engine opinions, at the cost of building your own scene graph, material system and render loop. Orillusion's value is precisely that it has already made those decisions for you in TypeScript.

Licence, maintenance and what an upgrade actually costs

The engine is released under the MIT licence, and package.json declares the same identifier. MIT is permissive: it allows commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a statement about the licence text, not legal advice, and the beta warning in the README is a separate matter from the licence. A permissive licence does not make the software production-ready; it only removes licence friction if you decide it is.

Maintenance looks current rather than dormant. The repository is not archived, and the last push was on 2026-09-18, days before the newest release tag of v0.9.2 on 2026-07-31. There is a CI workflow referenced by the badge in the README, and a contributing guide at .github/contributing.md that the README asks you to read before opening a pull request.

The upgrade cost is the part to budget for. Because the project is pre-1.0 and the README warns against commercial use, you should expect to track releases rather than pin and forget. The ./dev export exists so you can debug against unminified builds, but the shipped dist is what your users load, and both come from the same version number. If you adopt v0.9.2, plan to re-read the documentation when the version changes rather than assuming the API is frozen.

Editorial conclusion

Adopt Orillusion if you want to write WGSL-era rendering code in TypeScript and can target Chrome or Edge 113 and above; the repository was pushed on 2026-09-18 and the newest release is v0.9.2 from 2026-07-31. Do not adopt it for a commercial product: the README states it is a beta version and not recommended for any commercial application, and Android support sits behind the enable-unsafe-webgpu flag on Canary builds. Verify first that your target browsers expose WebGPU, that you are comfortable with the API surface of v0.9.2 rather than the older v0.8.x line, and that the samples under samples/ run on your machine before you port any of your own assets.

Frequently asked questions

Official sources

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