M3: Asset pipeline — ContentPaths + ContentLoader + asset-test

Formalises Content/ access from the Godot host. Content lives at the
repo root (sibling of Theriapolis.Godot/), not duplicated under res://,
so the MonoGame branch and headless Tools keep reading from the same
single source of truth.

ContentPaths.cs:
  Static ContentRoot/DataDir/GfxDir resolved once via res:// walk-up
  and cached. Replaces two inline ResolveDataDir copies in SmokeTest
  and WorldMapView.

ContentLoader.cs:
  LoadGfx(relativePath) -> ImageTexture, cached by relative path.
  Bypasses the res:// import pipeline because Content/ lives outside
  the project — fine for static pixel-art assets at native size, and
  the project default texture filter is already Nearest. Cache is
  per-process, never evicted (full atlas <1 MB).

AssetTest.cs + Main.cs --asset-test flag:
  Smoke-tests the pipeline. Walks Content/Data and Content/Gfx,
  reports counts, attempts to load every PNG, prints per-subdir
  breakdown. Quits with non-zero on any failure.

Verified post-refactor (--asset-test):
  53 JSON files in Data, 50 PNG files in Gfx (8 tactical/deco +
  42 tactical/surface), 50/50 loaded, 0 failures.

Verified no regressions:
  --smoke-test (M1) still produces canonical FNV hashes.
  --world-map 12345 (M2) still produces 3 rivers / 91 roads /
  226 settlements / 0 rails / 0 bridges.

Scope note: plan mentioned "tile/NPC/CodexUI atlases — three
separate themes". Only tactical/ exists in Content/Gfx today; NPC
and CodexUI atlases never landed during MonoGame development. M3
ships what's actually present. ContentLoader.LoadGfx works for any
future sub-directories without changes.

Closes M3 of theriapolis-rpg-implementation-plan-godot-port.md.
Next: M4 (tactical render).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Theriapolis.Godot/Main.cs

@@ -1,4 +1,5 @@
 using Godot;
+using Theriapolis.GodotHost.Platform;
 using Theriapolis.GodotHost.Rendering;
 
 namespace Theriapolis.GodotHost;
@@ -18,6 +19,7 @@ public partial class Main : Node
 
         ulong? smokeTestSeed = null;
         ulong? worldMapSeed = null;
+        bool runAssetTest = false;
         for (int i = 0; i < args.Length; i++)
         {
             if (args[i] == "--smoke-test")
@@ -28,6 +30,11 @@ public partial class Main : Node
                 smokeTestSeed = seed;
                 break;
             }
+            if (args[i] == "--asset-test")
+            {
+                runAssetTest = true;
+                break;
+            }
             if (args[i] == "--world-map")
             {
                 ulong seed = 12345UL;
@@ -45,6 +52,13 @@ public partial class Main : Node
             return;
         }
 
