three-rb 0.1.0 → 0.2.1

data/lib/three/generators/browser_example.rb

@@ -0,0 +1,396 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "cgi"
+require "json"
+require "pathname"
+
+module Three
+  module Generators
+    class BrowserExample
+      attr_reader :created, :skipped
+
+      def initialize(target:, root: Dir.pwd, force: false, stream: $stdout)
+        @root = File.expand_path(root)
+        @target = File.expand_path(target, @root)
+        @force = force
+        @stream = stream
+        @created = []
+        @skipped = []
+      end
+
+      def call
+        validate_target!
+        validate_example_files!
+        copy_runtime
+        write_example_files
+        report
+        self
+      end
+
+      private
+
+      def validate_target!
+        target_path = Pathname.new(@target)
+        root_path = Pathname.new(@root)
+        relative = begin
+          target_path.relative_path_from(root_path).to_s
+        rescue ArgumentError
+          raise ArgumentError, "target must be inside #{root_path}"
+        end
+
+        raise ArgumentError, "target must be a directory inside #{root_path}, not the project root" if relative == "."
+        return unless relative == ".." || relative.start_with?("../")
+
+        raise ArgumentError, "target must be inside #{root_path}"
+      end
+
+      def validate_example_files!
+        return if @force
+
+        example_files.each do |path|
+          next unless File.exist?(path)
+
+          raise ArgumentError, "#{relative_path(path)} already exists; pass --force to overwrite generated example files"
+        end
+      end
+
+      def copy_runtime
+        copy_file(runtime_path("package.json"), File.join(@root, "package.json"), overwrite: false)
+        copy_file(runtime_path("pnpm-lock.yaml"), File.join(@root, "pnpm-lock.yaml"), overwrite: false)
+        copy_tree(runtime_path("lib"), File.join(@root, "lib"), overwrite: false)
+        copy_file(
+          runtime_path("examples/browser/shared/boot.mjs"),
+          File.join(File.dirname(@target), "shared", "boot.mjs"),
+          overwrite: @force
+        )
+      end
+
+      def write_example_files
+        if ruby_example?
+          copy_ruby_example_files
+        else
+          write_file(example_path("index.html"), index_html, overwrite: @force)
+          write_file(example_path("boot.mjs"), boot_js, overwrite: @force)
+          write_file(example_path("main.rb"), main_rb, overwrite: @force)
+          write_file(example_path("README.md"), readme, overwrite: @force)
+        end
+      end
+
+      def copy_ruby_example_files
+        {
+          "index.html" => "index.html",
+          "boot.mjs" => "boot.mjs",
+          "main.rb" => "main.rb",
+          "assets/studio.hdr" => "assets/studio.hdr"
+        }.each do |source_name, destination_name|
+          copy_generated_file(
+            runtime_path(File.join("examples/browser/ruby", source_name)),
+            example_path(destination_name),
+            overwrite: @force
+          )
+        end
+
+        write_ruby_readme
+      end
+
+      def write_ruby_readme
+        source = runtime_path("examples/browser/ruby/README.md")
+        destination = example_path("README.md")
+        if File.exist?(destination) && File.identical?(source, destination)
+          @skipped << relative_path(destination)
+          return
+        end
+
+        write_file(destination, ruby_readme, overwrite: @force)
+      end
+
+      def copy_tree(source, destination, overwrite:)
+        Dir.glob(File.join(source, "**/*"), File::FNM_DOTMATCH).each do |path|
+          next if File.directory?(path)
+
+          relative = Pathname.new(path).relative_path_from(Pathname.new(source)).to_s
+          copy_file(path, File.join(destination, relative), overwrite: overwrite)
+        end
+      end
+
+      def copy_file(source, destination, overwrite:)
+        if File.exist?(destination) && File.identical?(source, destination)
+          @skipped << relative_path(destination)
+          return
+        end
+
+        if File.exist?(destination) && !overwrite
+          @skipped << relative_path(destination)
+          return
+        end
+
+        FileUtils.mkdir_p(File.dirname(destination))
+        FileUtils.cp(source, destination)
+        @created << relative_path(destination)
+      end
+
+      def copy_generated_file(source, destination, overwrite:)
+        if File.exist?(destination) && File.identical?(source, destination)
+          @skipped << relative_path(destination)
+          return
+        end
+
+        if File.exist?(destination) && !overwrite
+          raise ArgumentError, "#{relative_path(destination)} already exists; pass --force to overwrite generated example files"
+        end
+
+        FileUtils.mkdir_p(File.dirname(destination))
+        FileUtils.cp(source, destination)
+        @created << relative_path(destination)
+      end
+
+      def write_file(path, content, overwrite:)
+        if File.exist?(path) && !overwrite
+          raise ArgumentError, "#{relative_path(path)} already exists; pass --force to overwrite generated example files"
+        end
+
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, content)
+        @created << relative_path(path)
+      end
+
+      def report
+        @stream.puts "Created browser example at #{relative_path(@target)}"
+        @stream.puts "Created #{created.length} files" unless created.empty?
+        @stream.puts "Skipped #{skipped.length} existing runtime files" unless skipped.empty?
+      end
+
+      def runtime_path(relative)
+        File.expand_path(File.join("../../../", relative), __dir__)
+      end
+
+      def example_files
+        names = %w[index.html boot.mjs main.rb README.md]
+        names << "assets/studio.hdr" if ruby_example?
+        names.map { |name| example_path(name) }
+      end
+
+      def example_path(name)
+        File.join(@target, name)
+      end
+
+      def relative_path(path)
+        Pathname.new(path).relative_path_from(Pathname.new(@root)).to_s
+      end
+
+      def main_module_path
+        File.join(relative_path(@target), "main").delete_prefix("./")
+      end
+
+      def require_three_path
+        Pathname
+          .new(File.join(@root, "lib", "three"))
+          .relative_path_from(Pathname.new(@target))
+          .to_s
+      end
+
+      def shared_boot_path
+        Pathname
+          .new(File.join(File.dirname(@target), "shared", "boot.mjs"))
+          .relative_path_from(Pathname.new(@target))
+          .to_s
+      end
+
+      def title
+        "three-rb #{File.basename(@target)}"
+      end
+
+      def html_text(text)
+        CGI.escapeHTML(text)
+      end
+
+      def js_string(text)
+        JSON.generate(text)
+      end
+
+      def ruby_example?
+        relative_path(@target) == "examples/browser/ruby"
+      end
+
+      def index_html
+        <<~HTML
+          <!doctype html>
+          <html lang="en">
+            <head>
+              <meta charset="utf-8">
+              <meta name="viewport" content="width=device-width, initial-scale=1">
+              <title>#{html_text(title)}</title>
+              <style>
+                :root {
+                  color-scheme: dark;
+                  font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+                  background: #101418;
+                  color: #eef3f7;
+                }
+
+                * { box-sizing: border-box; }
+                html, body, #viewport { width: 100%; height: 100%; margin: 0; }
+                body { overflow: hidden; }
+                #viewport { position: relative; min-width: 320px; min-height: 320px; }
+                canvas { display: block; width: 100%; height: 100%; }
+                .hud {
+                  position: absolute;
+                  top: 16px;
+                  left: 16px;
+                  display: flex;
+                  align-items: center;
+                  gap: 8px;
+                  padding: 8px 10px;
+                  border: 1px solid rgba(255, 255, 255, 0.14);
+                  border-radius: 6px;
+                  background: rgba(10, 14, 18, 0.72);
+                  color: #dce7ef;
+                  font-size: 13px;
+                  backdrop-filter: blur(10px);
+                }
+                .status-dot {
+                  width: 8px;
+                  height: 8px;
+                  border-radius: 999px;
+                  background: #f2b84b;
+                }
+                .status-dot[data-state="running"] { background: #4ed08f; }
+                .status-dot[data-state="error"] { background: #f15b5b; }
+              </style>
+              <script type="importmap">
+                {
+                  "imports": {
+                    "@bjorn3/browser_wasi_shim": "/node_modules/@bjorn3/browser_wasi_shim/dist/index.js",
+                    "@ruby/wasm-wasi/browser": "/node_modules/@ruby/wasm-wasi/dist/esm/browser.js",
+                    "three": "/node_modules/three/build/three.module.js",
+                    "three/addons/": "/node_modules/three/examples/jsm/"
+                  }
+                }
+              </script>
+              <script type="module">
+                const status = document.querySelector("#status");
+                const statusDot = document.querySelector("#status-dot");
+
+                globalThis.__threeRbSetStatus = (message, state) => {
+                  if (status) status.textContent = message;
+                  if (statusDot) statusDot.dataset.state = state;
+                };
+                globalThis.__threeRbBootFailed = (message) => globalThis.__threeRbSetStatus(message, "error");
+                globalThis.addEventListener("error", (event) => globalThis.__threeRbBootFailed(event.message || "Browser error"));
+                globalThis.addEventListener("unhandledrejection", (event) => {
+                  const reason = event.reason;
+                  globalThis.__threeRbBootFailed(reason && reason.message ? reason.message : "Ruby boot failed");
+                });
+                globalThis.__threeRbSetStatus("Loading ruby.wasm", "loading");
+              </script>
+              <script type="module" src="./boot.mjs"></script>
+            </head>
+            <body>
+              <main id="viewport">
+                <canvas id="scene" data-testid="scene-canvas"></canvas>
+                <div class="hud" aria-live="polite">
+                  <span class="status-dot" id="status-dot"></span>
+                  <span id="status" data-testid="status">Loading ruby.wasm</span>
+                </div>
+              </main>
+            </body>
+          </html>
+        HTML
+      end
+
+      def boot_js
+        <<~JS
+          import { bootRubyExample } from #{js_string(shared_boot_path)};
+
+          await bootRubyExample({
+            main: #{js_string(main_module_path)},
+            clearColor: 0x101418
+          });
+        JS
+      end
+
+      def main_rb
+        <<~RUBY
+          # frozen_string_literal: true
+
+          require_relative "#{require_three_path}"
+
+          Three::Browser.run(starting: "Starting Ruby scene") do |app|
+            scene = Three::Scene.new
+            camera = Three::PerspectiveCamera.new(70, aspect: 1.0, near: 0.1, far: 100)
+            camera.position.z = 3
+
+            cube = Three::Mesh.new(
+              Three::BoxGeometry.new(1, 1, 1),
+              Three::MeshBasicMaterial.new(color: 0x4ed08f)
+            )
+            scene.add(cube)
+
+            renderer = Three::Renderers::ThreeJSRenderer.new(
+              canvas: "#scene",
+              antialias: true,
+              alpha: false
+            )
+            renderer.set_clear_color(0x101418, 1)
+
+            app.resize_renderer(renderer, camera)
+            renderer.render(scene, camera)
+
+            app.animation_loop(renderer) do
+              cube.rotation.x += 0.01
+              cube.rotation.y += 0.015
+              renderer.render(scene, camera)
+            end
+          end
+        RUBY
+      end
+
+      def readme
+        <<~MARKDOWN
+          # #{title}
+
+          This generated browser example runs Ruby through ruby.wasm and renders with three.js.
+
+          From the project root:
+
+          ```sh
+          pnpm install
+          ruby -run -e httpd . -p 8000
+          ```
+
+          Open:
+
+          ```text
+          http://localhost:8000/#{relative_path(@target)}/
+          ```
+
+          Keep serving the project root. The browser runtime loads `node_modules/`, `lib/`, and this example over HTTP.
+        MARKDOWN
+      end
+
+      def ruby_readme
+        <<~MARKDOWN
+          # three-rb Ruby Example
+
+          This generated browser example runs Ruby through ruby.wasm and renders a faceted red gemstone with a three-dimensional `three-rb` title.
+
+          From the project root:
+
+          ```sh
+          pnpm install
+          ruby -run -e httpd . -p 8000
+          ```
+
+          Open:
+
+          ```text
+          http://localhost:8000/#{relative_path(@target)}/
+          ```
+
+          Keep serving the project root. The browser runtime loads `node_modules/`, `lib/`, and this example's local `assets/` directory over HTTP.
+        MARKDOWN
+      end
+    end
+  end
+end

data/lib/three/geometries/text_geometry.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "../core/buffer_geometry"
+
+module Three
+  class TextGeometry < BufferGeometry
+    attr_reader :text, :parameters
+
+    def initialize(
+      text,
+      font:,
+      size: 1,
+      depth: 0.2,
+      curve_segments: 12,
+      steps: 1,
+      bevel_enabled: false,
+      bevel_thickness: 0.01,
+      bevel_size: 0.01,
+      bevel_offset: 0,
+      bevel_segments: 3,
+      direction: "ltr"
+    )
+      super()
+      @type = "TextGeometry"
+      @text = text.to_s
+      @parameters = {
+        font: font,
+        size: size,
+        depth: depth,
+        curve_segments: curve_segments,
+        steps: steps,
+        bevel_enabled: bevel_enabled,
+        bevel_thickness: bevel_thickness,
+        bevel_size: bevel_size,
+        bevel_offset: bevel_offset,
+        bevel_segments: bevel_segments,
+        direction: direction
+      }
+    end
+  end
+end

data/lib/three/loaders/font_loader.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "../backends/threejs"
+
+module Three
+  class Font
+    attr_reader :handle
+
+    def initialize(handle)
+      @handle = handle
+    end
+  end
+
+  module Loaders
+    class FontLoader
+      def initialize(adapter: nil, backend: nil)
+        @adapter = adapter || backend&.adapter || Backends::ThreeJS::RubyWasmAdapter.new
+      end
+
+      def load(source)
+        handle = @adapter.load_font(source)
+        handle = handle.await if handle.respond_to?(:await)
+        font = Font.new(handle)
+        yield font if block_given?
+        font
+      end
+    end
+  end
+end

data/lib/three/loaders/three_json_loader.rb

@@ -22,17 +22,20 @@ module Three
       end
 
       def build_texture(entry)
-        case value(entry, :type)
-        when "CubeTexture"
-          CubeTexture.new(
-            value(entry, :sources) || value(entry, :source),
-            **texture_parameters(entry)
-          )
-        when "RGBETexture"
-          RGBETexture.new(value(entry, :source), **texture_parameters(entry))
-        else
-          Texture.new(value(entry, :source), **texture_parameters(entry))
-        end
+        texture =
+          case value(entry, :type)
+          when "CubeTexture"
+            CubeTexture.new(
+              value(entry, :sources) || value(entry, :source),
+              **texture_parameters(entry)
+            )
+          when "RGBETexture"
+            RGBETexture.new(value(entry, :source), **texture_parameters(entry))
+          else
+            Texture.new(value(entry, :source), **texture_parameters(entry))
+          end
+        texture.user_data = value(entry, :user_data) || {}
+        texture
       end
 
       def texture_parameters(entry)
@@ -57,25 +60,25 @@ module Three
         case value(entry, :type)
         when "BoxGeometry"
           parameters = value(entry, :parameters) || {}
-          BoxGeometry.new(
+          apply_geometry_properties(BoxGeometry.new(
             value(parameters, :width) || 1,
             value(parameters, :height) || 1,
             value(parameters, :depth) || 1,
             width_segments: value(parameters, :width_segments) || 1,
             height_segments: value(parameters, :height_segments) || 1,
             depth_segments: value(parameters, :depth_segments) || 1
-          )
+          ), entry)
         when "PlaneGeometry"
           parameters = value(entry, :parameters) || {}
-          PlaneGeometry.new(
+          apply_geometry_properties(PlaneGeometry.new(
             value(parameters, :width) || 1,
             value(parameters, :height) || 1,
             width_segments: value(parameters, :width_segments) || 1,
             height_segments: value(parameters, :height_segments) || 1
-          )
+          ), entry)
         when "SphereGeometry"
           parameters = value(entry, :parameters) || {}
-          SphereGeometry.new(
+          apply_geometry_properties(SphereGeometry.new(
             value(parameters, :radius) || 1,
             width_segments: value(parameters, :width_segments) || 32,
             height_segments: value(parameters, :height_segments) || 16,
@@ -83,7 +86,7 @@ module Three
             phi_length: value(parameters, :phi_length) || Math::PI * 2,
             theta_start: value(parameters, :theta_start) || 0,
             theta_length: value(parameters, :theta_length) || Math::PI
-          )
+          ), entry)
         else
           build_buffer_geometry(entry)
         end
@@ -91,7 +94,6 @@ module Three
 
       def build_buffer_geometry(entry)
         geometry = BufferGeometry.new
-        geometry.name = value(entry, :name) if value(entry, :name)
         geometry.set_index(build_buffer_attribute(value(entry, :index))) if value(entry, :index)
 
         (value(entry, :attributes) || {}).each do |name, attribute_entry|
@@ -106,9 +108,29 @@ module Three
           )
         end
 
+        apply_geometry_properties(geometry, entry)
+      end
+
+      def apply_geometry_properties(geometry, entry)
+        geometry.name = value(entry, :name) if value(entry, :name)
+        geometry.user_data = value(entry, :user_data) || {}
+        draw_range = value(entry, :draw_range)
+        if draw_range
+          geometry.set_draw_range(
+            deserialize_number(value(draw_range, :start)),
+            deserialize_number(value(draw_range, :count))
+          )
+        end
         geometry
       end
 
+      def deserialize_number(value)
+        return Float::INFINITY if value == "Infinity"
+        return -Float::INFINITY if value == "-Infinity"
+
+        value
+      end
+
       def build_buffer_attribute(entry)
         component_type = (value(entry, :component_type) || :generic).to_sym
         array = value(entry, :array) || []
@@ -129,34 +151,37 @@ module Three
 
       def build_material(entry)
         parameters = material_parameters(entry)
-        case value(entry, :type)
-        when "MeshBasicMaterial"
-          MeshBasicMaterial.new(parameters)
-        when "LineBasicMaterial"
-          LineBasicMaterial.new(parameters)
-        when "MeshLambertMaterial"
-          MeshLambertMaterial.new(parameters)
-        when "MeshMatcapMaterial"
-          MeshMatcapMaterial.new(parameters)
-        when "MeshNormalMaterial"
-          MeshNormalMaterial.new(parameters)
-        when "MeshPhongMaterial"
-          MeshPhongMaterial.new(parameters)
-        when "MeshPhysicalMaterial"
-          MeshPhysicalMaterial.new(parameters)
-        when "MeshStandardMaterial"
-          MeshStandardMaterial.new(parameters)
-        when "MeshToonMaterial"
-          MeshToonMaterial.new(parameters)
-        when "PointsMaterial"
-          PointsMaterial.new(parameters)
-        when "ShadowMaterial"
-          ShadowMaterial.new(parameters)
-        when "SpriteMaterial"
-          SpriteMaterial.new(parameters)
-        else
-          Material.new(parameters)
-        end
+        material =
+          case value(entry, :type)
+          when "MeshBasicMaterial"
+            MeshBasicMaterial.new(parameters)
+          when "LineBasicMaterial"
+            LineBasicMaterial.new(parameters)
+          when "MeshLambertMaterial"
+            MeshLambertMaterial.new(parameters)
+          when "MeshMatcapMaterial"
+            MeshMatcapMaterial.new(parameters)
+          when "MeshNormalMaterial"
+            MeshNormalMaterial.new(parameters)
+          when "MeshPhongMaterial"
+            MeshPhongMaterial.new(parameters)
+          when "MeshPhysicalMaterial"
+            MeshPhysicalMaterial.new(parameters)
+          when "MeshStandardMaterial"
+            MeshStandardMaterial.new(parameters)
+          when "MeshToonMaterial"
+            MeshToonMaterial.new(parameters)
+          when "PointsMaterial"
+            PointsMaterial.new(parameters)
+          when "ShadowMaterial"
+            ShadowMaterial.new(parameters)
+          when "SpriteMaterial"
+            SpriteMaterial.new(parameters)
+          else
+            Material.new(parameters)
+          end
+        material.user_data = value(entry, :user_data) || {}
+        material
       end
 
       def material_parameters(entry)
@@ -312,9 +337,29 @@ module Three
         scene = Scene.new
         scene.background = @textures[value(entry, :background)] if value(entry, :background)
         scene.environment = @textures[value(entry, :environment)] if value(entry, :environment)
+        scene.fog = build_fog(value(entry, :fog)) if value(entry, :fog)
+        scene.override_material = @materials[value(entry, :override_material)] if value(entry, :override_material)
         scene
       end
 
+      def build_fog(entry)
+        case value(entry, :type)
+        when "FogExp2"
+          FogExp2.new(
+            value(entry, :color) || 0xffffff,
+            density: has_value?(entry, :density) ? value(entry, :density) : 0.00025,
+            name: value(entry, :name) || ""
+          )
+        else
+          Fog.new(
+            value(entry, :color) || 0xffffff,
+            near: has_value?(entry, :near) ? value(entry, :near) : 1,
+            far: has_value?(entry, :far) ? value(entry, :far) : 1000,
+            name: value(entry, :name) || ""
+          )
+        end
+      end
+
       def build_directional_light(entry)
         light = DirectionalLight.new(value(entry, :color) || 0xffffff, value(entry, :intensity) || 1)
         camera = value(entry, :shadow_camera)
@@ -361,6 +406,7 @@ module Three
         object.matrix_auto_update = value(entry, :matrix_auto_update) if has_value?(entry, :matrix_auto_update)
         object.user_data = value(entry, :user_data) || {}
 
+        object.matrix.from_array(value(entry, :matrix)) if value(entry, :matrix)
         object.position.set(*value(entry, :position)) if value(entry, :position)
         object.quaternion.set(*value(entry, :quaternion)) if value(entry, :quaternion)
         object.scale.set(*value(entry, :scale)) if value(entry, :scale)

data/lib/three/materials/material.rb

@@ -140,7 +140,8 @@ module Three
         opacity: @opacity,
         transparent: @transparent,
         visible: @visible,
-        vertex_colors: @vertex_colors
+        vertex_colors: @vertex_colors,
+        user_data: @user_data
       }
     end