resource stuff

- serialization
- chunks
- parralelfor test

.github/copilot-instructions.md

@@ -0,0 +1,4 @@
+# Copilot Instructions
+
+## Project Guidelines
+- In MoonTools.ECS, do not store plain references to `Entity` objects in long-lived collections outside the ECS world, because their underlying IDs can be reused or destroyed. Instead, query the ECS world to track or process entities based on their assigned components.

.gitmodules

@@ -16,6 +16,6 @@
 [submodule "Nerfed.Runtime/Libraries/ImGui.NET"]
 	path = Nerfed.Runtime/Libraries/ImGui.NET
 	url = https://github.com/ImGuiNET/ImGui.NET.git
-[submodule "Nerfed.Runtime/Libraries/ECS"]
+[submodule "Nerfed.Runtime/Libraries/MoonTools.ECS"]
-	path = Nerfed.Runtime/Libraries/ECS
+	path = Nerfed.Runtime/Libraries/MoonTools.ECS
 	url = https://github.com/MoonsideGames/MoonTools.ECS.git

.idea/.idea.Nerfed/.idea/vcs.xml

@@ -4,6 +4,7 @@
     <mapping directory="" vcs="Git" />
     <mapping directory="$PROJECT_DIR$/Nerfed.Runtime/Libraries/FAudio" vcs="Git" />
     <mapping directory="$PROJECT_DIR$/Nerfed.Runtime/Libraries/ImGui.NET" vcs="Git" />
+    <mapping directory="$PROJECT_DIR$/Nerfed.Runtime/Libraries/MoonTools.ECS" vcs="Git" />
     <mapping directory="$PROJECT_DIR$/Nerfed.Runtime/Libraries/RefreshCS" vcs="Git" />
     <mapping directory="$PROJECT_DIR$/Nerfed.Runtime/Libraries/SDL2CS" vcs="Git" />
     <mapping directory="$PROJECT_DIR$/Nerfed.Runtime/Libraries/WellspringCS" vcs="Git" />

Nerfed.Builder/Builder/Builder.cs

@@ -1,4 +1,6 @@
 using System.Diagnostics;
+using System.Text.Json;
+using Nerfed.Builder.Meta;
 
 namespace Nerfed.Builder;
 
@@ -57,15 +59,45 @@ public class Builder : IDisposable
                     string outFile = $"{args.ResourceOutPath}/{relativeFile}{PathUtil.ImportedFileExtension}";
 
                     FileInfo inFileInfo = new FileInfo(inFile);
-                    FileInfo outFileInfo = new FileInfo(outFile);
 
-                    if (!FileUtil.IsNewer(inFileInfo, outFileInfo))
+                    // =========================================================================
+                    // STEP 1: GUID META FILE SYNC
+                    // Ensure the source file has a backing .meta file generating its Guid 
+                    // =========================================================================
+                    string metaFile = inFile + ".meta";
+                    AssetMeta metaData;
+                    
+                    if (!File.Exists(metaFile))
+                    {
+                        // Generate a brand new meta file to track this asset permanently
+                        metaData = new AssetMeta(Guid.NewGuid());
+                        string json = JsonSerializer.Serialize(metaData, new JsonSerializerOptions { WriteIndented = true });
+                        File.WriteAllText(metaFile, json);
+                        Console.WriteLine($"[Meta] Generated new tracking ID '{metaData.Id}' for {relativeFile}");
+                    }
+                    else
+                    {
+                        // Load the existing guid
+                        metaData = JsonSerializer.Deserialize<AssetMeta>(File.ReadAllText(metaFile))!;
+                    }
+
+                    // Change output file from Name.ext.bin -> /GUID.bin  to completely anonymize the actual game package!
+                    string cacheOutFile = $"{args.ResourceOutPath}/{metaData.Id}.bin";
+                    FileInfo outFileInfo = new FileInfo(cacheOutFile);
+
+                    // Rebuild if the source file changed, or if the meta file changed!
+                    FileInfo metaFileInfo = new FileInfo(metaFile);
+                    bool requiresCompile = !outFileInfo.Exists || 
+                                           FileUtil.IsNewer(inFileInfo, outFileInfo) || 
+                                           FileUtil.IsNewer(metaFileInfo, outFileInfo);
+
+                    if (!requiresCompile)
                     {
                         // File has not changed since last build, no need to build this one.
                         return;
                     }
 
-                    string outDir = Path.GetDirectoryName(outFile);
+                    string outDir = Path.GetDirectoryName(cacheOutFile)!;
                     if (!Directory.Exists(outDir))
                     {
                         Directory.CreateDirectory(outDir);
@@ -74,14 +106,14 @@ public class Builder : IDisposable
                     string ext = Path.GetExtension(inFile).ToLower();
                     if (importers.TryGetValue(ext, out IImporter importer))
                     {
-                        importer.Import(inFile, outFile);
+                        importer.Import(inFile, cacheOutFile); // Compile source directly to hash.bin
                     }
                     else
                     {
-                        rawFileImporter.Import(inFile, outFile);
+                        rawFileImporter.Import(inFile, cacheOutFile);
                     }
 
-                    Console.WriteLine(relativeFile);
+                    Console.WriteLine($"Compiled {relativeFile} -> {metaData.Id}.bin");
                 }
                 catch (Exception e)
                 {

Nerfed.Builder/Meta/AssetMeta.cs

@@ -0,0 +1,30 @@
+        using System;
+
+        namespace Nerfed.Builder.Meta
+        {
+            /// <summary>
+            /// Foundation for JSON-serialized metadata files (e.g. hero.png.meta)
+            /// </summary>
+            public class AssetMeta
+            {
+                /// <summary>
+                /// The universally unique identifier for this asset, generated on first import.
+                /// </summary>
+                public Guid Id { get; set; }
+
+                /// <summary>
+                /// The importer version. Useful to force re-imports if your engine updates how it parses textures.
+                /// </summary>
+                public int ImporterVersion { get; set; } = 1;
+
+                /// <summary>
+                /// Base constructor needed for JSON deserialization
+                /// </summary>
+                public AssetMeta() { }
+
+                public AssetMeta(Guid id)
+                {
+                    Id = id;
+                }
+            }
+        }

Nerfed.Editor/Components/HierachyComponents.cs

@@ -2,5 +2,3 @@
 
 public readonly record struct SelectedInHierachy;
 public readonly record struct ClickedInHierachy;
-public readonly record struct PayloadSourceInHierachy;
-public readonly record struct PayloadTargetInHierachy;

Nerfed.Editor/Editor/EditorGui.cs

@@ -69,6 +69,7 @@ namespace Nerfed.Editor
 
             foreach (MoonTools.ECS.System system in Program.editorSystems)
             {
+                using ProfilerScope scope = new(system.GetType().Name);
                 system.Update(Engine.Timestep);
             }
         }

Nerfed.Editor/Program.cs

