ruby_rpg 0.0.5 → 0.1.1

data/lib/engine/rendering/render_texture.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Rendering
+  class RenderTexture
+    attr_reader :width, :height, :framebuffer, :depth_stencil_texture, :color_textures
+
+    def initialize(width, height, num_color_attachments: 1)
+      @width = width
+      @height = height
+      @num_color_attachments = num_color_attachments
+      @color_textures = []
+      create_framebuffer
+      create_color_textures
+      create_depth_stencil_texture
+      attach_to_framebuffer
+      check_framebuffer_complete
+    end
+
+    def color_texture
+      @color_textures[0]
+    end
+
+    # Accessor for normal+roughness texture (second attachment)
+    def normal_texture
+      @color_textures[1]
+    end
+
+    # Alias for backward compatibility (depth can still be sampled from depth-stencil)
+    alias depth_texture depth_stencil_texture
+
+    def bind
+      Engine::GL.BindFramebuffer(Engine::GL::FRAMEBUFFER, @framebuffer)
+      Engine::GL.Viewport(0, 0, @width, @height)
+    end
+
+    def resize(width, height)
+      return if width == @width && height == @height
+
+      @width = width
+      @height = height
+
+      @color_textures.each do |tex|
+        Engine::GL.BindTexture(Engine::GL::TEXTURE_2D, tex)
+        Engine::GL.TexImage2D(Engine::GL::TEXTURE_2D, 0, Engine::GL::RGBA16F, @width, @height, 0, Engine::GL::RGBA, Engine::GL::FLOAT, nil)
+      end
+
+      Engine::GL.BindTexture(Engine::GL::TEXTURE_2D, @depth_stencil_texture)
+      Engine::GL.TexImage2D(Engine::GL::TEXTURE_2D, 0, Engine::GL::DEPTH24_STENCIL8, @width, @height, 0, Engine::GL::DEPTH_STENCIL, Engine::GL::UNSIGNED_INT_24_8, nil)
+    end
+
+    private
+
+    def create_framebuffer
+      fbo_buf = ' ' * 4
+      Engine::GL.GenFramebuffers(1, fbo_buf)
+      @framebuffer = fbo_buf.unpack1('L')
+    end
+
+    def create_color_textures
+      @num_color_attachments.times do
+        tex_buf = ' ' * 4
+        Engine::GL.GenTextures(1, tex_buf)
+        texture = tex_buf.unpack1('L')
+
+        Engine::GL.BindTexture(Engine::GL::TEXTURE_2D, texture)
+        Engine::GL.TexImage2D(Engine::GL::TEXTURE_2D, 0, Engine::GL::RGBA16F, @width, @height, 0, Engine::GL::RGBA, Engine::GL::FLOAT, nil)
+        Engine::GL.TexParameteri(Engine::GL::TEXTURE_2D, Engine::GL::TEXTURE_MIN_FILTER, Engine::GL::LINEAR)
+        Engine::GL.TexParameteri(Engine::GL::TEXTURE_2D, Engine::GL::TEXTURE_MAG_FILTER, Engine::GL::LINEAR)
+        Engine::GL.TexParameteri(Engine::GL::TEXTURE_2D, Engine::GL::TEXTURE_WRAP_S, Engine::GL::CLAMP_TO_EDGE)
+        Engine::GL.TexParameteri(Engine::GL::TEXTURE_2D, Engine::GL::TEXTURE_WRAP_T, Engine::GL::CLAMP_TO_EDGE)
+
+        @color_textures << texture
+      end
+    end
+
+    def create_depth_stencil_texture
+      tex_buf = ' ' * 4
+      Engine::GL.GenTextures(1, tex_buf)
+      @depth_stencil_texture = tex_buf.unpack1('L')
+
+      Engine::GL.BindTexture(Engine::GL::TEXTURE_2D, @depth_stencil_texture)
+      Engine::GL.TexImage2D(Engine::GL::TEXTURE_2D, 0, Engine::GL::DEPTH24_STENCIL8, @width, @height, 0, Engine::GL::DEPTH_STENCIL, Engine::GL::UNSIGNED_INT_24_8, nil)
+      Engine::GL.TexParameteri(Engine::GL::TEXTURE_2D, Engine::GL::TEXTURE_MIN_FILTER, Engine::GL::NEAREST)
+      Engine::GL.TexParameteri(Engine::GL::TEXTURE_2D, Engine::GL::TEXTURE_MAG_FILTER, Engine::GL::NEAREST)
+      Engine::GL.TexParameteri(Engine::GL::TEXTURE_2D, Engine::GL::TEXTURE_WRAP_S, Engine::GL::CLAMP_TO_EDGE)
+      Engine::GL.TexParameteri(Engine::GL::TEXTURE_2D, Engine::GL::TEXTURE_WRAP_T, Engine::GL::CLAMP_TO_EDGE)
+      # Disable depth comparison for direct sampling
+      Engine::GL.TexParameteri(Engine::GL::TEXTURE_2D, Engine::GL::TEXTURE_COMPARE_MODE, Engine::GL::NONE)
+      # Specify we want to read depth component (not stencil)
+      Engine::GL.TexParameteri(Engine::GL::TEXTURE_2D, Engine::GL::DEPTH_STENCIL_TEXTURE_MODE, Engine::GL::DEPTH_COMPONENT)
+    end
+
+    def attach_to_framebuffer
+      Engine::GL.BindFramebuffer(Engine::GL::FRAMEBUFFER, @framebuffer)
+
+      # Attach all color textures
+      @color_textures.each_with_index do |tex, i|
+        Engine::GL.FramebufferTexture2D(Engine::GL::FRAMEBUFFER, Engine::GL::COLOR_ATTACHMENT0 + i, Engine::GL::TEXTURE_2D, tex, 0)
+      end
+
+      # Attach depth-stencil texture
+      Engine::GL.FramebufferTexture2D(Engine::GL::FRAMEBUFFER, Engine::GL::DEPTH_STENCIL_ATTACHMENT, Engine::GL::TEXTURE_2D, @depth_stencil_texture, 0)
+
+      # Tell OpenGL which color attachments to draw to (MRT)
+      if @num_color_attachments > 1
+        attachments = (0...@num_color_attachments).map { |i| Engine::GL::COLOR_ATTACHMENT0 + i }
+        Engine::GL.DrawBuffers(@num_color_attachments, attachments.pack('L*'))
+      end
+    end
+
+    def check_framebuffer_complete
+      status = Engine::GL.CheckFramebufferStatus(Engine::GL::FRAMEBUFFER)
+      unless status == Engine::GL::FRAMEBUFFER_COMPLETE
+        raise "Framebuffer not complete: #{status}"
+      end
+    end
+  end
+end

