tosijs-3d

github | live demo | npm

tosijs-3d logo

tosijs-3d is a library for building 3D web apps — and standalone apps, if that is what you want. Under the hood it uses Babylon.js for rendering, glTF/GLB for models and the usual bitmap formats for textures — but it also leans on SVG, for textures and for the entire user interface.

Free and open source, and light for what it is (Babylon is not small; this adds little to it). Scenes are composed from web components, so a world is markup you can read:

b3d(
  b3dSun(),
  b3dSkybox({ timeOfDay: 6 }),
  b3dLoader({ url: './scene.glb' }),
  b3dWater({ y: -0.2 })
)

The doc site has about a hundred live demos you can edit in place; the b3d page is that scene running.

Getting started

npm install tosijs-3d tosijs @babylonjs/core @babylonjs/gui @babylonjs/loaders @babylonjs/materials

Babylon (^9) and tosijs (^1.9.2) are peer dependencies: you install them, so there is exactly one copy of the engine in your app. jolt-physics is an optional peer, needed only if you use b3dPhysics.

A first scene, with no model file to find:

import { b3d, b3dSun, b3dSkybox, b3dGround, b3dBox, b3dSphere } from 'tosijs-3d'

document.body.append(
  b3d(
    b3dSun(),
    b3dSkybox({ timeOfDay: 10 }),
    b3dGround({ size: 24, texture: 'checker' }),
    b3dBox({ x: -1.5, y: 0.5, color: '#c8553d' }),
    b3dSphere({ x: 1.5, y: 1, diameter: 2, color: '#ffd166' })
  )
)

Give tosi-b3d a size in CSS (tosi-b3d { width: 100vw; height: 100vh }) and you have a lit scene with shadows and an orbit camera. Then:

Four things you may not have seen in a 3D library

Flat 3D and VR are the same app. You can enter and leave an immersive session without the simulation resetting — the scene, the physics and your place in the world all survive the transition, because nothing is torn down to make it.

One user interface, in three places. The SVG-powered widget set renders identically as a DOM overlay, on a plane inside a 3D scene, and in VR. Not three implementations that drift — one, with three presentations, where any divergence is treated as a bug.

One control system, every input. Keyboard and mouse, gamepads, VR controllers and touch all arrive as the same ControlInput. You write the behaviour once; supporting a new device is a new provider, not a rewrite.

The simulation is testable without a GPU. The flight model, the combat maths, the world state and the layout engine are deliberately Babylon-free, deterministic, and unit-tested — so the interesting logic can be exercised in milliseconds rather than in a browser.

Finding things

Search the attribute index before assuming a capability does not exist — one greppable line per attribute, generated from source on every build. There is a JSON form for tools, and both ship inside the package, so an agent already in a consumer project reads node_modules/tosijs-3d/static/attributes.txt with no network.

It exists because the recurring adopter failure is not a missing feature, it is a feature that ships, is documented, and cannot be found: three issues in one week turned out to be capability that was already there. One grep water finds submersible; reading two hundred doc pages does not.

Upgrading? See Migration for the breaking changes and what to do about them, and the Changelog for the full detail, one page per version. Both ship inside the package (Migration.md, and CHANGELOG.md with its changelog/ folder), so they work from node_modules too.

Highlights

Procedural astronomical objects — planets, stars and star systems, galaxies, and black holes with accretion disk, photon ring and lensing. Generated, not modelled — a solar system is a few attributes.

Procedural terrain — streaming LOD terrain with a biome shader that runs one material from seafloor to mountain, a floating origin so worlds can be large, and carved landforms — volcanoes with lava tubes bored through them, arches, caverns.

Biped control — a character controller with an animation state machine and follow/XR cameras, from a GLB: walk, run and sprint, jump, swim, climb ledges, and hold a gun that points where you aim, crouched or standing. Crowds of thousands are drawn on the GPU, and each figure can be moved, turned and re-clipped.

Any character on one animation library — retargeting plays the Universal Animation Library's clips on a Mixamo, Kenney or Blender-named rig, A-pose or T-pose. A mesh with no skeleton at all is auto-rigged from eight markers, fingers and tail found from its shape and bound by bone heat. Hair, tails and capes hang on spring bones. The rig tool does it in the browser and saves a recipe a game applies in one call, and an editor can mount it in its own scene.

Effects as data — an effect is particles, light and sound as layers on one clock, with one activity dial (a volcano dormant, semi-active or erupting is one recipe). Presets for volcanoes, geysers, explosions, fireballs, splashes and sparks; sprites and sounds generated, no files. The effect tool edits them live.

Vehicles and a city to drive them in — a car and a tank on one pure vehicle model (springs, tyre grip, skid steer; no physics engine), with a chase camera that orbits, booms up to overhead and climbs over what is in its way, flat and in a headset. A procedural city of Kenney's kits with traffic, street lights, lit windows and their sound; City Drive and Cross Country are the demos.

Aircraft control — a forgiving flight model that flies like a drone below transition speed and like a plane above it, with VTOL, bank-to-turn, a HUD and radar.

One UI for flat, in-scene and VR — the widget set renders as a DOM overlay, as a texture on a surface in the scene, and as a floating panel in a headset, from the same declaration. Includes a flowing box model, menus and panels, a data table, and an on-screen keyboard — because a headset has nowhere to type. A system bar of buttons and cascading menus sits in the corner flat and up ahead in VR.

SVG textures — draw with SVG, use it as a live texture. Designer artwork becomes a HUD, a gauge, or a control surface without a round-trip through a bitmap.

...and a few things that are less visible but are why the rest works:

Every input device behind one interface — keyboard/mouse, touch, hardware gamepads and XR controllers all produce the same ControlInput, so an entity is driven identically by a thumbstick, a glass pad, or an AI. Vehicle enter/exit and input focus come with it. Most frameworks hand you the input surface and wish you luck.

Simulation that doesn't know about the renderer — a pure, deterministic world store with a documented contract, so an external driver (a narrative engine, a test, a headless run) can drive a world the simulation never had to anticipate.

Adaptive by default — a device-capability probe vends per-tier budgets, and performance-sensitive settings resolve to auto rather than to a number that is always wrong for something. A Quest and a workstation get different worlds.

A character core for any engine — the character creator's working parts (body, shape, rig, retargeting, hair, clothes, the character file) are engine-free subpaths, so a three.js app or a server imports them without Babylon.

Pure models, actually tested — the flight model, ballistics, guidance, biome classification, layout and text editing are engine-free and unit-tested (about 3,900 tests, run in about a minute with no GPU). If it can be a function of its inputs, it is.

Development

Requires Bun.

bun install
bun tls     # once: local HTTPS certificates (needs mkcert)
bun start   # the doc site and dev server, rebuilding on change
bun test

The dev server runs on https://localhost:8030.