beezm/islaApocalypse
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: blueprint v2 envelope — writer, dual-write, round-trip harness (terrain-water task 02)

Browse source 
v2 tagged-section container (D-030): raw ISLA magic + u32 version gate,
[u32 tag][u64 length][payload] sections — params (resolved generation
inputs incl. impact centre), heights f32, biomes u8, towns with the
highway-node flag, four road tiers identified by tag not position.

- BlueprintFormat.cs: the single tag/constant registry.
- BlueprintWriter.WriteV2: blueprint-typed, callable outside a
  generation run; generator and harness are both just callers.
- ExportMapData dual-writes: v2 under the primary seed name, legacy v1
  beside it as _v1.dat (safety net; removal is a future task).
- MapDataParser: LoadMapDataFromPath entry point; v1 parse body
  extracted intact as LoadV1 (v2 reader lands in the next commit).
- RoundTripHarness scene: load v1 -> write v2 -> load v2 -> semantic
  equality, headless, seconds per cycle.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Stewart Howe 2026-08-06 07:24:08 -04:00
parent ad541dfbd8
commit c305fd6565
6 changed files with 494 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

54
Core/Scripts/BlueprintFormat.cs Normal file
View file

@ -0,0 +1,54 @@
namespace IslaApocalypse.Core
{
/// <summary>
/// The single registry of constants for the v2 blueprint container — magic, version,
/// section tags, validation bounds, and the sentinel values used when a v2 file is
/// re-encoded from a v1 source that cannot supply real generation parameters.
///
/// The byte-accurate layout lives in Core/Scripts/BLUEPRINT_FORMAT.md. Writer:
/// BlueprintWriter.WriteV2. Reader: MapDataParser (v2 branch). Tags are FourCC codes
/// stored as little-endian u32, so the raw bytes on disk read as ASCII ("PRMS", "HGTS",
/// ...) in a hex dump.
/// </summary>
public static class BlueprintFormat
{
// "ISLA" as raw bytes 'I','S','L','A' == little-endian u32 0x414C5349.
// Deliberately NOT a length-prefixed .NET string: the v1 header starts with the
// 7-bit length prefix 0x07, so the first byte alone (0x49 vs 0x07) identifies the
// format and the reader can dispatch without ambiguity.
public const uint MAGIC = 0x414C5349;
public const uint VERSION = 2;
// Section tags (FourCC, little-endian). Reader rule: known tag -> parse,
// unknown tag -> skip by length and continue. Never reuse a retired tag value.
public const uint TAG_PARAMS = 0x534D5250; // "PRMS"
public const uint TAG_HEIGHTS = 0x53544748; // "HGTS"
public const uint TAG_BIOMES = 0x4D4F4942; // "BIOM"
public const uint TAG_TOWNS = 0x4E574F54; // "TOWN"
public const uint TAG_ROADS_HIGHWAY = 0x57484452; // "RDHW"
public const uint TAG_ROADS_BRANCH = 0x52424452; // "RDBR"
public const uint TAG_ROADS_RUGGED = 0x47524452; // "RDRG"
public const uint TAG_ROADS_TRAIL = 0x4C544452; // "RDTL"
// MapSize sanity bounds, checked before any allocation on read.
public const int MIN_MAP_SIZE = 256;
public const int MAX_MAP_SIZE = 32768;
// Sentinels written into the params section when the source blueprint came from a
// v1 file (a re-encode cannot know the original generation inputs). WorldSeed 0 is
// also the config "randomize" sentinel, which no real resolved seed ever is.
public const int SENTINEL_WORLD_SEED = 0;
public const float SENTINEL_CRATER_RADIUS = -1f;
public const float SENTINEL_DENSITY_MULTIPLIER = -1f;
public const float SENTINEL_IMPACT_CENTER = -1f; // both components
/// <summary>Renders a tag as its 4 ASCII characters, for log messages.</summary>
public static string TagToString(uint tag)
{
return new string(new[] {
(char)(tag & 0xFF), (char)((tag >> 8) & 0xFF),
(char)((tag >> 16) & 0xFF), (char)((tag >> 24) & 0xFF)
});
}
}
}

165
Core/Scripts/BlueprintWriter.cs Normal file
View file