data/lib/engine/rendering/screen_quad.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Rendering
+  class ScreenQuad
+    def initialize
+      setup_vao
+      setup_vbo
+      Engine::GL.BindVertexArray(0)
+    end
+
+    def draw(material, texture)
+      material.set_runtime_texture("screenTexture", texture)
+      draw_with_material(material)
+    end
+
+    def draw_with_material(material)
+      material.update_shader
+      Engine::GL.BindVertexArray(@vao)
+      Engine::GL.DrawArrays(Engine::GL::TRIANGLES, 0, 6)
+    end
+
+    def draw_raw
+      Engine::GL.BindVertexArray(@vao)
+      Engine::GL.DrawArrays(Engine::GL::TRIANGLES, 0, 6)
+    end
+
+    private
+
+    def setup_vao
+      vao_buf = ' ' * 4
+      Engine::GL.GenVertexArrays(1, vao_buf)
+      @vao = vao_buf.unpack1('L')
+      Engine::GL.BindVertexArray(@vao)
+    end
+
+    def setup_vbo
+      # Fullscreen quad: 2 triangles covering -1 to 1 in NDC
+      # Each vertex: x, y, u, v
+      vertices = [
+        # First triangle
+        -1.0,  1.0,  0.0, 1.0,
+        -1.0, -1.0,  0.0, 0.0,
+         1.0, -1.0,  1.0, 0.0,
+        # Second triangle
+        -1.0,  1.0,  0.0, 1.0,
+         1.0, -1.0,  1.0, 0.0,
+         1.0,  1.0,  1.0, 1.0
+      ]
+
+      vbo_buf = ' ' * 4
+      Engine::GL.GenBuffers(1, vbo_buf)
+      vbo = vbo_buf.unpack1('L')
+
+      Engine::GL.BindBuffer(Engine::GL::ARRAY_BUFFER, vbo)
+      Engine::GL.BufferData(Engine::GL::ARRAY_BUFFER, vertices.length * Fiddle::SIZEOF_FLOAT, vertices.pack('F*'), Engine::GL::STATIC_DRAW)
+
+      stride = 4 * Fiddle::SIZEOF_FLOAT
+      Engine::GL.VertexAttribPointer(0, 2, Engine::GL::FLOAT, Engine::GL::FALSE, stride, 0)
+      Engine::GL.VertexAttribPointer(1, 2, Engine::GL::FLOAT, Engine::GL::FALSE, stride, 2 * Fiddle::SIZEOF_FLOAT)
+      Engine::GL.EnableVertexAttribArray(0)
+      Engine::GL.EnableVertexAttribArray(1)
+    end
+  end
+end

