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.

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/Program.cs

@@ -29,40 +29,40 @@ internal class Program
         //systems.Add(new ParentSystem(world));
         systems.Add(new LocalToWorldSystem(world));
         editorSystems.Add(new EditorProfilerWindow(world));
-        editorSystems.Add(new EditorHierarchyWindow(world));
+        // editorSystems.Add(new EditorHierarchyWindow(world));
 #if DEBUG
         editorSystems.Add(new EditorInspectorWindow(world));
 #endif
 
-        Entity ent1 = world.CreateEntity("parent");
-        world.Set(ent1, new Root());
-        world.Set(ent1, new LocalTransform(new Vector3(1, 0, 0), Quaternion.Identity, Vector3.One));
+        // Entity ent1 = world.CreateEntity("parent");
+        // world.Set(ent1, new Root());
+        // 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");
-        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");
-
-        for (int i = 0; i < 256; i++)
+        for (int i = 0; i < 1000000; i++)
         {
             Entity newEnt = world.CreateBaseEntity();
             world.Set(newEnt, new LocalTransform(new Vector3(i, i, i), Quaternion.Identity, Vector3.One));
 
-            Entity parent = newEnt;
-            for (int j = 0; j < 2; j++) {
-                Entity newChildEnt = world.CreateEntity();
-                world.Set(newChildEnt, new LocalTransform(new Vector3(i + j * i, i - j * i, j - i * i), Quaternion.Identity, Vector3.One));
-                Transform.SetParent(world, newChildEnt, parent);
-                parent = newChildEnt;
-            }
+            // Entity parent = newEnt;
+            // for (int j = 0; j < 2; j++) {
+            //     Entity newChildEnt = world.CreateEntity();
+            //     world.Set(newChildEnt, new LocalTransform(new Vector3(i + j * i, i - j * i, j - i * i), Quaternion.Identity, Vector3.One));
+            //     Transform.SetParent(world, newChildEnt, parent);
+            //     parent = newChildEnt;
+            // }
         }
 
         // Open project.

Nerfed.Runtime/Components/LocalTransform.cs

@@ -1,7 +1,9 @@
 using System.Numerics;
+using Nerfed.Runtime.Scene;
 
 namespace Nerfed.Runtime.Components
 {
+    [SceneComponent]
     public readonly record struct LocalTransform(Vector3 position, Quaternion rotation, Vector3 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,40 +78,33 @@ 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,
@@ -124,8 +112,7 @@ public static class Engine
              * 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);
@@ -136,8 +123,7 @@ 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();
             }
@@ -146,15 +132,12 @@ public static class Engine
         }
 
         // Do not let any step take longer than our maximum.
