fancy-3d-babylon

Building production 3D scenes forces a hard choice: pull in a full engine SDK (a multi-megabyte WebGL runtime every visitor downloads) or hand-roll a renderer from scratch. fancy-3d-babylon closes the gap with a turnkey Babylon.js adapter that plugs straight into the engine-agnostic @particle-academy/fancy-3d core — you describe a scene, this package renders it in real WebGL. Crucially, it is a Human+ surface: children of a <Monitor> render as live, interactive React projected onto a 3D plane — real DOM with full styling, accessibility, and event handling, not a rasterized texture snapshot. And because fancy-3d exposes the same Scene graph to its scene_* MCP bridge regardless of engine, an agent can position, paint, and rearrange nodes in the scene without ever scraping the canvas.

The package layers a WebGL renderer plus React components onto the fancy-3d core. The babylonEngine adapter (from the /engine subpath) mounts a Babylon Engine + Scene onto the core's <Canvas>, while the /react subpath ships declarative components: <Stage> owns the engine, camera (cameraRadius, cameraTarget, cameraAlpha/cameraBeta), lights, and render loop, and <Monitor> builds a bezel mesh and projects live React children onto it each frame via a matrix3d homography. The root entry adds createBabylonAdapter (painting widgets onto DynamicTexture planes) plus the full layout-helper set — placeOnGrid, placeOnArc, placeOnWall, placeOnSphere, placeOnPath, and placeOnCylinder — each mapping a node's 2D position onto a 3D arrangement, with sceneBounds to compute the extents they need. Every helper mutates the mesh in place, so swapping a globe for a gallery wall is a one-line change. @babylonjs/core is a peer dependency — it is lazy-required only when a Babylon scene actually mounts, so consumers using only the lightweight DOM engine pay zero Babylon bundle cost. The same applies in reverse: @particle-academy/fancy-3d-three mirrors this exact API against the same CanvasEngine interface, so engines are swappable without rewriting your scene. See the Babylon.js documentation for the underlying camera, mesh, and material primitives.

Install all three together — the core, this adapter, and Babylon itself: npm install @particle-academy/fancy-3d @particle-academy/fancy-3d-babylon @babylonjs/core. Mount the engine on the core's canvas with import { babylonEngine } from "@particle-academy/fancy-3d-babylon/engine" then <Canvas engine={babylonEngine} style={{ height: 480 }} />. For the declarative React API, the smallest scene is a <Stage> wrapping a <Monitor>: <Stage cameraTarget={[0, 1.5, 0]}><Monitor position={[0, 1.5, 0]} width={4} height={2.5}>…</Monitor></Stage>. To project live React, drop real components inside — e.g. a react-fancy <Card> — and they render as a fully interactive overlay tracked to the mesh, not a flat texture. To arrange many nodes, reach for a layout helper after computing bounds: const b = sceneBounds(scene); placeOnArc(node, mesh, b, { radius: 6, arc: Math.PI }) wraps your panels onto a gentle cylinder facing the camera. Swap placeOnArc for placeOnSphere or placeOnWall to restage the same scene without touching node data.