# G86 — Async Content Loading & Texture Streaming > **Category:** guide · **Engine:** MonoGame · **Related:** [G8 Content Pipeline](./G8_content_pipeline.md) · [G26 Resource Loading & Caching](./G26_resource_loading_caching.md) · [G33 Profiling & Optimization](./G33_profiling_optimization.md) · [G67 Object Pooling](./G67_object_pooling.md) · [G71 Spatial Partitioning](./G71_spatial_partitioning.md) How to load game content asynchronously in MonoGame without stalling the game loop. Covers background thread loading patterns, the thread-safety constraints of `ContentManager` and `Texture2D`, queue-based GPU upload strategies, and architectural patterns for streaming large worlds with loading screens and seamless zone transitions. ## The Problem: Main-Thread Loading Stalls MonoGame's `ContentManager.Load()` is synchronous and performs both I/O (reading `.xnb` files from disk) and GPU work (creating textures, vertex buffers). Calling it during gameplay causes frame hitches — sometimes hundreds of milliseconds for large textures or complex models. The challenge is that **OpenGL and DirectX require GPU resource creation on the graphics thread**. You cannot simply move everything to `Task.Run` — the GPU upload step must execute on the thread that owns the graphics context. ## Architecture: Split I/O from GPU Upload The proven pattern separates work into two phases: ``` Background Thread Main Thread (game loop) ───────────────── ────────────────────── 1. Read .xnb from disk 3. Dequeue loaded data 2. Decode/decompress bytes 4. Create GPU resource → Enqueue raw pixel data (Texture2D.SetData, etc.) ``` ### Phase 1: Background I/O and Decoding ```csharp public class AsyncContentLoader { private readonly ContentManager _content; private readonly ConcurrentQueue _pendingUploads = new(); private readonly HashSet _loading = new(); ///

/// Kicks off a background load. The raw pixel data is decoded off-thread, /// but actual GPU texture creation is deferred to the main thread. ///

public void RequestLoad(string assetPath) { if (_loading.Contains(assetPath)) return; _loading.Add(assetPath); Task.Run(() => { // Read and decode the file on a background thread. // Use FileStream directly — NOT ContentManager.Load, // which internally calls GraphicsDevice methods. string fullPath = Path.Combine(_content.RootDirectory, assetPath + ".xnb"); byte[] fileBytes = File.ReadAllBytes(fullPath); // For textures loaded from raw images (PNG/JPG) rather than .xnb, // decode the pixel data without touching the GPU: // using var stream = File.OpenRead(imagePath); // var imageData = DecodeImageToRGBA(stream); // your decoder _pendingUploads.Enqueue(new LoadRequest { AssetPath = assetPath, RawData = fileBytes }); }); } } ``` ### Phase 2: Main-Thread GPU Upload ```csharp ///

/// Call once per frame from Update() or Draw() to process /// a limited number of queued uploads without causing frame drops. ///

public void ProcessUploads(GraphicsDevice device, int maxPerFrame = 2) { int processed = 0; while (processed < maxPerFrame && _pendingUploads.TryDequeue(out var request)) { // GPU resource creation MUST happen on the main thread. var texture = new Texture2D(device, request.Width, request.Height); texture.SetData(request.PixelData); _loadedAssets[request.AssetPath] = texture; _loading.Remove(request.AssetPath); processed++; } } ``` ### Why Not Texture2D.FromStream on a Background Thread? `Texture2D.FromStream()` internally creates GPU resources. On DesktopGL (OpenGL), this hangs or crashes when called from a non-GL thread. On DesktopDX it may work due to D3D11's deferred context support, but it is **not safe cross-platform**. Always separate I/O from GPU creation. ## ContentManager Thread Safety `ContentManager.Load()` is **not thread-safe** in MonoGame. Key rules: 1. **Never call `Load` from multiple threads simultaneously.** The internal cache dictionary is not concurrent. 2. **Use separate ContentManager instances** if you must load from multiple threads — each instance has its own cache. Dispose them when done to avoid memory leaks. 3. **For .xnb loading specifically**, the XNB reader pipeline calls `GraphicsDevice` methods internally, making it inherently main-thread-only for GPU resources. ```csharp // Safe pattern: dedicated ContentManager per loading context var backgroundContent = new ContentManager(game.Services, "Content"); // Use only for non-GPU resources (SoundEffect, SpriteFont data, JSON, etc.) ``` ## Streaming Large Worlds: Zone-Based Loading For open-world or large-level games, divide the world into zones and load/unload them based on player position. ### Zone Manager Pattern ```csharp public class ZoneManager { private readonly Dictionary _zones = new(); private readonly HashSet _activeZones = new(); private readonly AsyncContentLoader _loader; private readonly int _loadRadius = 2; // zones ahead to preload private readonly int _unloadRadius = 4; // zones behind to release public void Update(Vector2 playerPosition) { Point currentZone = WorldToZone(playerPosition); // Request loading for zones within radius for (int dx = -_loadRadius; dx <= _loadRadius; dx++) for (int dy = -_loadRadius; dy <= _loadRadius; dy++) { var coord = new Point(currentZone.X + dx, currentZone.Y + dy); if (!_activeZones.Contains(coord)) { _loader.RequestLoad($"zones/zone_{coord.X}_{coord.Y}"); _activeZones.Add(coord); } } // Unload distant zones to reclaim memory var toUnload = _activeZones .Where(z => Math.Abs(z.X - currentZone.X) > _unloadRadius || Math.Abs(z.Y - currentZone.Y) > _unloadRadius) .ToList(); foreach (var coord in toUnload) { _zones[coord].Dispose(); _zones.Remove(coord); _activeZones.Remove(coord); } } } ``` ### Loading Priority Not all assets are equally urgent. Implement a priority queue: - **Priority 0 (Immediate):** Zone the player is currently in — block if not loaded. - **Priority 1 (High):** Adjacent zones in the player's movement direction. - **Priority 2 (Low):** Remaining zones within the load radius. ```csharp // Use a PriorityQueue (.NET 6+) for ordered processing private readonly PriorityQueue _loadQueue = new(); public void RequestLoad(string asset, int priority) { _loadQueue.Enqueue(new LoadRequest(asset), priority); } ``` ## Loading Screens and Progress Tracking For level transitions where seamless streaming is not needed, use a loading screen with progress feedback. ```csharp public class LoadingScreen { private readonly List _assetsToLoad; private int _loaded; public float Progress => _assetsToLoad.Count > 0 ? (float)_loaded / _assetsToLoad.Count : 1f; ///

/// Cooperative loader: loads one asset per frame to keep /// the loading screen animation smooth at 60fps. ///

public bool LoadNext(ContentManager content) { if (_loaded >= _assetsToLoad.Count) return true; // done content.Load