@ -0,0 +1,165 @@
using Godot;
using System;
using System.IO;
namespace IslaApocalypse.Core
{
/// <summary>
/// Writes a WorldBlueprint to disk in the v2 tagged-section container
/// (layout: Core/Scripts/BLUEPRINT_FORMAT.md; constants: BlueprintFormat).
///
/// Deliberately written against the blueprint data types, not the generator's
/// internal arrays, so it is callable outside a generation run — the map generator
/// and the round-trip harness are both just callers.
///
/// Provenance (timestamp, git hash) is stamped at write time — it describes the
/// file being written, not whatever was in blueprint.Params. If blueprint.Params is
/// null (a re-encode of a legacy v1 file), the sentinel values from BlueprintFormat
/// are written instead of real generation inputs.
/// </summary>
public static class BlueprintWriter
{
public static void WriteV2(string absolutePath, WorldBlueprint bp)
{
ulong started = Time.GetTicksMsec();
using (FileStream stream = File.Open(absolutePath, FileMode.Create))
using (BinaryWriter writer = new BinaryWriter(stream))
{
// Header: raw "ISLA" magic + u32 version. Little-endian throughout.
writer.Write(BlueprintFormat.MAGIC);
writer.Write(BlueprintFormat.VERSION);
WriteSection(writer, BlueprintFormat.TAG_PARAMS, w => WriteParams(w, bp));
WriteSection(writer, BlueprintFormat.TAG_HEIGHTS, w => WriteHeights(w, bp));
WriteSection(writer, BlueprintFormat.TAG_BIOMES, w => WriteBiomes(w, bp));
WriteSection(writer, BlueprintFormat.TAG_TOWNS, w => WriteTowns(w, bp));
WriteSection(writer, BlueprintFormat.TAG_ROADS_HIGHWAY, w => WriteRoadTier(w, bp.Highways));
WriteSection(writer, BlueprintFormat.TAG_ROADS_BRANCH, w => WriteRoadTier(w, bp.BranchRoads));
WriteSection(writer, BlueprintFormat.TAG_ROADS_RUGGED, w => WriteRoadTier(w, bp.RuggedRoads));
WriteSection(writer, BlueprintFormat.TAG_ROADS_TRAIL, w => WriteRoadTier(w, bp.TrailRoads));
}
double seconds = (Time.GetTicksMsec() - started) / 1000.0;
Vector2 impact = bp.Params?.ImpactCenter
?? new Vector2(BlueprintFormat.SENTINEL_IMPACT_CENTER, BlueprintFormat.SENTINEL_IMPACT_CENTER);
GD.Print($"[BlueprintWriter] v2 blueprint written in {seconds:F1}s to: {absolutePath} " +
$"(seed {bp.Params?.WorldSeed ?? BlueprintFormat.SENTINEL_WORLD_SEED}, " +
$"MapSize {bp.MapSize}, impactCenter ({impact.X:F1},{impact.Y:F1}))");
}
/// <summary>
/// Frames one section: [u32 tag][u64 payload-length][payload]. The length is
/// back-patched after the payload is written, so payload writers never have to
/// pre-compute their own size.
/// </summary>
private static void WriteSection(BinaryWriter writer, uint tag, Action<BinaryWriter> payload)
{
writer.Write(tag);
long lengthPos = writer.BaseStream.Position;
writer.Write((ulong)0);
long payloadStart = writer.BaseStream.Position;
payload(writer);
long payloadEnd = writer.BaseStream.Position;
writer.BaseStream.Position = lengthPos;
writer.Write((ulong)(payloadEnd - payloadStart));
writer.BaseStream.Position = payloadEnd;
}
private static void WriteParams(BinaryWriter writer, WorldBlueprint bp)
{
BlueprintParams p = bp.Params;
writer.Write(p?.WorldSeed ?? BlueprintFormat.SENTINEL_WORLD_SEED);
writer.Write(bp.MapSize); // always real — the blueprint knows its own size
writer.Write(p?.CraterRadius ?? BlueprintFormat.SENTINEL_CRATER_RADIUS);
writer.Write(p?.DensityMultiplier ?? BlueprintFormat.SENTINEL_DENSITY_MULTIPLIER);
Vector2 impact = p?.ImpactCenter
?? new Vector2(BlueprintFormat.SENTINEL_IMPACT_CENTER, BlueprintFormat.SENTINEL_IMPACT_CENTER);
writer.Write(impact.X);
writer.Write(impact.Y);
// Provenance, stamped now (length-prefixed .NET strings — fine inside a
// length-framed section; only the file HEADER must avoid them).
writer.Write(DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ"));
writer.Write(TryGetGitShortHash());
}
private static void WriteHeights(BinaryWriter writer, WorldBlueprint bp)
{
// X outer / Y inner — the v1 convention, kept: the second index is the map's
// north/south axis and the server consumes it as world Z.
int n = bp.MapSize;
for (int x = 0; x < n; x++)
for (int y = 0; y < n; y++)
writer.Write(bp.HeightMap[x, y]);
}
private static void WriteBiomes(BinaryWriter writer, WorldBlueprint bp)
{
int n = bp.MapSize;
for (int x = 0; x < n; x++)
{
for (int y = 0; y < n; y++)
{
int ordinal = (int)bp.BiomeMap[x, y];
if (ordinal < 0 || ordinal > byte.MaxValue)
throw new InvalidDataException(
$"[BlueprintWriter] Biome ordinal {ordinal} at ({x},{y}) does not fit in a byte.");
writer.Write((byte)ordinal);
}
}
}
private static void WriteTowns(BinaryWriter writer, WorldBlueprint bp)
{
writer.Write(bp.Towns.Count);
foreach (TownLocation town in bp.Towns)
{
int tier = (int)town.Tier;
if (tier < 0 || tier > byte.MaxValue)
throw new InvalidDataException(
$"[BlueprintWriter] TownTier ordinal {tier} does not fit in a byte.");
writer.Write(town.Position.X);
writer.Write(town.Position.Y);
writer.Write((byte)tier);
writer.Write(town.IsHighwayNode ? (byte)1 : (byte)0);
}
}
private static void WriteRoadTier(BinaryWriter writer, System.Collections.Generic.List<Vector2[]> paths)
{
writer.Write(paths.Count);
foreach (Vector2[] path in paths)
{
writer.Write(path.Length);
foreach (Vector2 p in path) { writer.Write(p.X); writer.Write(p.Y); }
}
}
/// <summary>
/// Best-effort short hash of the generator repo (reads res://.git directly, no
/// git invocation). Returns "" when unavailable — e.g. an exported build.
/// </summary>
private static string TryGetGitShortHash()
{
try
{
string gitDir = Path.Combine(ProjectSettings.GlobalizePath("res://"), ".git");
string head = File.ReadAllText(Path.Combine(gitDir, "HEAD")).Trim();
if (head.StartsWith("ref: "))
{
string refPath = Path.Combine(gitDir, head.Substring(5));
if (!File.Exists(refPath)) return "";
head = File.ReadAllText(refPath).Trim();
}
return head.Length >= 8 ? head.Substring(0, 8) : head;
}
catch
{
return "";
}
}
}
}

61
Core/Scripts/MapDataParser.cs
View file

@ -11,6 +11,29 @@ namespace IslaApocalypse.Core
{
public Vector2 Position;
public TownTier Tier;
// Whether the generator marked this settlement as a highway node (it drives the
// road topology at generation time). Carried by the v2 blueprint; always false
// when loading a legacy v1 file, which never stored it. Nothing server-side
// consumes it yet — it is carried and exposed, not acted on.
public bool IsHighwayNode;
}
/// <summary>
/// The resolved generation inputs embedded in a v2 blueprint, so a file is
/// self-describing and config desync is detectable. Null on a legacy v1 load.
/// A v2 file re-encoded from a v1 source carries the BlueprintFormat sentinel
/// values instead of real inputs.
/// </summary>
public class BlueprintParams
{
public int WorldSeed; // the generator's RESOLVED noise seed (names the file)
public int MapSize;
public float CraterRadius;
public float DensityMultiplier;
public Vector2 ImpactCenter; // the crater's _impactCenter, in map pixels
public string GeneratedUtc = ""; // stamped at write time, ISO-8601
public string GeneratorGitHash = ""; // short hash of the generator repo, "" if unknown
}
public class WorldBlueprint
@ -19,12 +42,17 @@ namespace IslaApocalypse.Core
public float[,] HeightMap;
public Biome[,] BiomeMap;
public List<TownLocation> Towns = new List<TownLocation>();
// All 4 road tiers!
public List<Vector2[]> Highways = new List<Vector2[]>();
public List<Vector2[]> BranchRoads = new List<Vector2[]>();
public List<Vector2[]> RuggedRoads = new List<Vector2[]>();
public List<Vector2[]> TrailRoads = new List<Vector2[]>();
// Which on-disk format this blueprint was parsed from (1 or 2), and the embedded
// generation parameters. Params is null when the source was a legacy v1 file.
public int FormatVersion = 1;
public BlueprintParams Params;
}
// 2. The Parser Utility
@ -33,18 +61,41 @@ namespace IslaApocalypse.Core
public static WorldBlueprint LoadMapData(string seedStr)
{
string filePath = ProjectSettings.GlobalizePath($"user://MapData_Seed_{seedStr}.dat");
return LoadMapDataFromPath(filePath);
}
/// <summary>
/// Loads a blueprint from an explicit absolute path. Same result as LoadMapData;
/// exists so tooling (the round-trip harness) can load files that do not follow
/// the seed-derived naming.
/// </summary>
public static WorldBlueprint LoadMapDataFromPath(string filePath)
{
if (!File.Exists(filePath))
{
GD.PrintErr($"[MapDataParser] CRITICAL ERROR: Map file not found at {filePath}");
return null;
}
WorldBlueprint blueprint = new WorldBlueprint();
using (FileStream stream = File.OpenRead(filePath))
{
using (BinaryReader reader = new BinaryReader(stream))
{
return LoadV1(reader);
}
}
}
// ===============================================================
// LEGACY v1 PARSE PATH — the original "ISLA_V1" positional format.
// Kept intact and untouched; do not extend it. New content belongs
// in the v2 tagged-section format.
// ===============================================================
private static WorldBlueprint LoadV1(BinaryReader reader)
{
WorldBlueprint blueprint = new WorldBlueprint();
{
{
// 1. Header Validation (CRITICAL: Must read string first to align bytes!)
string header = reader.ReadString();
@ -122,7 +173,7 @@ namespace IslaApocalypse.Core
}
}
GD.Print($"[MapDataParser] Successfully loaded Blueprint for Seed {seedStr}. Dimension: {blueprint.MapSize}x{blueprint.MapSize}.");
GD.Print($"[MapDataParser] Successfully loaded v1 Blueprint. Dimension: {blueprint.MapSize}x{blueprint.MapSize}.");
return blueprint;
}
}