three-rb 0.2.1 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +26 -2
- data/README.md +12 -6
- data/docs/browser-runtime.md +9 -7
- data/docs/cloudflare-pages.md +205 -0
- data/docs/implementation-plan.md +6 -4
- data/docs/next-work.md +26 -25
- data/docs/publishing.md +1 -1
- data/docs/release-readiness.md +11 -11
- data/docs/standalone-browser-app.md +5 -3
- data/examples/browser/README.md +3 -1
- data/examples/browser/composition/index.html +65 -4
- data/examples/browser/cube/README.md +3 -3
- data/examples/browser/cube/index.html +61 -6
- data/examples/browser/cubemap/index.html +60 -5
- data/examples/browser/dango/README.md +26 -0
- data/examples/browser/dango/boot.mjs +6 -0
- data/examples/browser/dango/index.html +197 -0
- data/examples/browser/dango/main.rb +278 -0
- data/examples/browser/dango/smoke_test.mjs +232 -0
- data/examples/browser/gltf/index.html +60 -5
- data/examples/browser/picking/index.html +61 -6
- data/examples/browser/postprocessing/index.html +61 -6
- data/examples/browser/primitives/index.html +61 -6
- data/examples/browser/ruby/README.md +1 -1
- data/examples/browser/ruby/assets/helvetiker_regular.typeface.json +1 -0
- data/examples/browser/ruby/index.html +112 -8
- data/examples/browser/ruby/main.rb +2 -6
- data/examples/browser/serialization/index.html +61 -6
- data/examples/browser/shared/boot.mjs +115 -13
- data/examples/browser/shared/config.mjs +3 -0
- data/examples/browser/shared/smoke_test_helpers.mjs +13 -8
- data/examples/browser/textures/index.html +61 -6
- data/lib/three/backends/threejs/parameters.rb +4 -1
- data/lib/three/backends/threejs/ruby_wasm_adapter.rb +8 -2
- data/lib/three/generators/browser_example.rb +136 -9
- data/lib/three/version.rb +1 -1
- data/package.json +9 -5
- data/pnpm-lock.yaml +1235 -31
- metadata +10 -3
- data/examples/browser/ruby/assets/studio.hdr +0 -5
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 3b2c30088eb50ea175bcfb1acff5671557efaec52ef06d8a8f262ee89a89d386
|
|
4
|
+
data.tar.gz: ca52f61e2113f82bc752801e48fcb80ddf8f128b48c9ff6b8b9e2f001ae82805
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: b0f152273904c156e653278e7d90cc9809bc3e064cd2e58f7866aedf04a7a6578775ce6f3cec3c67d687b13137ecfaf8eeee9d0889a0476cddf4b1908bd2e8ee
|
|
7
|
+
data.tar.gz: 12cd57afccf132fcf8e413a8c251eba6f6821a8087adb40ff96c7faa8fffbce0005a09d35072297aa51aa0eae8cad801875dab7c543614fa85e60a292c0575c9
|
data/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,30 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.3.0 - 2026-11-20
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- Added a dango browser example that builds a three-color dango from primitive meshes with lighting, shadows, and `OrbitControls`.
|
|
8
|
+
- Added a Cloudflare Pages deployment guide. In a repository checkout, `pnpm build:pages:ruby` builds a static `dist/` for the Ruby gemstone example. It bundles the Ruby entrypoint into one file, serves the browser packages under `/vendor/`, and loads ruby.wasm from jsDelivr, because the file is over the Pages 25 MiB asset limit.
|
|
9
|
+
- Added `examples/browser/shared/config.mjs`, which sets the URL the shared boot loads ruby.wasm from. It defaults to the local `node_modules` copy, and `globalThis.__threeRbRubyWasmUrl` overrides it. `three-rb browser` copies it into generated apps and keeps an existing copy even with `--force`.
|
|
10
|
+
- Browser examples and generated apps show a progress bar while ruby.wasm downloads and compiles, and suggest reloading if the page is still loading after 15 seconds.
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
|
|
14
|
+
- three-rb now requires Ruby 3.3 or later. Ruby 3.2 reached end of life on 2026-03-31. CI now also runs the Ruby tests on 3.3 and 4.0.
|
|
15
|
+
- Updated the pinned ruby.wasm packages, `@ruby/3.4-wasm-wasi` and `@ruby/wasm-wasi`, from a 2.9.4 nightly build to the 2.10.1 release.
|
|
16
|
+
- Updated the pinned three.js to 0.187.0 (r187). `MeshPhysicalMaterial#iridescence_thickness_range` is now sent to three.js as `iridescenceThicknessMinimum` and `iridescenceThicknessMaximum`, which require r187 or later.
|
|
17
|
+
- The Ruby gemstone and dango examples now request `PCFShadowMap`. three.js had already been rendering them with it in place of the deprecated `PCFSoftShadowMap`, which r187 removes.
|
|
18
|
+
- Removed the HDR environment from the Ruby gemstone example and its generated template. The bundled `studio.hdr` was a 2x2 uniform gray image that three.js r186 and earlier never applied, so the gem never showed it; from r187 on it only washed the gem out.
|
|
19
|
+
- `three-rb browser` now writes a `package.json` that lists only the browser runtime packages, and a `pnpm-lock.yaml` cut down to match, instead of copying the gem's own files with its test tooling and scripts. An existing `package.json` is kept, and no lockfile is written next to it.
|
|
20
|
+
- The shared boot aborts a ruby.wasm download that makes no progress for 20 seconds and retries it up to three times. It now chooses between `WebAssembly.compileStreaming` and `WebAssembly.compile` from the response's content type, instead of downloading the file again after a failed streaming compile.
|
|
21
|
+
- The browser smoke tests now generate apps with `three-rb browser`, install them with `pnpm install --frozen-lockfile`, and render them. They also fail on three.js console warnings.
|
|
22
|
+
|
|
23
|
+
### Fixed
|
|
24
|
+
|
|
25
|
+
- Textures from `TextureLoader` and the other loaders no longer make three.js warn "Texture marked for update but no image data found" on every frame until their image arrives.
|
|
26
|
+
- `MeshToonMaterial` no longer makes three.js warn that `flatShading` is not a property. `flat_shading` still takes effect.
|
|
27
|
+
|
|
3
28
|
## 0.2.1 - 2026-05-17
|
|
4
29
|
|
|
5
30
|
### Added
|
|
@@ -39,12 +64,11 @@
|
|
|
39
64
|
- Mesh, instanced mesh, line, points, and sprite object support.
|
|
40
65
|
- Common material APIs including basic, Lambert, Phong, standard, physical, matcap, toon, normal, shadow, line, points, and sprite materials.
|
|
41
66
|
- Browser rendering through ruby.wasm and a delegated three.js backend.
|
|
42
|
-
- `Three::Browser` helpers and a `three-rb browser` generator for Ruby-only browser entrypoints that avoid application-level `require "js"` and `JS.global` calls.
|
|
43
67
|
- Browser examples and Playwright smoke tests for cube, composition, textures, cubemap, glTF/DRACO, serialization, picking, primitives, and postprocessing.
|
|
44
68
|
- Texture loading, cube textures, RGBE environment textures, glTF loading, DRACO decoder configuration, animation mixers, OrbitControls, instancing, picking, shadows, and loaded-asset traversal/disposal helpers.
|
|
45
69
|
- Initial postprocessing wrappers for `EffectComposer`, `RenderPass`, `UnrealBloomPass`, `DotScreenPass`, and `OutputPass`.
|
|
46
70
|
- Deterministic JSON fixture regression coverage for exporter/loader compatibility.
|
|
47
|
-
- Release install smoke and preflight tasks for validating the built gem
|
|
71
|
+
- Release install smoke and preflight tasks for validating the built gem outside the repository load path.
|
|
48
72
|
|
|
49
73
|
### Notes
|
|
50
74
|
|
data/README.md
CHANGED
|
@@ -4,19 +4,23 @@ Ruby 3D Library.
|
|
|
4
4
|
|
|
5
5
|
Published to RubyGems as `three-rb`; require it in Ruby as `three`.
|
|
6
6
|
|
|
7
|
+