data/lib/engine/rendering/shadow_map_array.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Rendering
+  class ShadowMapArray
+    attr_reader :width, :height, :layer_count, :framebuffer, :depth_texture
+
+    def initialize(width: 2048, height: 2048, layer_count: 4)
+      @width = width
+      @height = height
+      @layer_count = layer_count
+      create_framebuffer
+      create_depth_texture_array
+      check_framebuffer_complete
+    end
+
+    def bind_layer(layer_index)
+      raise "Layer index #{layer_index} out of bounds (max: #{@layer_count - 1})" if layer_index >= @layer_count
+
+      Engine::GL.BindFramebuffer(Engine::GL::FRAMEBUFFER, @framebuffer)
+      Engine::GL.FramebufferTextureLayer(Engine::GL::FRAMEBUFFER, Engine::GL::DEPTH_ATTACHMENT, @depth_texture, 0, layer_index)
+      Engine::GL.Viewport(0, 0, @width, @height)
+      Engine::GL.Clear(Engine::GL::DEPTH_BUFFER_BIT)
+    end
+
+    private
+
+    def create_framebuffer
+      fbo_buf = ' ' * 4
+      Engine::GL.GenFramebuffers(1, fbo_buf)
+      @framebuffer = fbo_buf.unpack1('L')
+    end
+
+    def create_depth_texture_array
+      tex_buf = ' ' * 4
+      Engine::GL.GenTextures(1, tex_buf)
+      @depth_texture = tex_buf.unpack1('L')
+
+      Engine::GL.BindTexture(Engine::GL::TEXTURE_2D_ARRAY, @depth_texture)
+      Engine::GL.TexImage3D(
+        Engine::GL::TEXTURE_2D_ARRAY,
+        0,
+        Engine::GL::DEPTH_COMPONENT32F,
+        @width,
+        @height,
+        @layer_count,
+        0,
+        Engine::GL::DEPTH_COMPONENT,
+        Engine::GL::FLOAT,
+        nil
+      )
+
+      Engine::GL.TexParameteri(Engine::GL::TEXTURE_2D_ARRAY, Engine::GL::TEXTURE_MIN_FILTER, Engine::GL::NEAREST)
+      Engine::GL.TexParameteri(Engine::GL::TEXTURE_2D_ARRAY, Engine::GL::TEXTURE_MAG_FILTER, Engine::GL::NEAREST)
+      Engine::GL.TexParameteri(Engine::GL::TEXTURE_2D_ARRAY, Engine::GL::TEXTURE_WRAP_S, Engine::GL::CLAMP_TO_BORDER)
+      Engine::GL.TexParameteri(Engine::GL::TEXTURE_2D_ARRAY, Engine::GL::TEXTURE_WRAP_T, Engine::GL::CLAMP_TO_BORDER)
+      border_color = [1.0, 1.0, 1.0, 1.0].pack('F*')
+      Engine::GL.TexParameterfv(Engine::GL::TEXTURE_2D_ARRAY, Engine::GL::TEXTURE_BORDER_COLOR, border_color)
+    end
+
+    def check_framebuffer_complete
+      Engine::GL.BindFramebuffer(Engine::GL::FRAMEBUFFER, @framebuffer)
+      Engine::GL.FramebufferTextureLayer(Engine::GL::FRAMEBUFFER, Engine::GL::DEPTH_ATTACHMENT, @depth_texture, 0, 0)
+      Engine::GL.DrawBuffer(Engine::GL::NONE)
+      Engine::GL.ReadBuffer(Engine::GL::NONE)
+
+      status = Engine::GL.CheckFramebufferStatus(Engine::GL::FRAMEBUFFER)
+      unless status == Engine::GL::FRAMEBUFFER_COMPLETE
+        raise "Shadow map array framebuffer not complete: #{status}"
+      end
+    end
+  end
+end

