Ruby 3D Library.
Published to RubyGems as three-rb; require it in Ruby as three.
YouTube Demo: https://youtu.be/6JTtSg1pRp0
This project is in browser-first alpha. The current code covers the gem foundation, math primitives, scene graph basics, geometry/material objects, dirty-tracked backend sync, JSON export/load, browser examples, and a three.js backend/renderer bridge through ruby.wasm.
Supported scope for the first public release:
- Pure Ruby scene construction, math, cameras, lights, geometry, materials, textures, layers, raycasting helpers, and JSON export/load.
- Browser rendering through
Three::Renderers::ThreeJSRenderer, ruby.wasm, and pnpm-managedthree@0.184.0. - JavaScript-delegated browser features for texture loading, cube/RGBE textures, glTF/DRACO loading, OrbitControls, animation mixers, instancing, picking, shadows, and an initial postprocessing pipeline.
Out of scope for the first public release:
- A Ruby-native OpenGL/Vulkan/software renderer.
- Full three.js API compatibility.
- Stable APIs for every addon loader, render target, postprocessing pass, WebGPU, or XR workflow.
Install the released gem from RubyGems:
gem install three-rbOr add it to a Gemfile:
gem "three-rb", "~> 0.1"Browser rendering examples also need pnpm, because ruby.wasm, three.js, and three.js addons are installed from package.json.
three-rb is browser-first. The fastest way to try the released gem is to unpack a writable copy of the gem and run one of the included browser examples:
gem install three-rb
mkdir hello-three-rb
cd hello-three-rb
gem unpack three-rb
cd three-rb-*/
pnpm install
ruby -run -e httpd . -p 8000If Ruby reports that webrick is not found, install it once with gem install webrick. Ruby 3.0 and later no longer include WEBrick as a standard library.
http://localhost:8000/examples/browser/ruby/
This page runs the Ruby entrypoint at examples/browser/ruby/main.rb through ruby.wasm and renders a transparent red gemstone and extruded three-rb title with three.js. Use http://localhost:8000/...; do not open the files with file://, because the browser runtime loads ES modules, wasm, and assets over HTTP.
After the ruby example works, inspect examples/browser/ruby/main.rb to see the Ruby scene code. For the smallest possible browser scene, see examples/browser/cube/main.rb. For a standalone app directory with your own Ruby entrypoint, see Standalone Browser App. For Cloudflare Pages deployment, see Cloudflare Pages Deployment.
If you only want to confirm the Ruby API loads without browser rendering, create hello_three.rb:
require "three"
puts "three-rb #{Three::VERSION}"
scene = Three::Scene.new
camera = Three::PerspectiveCamera.new(75, aspect: 16.0 / 9.0)
camera.position.z = 5
geometry = Three::BoxGeometry.new(1, 1, 1)
material = Three::MeshBasicMaterial.new(color: 0x00ff00)
cube = Three::Mesh.new(geometry, material)
scene.add(cube)
puts scene.class
puts cube.classRun it:
ruby hello_three.rbYou should see the library load and create Ruby scene objects:
three-rb 0.1.0
Three::Scene
Three::Mesh
Browser rendering is available through Three::Renderers::ThreeJSRenderer, which targets three.js from ruby.wasm.
When developing this repository, install browser dependencies, serve the repository root, and open one of the browser examples:
pnpm install
ruby -run -e httpd . -p 8000If ruby -run -e httpd reports that webrick is not found, run gem install webrick and retry. Ruby 3.0 and later require WEBrick to be installed separately.
http://localhost:8000/examples/browser/ruby/
http://localhost:8000/examples/browser/cube/
http://localhost:8000/examples/browser/composition/
http://localhost:8000/examples/browser/textures/
http://localhost:8000/examples/browser/cubemap/
http://localhost:8000/examples/browser/gltf/
http://localhost:8000/examples/browser/serialization/
http://localhost:8000/examples/browser/picking/
http://localhost:8000/examples/browser/primitives/
http://localhost:8000/examples/browser/postprocessing/
See Browser Examples for the feature coverage map and per-example smoke commands. See Browser Runtime for the current embedding and boot contract.
The examples load pnpm-managed browser packages from node_modules/: @ruby/3.4-wasm-wasi@2.9.4-2026-05-11-a, @ruby/wasm-wasi@2.9.4-2026-05-11-a, and three@0.184.0.
To start a standalone browser app from the installed gem:
three-rb browser examples/browser/quickstart
pnpm install
ruby -run -e httpd . -p 8000Use three-rb browser examples/browser/ruby instead when you want the richer Ruby gemstone sample with its assets kept under examples/browser/ruby/assets/.
The generated Ruby entrypoint uses Three::Browser.run, so ordinary scene code does not need require "js" or JS.global.
Run the optional browser smoke tests:
pnpm install
pnpm exec playwright install chromium
pnpm test:browserRun the optional browser sync benchmarks:
pnpm benchmark:browser
pnpm benchmark:browser:mesh-sync
pnpm benchmark:browser:instanced-mesh-syncInstall dependencies:
bundle installRun tests:
bundle exec rake testBuild and install the gem into a temporary GEM_HOME, then run the install smoke test:
bundle exec rake release:gem_smokeExport a Ruby-authored scene to a deterministic JSON-friendly hash:
exported = Three::Exporters::ThreeJSONExporter.new.export(scene)
fixture = Three::Exporters::ThreeJSONExporter.new(deterministic_ids: true).export(scene)
json = scene.to_json
loaded_scene = Three::Loaders::ThreeJSONLoader.new.parse(json)Run the local release preflight check:
pnpm install
pnpm exec playwright install chromium
bundle exec rake release:preflightRun the full local CI-equivalent check, including dependency audits:
pnpm install --frozen-lockfile --ignore-scripts
pnpm audit --audit-level moderate
pnpm audit signatures
pnpm exec playwright install chromium
bundle exec rake release:preflight