stagecraft 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6d1a90ae88df85e52c63bab31d3f5b3979806af0b88357fd19ef068db91ab8c1
+  data.tar.gz: 96c88c48a551fd3ad8247d2015af3aa134ba5f445bac148f60b0d8332c37f770
+SHA512:
+  metadata.gz: 8d695c4ed18c43a8b12e83d01c18f028e4b0e28daecabe0419ad531631f99d4a6a9ebe14e8946543214e53c64b1cf4fa66b739d27fe1d8913d3a0400b718e276
+  data.tar.gz: ac497bca14f3a5628111135289aa5824263864a79ebc60a9eaef8de55a70283f6a664a66f45a3cb3a381b63681a816241dcb5dafa443e4127c335d825344496f

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,207 @@
+# Stagecraft
+
+Stagecraft is a three.js-like scene graph and WebGPU renderer for Ruby. It
+combines `wgpu`, `larb`, `rgltf`, and `texel` behind a compact
+Scene / Mesh / Material / Camera / Renderer API.
+
+The renderer uses WebGPU zero-to-one depth, PBR metallic-roughness materials,
+HDR rendering with ACES tone mapping, frustum culling, transparent and opaque
+queues, MSAA, directional shadow maps, skinning, and glTF animation.
+
+## Requirements
+
+- Ruby 3.2 or newer
+- A WebGPU backend supported by the `wgpu` gem
+- SDL3 for the default window adapter
+
+## Installation
+
+Add Stagecraft to your bundle:
+
+```sh
+bundle add stagecraft
+```
+
+Or install it directly:
+
+```sh
+gem install stagecraft
+```
+
+## First scene
+
+```ruby
+require "stagecraft"
+
+app = Stagecraft::App.new(title: "Hello Stagecraft", width: 1280, height: 720)
+
+scene = Stagecraft::Scene.new
+scene.background = Stagecraft::Color.new(0.05, 0.06, 0.08)
+scene.add(Stagecraft::Lights::Ambient.new(intensity: 0.25))
+
+sun = Stagecraft::Lights::Directional.new(intensity: 3.0, cast_shadow: true)
+sun.position.set(4, 8, 4)
+sun.look_at(Larb::Vec3.new)
+scene.add(sun)
+
+cube = Stagecraft::Mesh.new(
+  Stagecraft::Geometries.box(1, 1, 1),
+  Stagecraft::Materials::PBR.new(
+    base_color: "#e91e63",
+    roughness: 0.4,
+    metallic: 0.1
+  )
+)
+cube.cast_shadow = true
+scene.add(cube)
+
+camera = Stagecraft::Cameras::Perspective.new(
+  fov: 60,
+  aspect: app.aspect,
+  near: 0.1,
+  far: 100
+)
+camera.position.set(0, 2, 5)
+controls = Stagecraft::Controls::Orbit.new(camera, app.window)
+
+app.run do |dt|
+  controls.update(dt)
+  cube.rotation.rotate_y!(dt)
+  app.renderer.render(scene, camera)
+end
+```
+
+`App#run` clamps delta time to 100 ms, polls the window at vsync cadence, and
+disposes its renderer and window when the loop ends.
+
+## glTF and animation
+
+`Loaders::GLTF` accepts a `.gltf` / `.glb` path or an existing
+`Rgltf::Document`. It converts scenes, cameras, punctual lights, materials,
+textures, skins, and animation channels:
+
+```ruby
+model = Stagecraft::Loaders::GLTF.load("assets/robot.glb")
+scene.add(model.scene)
+
+mixer = Stagecraft::Animation::Mixer.new(model.scene)
+mixer.play(model.animations.first, loop: :repeat, fade_in: 0.25)
+
+app.run do |dt|
+  mixer.update(dt)
+  app.renderer.render(scene, camera)
+end
+```
+
+glTF `LINEAR`, `STEP`, and `CUBICSPLINE` tracks are supported. Multiple actions
+blend by weight; rotations use normalized quaternion blending.
+
+## Materials and textures
+
+Stagecraft includes PBR, Unlit, and custom WGSL materials. Base color and
+emissive textures are uploaded as sRGB; metallic-roughness, normal, and
+occlusion textures stay linear. KHR texture transforms are carried into the
+material uniforms.
+
+```ruby
+texture = Stagecraft::Texture.load(
+  "assets/albedo.png",
+  channels: 4,
+  color_space: :srgb
+)
+material = Stagecraft::Materials::PBR.new(
+  base_color_map: texture,
+  metallic: 0.0,
+  roughness: 0.7
+)
+```
+
+`Materials::Shader` accepts a WGSL string or any object responding to
+`#to_wgsl`. Stagecraft injects frame and object bindings and packs the uniform
+hash according to WGSL alignment:
+
+```ruby
+material = Stagecraft::Materials::Shader.new(
+  wgsl: File.read("effect.wgsl"),
+  uniforms: {
+    tint: Stagecraft::Color.new("#7c4dff"),
+    speed: 2.0
+  }
+)
+```
+
+Custom shaders own bind group 1. Frame data is group 0 and object / skin data
+is group 2. See [the tutorial](docs/tutorial.md#custom-wgsl) for the complete
+contract.
+
+## Headless rendering
+
+An offscreen renderer returns a readable frame backed by a `Texel::Image`:
+
+```ruby
+renderer = Stagecraft::Renderer.offscreen(width: 512, height: 512, msaa: 4)
+frame = renderer.render(scene, camera)
+Texel.save(frame.read_pixels, "frame.png")
+renderer.dispose
+```
+
+## Integration hooks
+
+The renderer exposes `device`, `queue`, and `surface_format`. UI renderers such
+as imgui-ruby can append commands after the main pass:
+
+```ruby
+renderer.on_after_render do |encoder, hdr_target_view|
+  overlay.render(encoder, hdr_target_view, stats: renderer.stats)
+end
+```
+
+`PhysicsBinding` connects any body exposing `position` and quaternion
+`rotation`. `Materials::Shader` accepts rlsl-like objects through `#to_wgsl`.
+
+## Resource lifetime and diagnostics
+
+GPU resources are versioned and cached. Call `dispose` on mutable geometry and
+textures when they are no longer needed, and always dispose standalone
+renderers. `App` handles renderer shutdown automatically.
+
+Set `STAGECRAFT_DEBUG=1` to report live render statistics once per second and
+warn about cached resources remaining at renderer shutdown:
+
+```sh
+STAGECRAFT_DEBUG=1 bundle exec ruby examples/01_spinning_cube.rb
+```
+
+## Window adapters
+
+SDL3 is the portable default. `window: :glfw` is available when the application
+supplies the platform-specific WebGPU `surface_factory`, because glfw-ruby does
+not expose a portable WebGPU surface handle.
+
+An existing object implementing the window adapter protocol can be passed as
+`window:`. It must provide `poll_events`, `should_close?`, `drawable_size`,
+`create_surface(instance)`, and `close`.
+
+## Learn and explore
+
+- [Learn Stagecraft tutorial](docs/tutorial.md)
+- [v1 public API map](docs/api.md)
+- [20 runnable gallery examples](examples/README.md)
+
+Use `STAGECRAFT_SMOKE=1` to close a window example after one frame.
+
+## Development
+
+```sh
+bin/setup
+bundle exec rake spec
+bundle exec rake build
+```
+
+GPU-free unit tests cover scene traversal, bounds, culling, sorting, shader
+composition, uniform layout, glTF conversion, and animation. Offscreen WebGPU
+rendering can be used for platform integration tests.
+
+## License
+
+Stagecraft is released under the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/docs/api.md

@@ -0,0 +1,85 @@
+# Stagecraft v1 public API
+
+The following namespaces and entry points form the v1 API.
+
+## Application and rendering
+
+- `Stagecraft::App`
+- `Stagecraft::Renderer`
+- `Stagecraft::Renderer.offscreen`
+- `Stagecraft::Renderer::Frame#read_pixels`
+- `Stagecraft::Renderer::Stats`
+- `Stagecraft::Window::Adapter`
+- `Stagecraft::Window::Sdl3`
+- `Stagecraft::Window::Glfw`
+
+## Scene graph
+
+- `Stagecraft::Node`
+- `Stagecraft::MatrixNode`
+- `Stagecraft::Scene`
+- `Stagecraft::Mesh`
+- `Stagecraft::Geometry`
+- `Stagecraft::Attribute`
+- `Stagecraft::Raycaster`
+- `Stagecraft::Skin`
+
+## Cameras and controls
+
+- `Stagecraft::Cameras::Camera`
+- `Stagecraft::Cameras::Perspective`
+- `Stagecraft::Cameras::Orthographic`
+- `Stagecraft::Controls::Orbit`
+
+The longer `PerspectiveCamera`, `OrthographicCamera`, and `OrbitControls`
+constants are compatibility aliases.
+
+## Lights
+
+- `Stagecraft::Lights::Ambient`
+- `Stagecraft::Lights::Directional`
+- `Stagecraft::Lights::Point`
+- `Stagecraft::Lights::Spot`
+- `Stagecraft::Lights::ShadowConfig`
+
+## Materials and textures
+
+- `Stagecraft::Materials::Base`
+- `Stagecraft::Materials::Unlit`
+- `Stagecraft::Materials::PBR`
+- `Stagecraft::Materials::Shader`
+- `Stagecraft::Textures::Texture`
+- `Stagecraft::Textures::CubeTexture`
+- `Stagecraft::Textures::SamplerState`
+- `Stagecraft::Texture`
+
+## Assets and animation
+
+- `Stagecraft::Loaders::GLTF.load`
+- `Stagecraft::Loaders::GLTF::Result`
+- `Stagecraft::Animation::Track`
+- `Stagecraft::Animation::Clip`
+- `Stagecraft::Animation::Action`
+- `Stagecraft::Animation::Mixer`
+
+## Math-facing helpers
+
+- `Stagecraft::Color`
+- `Stagecraft::ObservedVec3`
+- `Stagecraft::ObservedQuat`
+- `Stagecraft::Bounding::Box3`
+- `Stagecraft::Bounding::Sphere`
+- `Stagecraft::Bounding::Plane`
+- `Stagecraft::Bounding::Frustum`
+
+## Primitive geometry and integration
+
+- `Stagecraft::Geometries.box`
+- `Stagecraft::Geometries.plane`
+- `Stagecraft::Geometries.sphere`
+- `Stagecraft::Geometries.cylinder`
+- `Stagecraft::Geometries.torus`
+- `Stagecraft::PhysicsBinding`
+
+Nested renderer implementation types are public for inspection but are not part
+of the compatibility contract.

data/docs/tutorial.md

@@ -0,0 +1,344 @@
+# Learn Stagecraft
+
+This tutorial builds the mental model behind Stagecraft from the scene graph up
+to the WebGPU frame. Every section corresponds to a runnable file in
+[`examples/`](../examples/README.md).
+
+## 1. The frame
+
+A Stagecraft application has four moving parts:
+
+1. A `Scene` owns a hierarchy of nodes.
+2. A `Camera` turns world positions into WebGPU clip coordinates.
+3. A `Renderer` collects visible meshes and encodes render passes.
+4. `App` owns the window and supplies a clamped delta time.
+
+```ruby
+app.run do |dt|
+  update_simulation(dt)
+  app.renderer.render(scene, camera)
+end
+```
+
+The render call performs world-matrix resolution, frustum culling, queue
+sorting, uniform upload, shadow rendering, HDR rendering, and ACES tone mapping.
+The surface is presented only after all callbacks have encoded their work.
+
+## 2. Coordinates and transforms
+
+Stagecraft uses `larb` values throughout. A node exposes observable position,
+rotation, and scale values:
+
+```ruby
+node.position.set(1, 2, 3)
+node.rotation.rotate_y!(Math::PI / 4)
+node.scale.set(2, 2, 2)
+```
+
+The local transform is composed as translation × rotation × scale. A child's
+world transform is its parent world transform multiplied by its local
+transform. Version stamps make this lazy: unchanged branches do not recompute
+their matrices.
+
+Use `add`, `remove`, `traverse`, and `find` to work with a hierarchy:
+
+```ruby
+solar_system.add(sun, orbit)
+orbit.add(planet)
+planet = solar_system.find("planet")
+```
+
+Adding an existing child detaches it from its previous parent. Cycles are
+rejected.
+
+## 3. Cameras
+
+Perspective cameras use degrees for vertical field of view:
+
+```ruby
+camera = Stagecraft::Cameras::Perspective.new(
+  fov: 60, aspect: 16.0 / 9.0, near: 0.1, far: 1_000
+)
+camera.position.set(0, 2, 5)
+camera.look_at(Larb::Vec3.new)
+```
+
+Orthographic cameras use explicit view extents:
+
+```ruby
+camera = Stagecraft::Cameras::Orthographic.new(
+  left: -4, right: 4, top: 2.25, bottom: -2.25,
+  near: 0.1, far: 100
+)
+```
+
+Both projections map depth to WebGPU NDC z ∈ [0, 1]. Update a perspective
+camera's `aspect` after a drawable-size change. The gallery helper demonstrates
+the resize callback.
+
+`Controls::Orbit` can rotate, pan, and zoom a camera with exponential damping:
+
+```ruby
+controls = Stagecraft::Controls::Orbit.new(camera, app.window)
+app.run do |dt|
+  controls.update(dt)
+  app.renderer.render(scene, camera)
+end
+```
+
+## 4. Geometry
+
+A geometry is a set of packed vertex attributes plus an optional index buffer:
+
+```ruby
+geometry = Stagecraft::Geometry.new
+geometry.set_attribute(
+  :position,
+  data: [0, 1, 0, -1, -1, 0, 1, -1, 0].pack("e*"),
+  format: :float32x3,
+  count: 3
+)
+geometry.compute_normals!
+```
+
+Supported attribute names are `position`, `normal`, `uv`, `uv1`, `tangent`,
+`color`, `joints`, and `weights`. Supported primitive topologies are points,
+lines, line strips, triangle lists, and triangle strips.
+
+Changing an attribute's packed `data` increments the owning geometry version,
+so its GPU buffers are replaced on the next render. Bounds are calculated
+lazily from float32x3 positions.
+
+The `Geometries` module includes box, plane, sphere, cylinder, and torus
+builders. Their indexed triangles are counter-clockwise on the front face.
+
+## 5. Materials
+
+### Unlit
+
+Unlit materials return their color without lighting:
+
+```ruby
+material = Stagecraft::Materials::Unlit.new(
+  color: "#448aff",
+  opacity: 0.8,
+  transparent: true
+)
+```
+
+### Metallic-roughness PBR
+
+PBR combines Lambert diffuse with GGX / Smith / Fresnel-Schlick specular:
+
+```ruby
+material = Stagecraft::Materials::PBR.new(
+  base_color: "#eceff1",
+  metallic: 0.75,
+  roughness: 0.2,
+  emissive: "#ff6d00",
+  emissive_strength: 0.1
+)
+```
+
+Metallic and roughness are clamped API values in the 0..1 range. PBR supports
+base color, metallic-roughness, normal, occlusion, and emissive maps.
+
+Opaque meshes are sorted front-to-back by pipeline and material. Transparent
+meshes are sorted back-to-front after `render_order`. Use `depth_write: false`
+for layered alpha-blended surfaces.
+
+## 6. Lights and shadows
+
+Ambient light contributes a constant scene term. Directional, point, and spot
+lights are packed into a storage buffer every frame:
+
+```ruby
+scene.add(Stagecraft::Lights::Ambient.new(intensity: 0.2))
+
+sun = Stagecraft::Lights::Directional.new(
+  color: "#fff5e1",
+  intensity: 4.0,
+  cast_shadow: true
+)
+sun.position.set(4, 8, 5)
+sun.look_at(Larb::Vec3.new)
+scene.add(sun)
+```
+
+The first shadow-casting directional light renders a depth32float map. The main
+PBR pass samples it with 3×3 percentage-closer filtering. Set
+`mesh.cast_shadow` on occluders and `mesh.receive_shadow` on receivers.
+
+Point and spot lights use the glTF punctual-light attenuation curve. Their
+`range` avoids spending light outside a useful radius.
+
+## 7. Textures
+
+`Texture.load` delegates decoding to texel:
+
+```ruby
+albedo = Stagecraft::Texture.load(
+  "albedo.png",
+  channels: 4,
+  color_space: :srgb
+)
+material.base_color_map = albedo
+```
+
+Request four channels because WebGPU has no three-channel sampled format.
+Texel builds mip levels and Stagecraft copies them with WebGPU row alignment.
+Color maps and emissive maps should be sRGB; data maps should be linear.
+
+Sampler state is immutable:
+
+```ruby
+sampler = Stagecraft::Textures::SamplerState.new(
+  wrap_u: :repeat,
+  wrap_v: :repeat,
+  mag_filter: :linear,
+  min_filter: :linear,
+  mipmap_filter: :linear
+)
+```
+
+## 8. glTF assets
+
+```ruby
+result = Stagecraft::Loaders::GLTF.load("robot.glb")
+scene.add(result.scene)
+```
+
+The result contains the default `scene`, every converted `scene`, all
+`animations`, and converted `cameras`. Mesh primitives become child Mesh
+objects so each primitive can keep its own material and topology.
+
+The loader passes compatible packed accessors directly into Geometry. WebGPU
+does not support u8 indices, so those are expanded to u32. glTF line loops and
+triangle fans are expanded to supported indexed topologies.
+
+KHR_materials_unlit, KHR_materials_emissive_strength,
+KHR_texture_transform, and KHR_lights_punctual are converted. Images are
+decoded by texel.
+
+## 9. Skinning and animation
+
+A skin stores joint nodes and inverse-bind matrices. Each frame the renderer
+calculates mesh-local joint matrices and uploads them to bind group 2:
+
+```text
+inverse_bind × joint.world_matrix × mesh.world_matrix.inverse
+```
+
+The vertex shader blends four matrices using the `joints` and `weights`
+attributes.
+
+Animation clips group tracks. A mixer resolves track targets once and advances
+every playing action:
+
+```ruby
+mixer = Stagecraft::Animation::Mixer.new(result.scene)
+walk = mixer.play(result.animations.fetch(0), loop: :repeat)
+walk.weight = 0.8
+
+app.run do |dt|
+  mixer.update(dt)
+  renderer.render(scene, camera)
+end
+```
+
+Use `loop: :once`, `:repeat`, or `:ping_pong`. `fade_in:` raises an action's
+weight from zero to one. Translation and scale use component interpolation;
+rotations use slerp; glTF cubic spline tracks use Hermite tangents.
+
+## 10. Custom WGSL
+
+Custom shaders define `vs_main` and `fs_main`, and include the engine common
+bindings:
+
+```wgsl
+//#include "common.wgsl"
+
+struct VertexInput {
+  @location(0) position: vec3f,
+};
+
+@vertex fn vs_main(input: VertexInput) -> @builtin(position) vec4f {
+  return frame.view_proj * object.model * vec4f(input.position, 1.0);
+}
+
+@fragment fn fs_main() -> @location(0) vec4f {
+  return material.tint;
+}
+```
+
+The associated Ruby material supplies the group 1 layout:
+
+```ruby
+Stagecraft::Materials::Shader.new(
+  wgsl: source,
+  uniforms: { tint: Stagecraft::Color.new("#ff4081") }
+)
+```
+
+Numeric, color, larb vector / quaternion / matrix, numeric array, and Texture
+values are supported. The packer inserts WGSL padding and generates
+`MaterialUniforms`. Texture values become paired sampler and texture bindings.
+
+The stable binding contract is:
+
+| Group | Content |
+|---|---|
+| 0 | frame uniform, light storage, shadow map and sampler |
+| 1 | material uniform, material textures and samplers |
+| 2 | dynamic object uniform and joint storage |
+
+## 11. Picking and physics
+
+Create a ray from normalized device coordinates and intersect scene bounds:
+
+```ruby
+ray = Stagecraft::Raycaster.new
+ray.set_from_camera(pointer_x, pointer_y, camera)
+hits = ray.intersect(scene)
+```
+
+Hits are nearest-first and expose object, distance, and world point.
+
+`PhysicsBinding` is deliberately duck typed:
+
+```ruby
+binding = Stagecraft::PhysicsBinding.new
+binding.bind(mesh, rigid_body)
+binding.sync!(interpolation_alpha)
+```
+
+The body only needs `position` and quaternion `rotation`.
+
+## 12. Offscreen and UI integration
+
+Use `Renderer.offscreen` when no surface is needed. `Frame#read_pixels` returns
+an sRGB, four-channel texel image.
+
+For overlays, use `on_after_render`. The callback receives the shared command
+encoder and HDR target view before tone mapping. The renderer exposes the same
+`device`, `queue`, and `surface_format` required by a WebGPU UI backend.
+
+## 13. Lifetime and performance
+
+Geometry, texture, material, and world transforms use version keys. Pipeline
+objects use a 256-entry LRU keyed by material type, shader features, vertex
+layout, blending, depth, culling, sample count, target format, and pass.
+
+Object uniforms occupy 256-byte dynamic slots in a three-frame ring buffer.
+Lights and joints use storage buffers. CPU resources must be disposed
+explicitly when their GPU allocations are no longer needed:
+
+```ruby
+geometry.dispose
+texture.dispose
+renderer.dispose
+```
+
+Set `STAGECRAFT_DEBUG=1` while developing. `renderer.stats.to_h` always exposes
+draw calls, triangles, live buffers, live textures, live pipelines, visible
+objects, and culled objects.

data/examples/01_spinning_cube.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "support/demo"
+
+demo = StagecraftExamples::Demo.new(title: "01 — Spinning cube")
+demo.light!
+cube = Stagecraft::Mesh.new(
+  Stagecraft::Geometries.box,
+  Stagecraft::Materials::PBR.new(base_color: "#e91e63", roughness: 0.35, metallic: 0.15)
+)
+demo.scene.add(cube)
+demo.update { |dt| cube.rotation.rotate_y!(dt) }
+demo.run

data/examples/02_primitives.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "support/demo"
+
+demo = StagecraftExamples::Demo.new(title: "02 — Primitives")
+demo.light!
+geometries = [
+  Stagecraft::Geometries.box,
+  Stagecraft::Geometries.sphere,
+  Stagecraft::Geometries.cylinder(0.7, 0.7, 1.5),
+  Stagecraft::Geometries.torus
+]
+geometries.each_with_index do |geometry, index|
+  mesh = Stagecraft::Mesh.new(
+    geometry,
+    Stagecraft::Materials::PBR.new(base_color: ["#ff5252", "#40c4ff", "#69f0ae", "#ffd740"][index])
+  )
+  mesh.position.x = (index - 1.5) * 2.0
+  demo.scene.add(mesh)
+end
+demo.run