|
|
8
|
+
|
|
9
|
+
YouTube Demo: https://youtu.be/6JTtSg1pRp0
|
|
10
|
+
|
|
7
11
|
## Status
|
|
8
12
|
|
|
9
13
|
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.
|
|
10
14
|
|
|
11
15
|
## Browser-first alpha scope
|
|
12
16
|
|
|
13
|
-
Supported scope for the
|
|
17
|
+
Supported scope for the alpha releases:
|
|
14
18
|
|
|
15
19
|
- Pure Ruby scene construction, math, cameras, lights, geometry, materials, textures, layers, raycasting helpers, and JSON export/load.
|
|
16
|
-
- Browser rendering through `Three::Renderers::ThreeJSRenderer`, ruby.wasm, and pnpm-managed `three@0.
|
|
20
|
+
- Browser rendering through `Three::Renderers::ThreeJSRenderer`, ruby.wasm, and pnpm-managed `three@0.187.0`.
|
|
17
21
|
- JavaScript-delegated browser features for texture loading, cube/RGBE textures, glTF/DRACO loading, OrbitControls, animation mixers, instancing, picking, shadows, and an initial postprocessing pipeline.
|
|
18
22
|
|
|
19
|
-
Out of scope for the
|
|
23
|
+
Out of scope for the alpha releases:
|
|
20
24
|
|
|
21
25
|
- A Ruby-native OpenGL/Vulkan/software renderer.
|
|
22
26
|
- Full three.js API compatibility.
|
|
@@ -60,7 +64,7 @@ http://localhost:8000/examples/browser/ruby/
|
|
|
60
64
|
|
|
61
65
|
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.
|
|
62
66
|
|
|
63
|
-
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](docs/standalone-browser-app.md).
|
|
67
|
+
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](docs/standalone-browser-app.md). For Cloudflare Pages deployment, see [Cloudflare Pages Deployment](docs/cloudflare-pages.md).
|
|
64
68
|
|
|
65
69
|
## Plain Ruby Check
|
|
66
70
|
|
|
@@ -94,7 +98,7 @@ ruby hello_three.rb
|
|
|
94
98
|
You should see the library load and create Ruby scene objects:
|
|
95
99
|
|
|
96
100
|
```text
|
|
97
|
-
three-rb 0.
|
|
101
|
+
three-rb 0.3.0
|
|
98
102
|
Three::Scene
|
|
99
103
|
Three::Mesh
|
|
100
104
|
```
|
|
@@ -115,6 +119,7 @@ If `ruby -run -e httpd` reports that `webrick` is not found, run `gem install we
|
|
|
115
119
|
```text
|
|
116
120
|
http://localhost:8000/examples/browser/ruby/
|
|
117
121
|
http://localhost:8000/examples/browser/cube/
|
|
122
|
+
http://localhost:8000/examples/browser/dango/
|
|
118
123
|
http://localhost:8000/examples/browser/composition/
|
|
119
124
|
http://localhost:8000/examples/browser/textures/
|
|
120
125
|
http://localhost:8000/examples/browser/cubemap/
|
|
@@ -127,7 +132,7 @@ http://localhost:8000/examples/browser/postprocessing/
|
|
|
127
132
|
|
|
128
133
|
See [Browser Examples](examples/browser/README.md) for the feature coverage map and per-example smoke commands. See [Browser Runtime](docs/browser-runtime.md) for the current embedding and boot contract.
|
|
129
134
|
|
|
130
|
-
The examples load pnpm-managed browser packages from `node_modules/`: `@ruby/3.4-wasm-wasi@2.
|
|
135
|
+
The examples load pnpm-managed browser packages from `node_modules/`: `@ruby/3.4-wasm-wasi@2.10.1`, `@ruby/wasm-wasi@2.10.1`, and `three@0.187.0`.
|
|
131
136
|
|
|
132
137
|
To start a standalone browser app from the installed gem:
|
|
133
138
|
|
|
@@ -211,6 +216,7 @@ bundle exec rake release:preflight
|
|
|
211
216
|
- [Browser Runtime](docs/browser-runtime.md)
|
|
212
217
|
- [Browser Examples](examples/browser/README.md)
|
|
213
218
|
- [Standalone Browser App](docs/standalone-browser-app.md)
|
|
219
|
+
- [Cloudflare Pages Deployment](docs/cloudflare-pages.md)
|
|
214
220
|
- [Loaded Asset Traversal and Disposal Design](docs/loaded-assets-design.md)
|
|
215
221
|
- [Release Readiness](docs/release-readiness.md)
|
|
216
222
|
- [Publishing](docs/publishing.md)
|
data/docs/browser-runtime.md
CHANGED
|
@@ -20,9 +20,9 @@ Do not use `file://` for browser runs. The examples assume an HTTP server becaus
|
|
|
20
20
|
The runtime currently follows the pinned versions in `package.json`:
|
|
21
21
|
|
|
22
22
|
- `@bjorn3/browser_wasi_shim@0.4.2`
|
|
23
|
-
- `@ruby/3.4-wasm-wasi@2.
|
|
24
|
-
- `@ruby/wasm-wasi@2.
|
|
25
|
-
- `three@0.
|
|
23
|
+
- `@ruby/3.4-wasm-wasi@2.10.1`
|
|
24
|
+
- `@ruby/wasm-wasi@2.10.1`
|
|
25
|
+
- `three@0.187.0`
|
|
26
26
|
|
|
27
27
|
Install them from the repository root with:
|
|
28
28
|
|
|
@@ -70,6 +70,8 @@ The boot module is responsible for:
|
|
|
70
70
|
- `globalThis.THREE_GLTF_LOADER`
|
|
71
71
|
- `globalThis.THREE_DRACO_LOADER`
|
|
72
72
|
- `globalThis.THREE_RGBE_LOADER`
|
|
73
|
+
- `globalThis.THREE_FONT_LOADER`
|
|
74
|
+
- `globalThis.THREE_TEXT_GEOMETRY`
|
|
73
75
|
- `globalThis.THREE_ORBIT_CONTROLS`
|
|
74
76
|
- `globalThis.THREE_EFFECT_COMPOSER`
|
|
75
77
|
- `globalThis.THREE_RENDER_PASS`
|
|
@@ -77,7 +79,7 @@ The boot module is responsible for:
|
|
|
77
79
|
- `globalThis.THREE_DOT_SCREEN_PASS`
|
|
78
80
|
- `globalThis.THREE_OUTPUT_PASS`
|
|
79
81
|
- Setting `globalThis.__threeReady` to a promise Ruby can wait on.
|
|
80
|
-
- Loading `/node_modules/@ruby/3.4-wasm-wasi/dist/ruby+stdlib.wasm
|
|
82
|
+
- Loading ruby.wasm from the URL exported by `examples/browser/shared/config.mjs`. It defaults to `/node_modules/@ruby/3.4-wasm-wasi/dist/ruby+stdlib.wasm`; set `globalThis.__threeRbRubyWasmUrl` before the boot module loads, or edit `config.mjs`, to load it from another host.
|
|
81
83
|
- Starting the Ruby VM and loading the Ruby entrypoint through `JS::RequireRemote`.
|
|
82
84
|
|
|
83
85
|
The shared helper also installs optional render helpers used by smoke tests to draw immediately from Ruby renderer calls and expose render counters for deterministic assertions. Custom applications can keep that behavior or call directly into three.js through the renderer backend fallback.
|
|
@@ -183,9 +185,9 @@ For standalone projects, install the gem and generate a Ruby-only browser exampl
|
|
|
183
185
|
three-rb browser examples/browser/quickstart
|
|
184
186
|
```
|
|
185
187
|
|
|
186
|
-
`quickstart` generates an asset-free rotating cube. Use `three-rb browser examples/browser/ruby` to generate the richer Ruby gemstone sample; its
|
|
188
|
+
`quickstart` generates an asset-free rotating cube. Use `three-rb browser examples/browser/ruby` to generate the richer Ruby gemstone sample; its title font is copied under `examples/browser/ruby/assets/`.
|
|
187
189
|
|
|
188
|
-
The generator
|
|
190
|
+
The generator writes a `package.json` and `pnpm-lock.yaml` that list only the browser runtime packages, and copies the browser runtime files and `lib/` into the served project root, then creates `index.html`, `boot.mjs`, `main.rb`, and `README.md` for the example. Templates that need local files keep them under the generated example's `assets/` directory.
|
|
189
191
|
|
|
190
192
|
## JavaScript Escape Hatch
|
|
191
193
|
|
|
@@ -206,7 +208,7 @@ The browser runtime intentionally does not promise full three.js compatibility y
|
|
|
206
208
|
- Rendering is delegated to three.js through ruby.wasm.
|
|
207
209
|
- Addon wrappers only work when their JavaScript constructors are registered on `globalThis`.
|
|
208
210
|
- The JavaScript boot module is still required to import ES modules and start ruby.wasm, even though ordinary Ruby scene entrypoints can stay Ruby-only.
|
|
209
|
-
- The
|
|
211
|
+
- The alpha scope does not include stable APIs for every loader, material, render target, postprocessing pass, WebGPU, or XR workflow.
|
|
210
212
|
- `examples/browser/shared/boot.mjs` is a reference implementation for this repository's examples, not a separate stable package.
|
|
211
213
|
- `preserveDrawingBuffer: true` is useful for deterministic canvas smoke tests, but applications do not need it by default.
|
|
212
214
|
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
# Cloudflare Pages Deployment
|
|
2
|
+
|
|
3
|
+
This guide shows how to deploy a three-rb browser example to Cloudflare Pages.
|
|
4
|
+
|
|
5
|
+
Cloudflare Pages does not run the example's Ruby code on the server. Pages serves static files, the browser downloads ruby.wasm, and ruby.wasm runs the Ruby entrypoint in the user's browser.
|
|
6
|
+
|
|
7
|
+
The build scripts under `scripts/` belong to the three-rb repository and are not included in the gem, so run these steps from a clone of the repository.
|
|
8
|
+
|
|
9
|
+
## What Must Be Deployed
|
|
10
|
+
|
|
11
|
+
The current browser examples use root-relative URLs. The deployed output must preserve these paths:
|
|
12
|
+
|
|
13
|
+
- `/examples/browser/ruby/` for the Ruby gemstone example page, boot file, Ruby entrypoint, and local assets.
|
|
14
|
+
- `/examples/browser/shared/` for the shared JavaScript boot runtime.
|
|
15
|
+
- `/vendor/@ruby/wasm-wasi/` for the browser Ruby VM JavaScript package.
|
|
16
|
+
- `/vendor/@bjorn3/browser_wasi_shim/` for WASI browser support.
|
|
17
|
+
- `/vendor/three/` for three.js and its addons.
|
|
18
|
+
- `/` for the public demo entrypoint generated from the Ruby example page.
|
|
19
|
+
|
|
20
|
+
`/lib` is not deployed. The build script bundles the Ruby entrypoint and everything it reaches through `require_relative` into a single `dist/examples/browser/ruby/main.rb`, so the browser Ruby VM fetches one file instead of one per source file. See "Bundled Ruby Source" below.
|
|
21
|
+
|
|
22
|
+
Do not set `examples/browser/ruby` itself as the Cloudflare Pages output directory. That directory alone does not contain `/examples/browser/shared` or the required browser packages.
|
|
23
|
+
|
|
24
|
+
Cloudflare Pages has a 25 MiB maximum size for each static asset. The current `ruby+stdlib.wasm` file is larger than that limit, so the Pages build script does not upload it as a Pages asset. Instead, the generated `dist/examples/browser/shared/config.mjs` points at a CDN URL for the pinned `@ruby/3.4-wasm-wasi` package by default. If you prefer to own that asset, upload `node_modules/@ruby/3.4-wasm-wasi/dist/ruby+stdlib.wasm` to Cloudflare R2 or another static host that supports large files and set `RUBY_WASM_URL` to that public URL in the Pages environment.
|
|
25
|
+
|
|
26
|
+
Do not point `RUBY_WASM_URL` at an R2 `pub-*.r2.dev` URL. That endpoint is rate limited, is documented as development-only, and is not served through the Cloudflare CDN cache, so every visitor downloads the full 30 MB from the bucket itself. Attach a custom domain to the bucket, or serve it from a Worker, so the file is cached at the edge.
|
|
27
|
+
|
|
28
|
+
The Pages build script copies browser packages under `/vendor/` instead of `/node_modules/`. This avoids Pages deployments that omit or fail to serve `node_modules` paths, and keeps the deployed URLs separate from package-manager internals.
|
|
29
|
+
|
|
30
|
+
## Local Verification
|
|
31
|
+
|
|
32
|
+
Install the browser dependencies and run the existing smoke test:
|
|
33
|
+
|
|
34
|
+
```sh
|
|
35
|
+
pnpm install
|
|
36
|
+
pnpm test:browser:ruby
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
The smoke test starts a local static HTTP server and verifies that the Ruby VM boots, the Ruby scene loads, and three.js renders visible pixels. Use `http://...` URLs for manual testing; `file://` will not work because the runtime fetches ES modules, wasm, Ruby files, and assets.
|
|
40
|
+
|
|
41
|
+
## Recommended Output Directory
|
|
42
|
+
|
|
43
|
+
Create a deployment directory that contains only the static files required by the example:
|
|
44
|
+
|
|
45
|
+
```sh
|
|
46
|
+
pnpm run build:pages:ruby
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
This script rebuilds `dist/` from scratch, copies the Ruby example, shared browser boot runtime, and required browser packages, and bundles the Ruby entrypoint. It also generates `dist/index.html` and `dist/boot.mjs` so the public Pages root URL runs the Ruby example directly. It uses `cp -RL` for packages copied from local `node_modules` so pnpm symlinks are resolved into real files, then deploys those package files under `/vendor/`. Cloudflare Pages uploads the output directory contents, and a copied symlink to `.pnpm/...` will not work unless the referenced package store is also present in the deployment.
|
|
50
|
+
|
|
51
|
+
By default, the script writes a Pages-specific wasm URL into `dist/examples/browser/shared/config.mjs`, pinned to the `@ruby/3.4-wasm-wasi` version in `package.json`:
|
|
52
|
+
|
|
53
|
+
```text
|
|
54
|
+
https://cdn.jsdelivr.net/npm/@ruby/3.4-wasm-wasi@<version>/dist/ruby+stdlib.wasm
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
The build fails if `@ruby/3.4-wasm-wasi` and `@ruby/wasm-wasi` are on different versions, because the wasm binary and the JavaScript glue that loads it must match.
|
|
58
|
+
|
|
59
|
+
To use an R2-hosted copy or another large-file host, set `RUBY_WASM_URL` before the build command.
|
|
60
|
+
|
|
61
|
+
Run the same shape locally before deploying:
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
ruby -run -e httpd dist -p 8000
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Open:
|
|
68
|
+
|
|
69
|
+
```text
|
|
70
|
+
http://localhost:8000/
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
If you rebuild `dist/` locally, start from an empty output directory so stale files do not hide missing copy steps.
|
|
74
|
+
|
|
75
|
+
## Bundled Ruby Source
|
|
76
|
+
|
|
77
|
+
The browser Ruby VM resolves `require_relative` over HTTP, one request per source file, and those requests are sequential. The gemstone example reaches 83 files, so an unbundled deployment pays 83 round trips before the scene can run. On a connection with 200 ms of latency that is roughly 17 seconds of waiting on its own.
|
|
78
|
+
|
|
79
|
+
`scripts/bundle-ruby.mjs` inlines those files into a single entrypoint at build time:
|
|
80
|
+
|
|
81
|
+
```sh
|
|
82
|
+
node scripts/bundle-ruby.mjs examples/browser/ruby/main.rb dist/examples/browser/ruby/main.rb
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Only literal top-level `require_relative "path"` lines are inlined, matching what `JS::RequireRemote` itself resolves. `require "json"` and other standard library requires are left alone, and each file is included once, in the order Ruby would have loaded it.
|
|
86
|
+
|
|
87
|
+
Local development and the smoke tests still serve the repository root and still load the unbundled sources, so `require_relative` stays the way you edit the code.
|
|
88
|
+
|
|
89
|
+
## Optional Headers
|
|
90
|
+
|
|
91
|
+
Cloudflare Pages normally serves static assets with appropriate content types. The runtime also falls back when `.wasm` is not served as `application/wasm`, but using the wasm content type is faster because it allows streaming compilation.
|
|
92
|
+
|
|
93
|
+
Add this file at `dist/_headers` if you want to force the wasm MIME type:
|
|
94
|
+
|
|
95
|
+
```text
|
|
96
|
+
/*.wasm
|
|
97
|
+
Content-Type: application/wasm
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
If you later add a Content Security Policy, make sure it still allows same-origin JavaScript modules, WebAssembly compilation, same-origin fetches, and WebGL. The example does not need a custom CSP by default.
|
|
101
|
+
|
|
102
|
+
## Cloudflare Pages Settings
|
|
103
|
+
|
|
104
|
+
Create a Pages project from the repository and use these settings:
|
|
105
|
+
|
|
106
|
+
```text
|
|
107
|
+
Framework preset: None
|
|
108
|
+
Build command: pnpm run build:pages:ruby
|
|
109
|
+
Build output directory: dist
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Set this environment variable to match the package manager version declared in `package.json`:
|
|
113
|
+
|
|
114
|
+
```text
|
|
115
|
+
PNPM_VERSION=11.1.1
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Optional, if you host `ruby+stdlib.wasm` yourself:
|
|
119
|
+
|
|
120
|
+
```text
|
|
121
|
+
RUBY_WASM_URL=https://<your-static-host>/ruby+stdlib.wasm
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Cloudflare Pages installs dependencies from `package.json` before the build command unless dependency installation is disabled. The build command creates `dist/` on Cloudflare during each deployment, so `dist/` should not be committed to the repository. The build only runs `sh` and Node, so Pages needs no Ruby at build time either, and the deployed site is static files.
|
|
125
|
+
|
|
126
|
+
After deployment, open:
|
|
127
|
+
|
|
128
|
+
```text
|
|
129
|
+
https://<project>.pages.dev/
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
## Direct Upload With Wrangler
|
|
133
|
+
|
|
134
|
+
For a manual deployment, build the output directory locally and upload it:
|
|
135
|
+
|
|
136
|
+
```sh
|
|
137
|
+
pnpm install
|
|
138
|
+
pnpm run build:pages:ruby
|
|
139
|
+
pnpm exec wrangler pages deploy dist --project-name <project>
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Open the deployed Pages root URL after Wrangler prints it.
|
|
143
|
+
|
|
144
|
+
## Deploying A Different Example
|
|
145
|
+
|
|
146
|
+
For another browser example, copy that example directory instead of `examples/browser/ruby`:
|
|
147
|
+
|
|
148
|
+
```sh
|
|
149
|
+
cp -R examples/browser/cube dist/examples/browser/cube
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Then open:
|
|
153
|
+
|
|
154
|
+
```text
|
|
155
|
+
https://<project>.pages.dev/examples/browser/cube/
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Keep `examples/browser/shared` and the same browser packages in the output directory, and bundle that example's entrypoint the same way. The build script also replaces `/node_modules/` with `/vendor/` in the Ruby example's `index.html` and bundled `main.rb`; do the same for the copied example, or its import map and asset URLs will point at paths that are not deployed. Examples with local files under `assets/` need those assets copied with the example directory.
|
|
159
|
+
|
|
160
|
+
## Troubleshooting
|
|
161
|
+
|
|
162
|
+
`Failed to load ruby.wasm: 404`
|
|
163
|
+
|
|
164
|
+
The configured wasm URL is not reachable. For Cloudflare Pages, do not rely on `/node_modules/@ruby/3.4-wasm-wasi/dist/ruby+stdlib.wasm` as a Pages asset: that file is larger than Pages' 25 MiB single-file limit. Use the default CDN URL generated by `pnpm run build:pages:ruby`, or set `RUBY_WASM_URL` to a public R2/CDN URL.
|
|
165
|
+
|
|
166
|
+
`Failed to resolve module specifier`
|
|
167
|
+
|
|
168
|
+
The import map in the example page points at a package path that is missing from the output directory. After the build script, the import map should point at `/vendor/...`; a page that still points at `/node_modules/...` was copied without that rewrite.
|
|
169
|
+
|
|
170
|
+
`/node_modules/three/examples/jsm/... not found`
|
|
171
|
+
|
|
172
|
+
The deployed site is using an older output layout or the output directory contains pnpm symlinks instead of package files. Rebuild `dist/` from an empty directory with `pnpm run build:pages:ruby`, then confirm the expected addon exists under `/vendor/`:
|
|
173
|
+
|
|
174
|
+
```sh
|
|
175
|
+
test -f dist/vendor/three/examples/jsm/postprocessing/UnrealBloomPass.js
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Ruby `require_relative` errors
|
|
179
|
+
|
|
180
|
+
The deployed `main.rb` was copied instead of bundled, or the example was moved without updating its relative Ruby paths. Confirm the deployed entrypoint is the generated bundle:
|
|
181
|
+
|
|
182
|
+
```sh
|
|
183
|
+
head -2 dist/examples/browser/ruby/main.rb
|
|
184
|
+
grep -c require_relative dist/examples/browser/ruby/main.rb
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
The second command should print `0`.
|
|
188
|
+
|
|
189
|
+
The status stays at `Loading ruby.wasm`
|
|
190
|
+
|
|
191
|
+
The boot runtime aborts and retries the wasm download up to three times if it stops making progress for 20 seconds, and the status line shows `Retrying ruby.wasm download (n/3)` while it does. If it still fails, check the browser network tab for failed `.wasm`, `.mjs`, `.rb`, font `.json`, or three.js addon requests. A missing static asset is the most common cause.
|
|
192
|
+
|
|
193
|
+
If the download completes but is simply slow for everyone, the wasm host is the problem rather than the page. Check whether the host returns a `cf-cache-status` header; an endpoint that never does is not being cached at the edge.
|
|
194
|
+
|
|
195
|
+
The canvas is blank after the status says `Running`
|
|
196
|
+
|
|
197
|
+
Run `pnpm test:browser:ruby` locally first. If the smoke test passes locally, compare the deployed network responses and browser console errors with the local server.
|
|
198
|
+
|
|
199
|
+
## Limitations
|
|
200
|
+
|
|
201
|
+
The Ruby source files are public static assets because the browser Ruby VM fetches them over HTTP.
|
|
202
|
+
|
|
203
|
+
Cloudflare Pages Functions are not a Ruby server runtime. If the app needs server-side behavior, implement it in Pages Functions or Workers and keep the three-rb browser scene as a static client.
|
|
204
|
+
|
|
205
|
+
The current examples assume root-relative paths. If you need to serve them from a nested path behind another proxy, update the import map, wasm URL, `JS::RequireRemote.instance.base_url`, and any asset URLs in the Ruby entrypoint.
|
data/docs/implementation-plan.md
CHANGED
|
@@ -63,7 +63,7 @@ These can be future extensions. Adding them too early would expand the scope bef
|
|
|
63
63
|
|
|
64
64
|
### three.js
|
|
65
65
|
|
|
66
|
-
|
|
66
|
+
When this plan was written, the local three.js reference had package version `0.184.0`; the browser runtime now pins `0.187.0` (see `docs/browser-runtime.md`). Its public API is assembled through `src/Three.Core.js` and `src/Three.js`, which re-export many modules.
|
|
67
67
|
|
|
68
68
|
The main module boundaries are:
|
|
69
69
|
|
|
@@ -81,7 +81,7 @@ The key architectural observation is that the renderer is much more complex than
|
|
|
81
81
|
|
|
82
82
|
### ruby.wasm
|
|
83
83
|
|
|
84
|
-
ruby.wasm provides CRuby builds for WebAssembly/WASI. It includes npm packages such as `@ruby/wasm-wasi` and Ruby-version-specific packages. In the local repository, `@ruby/3.4-wasm-wasi` and `@ruby/wasm-wasi` are version `2.
|
|
84
|
+
ruby.wasm provides CRuby builds for WebAssembly/WASI. It includes npm packages such as `@ruby/wasm-wasi` and Ruby-version-specific packages. In the local repository, `@ruby/3.4-wasm-wasi` and `@ruby/wasm-wasi` are version `2.10.1`.
|
|
85
85
|
|
|
86
86
|
Ruby can access JavaScript through `require "js"`. This enables Ruby code to use the DOM, call JavaScript constructors, pass callbacks, and await JavaScript promises.
|
|
87
87
|
|
|
@@ -497,6 +497,8 @@ Current implementation status:
|
|
|
497
497
|
- `Three::Renderers::ThreeJSRenderer` exists and delegates renderer creation, sizing, animation loops, scene syncing, and render calls to the backend.
|
|
498
498
|
- The bridge can materialize `Scene`, `Group`, `Object3D`, external loaded `Object3D` handles, `PerspectiveCamera`, `OrthographicCamera`, `Mesh`, `Line`, `Points`, `Sprite`, `AmbientLight`, `DirectionalLight`, `PointLight`, `HemisphereLight`, `Texture`, `CubeTexture`, `RGBETexture`, `BoxGeometry`, `PlaneGeometry`, `SphereGeometry`, generic `BufferGeometry`, `BufferAttribute`, `MeshBasicMaterial`, `LineBasicMaterial`, `PointsMaterial`, `SpriteMaterial`, `MeshLambertMaterial`, `MeshMatcapMaterial`, `MeshToonMaterial`, `MeshStandardMaterial`, `MeshPhysicalMaterial`, `MeshNormalMaterial`, and `ShadowMaterial`.
|
|
499
499
|
- Unit tests cover materialization, handle caching, transform syncing, rendering delegation, and disposal through a fake three.js adapter.
|
|
500
|
+
- `examples/browser/ruby` renders a Ruby-authored faceted gemstone from a generic `BufferGeometry` with `MeshPhysicalMaterial`, a three-dimensional `TextGeometry` title loaded through `FontLoader`, shadows, and `OrbitControls`.
|
|
501
|
+
- `examples/browser/dango` composes a three-color dango from `SphereGeometry` and `BoxGeometry` meshes in `Group`s, lit by directional, hemisphere, and point lights with shadows, under an `OrthographicCamera` with `OrbitControls`.
|
|
500
502
|
- `examples/browser/cube` loads pnpm-managed ruby.wasm and three.js browser packages, loads this library from `lib/`, and renders a rotating cube through `Three::Renderers::ThreeJSRenderer`.
|
|
501
503
|
- `examples/browser/cube/smoke_test.mjs` provides an opt-in Playwright smoke test that serves the repository root, waits for the example to reach `Running`, and samples the WebGL canvas for nonblank pixels.
|
|
502
504
|
- `examples/browser/composition` renders an `OrthographicCamera` view with ambient/directional/point/hemisphere lights, directional shadow mapping, `PlaneGeometry`, `SphereGeometry`, grouped meshes, `TextureLoader` repeat/wrap/filter settings, `MeshLambertMaterial`, `MeshPhongMaterial`, `MeshStandardMaterial`, `MeshNormalMaterial`, `ShadowMaterial`, backend material/texture disposal, and a material color update through the same renderer path.
|
|
@@ -866,9 +868,9 @@ The MVP is complete when:
|
|
|
866
868
|
The original MVP decisions are now resolved:
|
|
867
869
|
|
|
868
870
|
- Use `minitest` for the first public release test suite.
|
|
869
|
-
- Use pnpm-managed local browser dependencies for ruby.wasm and three.js, avoiding CDN runtime drift and browser ORB failures.
|
|
871
|
+
- Use pnpm-managed local browser dependencies for ruby.wasm and three.js, avoiding CDN runtime drift and browser ORB failures. The Cloudflare Pages build is the one exception: ruby.wasm is over the Pages asset size limit, so it loads from jsDelivr, pinned to the version in `package.json`.
|
|
870
872
|
- Defer broad camelCase three.js compatibility aliases until after the first public release; snake-case Ruby methods are the documented API style.
|
|
871
873
|
- Start geometry and attribute data with standard Ruby `Array` values instead of requiring `numo-narray`.
|
|
872
874
|
- Publish the gem as `three-rb`.
|
|
873
875
|
|
|
874
|
-
|
|
876
|
+
`0.1.0` was the first public browser-first alpha release. The release gate for later releases is tracked in `docs/release-readiness.md`.
|
data/docs/next-work.md
CHANGED
|
@@ -2,11 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
This document is the resume point for the next implementation session. It is intentionally narrower than `docs/implementation-plan.md`: use it to decide what to do next after conversation context is lost.
|
|
4
4
|
|
|
5
|
-
Last updated: 2026-
|
|
5
|
+
Last updated: 2026-11-20.
|
|
6
6
|
|
|
7
7
|
## Current Position
|
|
8
8
|
|
|
9
|
-
The project is past the original MVP and is in Phase 8, renderer maturity.
|
|
9
|
+
The project is past the original MVP and is in Phase 8, renderer maturity. `0.1.0` through `0.3.0` are published on RubyGems. Record changes made after `0.3.0` under an `## Unreleased` heading at the top of `CHANGELOG.md`.
|
|
10
10
|
|
|
11
11
|
Recent completed work:
|
|
12
12
|
|
|
@@ -29,30 +29,33 @@ Recent completed work:
|
|
|
29
29
|
- Browser examples were moved to Ruby-only entrypoints that use `Three::Browser` helpers instead of application-level `require "js"` or `JS.global`.
|
|
30
30
|
- Added the `three-rb browser` executable and generator for standalone Ruby-only browser examples.
|
|
31
31
|
- Release install smoke now validates the installed executable and generated browser app shape outside the repository load path.
|
|
32
|
-
- Local release gate and
|
|
32
|
+
- Local release gate and `main` CI were green for each published release.
|
|
33
|
+
|
|
34
|
+
Released in `0.3.0`:
|
|
35
|
+
|
|
36
|
+
- Dango browser example with primitive meshes, lighting, shadows, and smoke coverage.
|
|
37
|
+
- Cloudflare Pages deployment guide and the repository's `pnpm build:pages:ruby` build, which bundles the Ruby entrypoint and loads ruby.wasm from jsDelivr.
|
|
38
|
+
- Shared `config.mjs` for the ruby.wasm URL, a loading progress bar, and stalled-download retries in the shared boot.
|
|
39
|
+
- ruby.wasm 2.10.1 and three.js 0.187.0 (r187), including the r187 iridescence and shadow-map changes.
|
|
40
|
+
- Generated apps get a runtime-only `package.json` and matching lockfile, and a smoke test generates, installs, and renders them.
|
|
41
|
+
- Browser smoke tests fail on three.js console warnings.
|
|
33
42
|
|
|
34
43
|
Do not start Phase 9 native renderer work yet. The implementation plan still recommends keeping browser rendering delegated to three.js through ruby.wasm until the browser-first API is more stable.
|
|
35
44
|
|
|
36
45
|
## Recommended Next Task
|
|
37
46
|
|
|
38
|
-
|
|
47
|
+
Pick one feature target and keep the change small enough to verify through one browser example.
|
|
39
48
|
|
|
40
49
|
This is the best next step because:
|
|
41
50
|
|
|
42
|
-
-
|
|
43
|
-
- The
|
|
44
|
-
- `lib/three/version.rb` already contains `0.1.0`.
|
|
45
|
-
- `CHANGELOG.md` currently records `## 0.1.0 - 2026-05-15`; if the release date changes before publishing, update that heading during release metadata finalization.
|
|
46
|
-
- The release candidate now includes the Ruby-only browser generator and installed-generator smoke coverage.
|
|
47
|
-
- Further feature scope should wait until after the `0.1.0` release unless an already-advertised example breaks.
|
|
51
|
+
- `0.3.0` brought the pinned runtime up to three.js r187 and ruby.wasm 2.10.1 and fixed the generated-app install, so no release work is pending.
|
|
52
|
+
- The release gate, CI on Ruby 3.3, 3.4, and 4.0, and the browser smoke tests all pass on `main`.
|
|
48
53
|
|
|
49
54
|
## Scope
|
|
50
55
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
When the owner is ready to publish, follow `docs/publishing.md`: confirm the release date, update `CHANGELOG.md`, run `bundle exec rake release:preflight`, commit the metadata update, publish the gem, tag `v0.1.0`, push `main` and the tag, then verify installation from RubyGems.
|
|
56
|
+
Between releases, keep `CHANGELOG.md`, `docs/release-readiness.md`, and this resume point aligned with what is on `main`. Do not tag, push, or publish until the release owner confirms.
|
|
54
57
|
|
|
55
|
-
|
|
58
|
+
When the owner is ready to publish, follow `docs/publishing.md`: bump `lib/three/version.rb`, replace the current changelog heading `## Unreleased` with the version and date, run `bundle exec rake release:preflight`, commit the metadata update, publish the gem, tag the release, push `main` and the tag, then verify installation from RubyGems.
|
|
56
59
|
|
|
57
60
|
Candidate targets, in recommended order when there is no stronger product signal:
|
|
58
61
|
|
|
@@ -64,16 +67,14 @@ Candidate targets, in recommended order when there is no stronger product signal
|
|
|
64
67
|
|
|
65
68
|
## Suggested Implementation Plan
|
|
66
69
|
|
|
67
|
-
1.
|
|
68
|
-
2.
|
|
69
|
-
3.
|
|
70
|
-
4.
|
|
71
|
-
5.
|
|
72
|
-
6.
|
|
73
|
-
7.
|
|
74
|
-
8.
|
|
75
|
-
9. Add or update a deterministic Playwright smoke command in `package.json`.
|
|
76
|
-
10. Run Ruby tests, the affected browser smoke test, `bundle exec rake release:gem_smoke`, and `bundle exec rake release:preflight` before release work.
|
|
70
|
+
1. Start the next feature from a user-visible workflow and choose exactly one feature target.
|
|
71
|
+
2. Add Ruby API coverage, fake adapter/backend tests, JSON export/load coverage when the object is serializable, and resource-disposal coverage when it owns GPU resources.
|
|
72
|
+
3. Add or extend one browser example and keep `examples/browser/README.md` in sync.
|
|
73
|
+
4. Add or update a deterministic Playwright smoke command in `package.json`.
|
|
74
|
+
5. Record the change under an `## Unreleased` heading in `CHANGELOG.md`.
|
|
75
|
+
6. Run Ruby tests, the affected browser smoke test, `bundle exec rake release:gem_smoke`, and `bundle exec rake release:preflight` before release work.
|
|
76
|
+
7. Before the next release, keep the current changelog heading, release-readiness docs, and publishing checklist aligned with `main` without changing the version, tag, or published artifact until the release owner confirms.
|
|
77
|
+
8. When the release is confirmed, publish and tag using `docs/publishing.md`, with a release commit message that does not include co-author trailers.
|
|
77
78
|
|
|
78
79
|
## Acceptance Criteria
|
|
79
80
|
|
|
@@ -100,7 +101,7 @@ Do not prioritize these without a clear product need:
|
|
|
100
101
|
- Native renderer.
|
|
101
102
|
- Broad public API documentation beyond the current README, release readiness, implementation plan, browser examples overview, and browser runtime guide.
|
|
102
103
|
|
|
103
|
-
Those are valid later tasks, but they expand feature scope. The immediate gap is
|
|
104
|
+
Those are valid later tasks, but they expand feature scope. The immediate gap is publishing the unreleased changes, then choosing future feature work by visible workflow and smoke-testability instead of API breadth.
|
|
104
105
|
|
|
105
106
|
## After This Task
|
|
106
107
|
|
data/docs/publishing.md
CHANGED
|
@@ -138,7 +138,7 @@ test -f examples/browser/quickstart/main.rb
|
|
|
138
138
|
ruby -e 'main = File.read("examples/browser/quickstart/main.rb"); abort "generated Ruby entrypoint used JS bridge" if main.include?("require \"js\"") || main.include?("JS.global"); puts "generated Ruby entrypoint is Ruby-only"'
|
|
139
139
|
three-rb browser examples/browser/ruby
|
|
140
140
|
test -f examples/browser/ruby/main.rb
|
|
141
|
-
test -f examples/browser/ruby/assets/
|
|
141
|
+
test -f examples/browser/ruby/assets/helvetiker_regular.typeface.json
|
|
142
142
|
```
|
|
143
143
|
|
|
144
144
|
Both Ruby commands must print:
|
data/docs/release-readiness.md
CHANGED
|
@@ -1,42 +1,42 @@
|
|
|
1
1
|
# Release Readiness
|
|
2
2
|
|
|
3
|
-
This document defines the quality gate for publishing
|
|
3
|
+
This document defines the quality gate for publishing a `three-rb` release.
|
|
4
4
|
|
|
5
5
|
## Current Position
|
|
6
6
|
|
|
7
7
|
The project is past the original MVP. It is now in Phase 8, renderer maturity: core Ruby scene authoring, browser rendering, JSON export/load, interaction, asset loading, instancing, picking, shadows, and initial postprocessing are implemented and covered by unit or browser smoke tests.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
`0.1.0` was the first public release. Every release in the `0.x` series is a browser-first alpha. The stable promise is narrow: users can build Ruby-authored scenes and render them in a browser through ruby.wasm and the delegated three.js backend. Native rendering and full three.js API compatibility are not part of the alpha releases.
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## Alpha Release Definition
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
A `0.x` release is not a `1.0` stable API commitment. A future `1.0` should get a separate stability plan covering compatibility guarantees, deprecation policy, support windows, and any non-browser renderer commitment.
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
A `0.x` release is ready when all of these are true:
|
|
16
16
|
|
|
17
17
|
- Scope is frozen to the browser-first alpha surface in this document and `README.md`; no additional material, loader, render-target, postprocessing, WebGPU, XR, native-renderer, or broad compatibility work is required for the release unless an already-advertised example is broken.
|
|
18
18
|
- Public API documentation matches the implemented, tested Ruby API surface loaded by `require "three"`.
|
|
19
19
|
- Ruby-authored browser examples use `Three::Browser` helpers instead of application-level `require "js"` and `JS.global`, and the `three-rb browser` generator can create the same Ruby-only entrypoint shape for standalone apps.
|
|
20
|
-
- Snake-case Ruby methods are the documented API style. Broad camelCase three.js compatibility aliases
|
|
20
|
+
- Snake-case Ruby methods are the documented API style. Broad camelCase three.js compatibility aliases remain deferred.
|
|
21
21
|
- `Three::Exporters::ThreeJSONExporter` and `Three::Loaders::ThreeJSONLoader` continue to round-trip Ruby-authored scenes covered by the saved `test/fixtures/scene_export_v1.json` regression fixture.
|
|
22
|
-
- JavaScript-loaded assets remain opaque `ExternalObject3D` roots
|
|
22
|
+
- JavaScript-loaded assets remain opaque `ExternalObject3D` roots in the alpha releases; transform-level use, renderer traversal helpers, animation mixer usage, and explicit subtree disposal are in scope, while Ruby child mutation inside loaded external roots is out of scope.
|
|
23
23
|
- Every browser example advertised in `README.md` and `examples/browser/README.md` has a matching deterministic Playwright smoke command, and `pnpm test:browser` runs them all.
|
|
24
24
|
- The required gate below passes locally before tagging, and the CI workflow passes on the release commit.
|
|
25
25
|
- Release metadata is final: `lib/three/version.rb` contains the exact target version, `CHANGELOG.md` has either the unreleased heading during development or the final release date before publishing, and `docs/publishing.md` has the manual publish steps.
|
|
26
26
|
|
|
27
27
|
## Public Scope
|
|
28
28
|
|
|
29
|
-
Included in the
|
|
29
|
+
Included in the alpha scope:
|
|
30
30
|
|
|
31
31
|
- Ruby object model for scenes, groups, transforms, cameras, lights, geometries, non-mesh primitives including sprites, common materials including matcap, toon, sprite, and shadow materials, textures, and common math primitives.
|
|
32
|
-
- Browser rendering through `Three::Renderers::ThreeJSRenderer`, ruby.wasm, and `three@0.
|
|
32
|
+
- Browser rendering through `Three::Renderers::ThreeJSRenderer`, ruby.wasm, and `three@0.187.0`.
|
|
33
33
|
- `Three::Browser` helpers and the `three-rb browser` executable for generating standalone Ruby-only browser examples.
|
|
34
34
|
- Dirty-tracked synchronization from Ruby objects into three.js handles.
|
|
35
35
|
- JSON export/load for Ruby-authored scenes.
|
|
36
36
|
- JavaScript-delegated browser integrations for textures, cube maps, RGBE environment maps, glTF, DRACO, animation mixers, OrbitControls, raycasting, instancing, shadows, and initial postprocessing with composer/render/bloom/dot-screen/output passes.
|
|
37
37
|
- Browser examples and smoke tests that verify visible rendering paths.
|
|
38
38
|
|
|
39
|
-
Explicitly out of scope for the
|
|
39
|
+
Explicitly out of scope for the alpha releases:
|
|
40
40
|
|
|
41
41
|
- A native Ruby renderer.
|
|
42
42
|
- Full three.js API coverage.
|
|
@@ -82,4 +82,4 @@ Before expanding feature scope, prefer:
|
|
|
82
82
|
3. Keep `CHANGELOG.md` accurate while the next release remains under an unreleased heading.
|
|
83
83
|
4. Improve public docs around browser examples, browser boot, and unsupported APIs; see `docs/next-work.md`.
|
|
84
84
|
5. Add new material classes, postprocessing passes, render targets, or loaders only when a dedicated example and smoke test need them.
|
|
85
|
-
6. Treat KTX2, WebGPU, WebXR, and native rendering as
|
|
85
|
+
6. Treat KTX2, WebGPU, WebXR, and native rendering as later planning items.
|