-        if (accumulatedUpdateTime > MaxDeltaTime)
-        {
+        if(accumulatedUpdateTime > MaxDeltaTime) {
             accumulatedUpdateTime = MaxDeltaTime;
         }
 
-        if (!quit)
-        {
-            while (accumulatedUpdateTime >= Timestep)
-            {
+        if(!quit) {
+            while(accumulatedUpdateTime >= Timestep) {
                 Profiler.BeginSample("Update");
                 Keyboard.Update();
                 Mouse.Update();
@@ -167,7 +150,7 @@ public static class Engine
                 OnUpdate?.Invoke();
                 Profiler.EndSample();
 
-                AudioDevice.WakeThread();
+                //AudioDevice.WakeThread();
                 accumulatedUpdateTime -= Timestep;
                 Profiler.EndSample();
             }
@@ -185,8 +168,7 @@ public static class Engine
         Profiler.EndFrame();
     }
 
-    private static TimeSpan AdvanceElapsedTime()
-    {
+    private static TimeSpan AdvanceElapsedTime() {
         long currentTicks = gameTimer.Elapsed.Ticks;
         TimeSpan timeAdvanced = TimeSpan.FromTicks(currentTicks - previousTicks);
         accumulatedUpdateTime += timeAdvanced;
@@ -195,12 +177,9 @@ public static class Engine
         return timeAdvanced;
     }
 
-    private static void ProcessSDLEvents()
-    {
-        while (SDL.SDL_PollEvent(out SDL.SDL_Event ev) == 1)
-        {
-            switch (ev.type)
-            {
+    private static void ProcessSDLEvents() {
+        while(SDL.SDL_PollEvent(out SDL.SDL_Event ev) == 1) {
+            switch(ev.type) {
                 case SDL.SDL_EventType.SDL_QUIT:
                     Quit();
                     break;
@@ -236,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;
         }
 
@@ -254,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++)
-            {
-                if (previousSleepTimes[i] > maxSleepTime)
-                {
+            for(int i = 0; i < previousSleepTimes.Length; i++) {
+                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");
-        VideoFragmentShader = ResourceManager.Load<Shader>("Shaders/Video.frag");
-        TextVertexShader = ResourceManager.Load<Shader>("Shaders/Text.vert");
-        TextFragmentShader = ResourceManager.Load<Shader>("Shaders/Text.frag");
+        FullscreenVertexShader = ResourceManager.Retain<Shader>("Shaders/Fullscreen.vert");
+        VideoFragmentShader = ResourceManager.Retain<Shader>("Shaders/Video.frag");
+        TextVertexShader = ResourceManager.Retain<Shader>("Shaders/Text.vert");
+        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.Unload(TextFragmentShader);
-                ResourceManager.Unload(TextVertexShader);
-                ResourceManager.Unload(VideoFragmentShader);
+                ResourceManager.Release(FullscreenVertexShader);
+                ResourceManager.Release(TextFragmentShader);
+                ResourceManager.Release(TextVertexShader);
+                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");
-        imGuiFragmentShader = ResourceManager.Load<Shader>("Shaders/ImGui.frag");
+        imGuiVertexShader = ResourceManager.Retain<Shader>("Shaders/ImGui.vert");
+        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.Unload(imGuiFragmentShader);
+        ResourceManager.Release(imGuiVertexShader);
+        ResourceManager.Release(imGuiFragmentShader);
         imGuiPipeline?.Dispose();
         imGuiSampler?.Dispose();
         resourceUploader?.Dispose();

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 static readonly Dictionary<string, Resource> loadedResources = new Dictionary<string, Resource>();
+    private const string RootName = "Resources";
 
-    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");
-        }
-
-        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);
+                // Sleep cleanly if queue is empty to avoid burning total CPU usage on an infinite while-loop
+                Thread.Sleep(10);
+            }
+        }
     }
 }

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/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,10 +17,19 @@ namespace Nerfed.Runtime.Systems
 {
     public class LocalToWorldSystem : MoonTools.ECS.System
     {
-        private readonly bool useParallelFor = true; // When having a low amount of transforms or when in debug mode this might be slower.
+        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)
         {
@@ -39,49 +50,63 @@ namespace Nerfed.Runtime.Systems
 
             if (useParallelFor)
             {
-                Profiler.BeginSample("ParallelFor.LocalToWorldCheck");
                 // 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");
-                // This should only be used when the filter doesn't change by executing these functions!
-                // So no entity deletion or setting/removing of components used by the filters in this loop.
-                Parallel.For(0, rootEntitiesFilter.Count, updateWorldTransform);
+                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)
                 {
-                    Profiler.BeginSample("UpdateWorldTransform");
+                    // Profiler.BeginSample("UpdateWorldTransform");
                     UpdateWorldTransform(entity, Matrix4x4.Identity);
-                    Profiler.EndSample();
+                    // Profiler.EndSample();
                 }
             }
         }
 
         private void UpdateWorldTransformByIndex(int entityFilterIndex)
         {
-            Profiler.BeginSample("UpdateWorldTransformByIndex");
+            // Profiler.BeginSample("UpdateWorldTransformByIndex");
             Entity entity = rootEntitiesFilter.NthEntity(entityFilterIndex);
             UpdateWorldTransform(entity, Matrix4x4.Identity);
-            Profiler.EndSample();
+            // 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);
+
+                if (useParallelFor)
+                    _parallelWriter.Set(entity, localToWorld); // thread-safe: direct write, no structural mutation
+                else
                     Set(entity, localToWorld);
             }