data/lib/engine/rendering/skybox_cubemap.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Rendering
+  class SkyboxCubemap
+    CUBEMAP_SIZE = 512
+
+    def initialize
+      @rendered = false
+      @ground_color = nil
+      @horizon_color = nil
+      @sky_color = nil
+      @ground_y = nil
+      @horizon_y = nil
+      @sky_y = nil
+      create_cubemap_texture
+      create_framebuffer
+    end
+
+    def render_if_needed(ground_color, horizon_color, sky_color, ground_y, horizon_y, sky_y)
+      return if @rendered &&
+                @ground_color == ground_color &&
+                @horizon_color == horizon_color &&
+                @sky_color == sky_color &&
+                @ground_y == ground_y &&
+                @horizon_y == horizon_y &&
+                @sky_y == sky_y
+
+      @ground_color = ground_color
+      @horizon_color = horizon_color
+      @sky_color = sky_color
+      @ground_y = ground_y
+      @horizon_y = horizon_y
+      @sky_y = sky_y
+      render_all_faces
+      @rendered = true
+    end
+
+    def invalidate
+      @rendered = false
+    end
+
+    def texture
+      @cubemap_texture
+    end
+
+    private
+
+    def create_cubemap_texture
+      tex_buf = ' ' * 4
+      Engine::GL.GenTextures(1, tex_buf)
+      @cubemap_texture = tex_buf.unpack1('L')
+
+      Engine::GL.BindTexture(Engine::GL::TEXTURE_CUBE_MAP, @cubemap_texture)
+
+      6.times do |i|
+        Engine::GL.TexImage2D(
+          Engine::GL::TEXTURE_CUBE_MAP_POSITIVE_X + i,
+          0,
+          Engine::GL::RGBA16F,
+          CUBEMAP_SIZE,
+          CUBEMAP_SIZE,
+          0,
+          Engine::GL::RGBA,
+          Engine::GL::FLOAT,
+          nil
+        )
+      end
+
+      Engine::GL.TexParameteri(Engine::GL::TEXTURE_CUBE_MAP, Engine::GL::TEXTURE_MIN_FILTER, Engine::GL::LINEAR)
+      Engine::GL.TexParameteri(Engine::GL::TEXTURE_CUBE_MAP, Engine::GL::TEXTURE_MAG_FILTER, Engine::GL::LINEAR)
+      Engine::GL.TexParameteri(Engine::GL::TEXTURE_CUBE_MAP, Engine::GL::TEXTURE_WRAP_S, Engine::GL::CLAMP_TO_EDGE)
+      Engine::GL.TexParameteri(Engine::GL::TEXTURE_CUBE_MAP, Engine::GL::TEXTURE_WRAP_T, Engine::GL::CLAMP_TO_EDGE)
+      Engine::GL.TexParameteri(Engine::GL::TEXTURE_CUBE_MAP, Engine::GL::TEXTURE_WRAP_R, Engine::GL::CLAMP_TO_EDGE)
+
+      Engine::GL.BindTexture(Engine::GL::TEXTURE_CUBE_MAP, 0)
+    end
+
+    def create_framebuffer
+      fbo_buf = ' ' * 4
+      Engine::GL.GenFramebuffers(1, fbo_buf)
+      @fbo = fbo_buf.unpack1('L')
+    end
+
+    def render_all_faces
+      Engine::GL.BindFramebuffer(Engine::GL::FRAMEBUFFER, @fbo)
+      Engine::GL.Viewport(0, 0, CUBEMAP_SIZE, CUBEMAP_SIZE)
+
+      shader.use
+      shader.set_vec3("groundColour", @ground_color) if @ground_color
+      shader.set_vec3("horizonColour", @horizon_color) if @horizon_color
+      shader.set_vec3("skyColour", @sky_color) if @sky_color
+      shader.set_float("groundY", @ground_y) if @ground_y
+      shader.set_float("horizonY", @horizon_y) if @horizon_y
+      shader.set_float("skyY", @sky_y) if @sky_y
+
+      6.times do |face_index|
+        Engine::GL.FramebufferTexture2D(
+          Engine::GL::FRAMEBUFFER,
+          Engine::GL::COLOR_ATTACHMENT0,
+          Engine::GL::TEXTURE_CUBE_MAP_POSITIVE_X + face_index,
+          @cubemap_texture,
+          0
+        )
+
+        Engine::GL.Clear(Engine::GL::COLOR_BUFFER_BIT)
+        shader.set_int("faceIndex", face_index)
+        screen_quad.draw_raw
+      end
+    end
+
+    def shader
+      @shader ||= Engine::Shader.skybox_cubemap
+    end
+
+    def screen_quad
+      @screen_quad ||= ScreenQuad.new
+    end
+  end
+end