@@ -28,24 +28,42 @@ internal class Program
     {
         //systems.Add(new ParentSystem(world));
         systems.Add(new LocalToWorldSystem(world));
-        editorSystems.Add(new EditorHierarchyWindow(world));
+        editorSystems.Add(new EditorProfilerWindow(world));
+        // editorSystems.Add(new EditorHierarchyWindow(world));
+#if DEBUG
+        editorSystems.Add(new EditorInspectorWindow(world));
+#endif
 
-        Entity ent1 = world.CreateEntity("parent");
+        // Entity ent1 = world.CreateEntity("parent");
-        world.Set(ent1, new Root());
+        // world.Set(ent1, new Root());
-        world.Set(ent1, new LocalTransform(new Vector3(1, 0, 0), Quaternion.Identity, Vector3.One));
+        // world.Set(ent1, new LocalTransform(new Vector3(1, 0, 0), Quaternion.Identity, Vector3.One));
+        //
+        // Entity ent2 = world.CreateEntity("child");
+        // world.Set(ent2, new LocalTransform(new Vector3(0, 1, 0), Quaternion.Identity, Vector3.One));
+        // Transform.SetParent(world, ent2, ent1);
+        //
+        // Entity ent3 = world.CreateEntity("entity3");
+        // world.Set(ent3, new Root());
+        // Transform.SetParent(world, ent3, ent2);
+        //
+        // Entity ent4 = world.CreateEntity("entity4");
+        // world.Set(ent4, new Root());
+        //
+        // Entity ent5 = world.CreateBaseEntity("entity5");
 
-        Entity ent2 = world.CreateEntity("child");
+        for (int i = 0; i < 1000000; i++)
-        world.Set(ent2, new LocalTransform(new Vector3(0, 1, 0), Quaternion.Identity, Vector3.One));
+        {
-        Transform.SetParent(world, ent2, ent1);
+            Entity newEnt = world.CreateBaseEntity();
+            world.Set(newEnt, new LocalTransform(new Vector3(i, i, i), Quaternion.Identity, Vector3.One));
 
-        Entity ent3 = world.CreateEntity("entity3");
+            // Entity parent = newEnt;
-        world.Set(ent3, new Root());
+            // for (int j = 0; j < 2; j++) {
-        Transform.SetParent(world, ent3, ent2);
+            //     Entity newChildEnt = world.CreateEntity();
-
+            //     world.Set(newChildEnt, new LocalTransform(new Vector3(i + j * i, i - j * i, j - i * i), Quaternion.Identity, Vector3.One));
-        Entity ent4 = world.CreateEntity("entity4");
+            //     Transform.SetParent(world, newChildEnt, parent);
-        world.Set(ent4, new Root());
+            //     parent = newChildEnt;
-
+            // }
-        Entity ent5 = world.CreateBaseEntity("entity5");
+        }
 
         // Open project.
         // Setip EditorGui.
@@ -56,22 +74,31 @@ internal class Program
     {
         foreach (MoonTools.ECS.System system in systems)
         {
+            using ProfilerScope scope = new(system.GetType().Name);
             system.Update(Engine.Timestep);
         }
 
+        using (new ProfilerScope("EditorGui.Update"))
+        {
             // Editor Update.
             EditorGui.Update();
-
+        }
 
         // Try Catch UserCode Update.
 
+        using (new ProfilerScope("world.FinishUpdate"))
+        {
             world.FinishUpdate();
         }
+    }
 
     private static void HandleOnRender()
+    {
+        using (new ProfilerScope("EditorGui.Render"))
         {
             EditorGui.Render();
         }
+    }
 
     private static void HandleOnQuit()
     {

Nerfed.Editor/Systems/EditorHierarchyWindow.cs

@@ -8,7 +8,7 @@ using Nerfed.Runtime.Util;
 namespace Nerfed.Editor.Systems
 {
     // Window that draws entities.
-    internal class EditorHierarchyWindow : MoonTools.ECS.DebugSystem
+    internal class EditorHierarchyWindow : MoonTools.ECS.System
     {
         private const ImGuiTreeNodeFlags baseFlags = ImGuiTreeNodeFlags.OpenOnArrow | ImGuiTreeNodeFlags.OpenOnDoubleClick | ImGuiTreeNodeFlags.SpanAvailWidth;
 
@@ -17,7 +17,6 @@ namespace Nerfed.Editor.Systems
         private readonly Filter rootEntitiesFilter;
 
         private readonly EditorHierachySelectionSystem hierachySelectionSystem;
-        private readonly EditorHierachyDragAndDropSystem hierachyDragAndDropSystem;
 
         public EditorHierarchyWindow(World world) : base(world)
         {
@@ -34,7 +33,6 @@ namespace Nerfed.Editor.Systems
             // Or a EditorComponent, just a component that always gets added when in editor mode.
 
             hierachySelectionSystem = new EditorHierachySelectionSystem(world);
-            hierachyDragAndDropSystem = new EditorHierachyDragAndDropSystem(world);
         }
 
         public override void Update(TimeSpan delta)
@@ -46,23 +44,23 @@ namespace Nerfed.Editor.Systems
 
             if (ImGui.TreeNodeEx("World", flags))
             {
-                //if (ImGui.BeginDragDropTarget())
+                if (ImGui.BeginDragDropTarget())
-                //{
+                {
-                //    unsafe
+                    unsafe
-                //    {
+                    {
-                //        ImGuiPayloadPtr payload = ImGui.AcceptDragDropPayload($"{nameof(EditorHierarchyWindow)}");
+                        ImGuiPayloadPtr payload = ImGui.AcceptDragDropPayload($"{nameof(EditorHierarchyWindow)}");
-                //        if (payload.NativePtr != null)
+                        if (payload.NativePtr != null)
-                //        {
+                        {
-                //            Entity* data = (Entity*)payload.Data;
+                            Entity* data = (Entity*)payload.Data;
-                //            Entity child = data[0];
+                            Entity child = data[0];
 
-                //            Log.Info($"Dropped {child.ID}");
+                            Log.Info($"Dropped {child.ID}");
 
-                //            Transform.RemoveParent(World, child);
+                            Transform.RemoveParent(World, child);
-                //        }
+                        }
-                //    }
+                    }
-                //    ImGui.EndDragDropTarget();
+                    ImGui.EndDragDropTarget();
-                //}
+                }
 
                 //foreach (Entity entity in rootEntitiesWithTransformFilter.Entities)
                 //{
@@ -80,7 +78,6 @@ namespace Nerfed.Editor.Systems
             ImGui.End();
 
             hierachySelectionSystem.Update(delta);
-            hierachyDragAndDropSystem.Update(delta);
         }
 
         private void DrawEntityAndChildren(in Entity entity)
@@ -99,6 +96,7 @@ namespace Nerfed.Editor.Systems
 
             if (ImGui.TreeNodeEx($"{entity.ID} | {GetTag(entity)}", flags))
             {
+                // TODO: fix selection, look at ImGui 1.91, https://github.com/ocornut/imgui/wiki/Multi-Select
                 // Selection.
                 if (ImGui.IsItemClicked() && !ImGui.IsItemToggledOpen())
                 {
@@ -108,47 +106,35 @@ namespace Nerfed.Editor.Systems
                 // Drag and drop.
                 if (ImGui.BeginDragDropSource())
                 {
-                    ImGui.SetDragDropPayload($"{nameof(EditorHierarchyWindow)}", nint.Zero, 0);
+                    unsafe
-                    Set(entity, new PayloadSourceInHierachy());
+                    {
-                    Log.Info($"SetSource {entity.ID}");
+                        fixed (Entity* payload = &entity)
-
+                        {
-                    //unsafe
+                            ImGui.SetDragDropPayload($"{nameof(EditorHierarchyWindow)}", (IntPtr)payload, (uint)sizeof(Entity));
-                    //{
+                        }
-                    //    fixed (Entity* payload = &entity)
+                    }
-                    //    {
-                    //        ImGui.SetDragDropPayload($"{nameof(EditorHierarchyWindow)}", (IntPtr)payload, (uint)sizeof(Entity));
-                    //    }
-                    //}
 
                     ImGui.EndDragDropSource();
                 }
 
                 if (ImGui.BeginDragDropTarget())
                 {
-                    ImGuiPayloadPtr payload = ImGui.AcceptDragDropPayload($"{nameof(EditorHierarchyWindow)}");
                     unsafe
                     {
+                        ImGuiPayloadPtr payload = ImGui.AcceptDragDropPayload($"{nameof(EditorHierarchyWindow)}");
                         if (payload.NativePtr != null)
                         {
-                            Log.Info($"SetTarget {entity.ID}");
+                            Entity ent = *(Entity*)payload.Data;
-                            Set(entity, new PayloadTargetInHierachy());
+
+                            Log.Info($"Dropped {ent.ID}");
+
+                            Transform.SetParent(World, ent, entity);
                         }
                     }
-                    //unsafe
-                    //{
-                    //    ImGuiPayloadPtr payload = ImGui.AcceptDragDropPayload($"{nameof(EditorHierarchyWindow)}");
-                    //    if (payload.NativePtr != null)
-                    //    {
-                    //        Entity ent = *(Entity*)payload.Data;
-
-                    //        Log.Info($"Dropped {ent.ID}");
-
-                    //        Transform.SetParent(World, ent, entity);
-                    //    }
-                    //}
                     ImGui.EndDragDropTarget();
                 }
 
+                // Draw children.
                 ReverseSpanEnumerator<Entity> childEntities = World.InRelations<ChildParentRelation>(entity);
                 foreach (Entity childEntity in childEntities)
                 {
@@ -200,53 +186,5 @@ namespace Nerfed.Editor.Systems
                 }
             }
         }
-
-        private class EditorHierachyDragAndDropSystem : MoonTools.ECS.System
-        {
-            private readonly Filter sourceEntities;
-            private readonly Filter targetEntities;
-
-            public EditorHierachyDragAndDropSystem(World world) : base(world)
-            {
-                sourceEntities = FilterBuilder.Include<PayloadSourceInHierachy>().Build();
-                targetEntities = FilterBuilder.Include<PayloadTargetInHierachy>().Build();
-            }
-
-            public override void Update(TimeSpan delta)
-            {
-                if (!targetEntities.Empty)
-                {
-                    Entity target = GetSingletonEntity<PayloadTargetInHierachy>();
-
-                    foreach (Entity source in sourceEntities.Entities)
-                    {
-                        Transform.SetParent(World, source, target);
-                    }
-                }
-
-                bool clear = false;
-                unsafe
-                {
-                    ImGuiPayloadPtr payload = ImGui.GetDragDropPayload();
-                    if (payload.NativePtr == null)
-                    {
-                        clear = true;
-                    }
-                }
-
-                if (clear)
-                {
-                    foreach (Entity source in targetEntities.Entities)
-                    {
-                        Remove<PayloadTargetInHierachy>(source);
-                    }
-
-                    foreach (Entity source in sourceEntities.Entities)
-                    {
-                        Remove<PayloadSourceInHierachy>(source);
-                    }
-                }
-            }
-        }
     }
 }

Nerfed.Editor/Systems/EditorInspectorWindow.cs

@@ -0,0 +1,100 @@
+using System.Numerics;
+using ImGuiNET;
+using MoonTools.ECS;
+using Nerfed.Editor.Components;
+using Nerfed.Runtime.Serialization;
+
+#if DEBUG
+namespace Nerfed.Editor.Systems
+{
+    // Window that draws entities.
+    internal class EditorInspectorWindow : MoonTools.ECS.DebugSystem
+    {
+        private readonly Filter selectedEntityFilter;
+
+        public EditorInspectorWindow(World world) : base(world)
+        {
+            selectedEntityFilter = FilterBuilder.Include<SelectedInHierachy>().Build();
+        }
+
+        public override void Update(TimeSpan delta)
+        {
+            ImGui.Begin("Inspector");
+
+            foreach (Entity entity in selectedEntityFilter.Entities)
+            {
+                DrawEntityComponents(entity);
+            }
+
+            ImGui.End();
+        }
+
+        private void DrawEntityComponents(Entity entity)
+        {
+            World.ComponentTypeEnumerator componentTypes = World.Debug_GetAllComponentTypes(entity);
+            
+            // Add button of all types that we can add. Also filter out types we already have.
+            List<Type> componentTypesToAdd = ComponentHelper.AddComponentByType.Keys.ToList();
+            foreach (Type componentType in componentTypes)
+            {
+                componentTypesToAdd.Remove(componentType);
+            }
+
+            const string popupId = "AddComponentPopup";
+            if (ImGui.Button("Add Component"))
+            {
+                ImGui.OpenPopup(popupId);
+            }
+
+            if (ImGui.BeginPopup(popupId))
+            {
+                foreach (Type componentType in componentTypesToAdd)
+                {
+                    if (ImGui.Selectable(componentType.Name))
+                    {
+                        if (ComponentHelper.AddComponentByType.TryGetValue(componentType, out Action<World, Entity> componentSetter))
+                        {
+                            componentSetter.Invoke(World, entity);
+                        }
+                    }
+                }
+                ImGui.EndPopup();
+            }
+
+            ImGui.Dummy(new Vector2(16, 16));
+            
+            ImGui.Text("ComponentInspectorByType");
+            foreach (Type componentType in componentTypes)
+            {
+                if (ComponentHelper.ComponentInspectorByType.TryGetValue(componentType, out Action<World, Entity> componentInspector))
+                {
+                    componentInspector(World, entity);
+                }
+                else if (ComponentHelper.GetComponentByType.TryGetValue(componentType, out Func<World, Entity, ValueType> componentGetter))
+                {
+                    ValueType component = componentGetter.Invoke(World, entity);
+                    ImGui.Text(component.ToString());
+                }
+                else
+                {
+                    ImGui.Text(componentType.Name);
+                }
+                ImGui.Separator();
+            }
+            
+            ImGui.Dummy(new Vector2(16, 16));
+
+            // ImGui.Text("Reflection");
+            // foreach (Type component in componentTypes)
+            // {
+            //     System.Reflection.MethodInfo getMethodInfo = typeof(World).GetMethod("Get");
+            //     System.Reflection.MethodInfo getComponentMethod = getMethodInfo.MakeGenericMethod(component);
+            //     object result = getComponentMethod.Invoke(World, [entity]);
+            //
+            //     // process here
+            //     ImGui.Text(result.ToString());
+            // }
+        }
+    }
+}
+#endif

Nerfed.Editor/Systems/EditorProfilerWindow.cs

@@ -0,0 +1,204 @@
+using ImGuiNET;
+using MoonTools.ECS;
+using Nerfed.Runtime;
+
+namespace Nerfed.Editor.Systems
+{
+    internal class EditorProfilerWindow : MoonTools.ECS.System
+    {
+        const ImGuiTableFlags tableFlags = ImGuiTableFlags.Resizable | ImGuiTableFlags.BordersOuter | ImGuiTableFlags.NoBordersInBody | ImGuiTableFlags.ScrollY | ImGuiTableFlags.ScrollX;
+        const ImGuiTreeNodeFlags treeNodeFlags = ImGuiTreeNodeFlags.SpanAllColumns;
+        const ImGuiTreeNodeFlags treeNodeLeafFlags = ImGuiTreeNodeFlags.SpanAllColumns | ImGuiTreeNodeFlags.Leaf | ImGuiTreeNodeFlags.NoTreePushOnOpen;
+
+        private int selectedFrame = 0;
+        private int previousSelectedFrame = -1;
+        private IOrderedEnumerable<KeyValuePair<string, (double ms, uint calls)>> orderedCombinedData = null;
+
+        public EditorProfilerWindow(World world) : base(world)
+        {
+        }
+
+        public override void Update(TimeSpan delta)
+        {
+            if (Profiler.Frames.Count <= 0)
+            {
+                return;
+            }
+
+            ImGui.Begin("Profiler");
+
+            ImGui.BeginChild("Toolbar", new System.Numerics.Vector2(0, 0), ImGuiChildFlags.AutoResizeY);
+            if (ImGui.RadioButton("Recording", Profiler.IsRecording))
+            {
+                Profiler.SetActive(!Profiler.IsRecording);
+            }
+
+            ImGui.SameLine();
+
+            if (Profiler.IsRecording)
+            {
+                // Select last frame when recording to see latest frame data.
+                selectedFrame = Profiler.Frames.Count - 1;
+            }
+            if (ImGui.SliderInt(string.Empty, ref selectedFrame, 0, Profiler.Frames.Count - 1))
+            {
+                // Stop recording when browsing frames.
+                Profiler.SetActive(false);
+            }
+
+            Profiler.Frame frame = Profiler.Frames.ElementAt(selectedFrame);
+            double ms = frame.ElapsedMilliseconds();
+            double s = 1000;
+            ImGui.Text($"Frame: {frame.FrameCount} ({ms:0.000} ms | {(s / ms):0} fps)");
+            ImGui.EndChild();
+
+            if (!Profiler.IsRecording) {
+                if (previousSelectedFrame != selectedFrame)
+                {
+                    previousSelectedFrame = selectedFrame;
+                    orderedCombinedData = CalculateCombinedData(frame);
+                }
+
+                DrawFlameGraph(frame);
+
+                DrawHierachy(frame);
+
+                ImGui.SameLine();
+
+                DrawCombined(orderedCombinedData);
+            }
+
+            ImGui.End();
+        }
+
+        private static void DrawHierachy(Profiler.Frame frame)
+        {
+            if(frame == null)
+            {
+                return;
+            }
+
+            ImGui.BeginChild("Hierachy", new System.Numerics.Vector2(150, 0), ImGuiChildFlags.ResizeX);
+
+            if (ImGui.BeginTable("ProfilerData", 3, tableFlags, new System.Numerics.Vector2(0, 0)))
+            {
+                ImGui.TableSetupColumn("name", ImGuiTableColumnFlags.WidthStretch, 0.8f, 0);
+                ImGui.TableSetupColumn("thread", ImGuiTableColumnFlags.WidthStretch, 0.2f, 1);
+                ImGui.TableSetupColumn("ms", ImGuiTableColumnFlags.WidthStretch, 0.2f, 1);
+                ImGui.TableSetupScrollFreeze(0, 1); // Make row always visible
+                ImGui.TableHeadersRow();
+
+                foreach (Profiler.ScopeNode node in frame.RootNodes)
+                {
+                    DrawHierachyNode(node);
+                }
+
+                ImGui.EndTable();
+            }
+
+            ImGui.EndChild();
+        }
+
+        private static void DrawHierachyNode(Profiler.ScopeNode node)
+        {
+            ImGui.TableNextRow();
+            ImGui.TableNextColumn();
+
+            bool isOpen = false;
+            bool isLeaf = node.Children.Count == 0;
+
+            if (isLeaf) {
+                ImGui.TreeNodeEx(node.Label, treeNodeLeafFlags);
+            }
+            else
+            {
+                isOpen = ImGui.TreeNodeEx(node.Label, treeNodeFlags);
+            }
+
+            ImGui.TableNextColumn();
+            ImGui.Text($"{node.ManagedThreadId}");
+            ImGui.TableNextColumn();
+            ImGui.Text($"{node.ElapsedMilliseconds():0.000}");
+
+            if (isOpen)
+            {
+                for (int i = 0; i < node.Children.Count; i++)
+                {
+                    DrawHierachyNode(node.Children[i]);
+                }
+                ImGui.TreePop();
+            }
+        }
+
+        private static void DrawCombined(in IOrderedEnumerable<KeyValuePair<string, (double ms, uint calls)>> orderedCombinedData)
+        {
+            if(orderedCombinedData == null)
+            {
+                return;
+            }
+
+            ImGui.BeginChild("Combined", new System.Numerics.Vector2(0, 0));
+
+            if (ImGui.BeginTable("ProfilerCombinedData", 3, tableFlags, new System.Numerics.Vector2(0, 0)))
+            {
+                ImGui.TableSetupColumn("name", ImGuiTableColumnFlags.WidthStretch, 0.6f, 0);
+                ImGui.TableSetupColumn("ms", ImGuiTableColumnFlags.WidthStretch, 0.2f, 1);
+                ImGui.TableSetupColumn("calls", ImGuiTableColumnFlags.WidthStretch, 0.2f, 2);
+                ImGui.TableSetupScrollFreeze(0, 1); // Make row always visible
+                ImGui.TableHeadersRow();
+
+                foreach (KeyValuePair<string, (double ms, uint calls)> combinedData in orderedCombinedData)
+                {
+                    ImGui.TableNextRow();
+                    ImGui.TableNextColumn();
+                    ImGui.Text($"{combinedData.Key}");
+                    ImGui.TableNextColumn();
+                    ImGui.Text($"{combinedData.Value.ms:0.000}");
+                    ImGui.TableNextColumn();
+                    ImGui.Text($"{combinedData.Value.calls}");
+                }
+
+                ImGui.EndTable();
+            }
+
+            ImGui.EndChild();
+        }
+
+        private static IOrderedEnumerable<KeyValuePair<string, (double ms, uint calls)>> CalculateCombinedData(Profiler.Frame frame)
+        {
+            Dictionary<string, (double ms, uint calls)> combinedRecordData = new Dictionary<string, (double ms, uint calls)>(128);
+            foreach (Profiler.ScopeNode node in frame.RootNodes)
+            {
+                CalculateCombinedData(node, in combinedRecordData);
+            }
+            return combinedRecordData.OrderByDescending(x => x.Value.ms);
+        }
+
+        private static void CalculateCombinedData(Profiler.ScopeNode node, in Dictionary<string, (double ms, uint calls)> combinedRecordData)
+        {
+            if (combinedRecordData.TryGetValue(node.Label, out (double ms, uint calls) combined))
+            {
+                combinedRecordData[node.Label] = (combined.ms + node.ElapsedMilliseconds(), combined.calls + 1);
+            }
+            else
+            {
+                combinedRecordData.Add(node.Label, (node.ElapsedMilliseconds(), 1));
+            }
+
+            for (int i = 0; i < node.Children.Count; i++)
+            {
+                CalculateCombinedData(node.Children[i], combinedRecordData);
+            }
+        }
+
+        private static void DrawFlameGraph(Profiler.Frame frame)
+        {
+            if (frame == null)
+            {
+                return;
+            }
+
+            ProfilerVisualizer.RenderFlameGraph(frame);
+        }
+    }
+}

Nerfed.Runtime/Components/LocalTransform.cs

@@ -1,20 +1,11 @@
 using System.Numerics;
+using Nerfed.Runtime.Scene;
 
 namespace Nerfed.Runtime.Components
 {
-    public struct LocalTransform
+    [SceneComponent]
+    public readonly record struct LocalTransform(Vector3 position, Quaternion rotation, Vector3 scale)
     {
-        public Vector3 position;
-        public Quaternion rotation;
-        public Vector3 scale;
-
-        public LocalTransform(Vector3 position, Quaternion rotation, Vector3 scale)
-        {
-            this.position = position;
-            this.rotation = rotation;
-            this.scale = scale;
-        }
-
         public static readonly LocalTransform Identity = new(Vector3.Zero, Quaternion.Identity, Vector3.One);
     }
 }

Nerfed.Runtime/Components/Test.cs

@@ -1,4 +1,7 @@
-namespace Nerfed.Runtime.Components
+using Nerfed.Runtime.Scene;
+
+namespace Nerfed.Runtime.Components
 {
+    [SceneComponent]
     public readonly record struct Test();
 }

Nerfed.Runtime/Engine.cs

@@ -16,7 +16,7 @@ public static class Engine
     public static bool VSync { get; set; }
 
     public static GraphicsDevice GraphicsDevice { get; private set; }
-    public static AudioDevice AudioDevice { get; private set; }
+    //public static AudioDevice AudioDevice { get; private set; }
     public static Window MainWindow { get; private set; }
     public static TimeSpan Timestep { get; private set; }
 
@@ -44,19 +44,16 @@ public static class Engine
     private const string WindowTitle = "Nerfed";
     //..
 
-    public static void Run(string[] args)
+    public static void Run(string[] args) {
-    {
         Timestep = TimeSpan.FromTicks(TimeSpan.TicksPerSecond / TargetTimestep);
         gameTimer = Stopwatch.StartNew();
         SetFrameLimiter(new FrameLimiterSettings(FrameLimiterMode.Capped, MaxFps));
 
-        for (int i = 0; i < previousSleepTimes.Length; i += 1)
+        for(int i = 0; i < previousSleepTimes.Length; i += 1) {
-        {
             previousSleepTimes[i] = TimeSpan.FromMilliseconds(1);
         }
 
-        if (SDL.SDL_Init(SDL.SDL_INIT_VIDEO | SDL.SDL_INIT_TIMER | SDL.SDL_INIT_GAMECONTROLLER) < 0)
+        if(SDL.SDL_Init(SDL.SDL_INIT_VIDEO | SDL.SDL_INIT_TIMER | SDL.SDL_INIT_GAMECONTROLLER) < 0) {
-        {
             throw new Exception("Failed to init SDL");
         }
 
@@ -64,17 +61,15 @@ public static class Engine
         GraphicsDevice.LoadDefaultPipelines();
 
         MainWindow = new Window(GraphicsDevice, new WindowCreateInfo(WindowTitle, WindowWidth, WindowHeight, ScreenMode.Windowed));
-        if (!GraphicsDevice.ClaimWindow(MainWindow, SwapchainComposition.SDR, VSync ? PresentMode.VSync : PresentMode.Mailbox))
+        if(!GraphicsDevice.ClaimWindow(MainWindow, SwapchainComposition.SDR, VSync ? PresentMode.VSync : PresentMode.Mailbox)) {
-        {
             throw new Exception("Failed to claim window");
         }
 
-        AudioDevice = new AudioDevice();
+        //AudioDevice = new AudioDevice();
 
         OnInitialize?.Invoke();
 
-        while (!quit)
+        while(!quit) {
-        {
             Tick();
         }
 
@@ -83,45 +78,41 @@ public static class Engine
         GraphicsDevice.UnclaimWindow(MainWindow);
         MainWindow.Dispose();
         GraphicsDevice.Dispose();
-        AudioDevice.Dispose();
+        //AudioDevice.Dispose();
         SDL.SDL_Quit();
     }
 
     /// <summary>
     /// Updates the frame limiter settings.
     /// </summary>
-    public static void SetFrameLimiter(FrameLimiterSettings settings)
+    public static void SetFrameLimiter(FrameLimiterSettings settings) {
-    {
         framerateCapped = settings.Mode == FrameLimiterMode.Capped;
 
-        if (framerateCapped)
+        if(framerateCapped) {
-        {
             framerateCapTimeSpan = TimeSpan.FromTicks(TimeSpan.TicksPerSecond / settings.Cap);
-        }
+        } else {
-        else
-        {
             framerateCapTimeSpan = TimeSpan.Zero;
         }
     }
 
-    public static void Quit()
+    public static void Quit() {
-    {
         quit = true;
     }
 
-    private static void Tick()
+    private static void Tick() {
-    {
+        Profiler.BeginFrame();
+
         AdvanceElapsedTime();
 
-        if (framerateCapped)
+        if(framerateCapped) {
-        {
+            Profiler.BeginSample("framerateCapped");
+
             /* We want to wait until the framerate cap,
              * but we don't want to oversleep. Requesting repeated 1ms sleeps and
              * seeing how long we actually slept for lets us estimate the worst case
              * sleep precision so we don't oversleep the next frame.
              */
-            while (accumulatedDrawTime + worstCaseSleepPrecision < framerateCapTimeSpan)
+            while(accumulatedDrawTime + worstCaseSleepPrecision < framerateCapTimeSpan) {
-            {
                 Thread.Sleep(1);
                 TimeSpan timeAdvancedSinceSleeping = AdvanceElapsedTime();
                 UpdateEstimatedSleepPrecision(timeAdvancedSinceSleeping);
@@ -132,23 +123,22 @@ public static class Engine
              * SpinWait(1) works by pausing the thread for very short intervals, so it is
              * an efficient and time-accurate way to wait out the rest of the time.
              */
-            while (accumulatedDrawTime < framerateCapTimeSpan)
+            while(accumulatedDrawTime < framerateCapTimeSpan) {
-            {
                 Thread.SpinWait(1);
                 AdvanceElapsedTime();
             }
+
+            Profiler.EndSample();
         }
 
         // Do not let any step take longer than our maximum.
-        if (accumulatedUpdateTime > MaxDeltaTime)
+        if(accumulatedUpdateTime > MaxDeltaTime) {
-        {
             accumulatedUpdateTime = MaxDeltaTime;
         }
 
-        if (!quit)
+        if(!quit) {
-        {
+            while(accumulatedUpdateTime >= Timestep) {
-            while (accumulatedUpdateTime >= Timestep)
+                Profiler.BeginSample("Update");
-            {
                 Keyboard.Update();
                 Mouse.Update();
                 GamePad.Update();
@@ -156,23 +146,29 @@ public static class Engine
                 ProcessSDLEvents();
 
                 // Tick game here...
+                Profiler.BeginSample("OnUpdate");
                 OnUpdate?.Invoke();
+                Profiler.EndSample();
 
-                AudioDevice.WakeThread();
+                //AudioDevice.WakeThread();
                 accumulatedUpdateTime -= Timestep;
+                Profiler.EndSample();
             }
 
             double alpha = accumulatedUpdateTime / Timestep;
 
             // Render here..
+            Profiler.BeginSample("OnRender");
             OnRender?.Invoke();
+            Profiler.EndSample();
 
             accumulatedDrawTime -= framerateCapTimeSpan;
         }
+
+        Profiler.EndFrame();
     }
 
-    private static TimeSpan AdvanceElapsedTime()
+    private static TimeSpan AdvanceElapsedTime() {
-    {
         long currentTicks = gameTimer.Elapsed.Ticks;
         TimeSpan timeAdvanced = TimeSpan.FromTicks(currentTicks - previousTicks);
         accumulatedUpdateTime += timeAdvanced;
@@ -181,12 +177,9 @@ public static class Engine
         return timeAdvanced;
     }
 
-    private static void ProcessSDLEvents()
+    private static void ProcessSDLEvents() {
-    {
+        while(SDL.SDL_PollEvent(out SDL.SDL_Event ev) == 1) {
-        while (SDL.SDL_PollEvent(out SDL.SDL_Event ev) == 1)
+            switch(ev.type) {
-        {
-            switch (ev.type)
-            {
                 case SDL.SDL_EventType.SDL_QUIT:
                     Quit();
                     break;
@@ -222,16 +215,14 @@ public static class Engine
     /* To calculate the sleep precision of the OS, we take the worst case
      * time spent sleeping over the results of previous requests to sleep 1ms.
      */
-    private static void UpdateEstimatedSleepPrecision(TimeSpan timeSpentSleeping)
+    private static void UpdateEstimatedSleepPrecision(TimeSpan timeSpentSleeping) {
-    {
         /* It is unlikely that the scheduler will actually be more imprecise than
          * 4ms and we don't want to get wrecked by a single long sleep so we cap this
          * value at 4ms for sanity.
          */
         TimeSpan upperTimeBound = TimeSpan.FromMilliseconds(4);
 
-        if (timeSpentSleeping > upperTimeBound)
+        if(timeSpentSleeping > upperTimeBound) {
-        {
             timeSpentSleeping = upperTimeBound;
         }
 
@@ -240,17 +231,12 @@ public static class Engine
          * is if we either 1) just got a new worst case, or 2) the worst case was
          * the oldest entry on the list.
          */
-        if (timeSpentSleeping >= worstCaseSleepPrecision)
+        if(timeSpentSleeping >= worstCaseSleepPrecision) {
-        {
             worstCaseSleepPrecision = timeSpentSleeping;
-        }
+        } else if(previousSleepTimes[sleepTimeIndex] == worstCaseSleepPrecision) {
-        else if (previousSleepTimes[sleepTimeIndex] == worstCaseSleepPrecision)
-        {
             TimeSpan maxSleepTime = TimeSpan.MinValue;
-            for (int i = 0; i < previousSleepTimes.Length; i++)
+            for(int i = 0; i < previousSleepTimes.Length; i++) {
-            {
+                if(previousSleepTimes[i] > maxSleepTime) {
-                if (previousSleepTimes[i] > maxSleepTime)
-                {
                     maxSleepTime = previousSleepTimes[i];
                 }
             }

Nerfed.Runtime/Graphics/GraphicsDevice.cs

@@ -68,10 +68,10 @@ public class GraphicsDevice : IDisposable
 
     internal void LoadDefaultPipelines()
     {
-        FullscreenVertexShader = ResourceManager.Load<Shader>("Shaders/Fullscreen.vert");
+        FullscreenVertexShader = ResourceManager.Retain<Shader>("Shaders/Fullscreen.vert");
-        VideoFragmentShader = ResourceManager.Load<Shader>("Shaders/Video.frag");
+        VideoFragmentShader = ResourceManager.Retain<Shader>("Shaders/Video.frag");
-        TextVertexShader = ResourceManager.Load<Shader>("Shaders/Text.vert");
+        TextVertexShader = ResourceManager.Retain<Shader>("Shaders/Text.vert");
-        TextFragmentShader = ResourceManager.Load<Shader>("Shaders/Text.frag");
+        TextFragmentShader = ResourceManager.Retain<Shader>("Shaders/Text.frag");
 
         VideoPipeline = new GraphicsPipeline(
             this,
@@ -373,10 +373,10 @@ public class GraphicsDevice : IDisposable
                     resources.Clear();
                 }
 
-                ResourceManager.Unload(FullscreenVertexShader);
+                ResourceManager.Release(FullscreenVertexShader);
-                ResourceManager.Unload(TextFragmentShader);
+                ResourceManager.Release(TextFragmentShader);
-                ResourceManager.Unload(TextVertexShader);
+                ResourceManager.Release(TextVertexShader);
-                ResourceManager.Unload(VideoFragmentShader);
+                ResourceManager.Release(VideoFragmentShader);
             }
 
             Refresh.Refresh_DestroyDevice(Handle);

Nerfed.Runtime/Gui/GuiController.cs

@@ -60,8 +60,8 @@ public class GuiController : IDisposable
         io.DisplaySize = new Vector2(mainWindow.Width, mainWindow.Height);
         io.DisplayFramebufferScale = Vector2.One;
 
-        imGuiVertexShader = ResourceManager.Load<Shader>("Shaders/ImGui.vert");
+        imGuiVertexShader = ResourceManager.Retain<Shader>("Shaders/ImGui.vert");
-        imGuiFragmentShader = ResourceManager.Load<Shader>("Shaders/ImGui.frag");
+        imGuiFragmentShader = ResourceManager.Retain<Shader>("Shaders/ImGui.frag");
 
         imGuiSampler = new Sampler(graphicsDevice, SamplerCreateInfo.LinearClamp);
 
@@ -630,8 +630,8 @@ public class GuiController : IDisposable
         fontTexture?.Dispose();
         imGuiVertexBuffer?.Dispose();
         imGuiIndexBuffer?.Dispose();
-        ResourceManager.Unload(imGuiVertexShader);
+        ResourceManager.Release(imGuiVertexShader);
-        ResourceManager.Unload(imGuiFragmentShader);
+        ResourceManager.Release(imGuiFragmentShader);
         imGuiPipeline?.Dispose();
         imGuiSampler?.Dispose();
         resourceUploader?.Dispose();

Nerfed.Runtime/Nerfed.Runtime.csproj

@@ -32,13 +32,13 @@
     </PropertyGroup>
     
     <ItemGroup>
-		<Compile Include="Libraries\ECS\src\**\*.cs" />
-		<Compile Include="Libraries\SDL2CS\src\SDL2.cs" />
-        <Compile Include="Libraries\RefreshCS\RefreshCS.cs" />
         <Compile Include="Libraries\FAudio\csharp\FAudio.cs" />
+        <Compile Include="Libraries\ImGui.NET\src\ImGui.NET\**\*.cs" />
+        <Compile Include="Libraries\MoonTools.ECS\src\**\*.cs" />
+        <Compile Include="Libraries\RefreshCS\RefreshCS.cs" />
+        <Compile Include="Libraries\SDL2CS\src\SDL2.cs" />
         <Compile Include="Libraries\WellspringCS\WellspringCS.cs" />
         <Compile Include="Libraries\dav1dfile\csharp\dav1dfile.cs" />
-        <Compile Include="Libraries\ImGui.NET\src\ImGui.NET\**\*.cs" />
     </ItemGroup>
     
 </Project>

Nerfed.Runtime/Profiler.cs

@@ -1,29 +1,166 @@
-using System.Diagnostics;
+using System.Collections.Concurrent;
-using System.Reflection;
+using System.Diagnostics;
-using System.Runtime.CompilerServices;
 
 namespace Nerfed.Runtime;
 
 public struct ProfilerScope : IDisposable
 {
-    public ProfilerScope(string label) {
+    public ProfilerScope(string label)
+    {
         Profiler.BeginSample(label);
     }
 
-    public void Dispose() {
+    public void Dispose()
+    {
         Profiler.EndSample();
     }
 }
 
 public static class Profiler
 {
-    [Conditional("PROFILING")]
+    public class Frame(uint frameCount)
-    public static void BeginSample(string label) {
+    {
+        public uint FrameCount { get; } = frameCount;
+        public long StartTime { get; } = Stopwatch.GetTimestamp();
+        public long EndTime { get; private set; }
 
+        // Use a concurrent list to collect all thread root nodes per frame.
+        public ConcurrentBag<ScopeNode> RootNodes = new ConcurrentBag<ScopeNode>();
+
+        internal void End()
+        {
+            EndTime = Stopwatch.GetTimestamp();
+        }
+
+        public double ElapsedMilliseconds()
+        {
+            long elapsedTicks = EndTime - StartTime;
+            return ((double)(elapsedTicks * 1000)) / Stopwatch.Frequency;
+        }
+    }
+
+    public class ScopeNode(string label)
+    {
+        public string Label { get; } = label;
+        public long StartTime { get; private set; } = Stopwatch.GetTimestamp();  // Start time in ticks
+        public long EndTime { get; private set; }
+        public int ManagedThreadId { get; } = Environment.CurrentManagedThreadId;
+        public List<ScopeNode> Children { get; } = new List<ScopeNode>();
+
+        internal void End()
+        {
+            EndTime = Stopwatch.GetTimestamp();  // End time in ticks
+        }
+
+        public double ElapsedMilliseconds()
+        {
+            return ((double)(EndTime - StartTime)) * 1000 / Stopwatch.Frequency;  // Convert ticks to ms
+        }
+
+        // Add a child node (used for nested scopes)
+        internal ScopeNode AddChild(string label)
+        {
+            ScopeNode child = new ScopeNode(label);
+            Children.Add(child);
+            return child;
+        }
+    }
+
+    private const int maxFrames = 128;
+
+    public static bool IsRecording { get; private set; } = true;
+
+    // Store only the last x amount of frames in memory.
+    public static readonly BoundedQueue<Frame> Frames = new(maxFrames);
+
+    // Use ThreadLocal to store a stack of ScopeNodes per thread and enable tracking of thread-local values.
+    private static readonly ThreadLocal<Stack<ScopeNode>> threadLocalScopes = new ThreadLocal<Stack<ScopeNode>>(() => new Stack<ScopeNode>(), true);
+
+    private static Frame currentFrame = null;
+    private static uint frameCount = 0;
+
+    public static void SetActive(bool isRecording)
+    {
+        IsRecording = isRecording;
     }
 
     [Conditional("PROFILING")]
-    public static void EndSample() {
+    public static void BeginFrame()
+    {
+        if (!IsRecording)
+        {
+            return;
+        }
 
+        currentFrame = new Frame(frameCount);
+    }
+
+    [Conditional("PROFILING")]
+    public static void EndFrame()
+    {
+        if (!IsRecording)
+        {
+            return;
+        }
+
+        foreach (Stack<ScopeNode> scopes in threadLocalScopes.Values)
+        {
+            if (scopes.Count > 0)
+            {
+                // Pop the left over root nodes.
+                ScopeNode currentScope = scopes.Pop();
+                currentScope.End();
+            }
+
+            // Clean up the thread-local stack to ensure it's empty for the next frame.
+            scopes.Clear();
+        }
+
+        currentFrame.End();
+        Frames.Enqueue(currentFrame);
+        frameCount++;
+    }
+
+    [Conditional("PROFILING")]
+    public static void BeginSample(string label)
+    {
+        if (!IsRecording)
+        {
+            return;
+        }
+
+        Stack<ScopeNode> scopes = threadLocalScopes.Value;  // Get the stack for the current thread
+
+        if (scopes.Count == 0)
+        {
+            // First scope for this thread (new root for this thread)
+            ScopeNode rootScopeNode = new ScopeNode($"Thread-{Environment.CurrentManagedThreadId}");
+            scopes.Push(rootScopeNode);
+            currentFrame.RootNodes.Add(rootScopeNode);  // Add root node to the frame list
+        }
+
+        // Create a new child under the current top of the stack
+        ScopeNode newScope = scopes.Peek().AddChild(label);
+
+        scopes.Push(newScope);  // Push new scope to the thread's stack
+    }
+
+    [Conditional("PROFILING")]
+    public static void EndSample()
+    {
+        if (!IsRecording)
+        {
+            return;
+        }
+
+        Stack<ScopeNode> scopes = threadLocalScopes.Value;
+
+        if (scopes.Count > 0)
+        {
+            // Only pop if this is not the root node.
+            //ScopeNode currentScope = scopes.Count > 1 ? scopes.Pop() : scopes.Peek();
+            ScopeNode currentScope = scopes.Pop();
+            currentScope.End();
+        }
     }
 }

Nerfed.Runtime/ProfilerVisualizer.cs

@@ -0,0 +1,156 @@
+using ImGuiNET;
+using System.Numerics;
+
+namespace Nerfed.Runtime;
+
+public static class ProfilerVisualizer
+{
+    private const float barHeight = 20f;
+    private const float barPadding = 2f;
+
+    // Render the flame graph across multiple threads
+    public static void RenderFlameGraph(Profiler.Frame frame)
+    {
+        if (frame == null) return;
+        if (frame.RootNodes == null) return;
+
+        // Calculate the total timeline duration (max end time across all nodes)
+        double totalDuration = frame.EndTime - frame.StartTime;
+        double startTime = frame.StartTime;
+
+        // Precompute the maximum depth for each thread's call stack
+        Dictionary<int, int> threadMaxDepths = new Dictionary<int, int>();
+        foreach (IGrouping<int, Profiler.ScopeNode> threadGroup in frame.RootNodes.GroupBy(node => node.ManagedThreadId))
+        {
+            int maxDepth = 0;
+            foreach (Profiler.ScopeNode rootNode in threadGroup)
+            {
+                maxDepth = Math.Max(maxDepth, GetMaxDepth(rootNode, 0));
+            }
+            threadMaxDepths[threadGroup.Key] = maxDepth;
+        }
+
+        // Start a child window to support scrolling
+        ImGui.BeginChild("FlameGraph", new Vector2(0, 64), ImGuiChildFlags.Border | ImGuiChildFlags.ResizeY, ImGuiWindowFlags.HorizontalScrollbar | ImGuiWindowFlags.AlwaysVerticalScrollbar);
+
+        ImDrawListPtr drawList = ImGui.GetWindowDrawList();
+        Vector2 windowPos = ImGui.GetCursorScreenPos();
+
+        // Sort nodes by ThreadID, ensuring main thread (Thread ID 1) is on top
+        IOrderedEnumerable<IGrouping<int, Profiler.ScopeNode>> threadGroups = frame.RootNodes.GroupBy(node => node.ManagedThreadId).OrderBy(g => g.Key);
+
+        // Initial Y position for drawing
+        float baseY = windowPos.Y;
+        bool alternate = false;
+        float contentWidth = ImGui.GetContentRegionAvail().X;
+
+        // Draw each thread's flame graph row by row
+        foreach (IGrouping<int, Profiler.ScopeNode> threadGroup in threadGroups)
+        {
+            int threadId = threadGroup.Key;
+
+            // Compute the base Y position for this thread
+            float threadBaseY = baseY;
+
+            // Calculate the maximum height for this thread's flame graph
+            float threadHeight = (threadMaxDepths[threadId] + 1) * (barHeight + barPadding);
+
+            // Draw the alternating background for each thread row
+            uint backgroundColor = ImGui.ColorConvertFloat4ToU32(alternate ? new Vector4(0.2f, 0.2f, 0.2f, 1f) : new Vector4(0.1f, 0.1f, 0.1f, 1f));
+            drawList.AddRectFilled(new Vector2(windowPos.X, threadBaseY), new Vector2(windowPos.X + contentWidth, threadBaseY + threadHeight), backgroundColor);
+
+            alternate = !alternate;
+
+            // Draw each root node in the group (one per thread)
+            foreach (Profiler.ScopeNode rootNode in threadGroup)
+            {
+                RenderNode(drawList, rootNode, startTime, totalDuration, windowPos.X, threadBaseY, 0, contentWidth, false);
+            }
+
+            // Move to the next thread's row (max depth * height per level)
+            baseY += (threadMaxDepths[threadId] + 1) * (barHeight + barPadding);
+        }
+
+        // Ensure that ImGui knows the size of the content.
+        ImGui.Dummy(new Vector2(contentWidth, baseY));
+
+        ImGui.EndChild();
+    }
+
+    private static void RenderNode(ImDrawListPtr drawList, Profiler.ScopeNode node, double startTime, double totalDuration, float startX, float baseY, int depth, float contentWidth, bool alternate)
+    {
+        if (node == null) return;
+
+        double nodeStartTime = node.StartTime - startTime;
+        double nodeEndTime = node.EndTime - startTime;
+        double nodeDuration = nodeEndTime - nodeStartTime;
+
+        // Calculate the position and width of the bar based on time
+        float xPos = (float)(startX + (nodeStartTime / totalDuration) * contentWidth);
+        float width = (float)((nodeDuration / totalDuration) * contentWidth);
+
+        // Calculate the Y position based on depth
+        float yPos = baseY + (depth * (barHeight + barPadding)) + (barPadding * 0.5f);
+
+        // Define the rectangle bounds for the node
+        Vector2 min = new Vector2(xPos, yPos);
+        Vector2 max = new Vector2(xPos + width, yPos + barHeight);
+
+        // Define color.
+        Vector4 barColor = alternate ? new Vector4(0.4f, 0.6f, 0.9f, 1f) : new Vector4(0.4f, 0.5f, 0.8f, 1f);
+        Vector4 textColor = new Vector4(1f, 1f, 1f, 1f);
+
+        if (depth != 0)
+        {
+            // Draw the bar for the node (colored based on thread depth)
+            drawList.AddRectFilled(min, max, ImGui.ColorConvertFloat4ToU32(barColor));
+
+            // Draw the label if it fits inside the bar
+            string label = $"{node.Label} ({node.ElapsedMilliseconds():0.000} ms)";
+            if (width > ImGui.CalcTextSize(label).X)
+            {
+                drawList.AddText(new Vector2(xPos + barPadding, yPos + barPadding), ImGui.ColorConvertFloat4ToU32(textColor), label);
+            }
+
+            // Add tooltip on hover
+            if (ImGui.IsMouseHoveringRect(min, max))
+            {
+                // Show tooltip when hovering over the node
+                ImGui.BeginTooltip();
+                ImGui.Text($"{node.Label}");
+                ImGui.Text($"{node.ElapsedMilliseconds():0.000} ms");
+                ImGui.Text($"{node.ManagedThreadId}");
+                ImGui.EndTooltip();
+            }
+        }
+        else
+        {
+            // Aka root node.
+            string label = $"{node.Label}";
+            drawList.AddText(new Vector2(startX + barPadding, yPos + barPadding), ImGui.ColorConvertFloat4ToU32(textColor), label);
+        }
+
+        // Draw each child node under this node
+        foreach (Profiler.ScopeNode child in node.Children)
+        {
+            alternate = !alternate;
+            RenderNode(drawList, child, startTime, totalDuration, startX, baseY, depth + 1, contentWidth, alternate);
+        }
+    }
+
+    // Recursive function to calculate the maximum depth of the node tree
+    private static int GetMaxDepth(Profiler.ScopeNode node, int currentDepth)
+    {
+        if (node.Children == null || node.Children.Count == 0)
+        {
+            return currentDepth;
+        }
+
+        int maxDepth = currentDepth;
+        foreach (Profiler.ScopeNode child in node.Children)
+        {
+            maxDepth = Math.Max(maxDepth, GetMaxDepth(child, currentDepth + 1));
+        }
+        return maxDepth;
+    }
+}

Nerfed.Runtime/Resource/Resource.cs

@@ -1,9 +1,31 @@
+using System;
 namespace Nerfed.Runtime;
 
+public enum ResourceState
+{
+    Unloaded,
+    Queued,
+    Loading,
+    Loaded,
+    Failed
+}
+
 public abstract class Resource
 {
+    public Guid Id { get; internal set; }
     public string Path { get; internal set; }
     
+    /// <summary>
+    /// Natively tracks if the resource is currently in RAM/VRAM.
+    /// </summary>
+    public ResourceState State { get; internal set; } = ResourceState.Unloaded;
+
+    /// <summary>
+    /// Tracks how many entities or systems currently need this loaded.
+    /// When it hits 0, the ResourceManager handles unloading natively.
+    /// </summary>
+    public int ReferenceCount { get; internal set; } = 0;
+
     internal abstract void Load(Stream stream);
     internal abstract void Unload();
 }

Nerfed.Runtime/Resource/ResourceComponents.cs

@@ -0,0 +1,19 @@
+namespace Nerfed.Runtime;
+
+/// <summary>
+/// Attach this component to an entity mapped to raw source-path strings.
+/// Useful for testing, hardcoded assets, or before full editor-guided GUID injection.
+/// </summary>
+public readonly record struct AssetReferenceComponent(Guid AssetId);
+
+/// <summary>
+/// A strongly-typed version of an asset reference, preventing the user from accidentally
+/// assigning a Shader GUID to a Texture component in the Editor.
+/// </summary>
+public readonly record struct TypedAssetReference<TRes>(Guid AssetId) where TRes : Resource;
+
+/// <summary>
+/// Added to an entity by the AssetStreamingSystem when the physical resource is fully 
+/// loaded in memory and ready to be used by the renderer or physics engine.
+/// </summary>
+public struct AssetLoadedTag { }

Nerfed.Runtime/Resource/ResourceManager.cs

@@ -1,43 +1,209 @@
+using System;
+using System.Collections.Concurrent;
+using System.Collections.Generic;
+using System.IO;
+using System.Threading;
+
 namespace Nerfed.Runtime;
 
+/// <summary>
+/// A highly scalable, multithreaded resource manager that handles asynchronous asset 
+/// loading and automatic reference-counted memory management.
+/// </summary>
 public static class ResourceManager
 {
-    private const string rootName = "Resources";
+    private const string RootName = "Resources";
-    private static readonly Dictionary<string, Resource> loadedResources = new Dictionary<string, Resource>();
 
-    public static T Load<T>(string resourcePath) where T : Resource
+    // Track resources by their Guid ID instead of simple strings.
+    private static readonly ConcurrentDictionary<Guid, Resource> _resourceCache = new();
+
+    // Mapping a string path to its runtime Guid identifier
+    private static readonly ConcurrentDictionary<string, Guid> _pathToGuid = new();
+
+    // Queues for background processing
+    private static readonly ConcurrentQueue<Resource> _loadQueue = new();
+
+    // Loader threads
+    private static readonly Thread _loaderThread;
+    private static bool _isRunning = true;
+
+    // A registry of how to create concrete Resource instances from a generic type without massive switch statements.
+    private static readonly Dictionary<Type, Func<Resource>> _resourceFactories = new()
     {
-        if (loadedResources.TryGetValue(resourcePath, out Resource resource))
+        { typeof(Shader), () => new Shader() }
+    };
+
+    static ResourceManager()
     {
+        _loaderThread = new Thread(LoaderWorkerLoop)
+        {
+            Name = "Nerfed Asset Loader",
+            IsBackground = true,
+            Priority = ThreadPriority.BelowNormal // Keeps CPU time focused on the main game loop
+        };
+        _loaderThread.Start();
+    }
+
+    /// <summary>
+    /// Synchronously shuts down the loader thread when the engine closes.
+    /// </summary>
+    public static void Shutdown()
+    {
+        _isRunning = false;
+        _loaderThread.Join();
+    }
+
+    /// <summary>
+    /// Registers a new resource type factory so the manager knows how to instantiate it.
+    /// Example: RegisterResourceType<Texture>(() => new Texture());
+    /// </summary>
+    public static void RegisterResourceType<T>(Func<T> factory) where T : Resource
+    {
+        _resourceFactories[typeof(T)] = factory;
+    }
+
+    /// <summary>
+    /// Gets the Guid associated with a specific asset path, making an initial id pass if required.
+    /// In a fully baked engine, the Guid is known at compile time or baked in the map data.
+    /// </summary>
+    public static Guid GetId(string resourcePath)
+    {
+        return _pathToGuid.GetOrAdd(resourcePath, _ => Guid.NewGuid());
+    }
+
+    /// <summary>
+    /// Begins an asynchronous load for a resource by its Guid.
+    /// In ECS systems, Entities should strictly prefer this overload over the string one.
+    /// </summary>
+    public static T Retain<T>(Guid id, string expectedPath) where T : Resource
+    {
+        var resource = _resourceCache.GetOrAdd(id, (assetId) =>
+        {
+            if (!_resourceFactories.TryGetValue(typeof(T), out var factory))
+            {
+                throw new Exception($"Failed to create resource. No factory registered for {typeof(T).Name}");
+            }
+
+            var newResource = factory();
+            newResource.Id = assetId;
+            // The path is still required so the background thread knows which file to open from disk.
+            newResource.Path = expectedPath; 
+            newResource.State = ResourceState.Unloaded;
+            
+            return newResource;
+        });
+
+        lock (resource)
+        {
+            resource.ReferenceCount++;
+            
+            if (resource.State == ResourceState.Unloaded)
+            {
+                resource.State = ResourceState.Queued;
+                _loadQueue.Enqueue(resource);
+            }
+        }
+
         return (T)resource;
     }
 
-        if (typeof(T) == typeof(Shader))
+    /// <summary>
+    /// Begins an asynchronous load utilizing the string path to find the matching Guid. 
+    /// This should generally be avoided in tight ECS loops.
+    /// </summary>
+    public static T Retain<T>(string resourcePath) where T : Resource
     {
-            resource = new Shader();
+        Guid id = GetId(resourcePath);
+        return Retain<T>(id, resourcePath);
+    }
+
+    /// <summary>
+    /// Gets the current loading state of a resource by its Guid without altering its reference count.
+    /// </summary>
+    public static ResourceState GetState(Guid id)
+    {
+        if (_resourceCache.TryGetValue(id, out var resource))
+        {
+            return resource.State;
+        }
+        return ResourceState.Unloaded;
+    }
+
+    /// <summary>
+    /// Decrements the reference count of a resource by its Guid.
+    /// </summary>
+    public static void Release(Guid id)
+    {
+        if (_resourceCache.TryGetValue(id, out var resource))
+        {
+            Release(resource);
+        }
+    }
+
+    /// <summary>
+    /// Decrements the reference count of a resource. 
+    /// If the count reaches 0, the asset is automatically unloaded from memory.
+    /// </summary>
+    public static void Release(Resource resource)
+    {
+        if (resource == null) return;
+
+        lock (resource)
+        {
+            resource.ReferenceCount--;
+
+            if (resource.ReferenceCount <= 0)
+            {
+                // Fully unused! We should unload it safely.
+                if (resource.State == ResourceState.Loaded)
+                {
+                    resource.Unload();
+                }
+
+                resource.State = ResourceState.Unloaded;
+                _resourceCache.TryRemove(resource.Id, out _);
+            }
+        }
+    }
+
+    /// <summary>
+    /// Background thread loop that pulls from the queue and does the slow file I/O operations.
+    /// </summary>
+    private static void LoaderWorkerLoop()
+    {
+        while (_isRunning)
+        {
+            if (_loadQueue.TryDequeue(out var resource))
+            {
+                // Safety check: Was the resource released before we even got around to loading it?
+                if (resource.ReferenceCount <= 0)
+                {
+                    resource.State = ResourceState.Unloaded;
+                    continue;
+                }
+
+                try
+                {
+                    resource.State = ResourceState.Loading;
+                    string fullPath = Path.Combine(AppContext.BaseDirectory, RootName, resource.Id.ToString()) + ".bin";
+                    
+                    // Do the slow synchronous disk read
+                    using var stream = StorageContainer.OpenStream(fullPath);
+                    resource.Load(stream);
+
+                    resource.State = ResourceState.Loaded;
+                }
+                catch (Exception e)
+                {
+                    Log.Error($"Failed to background load asset '{resource.Path}': {e.Message}");
+                    resource.State = ResourceState.Failed;
+                }
             }
             else
             {
-            throw new Exception("Failed to create resource");
+                // Sleep cleanly if queue is empty to avoid burning total CPU usage on an infinite while-loop
-        }
+                Thread.Sleep(10);
-
+            }
-        Assert.Always(resource != null);
+        }
-        resource.Path = resourcePath;
-        resource.Load(StorageContainer.OpenStream(Path.Combine(AppContext.BaseDirectory, rootName, resourcePath) + ".bin"));
-
-        loadedResources.Add(resourcePath, resource);
-        return (T)resource;
-    }
-
-    public static void Unload(Resource resource)
-    {
-        if (!loadedResources.ContainsKey(resource.Path))
-        {
-            return;
-        }
-
-        resource.Unload();
-        resource.Path = string.Empty;
-        loadedResources.Remove(resource.Path);
     }
 }

Nerfed.Runtime/Resource/SampleMeshVisualComponent.cs

@@ -0,0 +1,19 @@
+namespace Nerfed.Runtime.Resources;
+
+/// <summary>
+/// A sample component demonstrating how to use strongly-typed asset references
+/// in a realistic scenario where an entity requires multiple distinct resources.
+/// </summary>
+public struct SampleMeshVisualComponent
+{
+    // The user safely assigns a Mesh GUID in the Editor inspector.
+    public TypedAssetReference<Shader> VertexShader;
+
+    // The user safely assigns a Material GUID in the Editor inspector.
+    public TypedAssetReference<Shader> FragmentShader;
+
+    public SampleMeshVisualComponent(Guid vertexId, Guid fragId) {
+        VertexShader = new TypedAssetReference<Shader>(vertexId);
+        FragmentShader = new TypedAssetReference<Shader>(fragId);
+    }
+}

Nerfed.Runtime/Resource/SampleRenderSystem.cs

@@ -0,0 +1,53 @@
+using MoonTools.ECS;
+using Nerfed.Runtime.Scene.Streaming;
+using System;
+
+namespace Nerfed.Runtime.Resources;
+
+/// <summary>
+/// A typical rendering preparation system that natively resolves and requests
+/// asynchronous background loading for its own required assets, removing the 
+/// need for a monolithic generic AssetStreaming manager.
+/// </summary>
+public class SampleRenderSystem : MoonTools.ECS.System
+{
+    private readonly Filter _meshVisualsFilter;
+
+    public SampleRenderSystem(World world) : base(world) {
+        _meshVisualsFilter = FilterBuilder
+            .Include<SampleMeshVisualComponent>()
+            // Always ignore chunk entities technically "unloading" from RAM
+            .Exclude<ChunkUnloadPendingTag>()
+            .Build();
+    }
+
+    public override void Update(TimeSpan delta) {
+        foreach(Entity entity in _meshVisualsFilter.Entities) {
+            SampleMeshVisualComponent visualComp = Get<SampleMeshVisualComponent>(entity);
+
+            // 1. Resolve State
+            ResourceState vertState = ResourceManager.GetState(visualComp.VertexShader.AssetId);
+            ResourceState fragState = ResourceManager.GetState(visualComp.FragmentShader.AssetId);
+
+            // 2. Asynchronously request assets if they don't exist in memory yet
+            if(vertState == ResourceState.Unloaded) {
+                ResourceManager.Retain<Shader>(visualComp.VertexShader.AssetId, "Unknown/Path");
+            }
+            if(fragState == ResourceState.Unloaded) {
+                ResourceManager.Retain<Shader>(visualComp.FragmentShader.AssetId, "Unknown/Path");
+            }
+
+            // 3. Prevent rendering logic unless ALL strictly required assets are fully mapped
+            bool isReadyToDraw = vertState == ResourceState.Loaded && fragState == ResourceState.Loaded;
+
+            if(isReadyToDraw) {
+                // At this exact point, you can safely assume:
+                // 1) The background loading threads are 100% finished processing these shaders.
+                // 2) The GraphicsDevice can safely extract the native handle.
+
+                // e.g. GraphicsDevice.BindShader(visualComp.VertexShader.AssetId);
+                // e.g. GraphicsDevice.DrawPolygons(...);
+            }
+        }
+    }
+}

Nerfed.Runtime/Scene/ISceneSerializer.cs

@@ -0,0 +1,13 @@
+namespace Nerfed.Runtime.Scene;
+
+/// <summary>
+/// Abstraction over a concrete scene format (JSON, binary, …).
+/// Implementations read and write <see cref="SceneData"/> to a <see cref="Stream"/>,
+/// making it straightforward to add a compact binary format later without
+/// changing any of the surrounding scene infrastructure.
+/// </summary>
+public interface ISceneSerializer
+{
+    void Serialize(SceneData scene, Stream stream);
+    SceneData Deserialize(Stream stream);
+}

Nerfed.Runtime/Scene/JsonSceneSerializer.cs

@@ -0,0 +1,189 @@
+using System.Numerics;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Nerfed.Runtime.Scene;
+
+/// <summary>
+/// Human-readable JSON scene serializer.
+///
+/// Example output:
+/// <code>
+/// {
+///   "version": 1,
+///   "name": "MyScene",
+///   "entities": [
+///     {
+///       "id": "a1b2c3d4-...",
+///       "tag": "Player",
+///       "parentId": null,
+///       "components": [
+///         {
+///           "type": "Nerfed.Runtime.Components.LocalTransform",
+///           "data": {
+///             "position": { "x": 0.0, "y": 0.0, "z": 0.0 },
+///             "rotation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 },
+///             "scale":    { "x": 1.0, "y": 1.0, "z": 1.0 }
+///           }
+///         }
+///       ]
+///     }
+///   ],
+///   "relations": [
+///     {
+///       "type": "Nerfed.Runtime.Components.OwnerRelation",
+///       "entityA": "a1b2c3d4-...",
+///       "entityB": "e5f6a7b8-...",
+///       "data": {}
+///     }
+///   ]
+/// }
+/// </code>
+/// </summary>
+public sealed class JsonSceneSerializer : ISceneSerializer
+{
+    private static readonly JsonSerializerOptions Options = new() {
+        WriteIndented = true,
+        Converters =
+        {
+            new Vector3JsonConverter(),
+            new QuaternionJsonConverter(),
+            new SceneComponentDataJsonConverter(),
+            new SceneRelationDataJsonConverter(),
+        },
+    };
+
+    public void Serialize(SceneData scene, Stream stream) {
+        JsonSerializer.Serialize(stream, scene, Options);
+    }
+
+    public SceneData Deserialize(Stream stream) {
+        return JsonSerializer.Deserialize<SceneData>(stream, Options)
+            ?? throw new InvalidOperationException("Failed to deserialize scene: root element was null.");
+    }
+
+    // -------------------------------------------------------------------------
+    // Converters
+    // -------------------------------------------------------------------------
+
+    private sealed class Vector3JsonConverter : JsonConverter<Vector3>
+    {
+        public override Vector3 Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) {
+            float x = 0f, y = 0f, z = 0f;
+            reader.Read(); // StartObject
+            while(reader.Read() && reader.TokenType != JsonTokenType.EndObject) {
+                string name = reader.GetString()!;
+                reader.Read();
+                switch(name) {
+                    case "x": x = reader.GetSingle(); break;
+                    case "y": y = reader.GetSingle(); break;
+                    case "z": z = reader.GetSingle(); break;
+                }
+            }
+            return new Vector3(x, y, z);
+        }
+
+        public override void Write(Utf8JsonWriter writer, Vector3 value, JsonSerializerOptions options) {
+            writer.WriteStartObject();
+            writer.WriteNumber("x", value.X);
+            writer.WriteNumber("y", value.Y);
+            writer.WriteNumber("z", value.Z);
+            writer.WriteEndObject();
+        }
+    }
+
+    private sealed class QuaternionJsonConverter : JsonConverter<Quaternion>
+    {
+        public override Quaternion Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) {
+            float x = 0f, y = 0f, z = 0f, w = 1f;
+            reader.Read(); // StartObject
+            while(reader.Read() && reader.TokenType != JsonTokenType.EndObject) {
+                string name = reader.GetString()!;
+                reader.Read();
+                switch(name) {
+                    case "x": x = reader.GetSingle(); break;
+                    case "y": y = reader.GetSingle(); break;
+                    case "z": z = reader.GetSingle(); break;
+                    case "w": w = reader.GetSingle(); break;
+                }
+            }
+            return new Quaternion(x, y, z, w);
+        }
+
+        public override void Write(Utf8JsonWriter writer, Quaternion value, JsonSerializerOptions options) {
+            writer.WriteStartObject();
+            writer.WriteNumber("x", value.X);
+            writer.WriteNumber("y", value.Y);
+            writer.WriteNumber("z", value.Z);
+            writer.WriteNumber("w", value.W);
+            writer.WriteEndObject();
+        }
+    }
+
+    /// <summary>
+    /// Buffers the full JSON object, resolves the CLR component type from the "type" field,
+    /// then deserializes "data" using that concrete type.
+    /// </summary>
+    private sealed class SceneComponentDataJsonConverter : JsonConverter<SceneComponentData>
+    {
+        public override SceneComponentData Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) {
+            using JsonDocument doc = JsonDocument.ParseValue(ref reader);
+            JsonElement root = doc.RootElement;
+
+            string typeName = root.GetProperty("type").GetString()
+                ?? throw new JsonException("Missing or null 'type' field in component data.");
+
+            Type componentType = SceneManager.GetComponentType(typeName)
+                ?? throw new JsonException($"Unknown component type '{typeName}'. Ensure the struct is marked with [SceneComponent].");
+
+            string rawData = root.GetProperty("data").GetRawText();
+            ValueType value = (ValueType)JsonSerializer.Deserialize(rawData, componentType, options)!;
+
+            return new SceneComponentData { Type = typeName, Value = value };
+        }
+
+        public override void Write(Utf8JsonWriter writer, SceneComponentData value, JsonSerializerOptions options) {
+            writer.WriteStartObject();
+            writer.WriteString("type", value.Type);
+            writer.WritePropertyName("data");
+            JsonSerializer.Serialize(writer, value.Value, value.Value.GetType(), options);
+            writer.WriteEndObject();
+        }
+    }
+
+    /// <summary>
+    /// Same pattern as <see cref="SceneComponentDataJsonConverter"/> but for relation data.
+    /// Resolves the type via <see cref="SceneManager.GetRelationType"/>.
+    /// </summary>
+    private sealed class SceneRelationDataJsonConverter : JsonConverter<SceneRelationData>
+    {
+        public override SceneRelationData Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) {
+            using JsonDocument doc = JsonDocument.ParseValue(ref reader);
+            JsonElement root = doc.RootElement;
+
+            string typeName = root.GetProperty("type").GetString()
+                ?? throw new JsonException("Missing or null 'type' field in relation data.");
+
+            Type relationType = SceneManager.GetRelationType(typeName)
+                ?? throw new JsonException($"Unknown relation type '{typeName}'. Ensure the struct is marked with [SceneRelation].");
+
+            Guid entityA = root.GetProperty("entityA").GetGuid();
+            Guid entityB = root.GetProperty("entityB").GetGuid();
+
+            string rawData = root.GetProperty("data").GetRawText();
+            ValueType value = (ValueType)JsonSerializer.Deserialize(rawData, relationType, options)!;
+
+            return new SceneRelationData { Type = typeName, EntityA = entityA, EntityB = entityB, Value = value };
+        }
+
+        public override void Write(Utf8JsonWriter writer, SceneRelationData value, JsonSerializerOptions options) {
+            writer.WriteStartObject();
+            writer.WriteString("type", value.Type);
+            writer.WriteString("entityA", value.EntityA);
+            writer.WriteString("entityB", value.EntityB);
+            writer.WritePropertyName("data");
+            JsonSerializer.Serialize(writer, value.Value, value.Value.GetType(), options);
+            writer.WriteEndObject();
+        }
+    }
+}

Nerfed.Runtime/Scene/SceneComponentAttribute.cs

@@ -0,0 +1,8 @@
+namespace Nerfed.Runtime.Scene;
+
+/// <summary>
+/// Marks an unmanaged struct as a serializable scene component.
+/// Only types with this attribute will be saved/loaded by the scene system.
+/// </summary>
+[AttributeUsage(AttributeTargets.Struct, Inherited = false)]
+public sealed class SceneComponentAttribute : Attribute { }

Nerfed.Runtime/Scene/SceneData.cs

@@ -0,0 +1,65 @@
+namespace Nerfed.Runtime.Scene;
+
+/// <summary>
+/// Root data model for a scene. A scene and a prefab are the same thing —
+/// there is no distinction between the two, mirroring Godot's design.
+/// </summary>
+public sealed class SceneData
+{
+    /// <summary>Incremented when the file format changes in a breaking way.</summary>
+    public int Version { get; set; } = SceneData.CurrentVersion;
+    public string Name { get; set; } = string.Empty;
+    public List<SceneEntityData> Entities { get; set; } = new();
+    /// <summary>All user-defined relations between entities in this scene.</summary>
+    public List<SceneRelationData> Relations { get; set; } = new();
+
+    public const int CurrentVersion = 1;
+}
+
+/// <summary>
+/// Serialized representation of a single entity.
+/// The <see cref="Id"/> is a scene-local identifier that only exists in the
+/// serialized data and is used to reconstruct parent–child and relation references.
+/// It is never stored as a component on a live entity.
+/// An entity is included if it owns at least one <see cref="SceneComponentAttribute"/> component
+/// OR participates in at least one <see cref="SceneRelationAttribute"/> relation.
+/// </summary>
+public sealed class SceneEntityData
+{
+    public Guid Id { get; set; } = Guid.NewGuid();
+    public string Tag { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Scene-local <see cref="Id"/> of this entity's <see cref="Components.ChildParentRelation"/>
+    /// parent, or <c>null</c> if this is a root entity.
+    /// </summary>
+    public Guid? ParentId { get; set; }
+
+    public List<SceneComponentData> Components { get; set; } = new();
+}
+
+/// <summary>
+/// Serialized representation of a single component value on an entity.
+/// <see cref="Type"/> is the fully-qualified CLR type name used to resolve the component on load.
+/// <see cref="Value"/> is the boxed runtime value; each <see cref="ISceneSerializer"/> is
+/// responsible for converting it to/from its wire format.
+/// </summary>
+public sealed class SceneComponentData
+{
+    public string Type { get; set; } = string.Empty;
+    public ValueType Value { get; set; } = default!;
+}
+
+/// <summary>
+/// Serialized representation of a relation between two entities.
+/// <see cref="EntityA"/> and <see cref="EntityB"/> reference scene-local <see cref="SceneEntityData.Id"/> values.
+/// <see cref="Type"/> identifies the relation kind (must be marked with <see cref="SceneRelationAttribute"/>).
+/// <see cref="Value"/> holds the relation data payload (may be an empty struct).
+/// </summary>
+public sealed class SceneRelationData
+{
+    public string Type { get; set; } = string.Empty;
+    public Guid EntityA { get; set; }
+    public Guid EntityB { get; set; }
+    public ValueType Value { get; set; } = default!;
+}

Nerfed.Runtime/Scene/SceneManager.cs

@@ -0,0 +1,345 @@
+using System.Reflection;
+using MoonTools.ECS;
+using Nerfed.Runtime.Components;
+
+namespace Nerfed.Runtime.Scene;
+
+/// <summary>
+/// Central hub for scene serialization and deserialization.
+///
+/// On first use the static constructor scans all loaded assemblies for:
+///   • Structs annotated with <see cref="SceneComponentAttribute"/>  — serialized as per-entity component data.
+///   • Structs annotated with <see cref="SceneRelationAttribute"/>   — serialized as cross-entity relation data.
+///
+/// The <see cref="Components.ChildParentRelation"/> hierarchy is handled separately via
+/// <see cref="SceneEntityData.ParentId"/> and does NOT need a <see cref="SceneRelationAttribute"/>.
+///
+/// Usage:
+/// <code>
+/// var serializer = new JsonSceneSerializer();
+/// SceneManager.Save(world, "Assets/level1.scene", serializer, "Level 1");
+/// SceneManager.Load(world, "Assets/level1.scene", serializer);
+/// </code>
+/// </summary>
+public static class SceneManager
+{
+    // Full CLR type name  →  Type
+    private static readonly Dictionary<string, Type> ComponentRegistry = new();
+    private static readonly Dictionary<string, Type> RelationRegistry = new();
+
+    // Reflection cache so we only build the delegates once per type.
+    private static readonly Dictionary<Type, Func<World, Entity, bool>> HasComponentCache = new();
+    private static readonly Dictionary<Type, Func<World, Entity, ValueType>> GetComponentCache = new();
+    private static readonly Dictionary<Type, Action<World, Entity, ValueType>> SetComponentCache = new();
+    private static readonly Dictionary<Type, Func<World, Entity, bool>> HasOutRelationCache = new();
+    private static readonly Dictionary<Type, Func<World, Entity, Entity[]>> OutRelationsCache = new();
+    private static readonly Dictionary<Type, Func<World, Entity, Entity, ValueType>> GetRelationDataCache = new();
+    private static readonly Dictionary<Type, Action<World, Entity, Entity, ValueType>> RelateCache = new();
+
+    static SceneManager() {
+        foreach(Assembly assembly in AppDomain.CurrentDomain.GetAssemblies()) {
+            Type[] types;
+            try { types = assembly.GetTypes(); } catch(ReflectionTypeLoadException ex) { types = ex.Types.Where(t => t is not null).ToArray()!; }
+
+            foreach(Type type in types) {
+                if(type.FullName is null) continue;
+
+                if(type.GetCustomAttribute<SceneComponentAttribute>() is not null)
+                    ComponentRegistry[type.FullName] = type;
+
+                if(type.GetCustomAttribute<SceneRelationAttribute>() is not null)
+                    RelationRegistry[type.FullName] = type;
+            }
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Public registry accessors
+    // -------------------------------------------------------------------------
+
+    public static Type? GetComponentType(string fullName) {
+        ComponentRegistry.TryGetValue(fullName, out Type? type);
+        return type;
+    }
+
+    public static Type? GetRelationType(string fullName) {
+        RelationRegistry.TryGetValue(fullName, out Type? type);
+        return type;
+    }
+
+    public static IReadOnlyDictionary<string, Type> RegisteredComponentTypes => ComponentRegistry;
+    public static IReadOnlyDictionary<string, Type> RegisteredRelationTypes => RelationRegistry;
+
+    // -------------------------------------------------------------------------
+    // High-level Save / Load
+    // -------------------------------------------------------------------------
+
+    public static void Save(World world, string path, ISceneSerializer serializer, string sceneName = "") {
+        SceneData scene = Extract(world, sceneName);
+        string? directory = Path.GetDirectoryName(path);
+        if(!string.IsNullOrEmpty(directory))
+            Directory.CreateDirectory(directory);
+        using FileStream stream = File.Open(path, FileMode.Create, FileAccess.Write);
+        serializer.Serialize(scene, stream);
+    }
+
+    public static Dictionary<Guid, Entity> Load(World world, string path, ISceneSerializer serializer) {
+        using FileStream stream = File.Open(path, FileMode.Open, FileAccess.Read);
+        SceneData scene = serializer.Deserialize(stream);
+        return Instantiate(world, scene);
+    }
+
+    // -------------------------------------------------------------------------
+    // Extract  (world → SceneData)
+    // -------------------------------------------------------------------------
+
+    public static SceneData Extract(World world, string name = "") {
+        SceneData scene = new() { Name = name };
+
+        // ── 1. Collect entities ──────────────────────────────────────────────
+        // Include an entity if it has at least one scene component OR if it
+        // appears as an endpoint of at least one scene relation.  This ensures
+        // pure grouping nodes and relation-only entities are not dropped.
+
+        Dictionary<uint, Guid> entityToGuid = new();
+
+        void EnsureEntity(Entity e) {
+            if(!entityToGuid.ContainsKey(e.ID))
+                entityToGuid[e.ID] = Guid.NewGuid();
+        }
+
+        foreach(Entity entity in world.GetAllEntities()) {
+            if(HasAnySceneComponent(world, entity))
+                EnsureEntity(entity);
+        }
+
+        // Walk all registered relation types and pull in both endpoints.
+        foreach(Type relationType in RelationRegistry.Values) {
+            foreach((Entity a, Entity b) in WorldAllRelations(world, relationType)) {
+                EnsureEntity(a);
+                EnsureEntity(b);
+            }
+        }
+
+        // Also include entities that are part of the ChildParentRelation hierarchy
+        // even if they carry no scene components and no user-defined relations.
+        foreach((Entity child, Entity parent) in world.Relations<ChildParentRelation>()) {
+            EnsureEntity(child);
+            EnsureEntity(parent);
+        }
+
+        // ── 2. Build entity records (parents must be known before children so
+        //       we sort parents-before-children for readable output) ───────────
+        List<SceneEntityData> ordered = BuildSortedEntityList(world, entityToGuid);
+        scene.Entities.AddRange(ordered);
+
+        // ── 3. Build relation records ────────────────────────────────────────
+        foreach((string typeName, Type relationType) in RelationRegistry) {
+            foreach((Entity a, Entity b) in WorldAllRelations(world, relationType)) {
+                if(!entityToGuid.TryGetValue(a.ID, out Guid guidA) ||
+                    !entityToGuid.TryGetValue(b.ID, out Guid guidB))
+                    continue;
+
+                ValueType payload = WorldGetRelationData(world, a, b, relationType);
+                scene.Relations.Add(new SceneRelationData {
+                    Type = typeName,
+                    EntityA = guidA,
+                    EntityB = guidB,
+                    Value = payload,
+                });
+            }
+        }
+
+        return scene;
+    }
+
+    // -------------------------------------------------------------------------
+    // Instantiate  (SceneData → world)
+    // -------------------------------------------------------------------------
+
+    public static Dictionary<Guid, Entity> Instantiate(World world, SceneData scene) {
+        Dictionary<Guid, Entity> guidToEntity = new(scene.Entities.Count);
+
+        // Pass 1 – create all entities.
+        foreach(SceneEntityData entityData in scene.Entities) {
+            Entity entity = world.CreateEntity(entityData.Tag);
+            guidToEntity[entityData.Id] = entity;
+        }
+
+        // Pass 2 – set components and wire up the ChildParentRelation hierarchy.
+        foreach(SceneEntityData entityData in scene.Entities) {
+            Entity entity = guidToEntity[entityData.Id];
+
+            foreach(SceneComponentData componentData in entityData.Components)
+                WorldSetComponent(world, entity, componentData.Type, componentData.Value);
+
+            if(entityData.ParentId is Guid parentGuid && guidToEntity.TryGetValue(parentGuid, out Entity parent)) {
+                world.Set(entity, new Child());
+                world.Relate(entity, parent, new ChildParentRelation());
+            } else {
+                world.Set(entity, new Root());
+            }
+        }
+
+        // Pass 3 – restore all user-defined relations.
+        foreach(SceneRelationData relationData in scene.Relations) {
+            if(!guidToEntity.TryGetValue(relationData.EntityA, out Entity entityA) ||
+                !guidToEntity.TryGetValue(relationData.EntityB, out Entity entityB))
+                continue;
+
+            WorldRelate(world, entityA, entityB, relationData.Type, relationData.Value);
+        }
+
+        return guidToEntity;
+    }
+
+    // -------------------------------------------------------------------------
+    // Helpers – entity ordering
+    // -------------------------------------------------------------------------
+
+    // Returns entities sorted so that a parent always appears before its children,
+    // making the JSON file human-readable and easier to diff.
+    private static List<SceneEntityData> BuildSortedEntityList(
+        World world,
+        Dictionary<uint, Guid> entityToGuid) {
+        // Build per-entity data (unsorted first).
+        Dictionary<Guid, SceneEntityData> byGuid = new(entityToGuid.Count);
+
+        foreach((uint entityId, Guid guid) in entityToGuid) {
+            Entity entity = new(entityId);
+
+            Guid? parentId = null;
+            if(world.HasOutRelation<ChildParentRelation>(entity)) {
+                // Iterate all out-relations — an entity may have multiple parents
+                // in theory, but ChildParentRelation is designed as singleton.
+                // We capture the first valid one here.
+                foreach(Entity parent in world.OutRelations<ChildParentRelation>(entity)) {
+                    if(entityToGuid.TryGetValue(parent.ID, out Guid parentGuid)) {
+                        parentId = parentGuid;
+                        break;
+                    }
+                }
+            }
+
+            List<SceneComponentData> components = new();
+            foreach((string typeName, Type componentType) in ComponentRegistry) {
+                if(!WorldHasComponent(world, entity, componentType)) continue;
+                ValueType value = WorldGetComponent(world, entity, componentType);
+                components.Add(new SceneComponentData { Type = typeName, Value = value });
+            }
+
+            byGuid[guid] = new SceneEntityData {
+                Id = guid,
+                Tag = world.GetTag(entity),
+                ParentId = parentId,
+                Components = components,
+            };
+        }
+
+        // Topological sort: parents before children.
+        List<SceneEntityData> sorted = new(byGuid.Count);
+        HashSet<Guid> visited = new(byGuid.Count);
+
+        void Visit(Guid id) {
+            if(!visited.Add(id)) return;
+            SceneEntityData data = byGuid[id];
+            if(data.ParentId is Guid pid && byGuid.ContainsKey(pid))
+                Visit(pid);
+            sorted.Add(data);
+        }
+
+        foreach(Guid id in byGuid.Keys)
+            Visit(id);
+
+        return sorted;
+    }
+
+    // -------------------------------------------------------------------------
+    // Reflection helpers – components
+    // -------------------------------------------------------------------------
+
+    private static bool HasAnySceneComponent(World world, Entity entity) {
+        foreach(Type componentType in ComponentRegistry.Values) {
+            if(WorldHasComponent(world, entity, componentType)) return true;
+        }
+        return false;
+    }
+
+    private static bool WorldHasComponent(World world, Entity entity, Type componentType) {
+        if(!HasComponentCache.TryGetValue(componentType, out Func<World, Entity, bool>? fn)) {
+            MethodInfo method = FindGenericMethod(nameof(World.Has)).MakeGenericMethod(componentType);
+            fn = (w, e) => (bool)method.Invoke(w, new object[] { e })!;
+            HasComponentCache[componentType] = fn;
+        }
+        return fn(world, entity);
+    }
+
+    private static ValueType WorldGetComponent(World world, Entity entity, Type componentType) {
+        if(!GetComponentCache.TryGetValue(componentType, out Func<World, Entity, ValueType>? fn)) {
+            MethodInfo method = FindGenericMethod(nameof(World.Get)).MakeGenericMethod(componentType);
+            fn = (w, e) => (ValueType)method.Invoke(w, new object[] { e })!;
+            GetComponentCache[componentType] = fn;
+        }
+        return fn(world, entity);
+    }
+
+    private static void WorldSetComponent(World world, Entity entity, string typeName, ValueType value) {
+        if(!ComponentRegistry.TryGetValue(typeName, out Type? componentType)) return;
+
+        if(!SetComponentCache.TryGetValue(componentType, out Action<World, Entity, ValueType>? fn)) {
+            MethodInfo method = FindGenericMethod(nameof(World.Set)).MakeGenericMethod(componentType);
+            fn = (w, e, v) => method.Invoke(w, new object[] { e, v });
+            SetComponentCache[componentType] = fn;
+        }
+        fn(world, entity, value);
+    }
+
+    // -------------------------------------------------------------------------
+    // Reflection helpers – relations
+    // -------------------------------------------------------------------------
+
+    private static IEnumerable<(Entity, Entity)> WorldAllRelations(World world, Type relationType) {
+        // World.Relations<T>() returns ReverseSpanEnumerator<(Entity,Entity)>.
+        // We materialise it into a list so the caller can iterate freely.
+        MethodInfo method = FindGenericMethod(nameof(World.Relations)).MakeGenericMethod(relationType);
+        // Returns a boxed ReverseSpanEnumerator; invoke MoveNext/Current via dynamic.
+        // Easiest: call via dynamic to avoid unsafe span-from-box issues.
+        dynamic enumerator = method.Invoke(world, null)!;
+        List<(Entity, Entity)> results = new();
+        while(enumerator.MoveNext())
+            results.Add(enumerator.Current);
+        return results;
+    }
+
+    private static ValueType WorldGetRelationData(World world, Entity a, Entity b, Type relationType) {
+        if(!GetRelationDataCache.TryGetValue(relationType, out Func<World, Entity, Entity, ValueType>? fn)) {
+            MethodInfo method = FindGenericMethod(nameof(World.GetRelationData)).MakeGenericMethod(relationType);
+            fn = (w, ea, eb) => (ValueType)method.Invoke(w, new object[] { ea, eb })!;
+            GetRelationDataCache[relationType] = fn;
+        }
+        return fn(world, a, b);
+    }
+
+    private static void WorldRelate(World world, Entity a, Entity b, string typeName, ValueType value) {
+        if(!RelationRegistry.TryGetValue(typeName, out Type? relationType)) return;
+
+        if(!RelateCache.TryGetValue(relationType, out Action<World, Entity, Entity, ValueType>? fn)) {
+            MethodInfo method = FindGenericMethod(nameof(World.Relate)).MakeGenericMethod(relationType);
+            fn = (w, ea, eb, v) => method.Invoke(w, new object[] { ea, eb, v });
+            RelateCache[relationType] = fn;
+        }
+        fn(world, a, b, value);
+    }
+
+    // -------------------------------------------------------------------------
+    // Utility
+    // -------------------------------------------------------------------------
+
+    private static MethodInfo FindGenericMethod(string name) {
+        foreach(MethodInfo m in typeof(World).GetMethods(BindingFlags.Public | BindingFlags.Instance)) {
+            if(m.Name == name && m.IsGenericMethodDefinition)
+                return m;
+        }
+        throw new InvalidOperationException($"Could not find generic method '{name}' on {nameof(World)}.");
+    }
+}

Nerfed.Runtime/Scene/SceneRelationAttribute.cs

@@ -0,0 +1,10 @@
+namespace Nerfed.Runtime.Scene;
+
+/// <summary>
+/// Marks an unmanaged struct as a serializable scene relation kind.
+/// Both endpoints and the data payload will be saved/loaded by the scene system.
+/// The <see cref="Components.ChildParentRelation"/> hierarchy is handled separately via
+/// <see cref="SceneEntityData.ParentId"/> and should NOT be marked with this attribute.
+/// </summary>
+[AttributeUsage(AttributeTargets.Struct, Inherited = false)]
+public sealed class SceneRelationAttribute : Attribute { }

Nerfed.Runtime/Scene/Streaming/ChunkStreamingSystem.cs

@@ -0,0 +1,202 @@
+using MoonTools.ECS;
+using System.Collections.Generic;
+using System;
+using System.Numerics;
+using Nerfed.Runtime.Components;
+
+namespace Nerfed.Runtime.Scene.Streaming;
+
+/// <summary>
+/// Status of a chunk in the streaming system.
+/// </summary>
+public enum ChunkState
+{
+    Unloaded,
+    Loading,
+    Loaded,
+    Unloading
+}
+
+/// <summary>
+/// A system that manages spatial partitioning. It determines which chunks should be loaded based on observers.
+/// </summary>
+public class ChunkStreamingSystem : MoonTools.ECS.System
+{
+    private readonly struct ChunkCoord : IEquatable<ChunkCoord>
+    {
+        public readonly int X;
+        public readonly int Y;
+        public readonly int Z;
+        
+        // Pre-calculated on creation
+        public readonly long Id;
+        
+        public ChunkCoord(int x, int y, int z)
+        {
+            X = x;
+            Y = y;
+            Z = z;
+            
+            // We allocate 21 bits per axis (allowing ~2 million chunks positive and negative).
+            var hashX = (long)x & 0x1FFFFF; 
+            var hashY = (long)y & 0x1FFFFF; 
+            var hashZ = (long)z & 0x1FFFFF; 
+            
+            Id = hashX | (hashY << 21) | (hashZ << 42); 
+        }
+
+        public bool Equals(ChunkCoord other) => Id == other.Id;
+        public override bool Equals(object? obj) => obj is ChunkCoord other && Equals(other);
+        public override int GetHashCode() => Id.GetHashCode();
+    }
+
+    // Configurable size of a chunk in world coordinates.
+    public float ChunkSize { get; set; } = 64f;
+
+    private readonly Filter _observerFilter;
+    private readonly Filter _chunkMemberFilter;
+    private readonly Filter _unloadedFilter;
+
+    // Active loaded/loading chunks
+    private readonly Dictionary<ChunkCoord, ChunkState> _activeChunks = new();
+    
+    // Queue of chunks waiting to be loaded
+    private readonly Queue<ChunkCoord> _pendingLoads = new();
+    
+    // Queue of chunks waiting to be completely tagged for unloading
+    private readonly Queue<ChunkCoord> _pendingUnloads = new();
+
+    public ChunkStreamingSystem(World world) : base(world)
+    {
+        _observerFilter = FilterBuilder
+            .Include<ChunkObserverComponent>()
+            .Include<LocalToWorld>() // Needs a world position
+            .Exclude<ChunkUnloadPendingTag>()  // Ignore dying observers
+            .Build();
+
+        _chunkMemberFilter = FilterBuilder
+            .Include<ChunkMemberComponent>()
+            .Exclude<ChunkUnloadPendingTag>()  // Ignore entities already marked for death
+            .Build();
+
+        _unloadedFilter = FilterBuilder
+            .Include<ChunkUnloadPendingTag>()
+            .Build();
+    }
+
+    public override void Update(TimeSpan delta)
+    {
+        var requiredChunks = new HashSet<ChunkCoord>();
+
+        // 1. Find all chunks that should be loaded based on observers
+        foreach (var observerEntity in _observerFilter.Entities)
+        {
+            var observer = Get<ChunkObserverComponent>(observerEntity);
+            var transform = Get<LocalToWorld>(observerEntity);
+
+            // Convert world pos to grid coordinates
+            var worldPos = transform.localToWorldMatrix.Translation;
+            var centerChunk = GetChunkCoord(worldPos);
+
+            // Determine chunk radius based on observer radius and chunk size
+            int chunkRadius = (int)MathF.Ceiling(observer.ViewRadius / ChunkSize);
+
+            for (int x = -chunkRadius; x <= chunkRadius; x++)
+            {
+                for (int y = -chunkRadius; y <= chunkRadius; y++)
+                {
+                    for (int z = -chunkRadius; z <= chunkRadius; z++)
+                    {
+                        var coord = new ChunkCoord(centerChunk.X + x, centerChunk.Y + y, centerChunk.Z + z);
+                        requiredChunks.Add(coord);
+                    }
+                }
+            }
+        }
+
+        // 2. Unload chunks that are active but no longer required
+        var chunksToUnload = new List<ChunkCoord>();
+        foreach (var activeChunk in _activeChunks.Keys)
+        {
+            if (!requiredChunks.Contains(activeChunk) && _activeChunks[activeChunk] != ChunkState.Unloading)
+            {
+                chunksToUnload.Add(activeChunk);
+            }
+        }
+
+        foreach (var coord in chunksToUnload)
+        {
+            _activeChunks[coord] = ChunkState.Unloading;
+            _pendingUnloads.Enqueue(coord);
+        }
+
+        // 3. Queue newly required chunks
+        foreach (var coord in requiredChunks)
+        {
+            if (!_activeChunks.ContainsKey(coord))
+            {
+                // Mark as unloaded so we don't queue it multiple times
+                _activeChunks[coord] = ChunkState.Unloaded; 
+                _pendingLoads.Enqueue(coord);
+            }
+        }
+
+        // 4. Process only ONE chunk load per frame to prevent stuttering
+        if (_pendingLoads.Count > 0)
+        {
+            var chunkToLoad = _pendingLoads.Dequeue();
+            // Double check it wasn't unloaded before we got around to loading it
+            if (_activeChunks.TryGetValue(chunkToLoad, out var state) && state == ChunkState.Unloaded)
+            {
+                LoadChunk(chunkToLoad);
+            }
+        }
+        
+        // 5. Process only ONE chunk unload tagging per frame
+        if (_pendingUnloads.Count > 0)
+        {
+            var chunkToUnload = _pendingUnloads.Dequeue();
+            UnloadChunk(chunkToUnload);
+        }
+    }
+
+    private ChunkCoord GetChunkCoord(Vector3 worldPos)
+    {
+        return new ChunkCoord(
+            (int)MathF.Floor(worldPos.X / ChunkSize),
+            (int)MathF.Floor(worldPos.Y / ChunkSize),
+            (int)MathF.Floor(worldPos.Z / ChunkSize)
+        );
+    }
+
+    private void LoadChunk(ChunkCoord coord)
+    {
+        _activeChunks[coord] = ChunkState.Loading;
+
+        // TODO: In a real system, you'd queue async I/O here to read SceneData for this chunk
+        // and spawn the entities. Once they are all spawned, set state to Loaded.
+
+        // For demonstration, immediately set to loaded.
+        _activeChunks[coord] = ChunkState.Loaded;
+    }
+
+    private void UnloadChunk(ChunkCoord coord)
+    {
+        // Instead of destroying everything instantly, we tag the entities as 'Unloaded'
+        // so that they stop participating in rendering/gameplay, and get destroyed slowly
+        // by the ChunkTeardownSystem.
+        long coordId = coord.Id;
+        foreach (var entity in _chunkMemberFilter.Entities)
+        {
+            var chunkMember = Get<ChunkMemberComponent>(entity);
+            if (chunkMember.ChunkId == coordId)
+            {
+                Set(entity, new ChunkUnloadPendingTag());
+            }
+        }
+
+        // Immediately remove it from the required grid so it can be re-loaded 
+        // if the player turns around quickly, while older entities are just garbage collected.
+        _activeChunks.Remove(coord);
+    }
+}

Nerfed.Runtime/Scene/Streaming/ChunkTeardownSystem.cs

@@ -0,0 +1,35 @@
+using MoonTools.ECS;
+using System;
+
+namespace Nerfed.Runtime.Scene.Streaming;
+
+/// <summary>
+/// A centralized cleanup system for slowly destroying chunk entities to avoid frame stutters.
+/// </summary>
+public class ChunkTeardownSystem : MoonTools.ECS.System
+{
+    private readonly Filter _unloadedFilter;
+
+    // Adjustable limit to prevent massive stutters when unloading chunks.
+    public int MaxEntitiesToDestroyPerFrame { get; set; } = 250;
+
+    public ChunkTeardownSystem(World world) : base(world)
+    {
+        _unloadedFilter = FilterBuilder
+            .Include<ChunkUnloadPendingTag>()
+            .Build();
+    }
+
+    public override void Update(TimeSpan delta)
+    {
+        int destroyed = 0;
+
+        foreach (var entity in _unloadedFilter.Entities)
+        {
+            if (destroyed >= MaxEntitiesToDestroyPerFrame) break;
+
+            Destroy(entity);
+            destroyed++;
+        }
+    }
+}

Nerfed.Runtime/Scene/Streaming/StreamingComponents.cs

@@ -0,0 +1,28 @@
+using MoonTools.ECS;
+using System.Numerics;
+
+namespace Nerfed.Runtime.Scene.Streaming;
+
+/// <summary>
+/// Marks an entity as a streaming observer (e.g. the player camera) that causes chunks
+/// to be loaded around it.
+/// </summary>
+public struct ChunkObserverComponent
+{
+    public float ViewRadius;
+}
+
+/// <summary>
+/// Tags an entity as belonging to a specific chunk, allowing it to be unloaded when the chunk is out of range.
+/// </summary>
+public struct ChunkMemberComponent
+{
+    // A 64-bit spatial hash combining the X, Y, and Z coordinates.
+    public long ChunkId;
+}
+
+/// <summary>
+/// Added to entities that belong to a chunk that has been unloaded. 
+/// A dedicated system will process and destroy these slowly over multiple frames.
+/// </summary>
+public struct ChunkUnloadPendingTag { }

Nerfed.Runtime/Serialization/ComponentHelper.cs

@@ -0,0 +1,68 @@
+using System.Numerics;
+using ImGuiNET;
+using MoonTools.ECS;
+using Nerfed.Runtime.Components;
+
+namespace Nerfed.Runtime.Serialization;
+
+public static class ComponentHelper
+{
+    // Auto generate this.
+    public static readonly Dictionary<Type, Func<World, Entity, ValueType>> GetComponentByType = new()
+    {
+        { typeof(LocalTransform), (world, entity) => world.Get<LocalTransform>(entity) },
+        { typeof(Root), (world, entity) => world.Get<Root>(entity) },
+    };
+    
+    // Auto generate this.
+    public static readonly Dictionary<Type, Action<World, Entity, ValueType>> SetComponentByType = new()
+    {
+        { typeof(LocalTransform), (world, entity, component) => world.Set(entity, (LocalTransform)component) },
+        { typeof(Root), (world, entity, component) => world.Set(entity, (Root)component) },
+    };
+    
+    // Auto generate this, but it should only contain user assignable components (so something like 'root' should be excluded).
+    // Maybe use an attribute for this.
+    public static readonly Dictionary<Type, Action<World, Entity>> AddComponentByType = new()
+    {
+        { typeof(LocalTransform), (world, entity) => world.Set(entity, LocalTransform.Identity) },
+    };
+
+    // Auto generate this, but also keep the option for 'custom inspectors'.
+    // Maybe via attribute?
+    public static readonly Dictionary<Type, Action<World, Entity>> ComponentInspectorByType = new()
+    {
+        {
+            typeof(LocalTransform), (world, entity) =>
+            {
+                (Vector3 position, Quaternion rotation, Vector3 scale) = world.Get<LocalTransform>(entity);
+                Vector3 eulerAngles = MathEx.ToEulerAngles(rotation);
+                eulerAngles = new Vector3(float.RadiansToDegrees(eulerAngles.X), float.RadiansToDegrees(eulerAngles.Y), float.RadiansToDegrees(eulerAngles.Z));
+                bool isDirty = false;
+                
+                ImGui.BeginGroup();
+                ImGui.Text($"{nameof(LocalTransform)}");
+                isDirty |= ImGui.DragFloat3("Position", ref position, 0.2f, float.MinValue, float.MaxValue /*, "%f0 m" */); // TODO: right format.
+                isDirty |= ImGui.DragFloat3("Rotation", ref eulerAngles);
+                isDirty |= ImGui.DragFloat3("Scale", ref scale);
+                ImGui.EndGroup();
+
+                if (!isDirty)
+                {
+                    return;
+                }
+
+                eulerAngles = new Vector3(float.DegreesToRadians(eulerAngles.X), float.DegreesToRadians(eulerAngles.Y), float.DegreesToRadians(eulerAngles.Z));
+                world.Set(entity, new LocalTransform(position, MathEx.ToQuaternion(eulerAngles), scale));
+            }
+        },
+        {
+            typeof(Root), (world, entity) =>
+            {
+                ImGui.BeginGroup();
+                ImGui.Text($"{nameof(Root)}");
+                ImGui.EndGroup();
+            }
+        },
+    };
+}

Nerfed.Runtime/Systems/LocalToWorldSystem.cs

@@ -1,6 +1,8 @@
 using MoonTools.ECS;
 using Nerfed.Runtime.Components;
 using Nerfed.Runtime.Util;
+using System;
+using System.Collections.Generic;
 using System.Numerics;
 
 // TODO:
@@ -15,40 +17,100 @@ namespace Nerfed.Runtime.Systems
 {
     public class LocalToWorldSystem : MoonTools.ECS.System
     {
+        public override IReadOnlySet<Type> ReadsComponents { get; } = new HashSet<Type> { typeof(LocalTransform) };
+        public override IReadOnlySet<Type> WritesComponents { get; } = new HashSet<Type> { typeof(LocalToWorld) };
+
+        private readonly bool useParallelFor = true;
+        private const int ParallelForMinCount = 32; // Below this, parallel overhead costs more than it saves.
+        private static readonly System.Threading.Tasks.ParallelOptions ParallelOptions = new()
+        {
+            MaxDegreeOfParallelism = Environment.ProcessorCount
+        };
         private readonly Filter rootEntitiesFilter;
+        private readonly Filter entitiesWithoutLocalToWorldFilter;
+        private readonly Action<int> updateWorldTransform;
+        private ParallelWriter<LocalToWorld> _parallelWriter;
 
         public LocalToWorldSystem(World world) : base(world)
         {
             rootEntitiesFilter = FilterBuilder.Include<LocalTransform>().Exclude<Child>().Build();
+            if (useParallelFor)
+            {
+                entitiesWithoutLocalToWorldFilter = FilterBuilder.Include<LocalTransform>().Exclude<LocalToWorld>().Build();
+                updateWorldTransform = UpdateWorldTransformByIndex;
+            }
         }
 
         public override void Update(TimeSpan delta)
         {
-            Matrix4x4 rootMatrix = Matrix4x4.Identity;
+            if (rootEntitiesFilter.Empty)
+            {
+                return;
+            }
 
+            if (useParallelFor)
+            {
+                // This check is needed because some entities might not have a LocalToWorld component yet.
+                // Adding this during the loop will break.
+                Profiler.BeginSample("ParallelFor.LocalToWorldCheck");
+                foreach (Entity entity in entitiesWithoutLocalToWorldFilter.Entities) {
+                    Set(entity, new LocalToWorld(Matrix4x4.Identity));
+                }
+                Profiler.EndSample();
+
+                // Acquire a ParallelWriter AFTER pre-allocation — all entities now have LocalToWorld.
+                // This writer only permits updating existing values; no structural mutations allowed.
+                _parallelWriter = World.GetParallelWriter<LocalToWorld>();
+
+                Profiler.BeginSample("ParallelFor.LocalToWorldUpdate");
+                if (rootEntitiesFilter.Count >= ParallelForMinCount)
+                {
+                    Parallel.For(0, rootEntitiesFilter.Count, ParallelOptions, updateWorldTransform);
+                }
+                else
+                {
+                    // Not enough work to justify thread overhead — run serially.
+                    for (int i = 0; i < rootEntitiesFilter.Count; i++)
+                    {
+                        updateWorldTransform(i);
+                    }
+                }
+                Profiler.EndSample();
+            }
+            else
+            {
                 foreach (Entity entity in rootEntitiesFilter.Entities)
                 {
-                UpdateWorldTransform(entity, rootMatrix);
+                    // Profiler.BeginSample("UpdateWorldTransform");
+                    UpdateWorldTransform(entity, Matrix4x4.Identity);
+                    // Profiler.EndSample();
                 }
             }
+        }
+
+        private void UpdateWorldTransformByIndex(int entityFilterIndex)
+        {
+            // Profiler.BeginSample("UpdateWorldTransformByIndex");
+            Entity entity = rootEntitiesFilter.NthEntity(entityFilterIndex);
+            UpdateWorldTransform(entity, Matrix4x4.Identity);
+            // Profiler.EndSample();
+        }
 
         private void UpdateWorldTransform(in Entity entity, Matrix4x4 localToWorldMatrix)
         {
-            // TODO: Only update dirty transforms.
-            // If a parent is dirty all the children need to update their localToWorld matrix.
-            // How do we check if something is dirty? How do we know if a LocalTransform has been changed?
-
             if (Has<LocalTransform>(entity))
             {
                 LocalTransform localTransform = Get<LocalTransform>(entity);
                 localToWorldMatrix = Matrix4x4.Multiply(localToWorldMatrix, localTransform.TRS());
                 LocalToWorld localToWorld = new(localToWorldMatrix);
-                Set(entity, localToWorld);
 
-                //Log.Info($"Entity {entity} | local position {localTransform.position} | world position {localToWorldMatrix.Translation}");
+                if (useParallelFor)
+                    _parallelWriter.Set(entity, localToWorld); // thread-safe: direct write, no structural mutation
+                else
+                    Set(entity, localToWorld);
             }
 
-            ReverseSpanEnumerator<Entity> childEntities = World.OutRelations<ChildParentRelation>(entity);
+            ReverseSpanEnumerator<Entity> childEntities = World.InRelations<ChildParentRelation>(entity);
             foreach (Entity childEntity in childEntities)
             {
                 UpdateWorldTransform(childEntity, localToWorldMatrix);

Nerfed.Runtime/Systems/ParentSystem.cs

@@ -1,67 +0,0 @@
-using MoonTools.ECS;
-using Nerfed.Runtime.Components;
-
-namespace Nerfed.Runtime.Systems
-{
-    //public class ParentSystem : MoonTools.ECS.System
-    //{
-    //    private readonly Filter parentsAddedFilter;
-    //    private readonly Filter parentsRemovedFilter;
-    //    private readonly Filter parentsFilter;
-
-    //    public ParentSystem(World world) : base(world)
-    //    {
-    //        parentsAddedFilter = FilterBuilder.Include<Parent>().Exclude<PreviousParent>().Build();
-    //        parentsRemovedFilter = FilterBuilder.Include<PreviousParent>().Exclude<Parent>().Build();
-    //        parentsFilter = FilterBuilder.Include<Parent>().Include<PreviousParent>().Build();
-    //    }
-
-    //    public override void Update(TimeSpan delta)
-    //    {
-    //        // Update removed parents.
-    //        foreach (Entity entity in parentsRemovedFilter.Entities)
-    //        {
-    //            // Do stuff here to update/remove child relations etc.
-    //            //PreviousParent previousParent = Get<PreviousParent>(entity);
-    //            //World.Unrelate<ChildParentRelation>(previousParent.parentEntity, entity);
-    //            Remove<PreviousParent>(entity);
-    //        }
-
-    //        // Update added parents.
-    //        foreach (Entity entity in parentsAddedFilter.Entities)
-    //        {
-    //            Parent parent = Get<Parent>(entity);
-
-    //            if (Has<Parent>(parent.parentEntity) && Get<Parent>(parent.parentEntity).parentEntity == entity)
-    //            {
-    //                Log.Warning($"Entity {entity} cannot be a parent of entity {parent.parentEntity}, because {parent.parentEntity} is the parent of {entity}");
-    //                Remove<Parent>(entity);
-    //                continue;
-    //            }
-
-    //            PreviousParent previousParent = new(parent.parentEntity);
-    //            Set(entity, previousParent);
-    //            World.Relate(parent.parentEntity, entity, new ChildParentRelation());
-    //        }
-
-    //        // Update relations if the parent has changed.
-    //        foreach (Entity entity in parentsFilter.Entities)
-    //        {
-    //            Parent parent = Get<Parent>(entity);
-    //            PreviousParent previousParent = Get<PreviousParent>(entity);
-
-    //            if(parent.parentEntity != previousParent.parentEntity)
-    //            {
-    //                World.Unrelate<ChildParentRelation>(previousParent.parentEntity, entity);
-    //                Set(entity, new PreviousParent(parent.parentEntity));
-    //                World.Relate(parent.parentEntity, entity, new ChildParentRelation());
-    //            }
-    //        }
-
-    //        // TODO:
-    //        // What if an parent entity gets destroyed?
-    //        // How does the child know if the parent is in valid. Also we need to remove the parent component.
-    //        // Maybe if we also relate the other way around child -> parent via relations, and the relation is gone that means the parent is gone so we should remove the component.
-    //    }
-    //}
-}

Nerfed.Runtime/Util/BoundedQueue.cs

@@ -0,0 +1,73 @@
+using System.Collections;
+
+namespace Nerfed.Runtime;
+
+public class BoundedQueue<T> : IEnumerable<T>, ICollection, IReadOnlyCollection<T>
+{
+    private readonly Queue<T> queue = null;
+    private readonly int maxSize = 10;
+    private T lastAddedElement;
+
+    public BoundedQueue(int maxSize)
+    {
+        this.maxSize = maxSize;
+        queue = new Queue<T>(maxSize);
+    }
+
+    public void Enqueue(T item)
+    {
+        queue.Enqueue(item);
+        if (queue.Count > maxSize)
+        {
+            queue.Dequeue(); // Remove the oldest element
+        }
+
+        lastAddedElement = item;
+    }
+
+    public T Dequeue()
+    {
+        return queue.Dequeue();
+    }
+
+    public T Peek()
+    {
+        return queue.Peek();
+    }
+
+    public T LastAddedElement()
+    {
+        return lastAddedElement;
+    }
+
+    public void Clear()
+    {
+        queue.Clear();
+    }
+
+    public bool Contains(T item)
+    {
+        return queue.Contains(item);
+    }
+
+    public IEnumerator<T> GetEnumerator()
+    {
+        return queue.GetEnumerator();
+    }
+
+    IEnumerator IEnumerable.GetEnumerator()
+    {
+        return queue.GetEnumerator();
+    }
+
+    public void CopyTo(Array array, int index)
+    {
+        ((ICollection)queue).CopyTo(array, index);
+    }
+
+    public int Count => queue.Count;
+    public int Capacity => maxSize;
+    public bool IsSynchronized => ((ICollection)queue).IsSynchronized;
+    public object SyncRoot => ((ICollection)queue).SyncRoot;
+    int IReadOnlyCollection<T>.Count => queue.Count;
+}

Nerfed.Runtime/Util/MathEx.cs

@@ -1,3 +1,5 @@
+using System.Numerics;
+
 namespace Nerfed.Runtime;
 
 public static class MathEx
@@ -17,4 +19,51 @@ public static class MathEx
     public static float Remap(float value, float oldMin, float oldMax, float newMin, float newMax) {
         return (value - oldMin) / (oldMax - oldMin) * (newMax - newMin) + newMin;
     }
+    
+    // https://stackoverflow.com/questions/70462758/c-sharp-how-to-convert-quaternions-to-euler-angles-xyz
+    public static Quaternion ToQuaternion(Vector3 v)
+    {
+        float cy = (float)Math.Cos(v.Z * 0.5);
+        float sy = (float)Math.Sin(v.Z * 0.5);
+        float cp = (float)Math.Cos(v.Y * 0.5);
+        float sp = (float)Math.Sin(v.Y * 0.5);
+        float cr = (float)Math.Cos(v.X * 0.5);
+        float sr = (float)Math.Sin(v.X * 0.5);
+
+        return new Quaternion
+        {
+            W = (cr * cp * cy + sr * sp * sy),
+            X = (sr * cp * cy - cr * sp * sy),
+            Y = (cr * sp * cy + sr * cp * sy),
+            Z = (cr * cp * sy - sr * sp * cy),
+        };
+    }
+
+    public static Vector3 ToEulerAngles(Quaternion q)
+    {
+        Vector3 angles = new();
+
+        // roll / x
+        double sinrCosp = 2 * (q.W * q.X + q.Y * q.Z);
+        double cosrCosp = 1 - 2 * (q.X * q.X + q.Y * q.Y);
+        angles.X = (float)Math.Atan2(sinrCosp, cosrCosp);
+
+        // pitch / y
+        double sinp = 2 * (q.W * q.Y - q.Z * q.X);
+        if (Math.Abs(sinp) >= 1)
+        {
+            angles.Y = (float)Math.CopySign(Math.PI / 2, sinp);
+        }
+        else
+        {
+            angles.Y = (float)Math.Asin(sinp);
+        }
+
+        // yaw / z
+        double sinyCosp = 2 * (q.W * q.Z + q.X * q.Y);
+        double cosyCosp = 1 - 2 * (q.Y * q.Y + q.Z * q.Z);
+        angles.Z = (float)Math.Atan2(sinyCosp, cosyCosp);
+
+        return angles;
+    }
 }

Nerfed.Runtime/Util/RandomId.cs

@@ -0,0 +1,13 @@
+using System.Security.Cryptography;
+
+namespace Nerfed.Runtime.Util;
+
+public static class RandomId
+{
+    public static uint GenerateSecureRandomUInt()
+    {
+        byte[] buffer = new byte[4];
+        RandomNumberGenerator.Fill(buffer);
+        return BitConverter.ToUInt32(buffer, 0);
+    }
+}