stagecraft 1.0.0

data/examples/03_pbr_materials.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "support/demo"
+
+demo = StagecraftExamples::Demo.new(title: "03 — PBR material grid")
+demo.light!
+5.times do |row|
+  5.times do |column|
+    material = Stagecraft::Materials::PBR.new(
+      base_color: "#d6d9df",
+      metallic: column / 4.0,
+      roughness: [row / 4.0, 0.04].max
+    )
+    sphere = Stagecraft::Mesh.new(Stagecraft::Geometries.sphere(0.38), material)
+    sphere.position.set((column - 2) * 0.9, (row - 2) * 0.9, 0)
+    demo.scene.add(sphere)
+  end
+end
+demo.camera.position.set(0, 0, 7)
+demo.run

data/examples/04_lights.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "support/demo"
+
+demo = StagecraftExamples::Demo.new(title: "04 — Light types")
+demo.scene.add(Stagecraft::Lights::Ambient.new(intensity: 0.08))
+point = Stagecraft::Lights::Point.new(color: "#ff5252", intensity: 25, range: 8)
+point.position.set(-2, 2, 2)
+spot = Stagecraft::Lights::Spot.new(
+  color: "#40c4ff", intensity: 35, range: 10,
+  inner_angle: 0.2, outer_angle: 0.55
+)
+spot.position.set(2, 3, 3)
+spot.look_at(Larb::Vec3.new)
+demo.scene.add(point, spot)
+demo.scene.add(
+  Stagecraft::Mesh.new(
+    Stagecraft::Geometries.sphere(1.2),
+    Stagecraft::Materials::PBR.new(base_color: "#eeeeee", roughness: 0.45)
+  )
+)
+demo.run

data/examples/05_directional_shadow.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "support/demo"
+
+demo = StagecraftExamples::Demo.new(title: "05 — Directional shadow")
+demo.scene.add(Stagecraft::Lights::Ambient.new(intensity: 0.12))
+sun = Stagecraft::Lights::Directional.new(intensity: 4.0, cast_shadow: true)
+sun.position.set(4, 8, 5)
+sun.look_at(Larb::Vec3.new)
+cube = Stagecraft::Mesh.new(
+  Stagecraft::Geometries.box,
+  Stagecraft::Materials::PBR.new(base_color: "#ffab40", roughness: 0.5)
+)
+cube.position.y = 0.7
+cube.cast_shadow = true
+floor = Stagecraft::Mesh.new(
+  Stagecraft::Geometries.plane(12, 12),
+  Stagecraft::Materials::PBR.new(base_color: "#78909c", roughness: 0.9)
+)
+floor.rotation.rotate_x!(-Math::PI / 2)
+floor.receive_shadow = true
+demo.scene.add(sun, cube, floor)
+demo.run