data/lib/engine/rendering/skybox_renderer.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Rendering
+  class SkyboxRenderer
+    class << self
+      def set_colors(ground:, horizon:, sky:, ground_y: -0.3, horizon_y: 0.0, sky_y: 1.0)
+        @ground_color = ground
+        @horizon_color = horizon
+        @sky_color = sky
+        @ground_y = ground_y
+        @horizon_y = horizon_y
+        @sky_y = sky_y
+        @skybox_cubemap&.invalidate
+      end
+
+      def render_cubemap
+        @skybox_cubemap ||= SkyboxCubemap.new
+        @skybox_cubemap.render_if_needed(
+          @ground_color,
+          @horizon_color,
+          @sky_color,
+          @ground_y,
+          @horizon_y,
+          @sky_y
+        )
+      end
+
+      def draw(input_rt, alternate_rt, screen_quad)
+        output_rt = alternate_rt
+
+        output_rt.bind
+        Engine::GL.Clear(Engine::GL::COLOR_BUFFER_BIT)
+        Engine::GL.Disable(Engine::GL::DEPTH_TEST)
+
+        camera = Engine::Camera.instance
+        return input_rt unless camera
+
+        material.set_mat4("inverseVP", camera.inverse_vp_matrix)
+        material.set_vec3("cameraPos", camera.position)
+        material.set_cubemap("skyboxCubemap", @skybox_cubemap&.texture)
+        material.set_runtime_texture("depthTexture", input_rt.depth_texture)
+
+        screen_quad.draw(material, input_rt.color_texture)
+        output_rt
+      end
+
+      def cubemap
+        @skybox_cubemap
+      end
+
+      private
+
+      def material
+        @material ||= Engine::Material.create(
+          shader: Engine::Shader.for(
+            'fullscreen_vertex.glsl',
+            'post_process/skybox_frag.glsl',
+            source: :engine
+          )
+        )
+      end
+    end
+  end
+end

data/lib/engine/rendering/ui/stencil_manager.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Rendering
+  module UI
+    module StencilManager
+      class << self
+        def setup_for_rect(rect)
+          chain = rect.ancestor_masks
+
+          if chain.empty?
+            Engine::GL.Disable(Engine::GL::STENCIL_TEST)
+            return
+          end
+
+          # Rebuild stencil if chain changed
+          if chain != @current_chain
+            rebuild_stencil(chain)
+            @current_chain = chain
+          end
+
+          # Configure stencil test: only draw where stencil == chain.length (intersection of all masks)
+          Engine::GL.Enable(Engine::GL::STENCIL_TEST)
+          Engine::GL.StencilFunc(Engine::GL::EQUAL, chain.length, 0xFF)
+          Engine::GL.StencilOp(Engine::GL::KEEP, Engine::GL::KEEP, Engine::GL::KEEP)
+        end
+
+        def reset
+          Engine::GL.Disable(Engine::GL::STENCIL_TEST)
+          @current_chain = nil
+        end
+
+        private
+
+        def rebuild_stencil(chain)
+          # Clear stencil buffer
+          Engine::GL.Clear(Engine::GL::STENCIL_BUFFER_BIT)
+
+          Engine::GL.Enable(Engine::GL::STENCIL_TEST)
+
+          # Draw each mask in the chain, incrementing stencil ref
+          chain.each_with_index do |mask_rect, index|
+            write_mask_to_stencil(mask_rect, index + 1)
+          end
+        end
+
+        def write_mask_to_stencil(mask_rect, ref)
+          # Disable color writes - we only want to update stencil
+          Engine::GL.ColorMask(Engine::GL::FALSE, Engine::GL::FALSE, Engine::GL::FALSE, Engine::GL::FALSE)
+
+          if ref == 1
+            # First mask: write 1 everywhere it covers
+            Engine::GL.StencilFunc(Engine::GL::ALWAYS, ref, 0xFF)
+            Engine::GL.StencilOp(Engine::GL::KEEP, Engine::GL::KEEP, Engine::GL::REPLACE)
+          else
+            # Nested mask: only increment where previous masks passed (stencil == ref-1)
+            Engine::GL.StencilFunc(Engine::GL::EQUAL, ref - 1, 0xFF)
+            Engine::GL.StencilOp(Engine::GL::KEEP, Engine::GL::KEEP, Engine::GL::INCR)
+          end
+
+          # Draw the mask shape
+          mask_rect.game_object.ui_renderers.each(&:draw)
+
+          # Re-enable color writes
+          Engine::GL.ColorMask(Engine::GL::TRUE, Engine::GL::TRUE, Engine::GL::TRUE, Engine::GL::TRUE)
+        end
+      end
+    end
+  end
+end