+        if (runAssetTest)
+        {
+            int code = AssetTest.Run();
+            GetTree().Quit(code);
+            return;
+        }
+
         if (worldMapSeed.HasValue)
         {
             // Replace the M0 hello-world children with the M2 world-map view.

Theriapolis.Godot/Platform/AssetTest.cs

@@ -0,0 +1,78 @@
+using Godot;
+using System.IO;
+using System.Linq;
+
+namespace Theriapolis.GodotHost.Platform;
+
+/// <summary>
+/// M3 asset pipeline smoke test. Walks Content/Data and Content/Gfx,
+/// reports counts, and verifies every PNG under Gfx loads via
+/// ContentLoader. Exits non-zero on any failure.
+///
+/// Run with:
+///   godot --headless --path Theriapolis.Godot -- --asset-test
+/// </summary>
+public static class AssetTest
+{
+    public static int Run()
+    {
+        GD.Print($"[asset-test] Content root: {ContentPaths.ContentRoot}");
+        GD.Print($"[asset-test] Data dir:     {ContentPaths.DataDir}");
+        GD.Print($"[asset-test] Gfx dir:      {ContentPaths.GfxDir}");
+
+        if (!Directory.Exists(ContentPaths.DataDir))
+        {
+            GD.PrintErr($"[asset-test] FAIL: Data directory missing");
+            return 1;
+        }
+        if (!Directory.Exists(ContentPaths.GfxDir))
+        {
+            GD.PrintErr($"[asset-test] FAIL: Gfx directory missing");
+            return 1;
+        }
+
+        var jsonFiles = Directory.GetFiles(ContentPaths.DataDir, "*.json", SearchOption.AllDirectories);
+        GD.Print($"[asset-test] Data: {jsonFiles.Length} JSON files");
+
+        var pngFiles = Directory.GetFiles(ContentPaths.GfxDir, "*.png", SearchOption.AllDirectories);
+        GD.Print($"[asset-test] Gfx:  {pngFiles.Length} PNG files");
+
+        int loaded = 0;
+        int failed = 0;
+        foreach (var absolute in pngFiles)
+        {
+            string relative = Path.GetRelativePath(ContentPaths.GfxDir, absolute)
+                                  .Replace('\\', '/');
+            var tex = ContentLoader.LoadGfx(relative);
+            if (tex is null)
+            {
+                failed++;
+            }
+            else
+            {
+                loaded++;
+            }
+        }
+
+        GD.Print($"[asset-test] Loaded {loaded}/{pngFiles.Length} PNGs " +
+                 $"(cache size {ContentLoader.CacheCount}, failed {failed})");
+
+        if (failed > 0)
+        {
+            GD.PrintErr($"[asset-test] FAIL: {failed} texture(s) failed to load");
+            return 1;
+        }
+
+        // Also report the sub-tree breakdown, matching what M4 will care about
+        var bySubdir = pngFiles
+            .GroupBy(f => Path.GetRelativePath(ContentPaths.GfxDir, Path.GetDirectoryName(f)!)
+                              .Replace('\\', '/'))
+            .OrderBy(g => g.Key);
+        GD.Print($"[asset-test] PNG breakdown by sub-directory:");
+        foreach (var g in bySubdir)
+            GD.Print($"[asset-test]   {g.Key,-24} {g.Count(),3} files");
+
+        GD.Print($"[asset-test] OK");
+        return 0;
+    }
+}

Theriapolis.Godot/Platform/ContentLoader.cs

@@ -0,0 +1,55 @@
+using Godot;
+using System.Collections.Generic;
+using System.IO;
+
+namespace Theriapolis.GodotHost.Platform;
+
+/// <summary>
+/// Loads PNGs from Content/Gfx as Godot ImageTextures and caches them by
+/// relative path. Texture filter is set to Nearest (project default for
+/// pixel art).
+///
+/// This bypasses Godot's res:// import pipeline because Content/ lives
+/// outside the project — but for static pixel-art assets at native size
+/// the import pipeline doesn't add anything we need.
+///
+/// Tactical-view tile rendering (M4) will hit this from chunk streamers,
+/// so the cache is per-process and never evicted; the full atlas
+/// (~50 PNGs at 32x32) is well under 1 MB.
+/// </summary>
+public static class ContentLoader
+{
+    private static readonly Dictionary<string, ImageTexture> _cache = new();
+
+    /// <summary>
+    /// Loads a PNG from <c>Content/Gfx/&lt;relativePath&gt;</c>. Returns
+    /// null and logs an error if the file is missing or unreadable.
+    /// </summary>
+    public static ImageTexture? LoadGfx(string relativePath)
+    {
+        if (_cache.TryGetValue(relativePath, out var cached)) return cached;
+
+        string absolute = Path.Combine(ContentPaths.GfxDir, relativePath);
+        if (!File.Exists(absolute))
+        {
+            GD.PrintErr($"[ContentLoader] Missing texture: {absolute}");
+            return null;
+        }
+
+        var image = Image.LoadFromFile(absolute);
+        if (image is null)
+        {
+            GD.PrintErr($"[ContentLoader] Image.LoadFromFile failed: {absolute}");
+            return null;
+        }
+
+        var tex = ImageTexture.CreateFromImage(image);
+        _cache[relativePath] = tex;
+        return tex;
+    }
+
+    public static int CacheCount => _cache.Count;
+
+    /// <summary>Drops every cached texture. Useful for hot-reload tests.</summary>
+    public static void ClearCache() => _cache.Clear();
+}

Theriapolis.Godot/Platform/ContentPaths.cs

@@ -0,0 +1,46 @@
+using Godot;
+using System.IO;
+
+namespace Theriapolis.GodotHost.Platform;
+
+/// <summary>
+/// Single source of truth for resolving the project's Content/ directory.
+/// Content lives at the repository root (sibling to Theriapolis.Godot/),
+/// not inside res://. This avoids duplicating gigabytes of game data, and
+/// keeps the same Content/Data and Content/Gfx tree the MonoGame branch
+/// and headless Tools all read from.
+///
+/// Resolution walks up from res:// looking for Content/Data; once found,
+/// the parent of Data is the Content root, used for Gfx too. Cached after
+/// first hit so repeated calls are cheap.
+/// </summary>
+public static class ContentPaths
+{
+    private static string? _cachedContentRoot;
+
+    public static string ContentRoot => _cachedContentRoot ??= ResolveContentRoot();
+    public static string DataDir => Path.Combine(ContentRoot, "Data");
+    public static string GfxDir  => Path.Combine(ContentRoot, "Gfx");
+
+    private static string ResolveContentRoot()
+    {
+        // Try res://../Content first — the canonical layout.
+        string fromRes = ProjectSettings.GlobalizePath("res://../Content");
+        if (Directory.Exists(Path.Combine(fromRes, "Data"))) return fromRes;
+
+        // Walk up further in case Theriapolis.Godot is nested deeper.
+        string? dir = ProjectSettings.GlobalizePath("res://").TrimEnd('/', '\\');
+        for (int i = 0; i < 6; i++)
+        {
+            if (string.IsNullOrEmpty(dir)) break;
+            string candidate = Path.Combine(dir, "Content");
+            if (Directory.Exists(Path.Combine(candidate, "Data"))) return candidate;
+            dir = Path.GetDirectoryName(dir);
+        }
+
+        // Last resort — return the canonical path even if it doesn't exist;
+        // callers that care will fail with a useful error.
+        GD.PushWarning($"[ContentPaths] Content root not found; using {fromRes}");
+        return fromRes;
+    }
+}

Theriapolis.Godot/Rendering/WorldMapView.cs

@@ -6,6 +6,7 @@ using Theriapolis.Core.Util;
 using Theriapolis.Core.World;
 using Theriapolis.Core.World.Generation;
 using Theriapolis.Core.World.Polylines;
+using Theriapolis.GodotHost.Platform;
 
 namespace Theriapolis.GodotHost.Rendering;
 
@@ -53,7 +54,7 @@ public partial class WorldMapView : Node2D
 
     public override void _Ready()
     {
-        string dataDir = ResolveDataDir();
+        string dataDir = ContentPaths.DataDir;
         if (!Directory.Exists(dataDir))
         {
             GD.PrintErr($"[world-map] Data directory not found: {dataDir}");
@@ -285,22 +286,6 @@ public partial class WorldMapView : Node2D
         _                     => BiomeId.TemperateGrassland,
     };
 
-    private static string ResolveDataDir()
-    {
-        string fromRes = ProjectSettings.GlobalizePath("res://../Content/Data");
-        if (Directory.Exists(fromRes)) return fromRes;
-
-        string? dir = ProjectSettings.GlobalizePath("res://").TrimEnd('/', '\\');
-        for (int i = 0; i < 6; i++)
-        {
-            if (string.IsNullOrEmpty(dir)) break;
-            string candidate = Path.Combine(dir, "Content", "Data");
-            if (Directory.Exists(candidate)) return candidate;
-            dir = Path.GetDirectoryName(dir);
-        }
-
-        return fromRes;
-    }
 }
 
 /// <summary>

Theriapolis.Godot/SmokeTest.cs

@@ -2,6 +2,7 @@ using Godot;
 using System.IO;
 using System.Linq;
 using Theriapolis.Core.World.Generation;
+using Theriapolis.GodotHost.Platform;
 
 namespace Theriapolis.GodotHost;
 
@@ -15,7 +16,7 @@ public static class SmokeTest
 {
     public static int Run(ulong seed)
     {
-        string dataDir = ResolveDataDir();
+        string dataDir = ContentPaths.DataDir;
         if (!Directory.Exists(dataDir))
         {
             GD.PrintErr($"[smoke-test] Data directory not found: {dataDir}");
@@ -39,21 +40,4 @@ public static class SmokeTest
             GD.Print($"[smoke-test] {kv.Key,-32} = 0x{kv.Value:X16}");
         return 0;
     }
-
-    private static string ResolveDataDir()
-    {
-        string fromRes = ProjectSettings.GlobalizePath("res://../Content/Data");
-        if (Directory.Exists(fromRes)) return fromRes;
-
-        string? dir = ProjectSettings.GlobalizePath("res://").TrimEnd('/', '\\');
-        for (int i = 0; i < 6; i++)
-        {
-            if (string.IsNullOrEmpty(dir)) break;
-            string candidate = Path.Combine(dir, "Content", "Data");
-            if (Directory.Exists(candidate)) return candidate;
-            dir = Path.GetDirectoryName(dir);
-        }
-
-        return fromRes;
-    }
 }