data/examples/06_transparency.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "support/demo"
+
+demo = StagecraftExamples::Demo.new(title: "06 — Transparent sorting")
+colors = %w[#ff174480 #00e5ff80 #76ff0380]
+colors.each_with_index do |color, index|
+  material = Stagecraft::Materials::Unlit.new(
+    color:,
+    transparent: true,
+    alpha_mode: :blend,
+    depth_write: false
+  )
+  plane = Stagecraft::Mesh.new(Stagecraft::Geometries.plane(2.4, 2.4), material)
+  plane.position.set((index - 1) * 0.6, 0, -index * 0.5)
+  demo.scene.add(plane)
+end
+demo.camera.position.set(0, 0, 5)
+demo.run

data/examples/07_texture.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "support/demo"
+require "texel"
+
+pixels = [
+  255, 255, 255, 255, 20, 20, 20, 255,
+  20, 20, 20, 255, 255, 255, 255, 255
+].pack("C*")
+image = Texel::Image.new(
+  width: 2, height: 2, channels: 4, dtype: :u8, color_space: :srgb, data: pixels
+)
+texture = Stagecraft::Texture.new(image, color_space: :srgb)
+demo = StagecraftExamples::Demo.new(title: "07 — Texture")
+demo.light!
+demo.scene.add(
+  Stagecraft::Mesh.new(
+    Stagecraft::Geometries.box(2, 2, 2),
+    Stagecraft::Materials::PBR.new(base_color_map: texture, roughness: 0.7)
+  )
+)
+demo.run

data/examples/08_shader_material.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "support/demo"
+
+wgsl = <<~WGSL
+  //#include "common.wgsl"
+  struct VertexInput { @location(0) position: vec3f };
+  struct VertexOutput {
+    @builtin(position) position: vec4f,
+    @location(0) local: vec3f,
+  };
+  @vertex fn vs_main(input: VertexInput) -> VertexOutput {
+    var output: VertexOutput;
+    output.position = frame.view_proj * object.model * vec4f(input.position, 1.0);
+    output.local = input.position;
+    return output;
+  }
+  @fragment fn fs_main(input: VertexOutput) -> @location(0) vec4f {
+    let pulse = 0.55 + 0.45 * sin(frame.time * material.speed);
+    return vec4f(material.tint.rgb * pulse, material.tint.a);
+  }
+WGSL
+
+demo = StagecraftExamples::Demo.new(title: "08 — Shader material")
+material = Stagecraft::Materials::Shader.new(
+  wgsl:,
+  uniforms: { tint: Stagecraft::Color.new("#7c4dff"), speed: 3.0 }
+)
+demo.scene.add(Stagecraft::Mesh.new(Stagecraft::Geometries.torus, material))
+demo.run

data/examples/09_gltf_loader.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "support/demo"
+require "rgltf"
+
+positions = [-1, -1, 0, 1, -1, 0, 0, 1, 0].pack("e*")
+json = {
+  "asset" => { "version" => "2.0" },
+  "buffers" => [{ "byteLength" => positions.bytesize }],
+  "bufferViews" => [{ "buffer" => 0, "byteLength" => positions.bytesize }],
+  "accessors" => [
+    { "bufferView" => 0, "componentType" => 5_126, "count" => 3, "type" => "VEC3" }
+  ],
+  "meshes" => [{ "primitives" => [{ "attributes" => { "POSITION" => 0 } }] }],
+  "nodes" => [{ "name" => "triangle", "mesh" => 0 }],
+  "scenes" => [{ "nodes" => [0] }],
+  "scene" => 0
+}
+document = Rgltf.load_json(json, buffers: positions)
+model = Stagecraft::Loaders::GLTF.load(document)
+demo = StagecraftExamples::Demo.new(title: "09 — glTF loader")
+demo.scene.add(model.scene)
+demo.camera.position.set(0, 0, 4)
+demo.run

data/examples/10_animation.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "support/demo"
+
+demo = StagecraftExamples::Demo.new(title: "10 — Animation mixer")
+demo.light!
+cube = Stagecraft::Mesh.new(
+  Stagecraft::Geometries.box,
+  Stagecraft::Materials::PBR.new(base_color: "#00b0ff")
+)
+demo.scene.add(cube)
+track = Stagecraft::Animation::Track.new(
+  times: [0.0, 1.0, 2.0],
+  values: [-2, 0, 0, 2, 0, 0, -2, 0, 0],
+  target: cube,
+  target_path: :translation
+)
+mixer = Stagecraft::Animation::Mixer.new(demo.scene)
+mixer.play(Stagecraft::Animation::Clip.new(name: "slide", tracks: [track]))
+demo.update { |dt| mixer.update(dt) }
+demo.run

data/examples/11_scene_graph.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "support/demo"
+
+demo = StagecraftExamples::Demo.new(title: "11 — Scene graph")
+demo.light!
+pivot = Stagecraft::Node.new(name: "pivot")
+sun = Stagecraft::Mesh.new(
+  Stagecraft::Geometries.sphere(0.7),
+  Stagecraft::Materials::PBR.new(base_color: "#ffd740", emissive: "#ffab00", emissive_strength: 0.5)
+)
+moon = Stagecraft::Mesh.new(
+  Stagecraft::Geometries.sphere(0.25),
+  Stagecraft::Materials::PBR.new(base_color: "#b0bec5")
+)
+moon.position.x = 2.0
+pivot.add(sun, moon)
+demo.scene.add(pivot)
+demo.update { |dt| pivot.rotation.rotate_y!(dt) }
+demo.run

data/examples/12_orbit_controls.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "support/demo"
+
+demo = StagecraftExamples::Demo.new(title: "12 — Orbit controls")
+demo.light!
+demo.scene.add(
+  Stagecraft::Mesh.new(
+    Stagecraft::Geometries.torus(1.2, 0.35),
+    Stagecraft::Materials::PBR.new(base_color: "#18ffff", metallic: 0.65, roughness: 0.22)
+  )
+)
+demo.run

data/examples/13_orthographic_camera.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "support/demo"
+
+demo = StagecraftExamples::Demo.new(title: "13 — Orthographic camera", controls: false)
+demo.camera = Stagecraft::Cameras::Orthographic.new(
+  left: -4, right: 4, top: 2.25, bottom: -2.25, near: 0.1, far: 20
+)
+demo.camera.position.z = 6
+7.times do |index|
+  square = Stagecraft::Mesh.new(
+    Stagecraft::Geometries.plane(0.8, 0.8),
+    Stagecraft::Materials::Unlit.new(color: Stagecraft::Color.new(index / 7.0, 0.5, 1.0))
+  )
+  square.position.x = index - 3
+  demo.scene.add(square)
+end
+demo.run

data/examples/14_raycaster.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "support/demo"
+
+demo = StagecraftExamples::Demo.new(title: "14 — Raycaster")
+mesh = Stagecraft::Mesh.new(
+  Stagecraft::Geometries.sphere,
+  Stagecraft::Materials::Unlit.new(color: "#69f0ae")
+)
+demo.scene.add(mesh)
+raycaster = Stagecraft::Raycaster.new
+raycaster.set_from_camera(0.0, 0.0, demo.camera)
+warn "center ray hits: #{raycaster.intersect(demo.scene).map { |hit| hit.object.name || "mesh" }.join(", ")}"
+demo.run

data/examples/15_offscreen.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "support/demo"
+require "texel"
+
+scene = Stagecraft::Scene.new
+scene.background = "#263238"
+scene.add(
+  Stagecraft::Mesh.new(
+    Stagecraft::Geometries.box,
+    Stagecraft::Materials::Unlit.new(color: "#ff4081")
+  )
+)
+camera = Stagecraft::Cameras::Perspective.new(aspect: 1.0)
+camera.position.z = 3
+renderer = Stagecraft::Renderer.offscreen(width: 512, height: 512, msaa: 4)
+image = renderer.render(scene, camera).read_pixels
+destination = ARGV.first || File.expand_path("../tmp/stagecraft-offscreen.png", __dir__)
+Dir.mkdir(File.dirname(destination)) unless Dir.exist?(File.dirname(destination))
+Texel.save(image, destination)
+renderer.dispose
+puts destination

data/examples/16_msaa.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "support/demo"
+
+demo = StagecraftExamples::Demo.new(title: "16 — 4x MSAA", msaa: 4)
+demo.light!
+demo.scene.add(
+  Stagecraft::Mesh.new(
+    Stagecraft::Geometries.torus(1.2, 0.18, radial_segments: 8, tubular_segments: 96),
+    Stagecraft::Materials::PBR.new(base_color: "#ffffff", roughness: 0.25)
+  )
+)
+demo.run

data/examples/17_physics_binding.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "support/demo"
+
+Body = Struct.new(:position, :rotation)
+demo = StagecraftExamples::Demo.new(title: "17 — Physics binding")
+demo.light!
+mesh = Stagecraft::Mesh.new(
+  Stagecraft::Geometries.box,
+  Stagecraft::Materials::PBR.new(base_color: "#ff6d00")
+)
+body = Body.new(Larb::Vec3.new, Larb::Quat.new)
+binding = Stagecraft::PhysicsBinding.new.bind(mesh, body)
+elapsed = 0.0
+demo.scene.add(mesh)
+demo.update do |dt|
+  elapsed += dt
+  body.position = Larb::Vec3.new(Math.sin(elapsed) * 2.0, 0, 0)
+  body.rotation = Larb::Quat.from_axis_angle(Larb::Vec3.up, elapsed)
+  binding.sync!(1.0)
+end
+demo.run

data/examples/18_custom_geometry.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "support/demo"
+
+geometry = Stagecraft::Geometry.new
+geometry.set_attribute(
+  :position,
+  data: [0, 1.5, 0, -1.5, -1, 0, 1.5, -1, 0].pack("e*"),
+  format: :float32x3,
+  count: 3
+)
+geometry.compute_normals!
+demo = StagecraftExamples::Demo.new(title: "18 — Custom geometry")
+demo.light!
+demo.scene.add(
+  Stagecraft::Mesh.new(
+    geometry,
+    Stagecraft::Materials::PBR.new(base_color: "#d500f9", roughness: 0.55)
+  )
+)
+demo.camera.position.set(0, 0, 5)
+demo.run

data/examples/19_imgui_stats.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "support/demo"
+
+demo = StagecraftExamples::Demo.new(title: "19 — Stats / ImGui hook")
+demo.light!
+demo.scene.add(
+  Stagecraft::Mesh.new(
+    Stagecraft::Geometries.sphere,
+    Stagecraft::Materials::PBR.new(base_color: "#64ffda")
+  )
+)
+
+# An imgui-ruby WGPU backend can encode its draw data in this callback. The same
+# device and queue are available as demo.app.renderer.device / .queue.
+last_report = 0.0
+demo.app.renderer.on_after_render do |_encoder, _target_view|
+  now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  next unless now - last_report >= 1.0
+
+  warn demo.app.renderer.stats.to_s
+  last_report = now
+end
+demo.run

data/examples/20_window_adapters.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "support/demo"
+
+# SDL3 is the portable default. Set STAGECRAFT_WINDOW=glfw only when supplying
+# the platform-specific WebGPU surface bridge described in the README.
+window = ENV.fetch("STAGECRAFT_WINDOW", "sdl3").to_sym
+demo = StagecraftExamples::Demo.new(title: "20 — #{window} adapter", window:)
+demo.scene.add(
+  Stagecraft::Mesh.new(
+    Stagecraft::Geometries.box,
+    Stagecraft::Materials::Unlit.new(color: "#448aff")
+  )
+)
+demo.run

data/examples/README.md

@@ -0,0 +1,11 @@
+# Stagecraft gallery
+
+Run any example from the repository root:
+
+```sh
+bundle exec ruby examples/01_spinning_cube.rb
+```
+
+The window examples use SDL3 by default. Set `STAGECRAFT_SMOKE=1` to stop after
+one rendered frame. Example 15 is headless and writes a PNG; it accepts the
+destination path as its first argument.

data/examples/support/demo.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+
+require "stagecraft"
+
+module StagecraftExamples
+  class Demo
+    attr_reader :app, :scene
+    attr_accessor :camera
+
+    def initialize(title:, width: 960, height: 540, msaa: 4, window: :sdl3, controls: true)
+      @app = Stagecraft::App.new(title:, width:, height:, msaa:, window:)
+      @scene = Stagecraft::Scene.new
+      @scene.background = "#10141d"
+      @camera = Stagecraft::Cameras::Perspective.new(
+        fov: 55, aspect: app.aspect, near: 0.1, far: 200
+      )
+      @camera.position.set(0, 2, 6)
+      @controls_enabled = controls
+      @updates = []
+      app.window.on_resize do |next_width, next_height|
+        camera.aspect = next_width.to_f / [next_height, 1].max if camera.respond_to?(:aspect=)
+      end
+    end
+
+    def light!
+      scene.add(Stagecraft::Lights::Ambient.new(intensity: 0.3))
+      sun = Stagecraft::Lights::Directional.new(intensity: 3.0)
+      sun.position.set(4, 7, 5)
+      scene.add(sun)
+      sun
+    end
+
+    def update(&block)
+      @updates << block
+      self
+    end
+
+    def run
+      controls = Stagecraft::Controls::Orbit.new(camera, app.window) if @controls_enabled
+      app.run do |dt|
+        controls&.update(dt)
+        @updates.each { |callback| callback.call(dt) }
+        app.renderer.render(scene, camera)
+      end
+    end
+  end
+end

data/lib/stagecraft/animation/action.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Stagecraft
+  module Animation
+    class Action
+      LOOPS = %i[repeat once ping_pong].freeze
+
+      attr_reader :clip, :time, :loop
+      attr_accessor :weight, :time_scale, :enabled, :clamp_when_finished
+
+      def initialize(clip, loop: :repeat, fade_in: 0.0)
+        @clip = clip
+        @loop = loop.to_sym
+        raise ArgumentError, "invalid animation loop #{loop.inspect}" unless LOOPS.include?(@loop)
+
+        @time = 0.0
+        @weight = fade_in.to_f.positive? ? 0.0 : 1.0
+        @fade_duration = [Float(fade_in), 0.0].max
+        @fade_elapsed = 0.0
+        @time_scale = 1.0
+        @enabled = true
+        @clamp_when_finished = true
+        @ping_pong_phase = 0.0
+      end
+
+      def advance(dt)
+        return time unless enabled
+
+        elapsed = Float(dt)
+        update_fade(elapsed)
+        duration = clip.duration
+        return @time = 0.0 if duration.zero?
+
+        delta = elapsed * time_scale
+        return advance_ping_pong(delta, duration) if loop == :ping_pong
+
+        @time += delta
+        apply_loop(duration)
+        time
+      end
+
+      def stop
+        @enabled = false
+        self
+      end
+
+      private
+
+      def update_fade(dt)
+        return unless @fade_duration.positive? && weight < 1.0
+
+        @fade_elapsed += [dt, 0.0].max
+        @weight = [@fade_elapsed / @fade_duration, 1.0].min
+      end
+
+      def apply_loop(duration)
+        case loop
+        when :repeat
+          @time %= duration
+        when :once
+          return unless @time > duration || @time.negative?
+
+          @time = @time.clamp(0.0, duration)
+          @enabled = false unless clamp_when_finished
+        end
+      end
+
+      def advance_ping_pong(delta, duration)
+        period = duration * 2.0
+        @ping_pong_phase = (@ping_pong_phase + delta) % period
+        @time = if @ping_pong_phase <= duration
+                  @ping_pong_phase
+                else
+                  period - @ping_pong_phase
+                end
+      end
+    end
+  end
+end

data/lib/stagecraft/animation/clip.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Stagecraft
+  module Animation
+    class Clip
+      attr_reader :name, :tracks, :duration
+
+      def initialize(name: nil, tracks:, duration: nil)
+        @name = name
+        @tracks = tracks.freeze
+        @duration = duration ? Float(duration) : (@tracks.map(&:duration).max || 0.0)
+      end
+    end
+  end
+end

data/lib/stagecraft/animation/mixer.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Stagecraft
+  module Animation
+    class Mixer
+      attr_reader :root, :actions
+
+      def initialize(root)
+        @root = root
+        @actions = []
+        @resolved_targets = {}
+      end
+
+      def play(clip, loop: :repeat, fade_in: 0.0)
+        action = Action.new(clip, loop:, fade_in:)
+        actions << action
+        clip.tracks.each { |track| resolve_target(track) }
+        action
+      end
+
+      def stop_all
+        actions.each(&:stop)
+        actions.clear
+        self
+      end
+
+      def update(dt)
+        samples = Hash.new { |hash, key| hash[key] = [] }
+        actions.each do |action|
+          next unless action.enabled
+
+          action.advance(dt)
+          action.clip.tracks.each do |track|
+            target = resolve_target(track)
+            next unless target
+
+            samples[[target, track.target_path]] << [track.sample(action.time), action.weight]
+          end
+        end
+        samples.each { |(target, path), values| apply_blend(target, path, values) }
+        self
+      end
+
+      private
+
+      def resolve_target(track)
+        @resolved_targets[track.object_id] ||= case track.target
+                                               when Node then track.target
+                                               when String, Symbol then root.find(track.target.to_s)
+                                               else track.target
+                                               end
+      end
+
+      def apply_blend(target, path, samples)
+        total = samples.sum(&:last)
+        return if total.zero?
+
+        value = if path == :rotation
+                  blend_quaternions(samples, total)
+                else
+                  blend_vectors(samples, total)
+                end
+        case path
+        when :translation then target.position.set(value)
+        when :rotation then target.rotation.set(value)
+        when :scale then target.scale.set(value)
+        when :weights
+          if target.respond_to?(:morph_weights=)
+            target.morph_weights = value
+          elsif target.respond_to?(:traverse)
+            target.traverse do |node|
+              node.morph_weights = value.dup if node.respond_to?(:morph_weights=)
+            end
+          end
+        end
+      end
+
+      def blend_vectors(samples, total)
+        size = samples.first.first.length
+        Array.new(size) do |index|
+          samples.sum { |value, weight| value[index] * weight } / total
+        end
+      end
+
+      def blend_quaternions(samples, total)
+        reference = samples.first.first
+        components = Array.new(4, 0.0)
+        samples.each do |value, weight|
+          dot = 4.times.sum { |index| reference[index] * value[index] }
+          sign = dot.negative? ? -1.0 : 1.0
+          4.times { |index| components[index] += value[index] * weight * sign }
+        end
+        Larb::Quat.new(*components.map { |component| component / total }).normalize.to_a
+      end
+    end
+  end
+end