data/lib/engine/screenshoter.rb

@@ -1,34 +1,34 @@
-module Engine
-  class Screenshoter
-    def self.screenshot(&block)
-      @after_screenshot = block
-    end
-
-    def self.scheduled_screenshot
-      @after_screenshot != nil
-    end
-
-    def self.take_screenshot
-      @scheduled_screenshot = nil
-      width = Engine::Window.framebuffer_width
-      height = Engine::Window.framebuffer_height
-      pixels = ' ' * (width * height * 3)
-      GL.ReadPixels(0, 0, width, height, GL::RGB, GL::UNSIGNED_BYTE, pixels)
-      png = ChunkyPNG::Image.new(width, height, ChunkyPNG::Color::TRANSPARENT)
-      pixels = pixels.bytes.map { |b| b.to_i }
-      x = 0
-      y = 0
-      pixels.each_slice(3) do |r, g, b|
-        png[x, height - y - 1] = ChunkyPNG::Color.rgb(r, g, b)
-        x += 1
-        if x >= width
-          x = 0
-          y += 1
-        end
-      end
-      block = @after_screenshot
-      @after_screenshot = nil
-      block.call(png)
-    end
-  end
-end
+module Engine
+  class Screenshoter
+    def self.screenshot(&block)
+      @after_screenshot = block
+    end
+
+    def self.scheduled_screenshot
+      @after_screenshot != nil
+    end
+
+    def self.take_screenshot
+      @scheduled_screenshot = nil
+      width = Engine::Window.framebuffer_width
+      height = Engine::Window.framebuffer_height
+      pixels = ' ' * (width * height * 3)
+      Engine::GL.ReadPixels(0, 0, width, height, Engine::GL::RGB, Engine::GL::UNSIGNED_BYTE, pixels)
+      png = ChunkyPNG::Image.new(width, height, ChunkyPNG::Color::TRANSPARENT)
+      pixels = pixels.bytes.map { |b| b.to_i }
+      x = 0
+      y = 0
+      pixels.each_slice(3) do |r, g, b|
+        png[x, height - y - 1] = ChunkyPNG::Color.rgb(r, g, b)
+        x += 1
+        if x >= width
+          x = 0
+          y += 1
+        end
+      end
+      block = @after_screenshot
+      @after_screenshot = nil
+      block.call(png)
+    end
+  end
+end

data/lib/engine/serialization/graph_serializer.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Engine
+  module Serialization
+    class GraphSerializer
+      class << self
+        def serialize(root)
+          collected = {}
+          collect_refs(root, collected)
+          collected.values.map { |obj| ObjectSerializer.serialize(obj) }
+        end
+
+        def deserialize(data_array)
+          # Pass 1: Create all objects (with UnresolvedRefs)
+          objects = data_array.map { |data| ObjectSerializer.deserialize(data) }
+          registry = objects.each_with_object({}) { |obj, h| h[obj.uuid] = obj }
+
+          # Pass 2: Resolve all references
+          objects.each { |obj| resolve_references(obj, registry) }
+
+          # Pass 3: Call awake on all objects
+          objects.each(&:awake)
+
+          objects
+        end
+
+        private
+
+        def collect_refs(obj, collected)
+          return if collected.key?(obj.uuid)
+
+          collected[obj.uuid] = obj
+
+          obj.class.serializable_attributes.each do |attr|
+            value = obj.instance_variable_get("@#{attr}")
+            collect_refs_from_value(value, collected)
+          end
+        end
+
+        def collect_refs_from_value(value, collected)
+          case value
+          when Serializable
+            collect_refs(value, collected) unless value.respond_to?(:serializable_data)
+          when Array
+            value.each { |v| collect_refs_from_value(v, collected) }
+          when Hash
+            value.each_value { |v| collect_refs_from_value(v, collected) }
+          end
+        end
+
+        def resolve_references(obj, registry)
+          obj.class.serializable_attributes.each do |attr|
+            value = obj.instance_variable_get("@#{attr}")
+            resolved = resolve_value(value, registry)
+            obj.instance_variable_set("@#{attr}", resolved)
+          end
+        end
+
+        def resolve_value(value, registry)
+          case value
+          when ObjectSerializer::UnresolvedRef
+            registry[value.uuid]
+          when Hash
+            value.transform_values { |v| resolve_value(v, registry) }
+          when Array
+            value.map { |v| resolve_value(v, registry) }
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end