diff --git a/docs/docs/lib-graphic-3d/babylon-js.mdx b/docs/docs/lib-graphic-3d/babylon-js.mdx new file mode 100644 index 00000000..409137c4 --- /dev/null +++ b/docs/docs/lib-graphic-3d/babylon-js.mdx @@ -0,0 +1,68 @@ +--- +title: "Babylon.js" +icon: "cube" +description: "Babylon.js in the 3D graphics library benchmark: verdict, integration notes and evidence per criterion" +--- + +# Babylon.js + +Part of the [3D graphics library benchmark](./index). Scores: ✅ meets, ⚠️ partly, ❌ does not, ❓ unknown. + +| | | +| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| Package | `@babylonjs/core` (ES packages), plus `@babylonjs/loaders`, `@babylonjs/gui`, `@babylonjs/havok`, `@babylonjs/accessibility` as needed | +| Version | 9.34.0 | +| License | Apache-2.0 | +| Repository | [BabylonJS/Babylon.js](https://github.com/BabylonJS/Babylon.js) | +| Result | Finalist, first | +| Totals | ✅ 23 · ⚠️ 6 · ❌ 1 · ❓ 0 | + +## Verdict + +- The only library with something for player a11y: `@babylonjs/accessibility` mirrors tagged meshes as HTML for screen readers and keyboard navigation. +- Everything the editor needs is in core: picking, `GizmoManager`, editor cameras, scene serialization, a screenshot API. +- Clean engine integration: no hidden loop, no global left on `window`, types shipped, official Havok physics. +- Weak points: the bundle (424 KB gzip, 191 KB first chunk with code splitting), and in the POC its WebGPU backend was the slowest with 20,000 unbatched meshes (5.3 FPS, against 24.9 FPS on WebGL). + +## Integration notes + +- `__init`: `await EngineFactory.CreateAsync(canvas, {})` (WebGPU, then WebGL), or `new WebGPUEngine(canvas)` + `await initAsync()` with a WebGL `Engine` fallback. +- Tick: do not call `runRenderLoop`. Wrap each frame in `engine.beginFrame()`, `scene.render()`, `engine.endFrame()`: without them WebGPU never submits its commands and `CreateScreenshotAsync` never resolves (found in the POC). +- Viewport: `engine.setSize`, `setHardwareScalingLevel(1 / pixelRatio)`, camera `viewport` for the letterbox. +- `__clear`: `scene.dispose()`, `engine.dispose()`. Nothing to delete on `window`. +- Many entities: use instances or thin instances rather than `clone()` (3.1 s to set up 20,000 clones in the POC). + +## Evidence + +| Id | Score | Evidence | +| --- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| A1 | ✅ | `EngineFactory.CreateAsync` tries WebGPU, then WebGL, then `NullEngine`. [Docs](https://doc.babylonjs.com/setup/support/webGPU) | +| A2 | ⚠️ | Shadows, post-process and PBR on both; compute shaders are WebGPU only. [Status](https://doc.babylonjs.com/setup/support/webGPU/webGPUStatus) | +| A3 | ✅ | Built-in materials and `NodeMaterial` emit GLSL and WGSL; hand-written shaders need both. [Docs](https://doc.babylonjs.com/setup/support/webGPU/webGPUWGSL) | +| A4 | ✅ | WebGPU where available; WebGL2/1 fallback for mobile and older browsers. | +| B1 | ⚠️ | POC: 60 FPS (vsync cap) with 2,000 meshes; with 20,000 unbatched meshes 24.9 FPS on WebGL but 5.3 FPS on WebGPU (p95 340 ms). See [POC](./poc). | +| B2 | ❌ | Measured 1.81 MB raw, 424 KB gzip (WebGPU + fallback, deep imports). WebGL only: 344 KB. Code splitting: 191 KB first chunk. | +| B3 | ⚠️ | POC: about 345 ms to the first frame with 2,000 meshes, about 3.1 s with 20,000 (`clone()` per mesh). See [POC](./poc). | +| B4 | ✅ | OffscreenCanvas in a worker is documented. [Docs](https://doc.babylonjs.com/features/featuresDeepDive/scene/offscreenCanvas) | +| C1 | ✅ | `new Engine(canvas)` / `new WebGPUEngine(canvas)` takes our canvas. | +| C2 | ✅ | `runRenderLoop` is opt-in; from our tick call `engine.beginFrame()`, `scene.render()`, `engine.endFrame()` (POC: without them WebGPU never submits and screenshots never resolve). | +| C3 | ✅ | `scene.dispose()` and `engine.dispose()`; POC: no global left on `window` in the browser (ES packages; only the UMD build sets `window.BABYLON`). | +| C4 | ✅ | `engine.resize()`, `setHardwareScalingLevel()`, `adaptToDeviceRatio`, camera `viewport`. | +| C5 | ✅ | Measured: `Maths/math.vector.js` imports and computes in Node 24 with no DOM. | +| C6 | ⚠️ | No entity system imposed, but `TransformNode`/`Mesh` are heavy OOP objects. | +| D1 | ✅ | `scene.pick(x, y)`, `createPickingRay`, `Vector3.Project`. [Docs](https://doc.babylonjs.com/features/featuresDeepDive/mesh/interactions/picking_collisions) | +| D2 | ✅ | `GizmoManager` in core: position, rotation, scale, bounding box. [Docs](https://doc.babylonjs.com/features/featuresDeepDive/mesh/gizmo) | +| D3 | ✅ | ArcRotate, Universal and Free cameras; `scene.activeCamera` switch. | +| D4 | ✅ | `SceneSerializer`, `.babylon` JSON, `AssetContainer`. [Docs](https://doc.babylonjs.com/setup/support/.babylonFileFormat) | +| D5 | ✅ | POC: `CreateScreenshotAsync` and `canvas.toDataURL()` give a painted PNG on both backends, once frames are wrapped in `beginFrame`/`endFrame`. | +| D6 | ✅ | POC: the canvas moved into another document (iframe) keeps rendering on both backends, no error. A real `window.open` window is not tested. | +| E1 | ✅ | Large docs and a Playground with thousands of samples; hello cube and glTF in about 10 lines each. [Playground](https://playground.babylonjs.com) | +| E2 | ⚠️ | `@babylonjs/accessibility` mirrors tagged meshes as HTML for screen readers and keyboard navigation; no reduced-motion support. [Docs](https://doc.babylonjs.com/features/featuresDeepDive/accessibility/accessibilityScreenReader) | +| E3 | ⚠️ | Image processing and custom post-process, no built-in colorblind filter; GUI scales with `idealWidth`. | +| F1 | ✅ | Apache-2.0; Havok plugin MIT; no SaaS. | +| F2 | ✅ | 26k stars, about 1,700 commits and 100+ releases in 12 months, 369k npm downloads per week. | +| F3 | ✅ | Written in TypeScript, ships `.d.ts`. | +| F4 | ✅ | glTF via `@babylonjs/loaders`; KTX2/Basis, Draco, meshopt, skeletal and morph animation. | +| G1 | ✅ | `PBRMaterial`, cascaded shadows, IBL. | +| G2 | ✅ | Physics v2 with the official Havok plugin (`@babylonjs/havok`). | +| G3 | ✅ | `@babylonjs/gui`, sprites, text; Konva on top with a transparent `clearColor`. | diff --git a/docs/docs/lib-graphic-3d/index.mdx b/docs/docs/lib-graphic-3d/index.mdx new file mode 100644 index 00000000..e081c99a --- /dev/null +++ b/docs/docs/lib-graphic-3d/index.mdx @@ -0,0 +1,171 @@ +--- +title: "3D graphics library benchmark" +icon: "cube" +description: "Comparison of 3D libraries with WebGPU and a WebGL fallback, for the game and the editor" +--- + +# 3D graphics library benchmark + +NanoForge needs a 3D graphics library next to `graphics-2d` (Konva). It must render with WebGPU and fall back to WebGL by itself, perform well, and be accessible. It is used by the game and by the editor (Scene screen, entity drag, screenshots, pop-out window). + +Benchmark run on 2026-11-05. + +## Method + +- Each library is scored on every criterion: ✅ meets it, ⚠️ partly or with a workaround, ❌ does not, ❓ unknown (not measured or not tested yet). +- Each score has one line of evidence: official docs, the library's source, or a measurement. +- **Measured:** B2 (bundle size) and C5 (math in Node) for every candidate; B1, B3, C3, D5 and D6 in a browser for the two finalists (see [POC](./poc)). Everything else comes from docs and source code. +- **Eliminatory:** A1, and every ❌ in families C and D. Those decide whether the library can be integrated at all. + +## Criteria + +### A. Rendering and compatibility + +| Id | Criterion | Description | How it is measured | +| --- | ------------------ | ----------------------------------------------------------------------- | -------------------------------------------------------- | +| A1 | WebGL fallback | Falls back to WebGL by itself when WebGPU is missing, without app code. | Docs and source of the device/engine creation. | +| A2 | Backend parity | Features lost on WebGL (shadows, post-process, compute…). | Docs of WebGPU status; list of WebGPU-only features. | +| A3 | Write-once shaders | One material or custom shader source runs on both backends. | Docs of the shader/material system (TSL, NodeMaterial…). | +| A4 | Browser targets | Chrome, Firefox, Safari, mobile. | Docs and caniuse for WebGPU; WebGL2 support otherwise. | + +### B. Performance + +| Id | Criterion | Description | How it is measured | +| --- | --------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| B1 | FPS under load | Frame time of a typical scene (many meshes, instancing) on each backend. | In-browser POC scene, 2,000 and 20,000 meshes (finalists only). | +| B2 | Bundle size | Minimal cost of a game. The loader caches games per file and the editor tracks its chunk sizes. | Minimal scene (renderer, camera, box, material, light), `esbuild --bundle --minify --format=esm`, then `gzip -9`. | +| B3 | Init time | Time from `__init` to the first frame. | In-browser POC, time to the first frame (finalists only). | +| B4 | Off main thread | OffscreenCanvas and worker rendering. | Docs and constructor types. | + +### C. Engine integration + +Modelled on `Graphics2DLibrary` (`modules/graphics-2d`). + +| Id | Criterion | Description | How it is measured | +| --- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| C1 | Provided container | Renders into a canvas or element we give it, without its own page or app shell. | Constructor API. | +| C2 | Render from our tick | A frame can be rendered on demand from the engine tick, with no forced `requestAnimationFrame` loop. Needed for pause and step in the editor. | Source of the render loop. | +| C3 | Clean teardown | `__clear` destroys everything: no GPU leak, no leftover global (we already delete `window.Konva`). | Dispose API; globals added on import, checked in Node and in the bundle. | +| C4 | Follows the viewport | Resize, pixel ratio, letterbox, pixel perfect, from `ViewportState`. | Resize, pixel ratio and viewport APIs. | +| C5 | Math on the server | `Vector3`, `Quaternion` and matrices import in Node or Bun without a DOM, for components shared by client and server. | `node` ESM import of the math classes and one transform. | +| C6 | ECS friendly | A light scene graph we sync from our components, not an entity system of its own. | Docs of the scene model. | + +### D. Editor integration + +| Id | Criterion | Description | How it is measured | +| --- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| D1 | Picking | Screen to object raycast, and world to screen projection (the editor outlines entities over the game from the `viewport` event). | Picking and projection APIs. | +| D2 | Transform gizmos | Translate, rotate, scale, in the library or an official addon. | Docs and package contents. | +| D3 | Editor camera | Orbit and fly controls, separate from the game camera. | Official controls. | +| D4 | Scene from data | Builds the scene from the static model of `main.ts`, without running the game (what the 2D Scene screen does). | Serialization / scene loading APIs. | +| D5 | Canvas capture | PNG screenshot on WebGPU and WebGL. | Screenshot API, or `toBlob` constraints per backend. | +| D6 | Pop-out window | Rendering survives the canvas moving to another window or document. | In-browser POC: canvas moved to another document (finalists only). | + +### E. Accessibility + +| Id | Criterion | Description | How it is measured | +| --- | ---------------- | -------------------------------------------------------------------------------------- | ------------------------------------------ | +| E1 | Ease of learning | Docs quality, number of examples, effort for a hello cube with a glTF model. | Docs, example count, size of a hello cube. | +| E2 | Player a11y | 3D objects exposed to the DOM and ARIA, keyboard navigation, `prefers-reduced-motion`. | Docs and source search. | +| E3 | Visual a11y | Colorblind post-process, contrast, UI scaling. | Docs of post-process and UI. | + +### F. Ecosystem and sustainability + +| Id | Criterion | Description | How it is measured | +| --- | ---------- | -------------------------------------------------------------- | ------------------------------- | +| F1 | License | MIT or Apache, no proprietary part or mandatory SaaS. | `LICENSE` and package metadata. | +| F2 | Activity | Commits and releases over 12 months, maintainers (bus factor). | GitHub and npm APIs. | +| F3 | TypeScript | Shipped types and their quality. | Package contents. | +| F4 | Assets | glTF, KTX2/Basis, Draco, skeletal animation. | Docs of loaders. | + +### G. Game features + +| Id | Criterion | Description | How it is measured | +| --- | ------------------- | -------------------------------------------------- | ------------------ | +| G1 | Materials and light | PBR, shadows, environment lighting. | Docs. | +| G2 | Physics | Official integration or plugin. | Docs. | +| G3 | UI in 3D | Text, sprites, 2D overlay (combinable with Konva). | Docs. | + +## Candidates + +| Library | Version | License | +| ------------------------------------------------------------------------- | -------------- | ---------- | +| [Three.js](https://github.com/mrdoob/three.js) (`three/webgpu`) | r187 (0.187.0) | MIT | +| [Babylon.js](https://github.com/BabylonJS/Babylon.js) (`@babylonjs/core`) | 9.34.0 | Apache-2.0 | +| [PlayCanvas Engine](https://github.com/playcanvas/engine) (`playcanvas`) | 2.23.3 | MIT | +| [luma.gl](https://github.com/visgl/luma.gl) (`@luma.gl/*`) | 9.4.2 | MIT | + +### Eliminated at A1 + +| Library | Reason | +| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Galacean Engine](https://github.com/galacean/engine) 1.6.13 | No WebGPU backend, including the 2.0 alphas. | +| [LayaAir](https://github.com/layabox/LayaAir) 3.4.2 | WebGPU is picked at build time (separate WebGPU and WebGL bundles), no runtime fallback. The WebGPU driver is closed source and the engine is not on npm. | +| [RedGPU](https://github.com/redcamel/RedGPU) | WebGPU only. | +| Orillusion, TypeGPU | WebGPU only. | + +## Results + +| | Three.js | Babylon.js | PlayCanvas | luma.gl | +| -------------------------- | --------- | ---------- | ---------- | ---------- | +| A1 WebGL fallback | ✅ | ✅ | ✅ | ✅ | +| A2 Backend parity | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| A3 Write-once shaders | ✅ | ✅ | ⚠️ | ❌ | +| A4 Browser targets | ✅ | ✅ | ✅ | ✅ | +| B1 FPS under load | ⚠️ | ⚠️ | ❓ | ❓ | +| B2 Bundle size (gzip) | ⚠️ 222 KB | ❌ 424 KB | ⚠️ 279 KB | ⚠️ 112 KB | +| B3 Init time | ✅ | ⚠️ | ❓ | ❓ | +| B4 Off main thread | ⚠️ | ✅ | ⚠️ | ⚠️ | +| C1 Provided container | ✅ | ✅ | ✅ | ✅ | +| C2 Render from our tick | ⚠️ | ✅ | ⚠️ | ✅ | +| C3 Clean teardown | ⚠️ | ✅ | ⚠️ | ⚠️ | +| C4 Follows the viewport | ✅ | ✅ | ✅ | ✅ | +| C5 Math on the server | ✅ | ✅ | ✅ | ✅ | +| C6 ECS friendly | ⚠️ | ⚠️ | ❌ | ✅ | +| D1 Picking | ✅ | ✅ | ✅ | ⚠️ | +| D2 Transform gizmos | ✅ | ✅ | ✅ | ❌ | +| D3 Editor camera | ✅ | ✅ | ✅ | ✅ | +| D4 Scene from data | ✅ | ✅ | ⚠️ | ⚠️ | +| D5 Canvas capture | ✅ | ✅ | ⚠️ | ⚠️ | +| D6 Pop-out window | ✅ | ✅ | ❓ | ❓ | +| E1 Ease of learning | ✅ | ✅ | ✅ | ⚠️ | +| E2 Player a11y | ❌ | ⚠️ | ❌ | ❌ | +| E3 Visual a11y | ⚠️ | ⚠️ | ⚠️ | ❌ | +| F1 License | ✅ | ✅ | ✅ | ✅ | +| F2 Activity | ✅ | ✅ | ✅ | ⚠️ | +| F3 TypeScript | ⚠️ | ✅ | ✅ | ✅ | +| F4 Assets | ✅ | ✅ | ✅ | ⚠️ | +| G1 Materials and light | ✅ | ✅ | ✅ | ⚠️ | +| G2 Physics | ⚠️ | ✅ | ⚠️ | ❌ | +| G3 UI in 3D | ✅ | ✅ | ✅ | ⚠️ | +| **✅ Meets** | **19** | **23** | **15** | **10** | +| **⚠️ Partly** | **10** | **6** | **10** | **12** | +| **❌ Does not** | **1** | **1** | **2** | **5** | +| **❓ Unknown** | **0** | **0** | **3** | **3** | +| **Eliminatory (A1, C, D)** | passes | passes | fails (C6) | fails (D2) | + +## Findings + +- **PlayCanvas** is out on C6: its own entity-component system would compete with ours. [Details](./playcanvas) +- **luma.gl** is out on D2: no transform gizmo, and it is a GPU layer more than a 3D engine. [Details](./luma-gl) +- **Babylon.js** leads (23 ✅). [Details](./babylon-js) + - the only library with something for player a11y (`@babylonjs/accessibility`); + - picking, gizmos, editor cameras, serialization and screenshots all in core; no hidden loop and no global left on `window`; + - weak points: the bundle (424 KB gzip, 191 KB first chunk with code splitting), a slower start (about 350 ms), and a WebGPU backend that stalled with 20,000 unbatched meshes in the POC. +- **Three.js** is second (19 ✅). [Details](./three-js) + - lighter (222 KB gzip), starts in about 60 ms, the same speed on both backends, by far the largest ecosystem; + - but an internal `requestAnimationFrame` loop runs until `dispose()`, the import leaves `window.__THREE__`, types are a separate package, physics is only example wrappers, and nothing exists for a11y. +- **POC:** both finalists render from our tick, capture PNGs and survive a move to another document on both backends. With 2,000 meshes both reach the display rate. [Details](./poc) + +## Pages + +- [Three.js](./three-js): verdict, integration notes, evidence. +- [Babylon.js](./babylon-js): verdict, integration notes, evidence. +- [PlayCanvas](./playcanvas): verdict, integration notes, evidence. +- [luma.gl](./luma-gl): verdict, integration notes, evidence. +- [POC](./poc): in-browser measurements of the two finalists. + +## Next steps + +- Prototype a `graphics-3d` library on the chosen finalist, following `Graphics2DLibrary`. +- Measure with instancing, and on Firefox, Safari and mobile, before the final choice. diff --git a/docs/docs/lib-graphic-3d/luma-gl.mdx b/docs/docs/lib-graphic-3d/luma-gl.mdx new file mode 100644 index 00000000..d69f025b --- /dev/null +++ b/docs/docs/lib-graphic-3d/luma-gl.mdx @@ -0,0 +1,66 @@ +--- +title: "luma.gl" +icon: "cube" +description: "luma.gl in the 3D graphics library benchmark: verdict and evidence per criterion" +--- + +# luma.gl + +Part of the [3D graphics library benchmark](./index). Scores: ✅ meets, ⚠️ partly, ❌ does not, ❓ unknown. + +| | | +| ---------- | ---------------------------------------------------------------------------------------------------------------- | +| Packages | `@luma.gl/core`, `@luma.gl/webgpu`, `@luma.gl/webgl`, `@luma.gl/engine`, `@luma.gl/shadertools`, `@math.gl/core` | +| Version | 9.4.2 (`@math.gl/core` 4.1.0) | +| License | MIT | +| Repository | [visgl/luma.gl](https://github.com/visgl/luma.gl) | +| Result | Eliminated (D2) | +| Totals | ✅ 10 · ⚠️ 12 · ❌ 5 · ❓ 3 | + +## Verdict + +- A GPU abstraction layer more than a 3D engine: no built-in lit material, shaders are hand-written in both WGSL and GLSL. +- The best fit for our ECS (no entity system, no render loop, light `Model` objects) and the lightest bundle. +- Eliminated on D2: no transform gizmo. The editor would also need its own CPU raycast and world to screen projection. +- About 90% of commits come from one person; most downloads come from deck.gl, not standalone 3D use. + +## Integration notes + +- `__init`: `await luma.createDevice({ type: 'best-available', adapters: [webgpuAdapter, webgl2Adapter], createCanvasContext: { canvas } })`. +- `__clear`: `device.destroy()`, then delete the `globalThis.luma`, `mathgl`, `probe` and `Probe` globals set on import. +- `@math.gl/core` alone (8.7 KB gzip) works in Node and could serve shared components whatever the renderer. + +## Evidence + +| Id | Score | Evidence | +| --- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| A1 | ✅ | `luma.createDevice({ type: 'best-available', adapters: [webgpuAdapter, webgl2Adapter] })`. [Docs](https://luma.gl/docs/api-guide/background/webgpu-vs-webgl) | +| A2 | ⚠️ | No compute or storage buffers on WebGL2; 9.4 shadows are WebGPU only. | +| A3 | ❌ | App shaders need WGSL and GLSL; the Slang transpiler is still alpha. | +| A4 | ✅ | WebGL2 everywhere, WebGPU where available. | +| B1 | ❓ | Not measured; no 3D scene benchmark. | +| B2 | ⚠️ | Measured 399 KB raw, 112 KB gzip, without any built-in lit material (hand-written shaders). | +| B3 | ❓ | Async `createDevice`. Not measured. | +| B4 | ⚠️ | Canvas type accepts `OffscreenCanvas`; no worker docs. | +| C1 | ✅ | `createCanvasContext` with our canvas or container. [Docs](https://luma.gl/docs/api-reference/core/canvas-context) | +| C2 | ✅ | No rAF in core; `AnimationLoop` is optional. | +| C3 | ⚠️ | `destroy()` APIs; import sets `globalThis.luma`, `mathgl`, `probe`, `Probe`. | +| C4 | ✅ | `autoResize`, `useDevicePixels`, `pixelSizeSource`. | +| C5 | ✅ | Measured: `@math.gl/core` imports in Node 24 with no DOM (8.7 KB gzip). | +| C6 | ✅ | No entity system; `Model` per entity or optional `ScenegraphNode`. | +| D1 | ⚠️ | GPU picking only; no CPU raycast, world to screen by hand. | +| D2 | ❌ | No transform gizmo. | +| D3 | ✅ | `OrbitControls` in `@luma.gl/engine` 9.4. | +| D4 | ⚠️ | No scene format; glTF load and export only. | +| D5 | ⚠️ | No screenshot helper; `toBlob` right after `submit()`, untested. | +| D6 | ❓ | Not tested; the device belongs to the original window's `navigator.gpu`. | +| E1 | ⚠️ | 135 examples but low level: a hello cube needs hand-written WGSL and GLSL. | +| E2 | ❌ | No a11y features. | +| E3 | ❌ | No colorblind or contrast features. | +| F1 | ✅ | MIT. | +| F2 | ⚠️ | Active (about 1,000 commits in 12 months), but about 90% from one person; downloads come mostly from deck.gl. | +| F3 | ✅ | Written in TypeScript, detailed `.d.ts`. | +| F4 | ⚠️ | glTF with skin, morph and animation; Draco needs `@loaders.gl/draco` added. | +| G1 | ⚠️ | PBR and IBL; shadows only in `@luma.gl/experimental`, WebGPU only. | +| G2 | ❌ | No physics integration. | +| G3 | ⚠️ | `TextRenderer`, no sprite or UI system. | diff --git a/docs/docs/lib-graphic-3d/playcanvas.mdx b/docs/docs/lib-graphic-3d/playcanvas.mdx new file mode 100644 index 00000000..c0cf51d1 --- /dev/null +++ b/docs/docs/lib-graphic-3d/playcanvas.mdx @@ -0,0 +1,65 @@ +--- +title: "PlayCanvas" +icon: "cube" +description: "PlayCanvas in the 3D graphics library benchmark: verdict and evidence per criterion" +--- + +# PlayCanvas + +Part of the [3D graphics library benchmark](./index). Scores: ✅ meets, ⚠️ partly, ❌ does not, ❓ unknown. + +| | | +| ---------- | --------------------------------------------------------- | +| Package | `playcanvas` | +| Version | 2.23.3 | +| License | MIT (the SaaS editor is optional) | +| Repository | [playcanvas/engine](https://github.com/playcanvas/engine) | +| Result | Eliminated (C6) | +| Totals | ✅ 15 · ⚠️ 10 · ❌ 2 · ❓ 3 | + +## Verdict + +- Solid engine with editor tools (picking, official gizmos, camera controls) and good docs. +- Eliminated on C6: rendering goes through its own `Entity` + `ComponentSystem` model (render, camera and light are components). It would run a second ECS next to ours, or force us to drive low-level `GraphNode`/`MeshInstance` objects, which is not the documented use. +- Driving it from our tick works (`app.update(dt)` + `app.render()` without `app.start()`), but it is not documented. + +## Integration notes + +- `__init`: `await createGraphicsDevice(canvas, { deviceTypes: ['webgpu', 'webgl2'] })`, then `new AppBase(canvas)` with only the component systems we need (the measured 279 KB gzip). +- `__clear`: `app.destroy()` and `device.destroy()`; the static `AppBase._applications` registry keeps an entry per canvas id. +- Physics through the official components needs ammo.js as a global `Ammo`, which cannot be shared with a Node server. + +## Evidence + +| Id | Score | Evidence | +| --- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| A1 | ✅ | `createGraphicsDevice(canvas, { deviceTypes: ['webgpu', 'webgl2'] })` always appends WebGL2 as a last fallback. [Docs](https://developer.playcanvas.com/user-manual/graphics/webgpu/) | +| A2 | ⚠️ | Shadows, post-process and clustered lighting on both; compute is WebGPU only; WebGPU documented as maturing. | +| A3 | ⚠️ | Built-in materials run on both; custom `ShaderMaterial` needs GLSL and WGSL. | +| A4 | ✅ | WebGL2 everywhere, WebGPU where available. | +| B1 | ❓ | Not measured; no official benchmark. | +| B2 | ⚠️ | Measured 1.08 MB raw, 279 KB gzip (`AppBase` with render, camera and light systems). | +| B3 | ❓ | Async `createGraphicsDevice`. Not measured. | +| B4 | ⚠️ | No documented worker rendering path. | +| C1 | ✅ | `new AppBase(canvas)` takes our canvas. | +| C2 | ⚠️ | `app.start()` runs its own rAF loop; `update(dt)` + `render()` from our tick works but is not documented. | +| C3 | ⚠️ | `app.destroy()`, `device.destroy()`; static `AppBase._applications` registry, physics needs a global `Ammo`. | +| C4 | ✅ | `resizeCanvas`, `setCanvasResolution`, `setCanvasFillMode`, `maxPixelRatio`, camera `rect`. | +| C5 | ✅ | Measured: `Vec3`, `Quat`, `Mat4` import and compute in Node 24 with no DOM. | +| C6 | ❌ | Imposes its own Entity + ComponentSystem model. [Docs](https://developer.playcanvas.com/user-manual/ecs/) | +| D1 | ✅ | `screenToWorld`, `worldToScreen`, `Picker`. | +| D2 | ✅ | Official translate, rotate, scale gizmos and view cube. [Docs](https://developer.playcanvas.com/user-manual/gizmos/) | +| D3 | ✅ | Official `camera-controls` script (orbit, fly). | +| D4 | ⚠️ | Scene and template formats target the SaaS editor export. | +| D5 | ⚠️ | `toBlob` with `preserveDrawingBuffer` on WebGL; on WebGPU right after render or from a render target. | +| D6 | ❓ | Not tested; the device is tied to the canvas context. | +| E1 | ✅ | Large manual, 300+ live examples, hello cube in about 10 lines. [Examples](https://playcanvas.vercel.app/) | +| E2 | ❌ | No ARIA or reduced-motion support. | +| E3 | ⚠️ | No colorblind filter; UI screen scale modes. | +| F1 | ✅ | Engine MIT; the SaaS editor is optional. | +| F2 | ✅ | 17k stars, nightly betas, 148k npm downloads per week, maintained by Snap. | +| F3 | ✅ | Ships `playcanvas.d.ts`, generated from JSDoc. | +| F4 | ✅ | glTF/GLB, KTX2/Basis, Draco, skeletal animation and anim state graph. | +| G1 | ✅ | PBR `StandardMaterial`, clustered lights, cascaded shadows, IBL. | +| G2 | ⚠️ | Official rigidbody components rely on ammo.js as a global. | +| G3 | ✅ | Element component (MSDF text, images), sprites, screen-space UI. | diff --git a/docs/docs/lib-graphic-3d/poc.mdx b/docs/docs/lib-graphic-3d/poc.mdx new file mode 100644 index 00000000..333ddeb1 --- /dev/null +++ b/docs/docs/lib-graphic-3d/poc.mdx @@ -0,0 +1,70 @@ +--- +title: "3D benchmark POC" +icon: "flask" +description: "In-browser proof of concept for the two finalists, Three.js and Babylon.js" +--- + +# 3D benchmark POC + +In-browser proof of concept for the two finalists of the [3D graphics library benchmark](./index): [Three.js](./three-js) and [Babylon.js](./babylon-js). It fills the criteria that docs alone could not answer: B1, B3, D5, D6, and checks C2 and C3 in a real browser. + +Run on 2026-11-05. + +## Setup + +- **Machine:** Apple M5, macOS. +- **Browser:** Chrome 153, headless, with `--enable-unsafe-webgpu` and background throttling disabled, driven by Playwright. +- **Versions:** `three` 0.187.0, `@babylonjs/core` 9.34.0. +- **Runs:** 3 per configuration, medians reported. Spot checks in a visible 120 Hz browser gave the same results. + +## Scene + +The same scene in both libraries: + +- an 800×600 canvas; +- a perspective camera, an ambient (hemispheric) light and a directional light; +- N boxes sharing one geometry and one PBR material (`MeshStandardMaterial` / `PBRMetallicRoughnessMaterial`), on a grid; +- every frame, each box gets a new rotation, then the scene renders. + +The frame is rendered from our own `requestAnimationFrame` loop, which stands for the engine tick: Babylon's `runRenderLoop` is not used. Meshes are plain objects, without instancing or batching, which is what a naive ECS sync would produce. + +## Tests + +| Id | Test | +| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| B3 | Time from creating the renderer to the first frame shown (two `requestAnimationFrame` after the first render). Library import time is excluded. | +| B1 | Frame time over 5 seconds: average FPS and 95th percentile. N = 2,000 (a small game) and N = 20,000 (stress). | +| D5 | PNG right after a render, with `canvas.toDataURL()` and the library's own API (Babylon `CreateScreenshotAsync`), checked to contain more than the clear color. | +| D6 | The canvas is moved with `adoptNode` into a same-origin iframe (another document, as in a pop-out window) and renders 10 more frames; then a PNG is checked. | +| C3 | After dispose, the list of `window` keys added since before the import. | + +## Results + +| Library | Backend | N | Init (ms) | FPS | p95 frame (ms) | D5 capture | D6 other document | Globals left | +| ---------- | ------- | ------ | --------- | ---- | -------------- | ---------- | ----------------- | ------------ | +| Three.js | WebGPU | 2,000 | 57 | 60.1 | 16.8 | ✅ | ✅ | `__THREE__` | +| Three.js | WebGL | 2,000 | 58 | 60.0 | 17.3 | ✅ | ✅ | `__THREE__` | +| Babylon.js | WebGPU | 2,000 | 348 | 59.5 | 17.2 | ✅ | ✅ | none | +| Babylon.js | WebGL | 2,000 | 341 | 59.9 | 17.2 | ✅ | ✅ | none | +| Three.js | WebGPU | 20,000 | 367 | 11.7 | 90.5 | ✅ | ✅ | `__THREE__` | +| Three.js | WebGL | 20,000 | 327 | 12.4 | 83.9 | ✅ | ✅ | `__THREE__` | +| Babylon.js | WebGPU | 20,000 | 3,129 | 5.3 | 340.3 | ✅ | ✅ | none | +| Babylon.js | WebGL | 20,000 | 3,064 | 24.9 | 40.3 | ✅ | ✅ | none | + +Headless Chrome caps at 60 FPS, so 2,000 meshes run at the cap for both. In the visible browser (120 Hz) they ran at 120 FPS for both. + +## Findings + +- **B1:** with 2,000 meshes both reach the display rate. With 20,000 unbatched meshes neither is playable: Three.js gives about 12 FPS on both backends, Babylon.js 25 FPS on WebGL but 5 FPS on WebGPU with long stalls (p95 340 ms). Both libraries offer instancing for this case, which the POC does not use. +- **B3:** Three.js reaches the first frame in about 60 ms, Babylon.js in about 350 ms. With 20,000 meshes Babylon takes about 3 s, spent in `clone()`. +- **C2 (Babylon.js):** rendering from our tick needs `engine.beginFrame()` and `engine.endFrame()` around `scene.render()`. Without them, WebGPU frames are never submitted and `CreateScreenshotAsync` never resolves. This is not in the getting-started docs. +- **D5:** both capture a painted PNG on both backends, provided the capture happens right after a render. +- **D6:** both keep rendering after the canvas moves to another document, on both backends, with no error. +- **C3:** Babylon.js leaves nothing on `window`; Three.js leaves `window.__THREE__`. +- **Cold start:** the very first run of Three.js in a fresh browser took 3.4 s (WebGPU) and 27.6 s (WebGL) to the first frame. It did not happen again, including in new pages, so it is most likely the GPU shader cache warming up. Not investigated further. + +## Limits + +- One machine and one browser (Chrome on Apple Silicon). Firefox, Safari and mobile are not measured. +- D6 uses a same-origin iframe, not a real `window.open` pop-out window (popups need a user gesture in the test browser). +- The stress scene is not optimized (no instancing, no frozen meshes), so it measures the default per-object cost, not the best case. diff --git a/docs/docs/lib-graphic-3d/three-js.mdx b/docs/docs/lib-graphic-3d/three-js.mdx new file mode 100644 index 00000000..ced23014 --- /dev/null +++ b/docs/docs/lib-graphic-3d/three-js.mdx @@ -0,0 +1,67 @@ +--- +title: "Three.js" +icon: "cube" +description: "Three.js in the 3D graphics library benchmark: verdict, integration notes and evidence per criterion" +--- + +# Three.js + +Part of the [3D graphics library benchmark](./index). Scores: ✅ meets, ⚠️ partly, ❌ does not, ❓ unknown. + +| | | +| ---------- | ----------------------------------------------------- | +| Package | `three` (`three/webgpu` entry, `WebGPURenderer`) | +| Version | r187 (0.187.0) | +| License | MIT | +| Repository | [mrdoob/three.js](https://github.com/mrdoob/three.js) | +| Result | Finalist, second | +| Totals | ✅ 19 · ⚠️ 10 · ❌ 1 · ❓ 0 | + +## Verdict + +- Lighter than Babylon.js (222 KB gzip) and by far the largest ecosystem (33.5M npm downloads per week). +- Fast to start: 57 ms to the first frame with 2,000 meshes in the POC, and the same speed on WebGPU and WebGL. +- Editor needs are covered by official addons: `Raycaster`, `TransformControls`, `OrbitControls`, `ObjectLoader`. +- Weak points: an internal `requestAnimationFrame` loop runs until `dispose()` even when we render from our tick, the import leaves `window.__THREE__`, types are a separate package (`@types/three`), physics is only example wrappers, and nothing exists for player a11y. + +## Integration notes + +- `__init`: `new WebGPURenderer({ canvas })`, `await renderer.init()`. The WebGL2 fallback is automatic; `forceWebGL: true` forces it. +- Tick: `renderer.render(scene, camera)` from our loop. Capture with `canvas.toDataURL()` right after it. +- Viewport: `setSize(visibleWidth, visibleHeight, false)`, `setPixelRatio(pixelRatio)`, `camera.setViewOffset` for the origin. +- `__clear`: dispose geometries, materials and textures we created, `await renderer.dispose()`, then `delete window.__THREE__` (as we do for `window.Konva`). + +## Evidence + +| Id | Score | Evidence | +| --- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| A1 | ✅ | `WebGPURenderer` switches to its WebGL2 backend by itself; `forceWebGL` forces it. [Docs](https://threejs.org/docs/#api/en/renderers/webgpu/WebGPURenderer) | +| A2 | ⚠️ | Shadows and TSL post-processing on both; storage textures, indirect draw and full compute are reduced on WebGL2. [Manual](https://threejs.org/manual/#en/webgpurenderer) | +| A3 | ✅ | TSL and node materials compile to WGSL and GLSL from one source. [TSL](https://github.com/mrdoob/three.js/wiki/Three.js-Shading-Language) | +| A4 | ✅ | WebGPU on Chrome/Edge 113+, Safari 26, Firefox 141+ (Windows); WebGL2 elsewhere. [caniuse](https://caniuse.com/webgpu) | +| B1 | ⚠️ | POC: 60 FPS (vsync cap) with 2,000 meshes; 11.7 FPS on WebGPU and 12.4 on WebGL with 20,000 unbatched meshes. See [POC](./poc). | +| B2 | ⚠️ | Measured 818 KB raw, 222 KB gzip. The `three/webgpu` entry pulls the whole node system. | +| B3 | ✅ | POC: 57 ms to the first frame with 2,000 meshes, about 350 ms with 20,000, on both backends. See [POC](./poc). | +| B4 | ⚠️ | OffscreenCanvas documented for WebGL; WebGPU in a worker not verified. [Manual](https://threejs.org/manual/#en/offscreencanvas) | +| C1 | ✅ | Takes our `canvas`, or `renderer.domElement` goes in any container. | +| C2 | ⚠️ | `render()` can be called from our tick, but it starts an internal rAF bookkeeping loop that runs until `dispose()`. | +| C3 | ⚠️ | `await renderer.dispose()`, plus `.dispose()` on each geometry, material, texture. POC: `window.__THREE__` stays after dispose. | +| C4 | ✅ | `setSize`, `setPixelRatio`, `setViewport`, `setScissor`, `camera.setViewOffset`. | +| C5 | ✅ | Measured: `Vector3`, `Quaternion`, `Matrix4` import and compute in Node 24 with no DOM. | +| C6 | ⚠️ | `Object3D` imposes no entity system, but it is a heavy OOP hierarchy to keep in sync. | +| D1 | ✅ | `Raycaster.setFromCamera`, `Vector3.project(camera)`. [Docs](https://threejs.org/docs/#api/en/core/Raycaster) | +| D2 | ✅ | Official `TransformControls` addon. | +| D3 | ✅ | Official `OrbitControls`, `MapControls`, `FlyControls`, `ArcballControls`. | +| D4 | ✅ | `Object3D.toJSON()` and `ObjectLoader`. [Docs](https://threejs.org/docs/#api/en/loaders/ObjectLoader) | +| D5 | ✅ | POC: `canvas.toDataURL()` right after `render()` gives a painted PNG on WebGPU and WebGL, without `preserveDrawingBuffer`. | +| D6 | ✅ | POC: the canvas moved into another document (iframe) keeps rendering on both backends, no error. A real `window.open` window is not tested. | +| E1 | ✅ | Large manual, about 500 official examples, hello cube with `GLTFLoader` in about 20 lines. [Examples](https://threejs.org/examples/) | +| E2 | ❌ | No ARIA, keyboard navigation or reduced-motion support. | +| E3 | ⚠️ | No built-in colorblind pass; writable as a TSL post-process. | +| F1 | ✅ | MIT, no SaaS. | +| F2 | ✅ | About 2,300 commits in 12 months, monthly releases, 117k stars, 33.5M npm downloads per week. | +| F3 | ⚠️ | Types in the separate `@types/three`, sometimes behind a release. | +| F4 | ✅ | `GLTFLoader`, `KTX2Loader`, `DRACOLoader`, `AnimationMixer`. | +| G1 | ✅ | `MeshStandardMaterial`, `MeshPhysicalMaterial`, shadow maps, PMREM/IBL. | +| G2 | ⚠️ | No official physics; basic Rapier, Jolt and Ammo wrappers in the examples. | +| G3 | ✅ | Sprites, `CSS2DRenderer`/`CSS3DRenderer`, troika-three-text; Konva on top or as a `CanvasTexture`. |