Define writing and symbol data model (#17)

src/main/java/net/dnorberg/rivencraft/Rivencraft.java

@@ -18,6 +18,7 @@ import net.dnorberg.rivencraft.config.RivencraftClientConfig;
 import net.dnorberg.rivencraft.book.AgeDimensionService;
 import net.dnorberg.rivencraft.book.AgeWeatherService;
 import net.dnorberg.rivencraft.book.AgeRuntimeProfiles;
+import net.dnorberg.rivencraft.writing.SymbolCatalog;
 import net.neoforged.bus.api.IEventBus;
 import net.neoforged.fml.ModContainer;
 import net.neoforged.fml.common.Mod;
@@ -50,6 +51,7 @@ public final class Rivencraft {
         NeoForge.EVENT_BUS.addListener(AgeLifecycleEvents::onServerStopping);
         NeoForge.EVENT_BUS.addListener(RivencraftCommands::register);
         NeoForge.EVENT_BUS.addListener(AgeRuntimeProfiles::register);
+        NeoForge.EVENT_BUS.addListener(SymbolCatalog::register);
         LOGGER.info("Initializing Rivencraft");
     }
 }

src/main/java/net/dnorberg/rivencraft/gametest/WritingDataGameTests.java

@@ -0,0 +1,69 @@
+package net.dnorberg.rivencraft.gametest;
+
+import com.mojang.serialization.JsonOps;
+import io.netty.buffer.Unpooled;
+import java.util.List;
+import net.dnorberg.rivencraft.Rivencraft;
+import net.dnorberg.rivencraft.writing.OrderedWriting;
+import net.dnorberg.rivencraft.writing.SymbolCatalog;
+import net.dnorberg.rivencraft.writing.SymbolReference;
+import net.dnorberg.rivencraft.writing.WritingEntry;
+import net.minecraft.gametest.framework.GameTest;
+import net.minecraft.gametest.framework.GameTestHelper;
+import net.minecraft.network.FriendlyByteBuf;
+import net.minecraft.resources.ResourceLocation;
+import net.neoforged.neoforge.gametest.GameTestHolder;
+import net.neoforged.neoforge.gametest.PrefixGameTestTemplate;
+
+/** Acceptance coverage for Milestone 4's persistent writing contracts. */
+@GameTestHolder(Rivencraft.MOD_ID)
+@PrefixGameTestTemplate(false)
+public final class WritingDataGameTests {
+    private WritingDataGameTests() {
+    }
+
+    @GameTest(template = "empty")
+    public static void orderedWritingPreservesKnownUnknownAndLinkPanelEntries(GameTestHelper helper) {
+        SymbolReference known = reference("rivencraft:terrain/standard");
+        SymbolReference unknown = reference("example:removed_symbol");
+        OrderedWriting original = new OrderedWriting(List.of(
+                WritingEntry.symbol(known),
+                WritingEntry.symbol(unknown),
+                WritingEntry.linkPanel()
+        ));
+
+        var json = OrderedWriting.CODEC.encodeStart(JsonOps.INSTANCE, original).result().orElseThrow();
+        OrderedWriting persistentCopy = OrderedWriting.CODEC.parse(JsonOps.INSTANCE, json).result().orElseThrow();
+        helper.assertValueEqual(persistentCopy, original,
+                "Persistent writing codec must retain entry order and unknown symbol IDs");
+
+        FriendlyByteBuf buffer = new FriendlyByteBuf(Unpooled.buffer());
+        OrderedWriting.STREAM_CODEC.encode(buffer, original);
+        OrderedWriting networkCopy = OrderedWriting.STREAM_CODEC.decode(buffer);
+        helper.assertValueEqual(networkCopy, original,
+                "Network writing codec must retain entry order and unknown symbol IDs");
+        helper.succeed();
+    }
+
+    @GameTest(template = "empty")
+    public static void serverCatalogResolvesBuiltinsAndKeepsUnknownReferencesReadable(GameTestHelper helper) {
+        SymbolReference known = reference("rivencraft:terrain/standard");
+        SymbolReference unknown = reference("example:removed_symbol");
+        helper.assertTrue(SymbolCatalog.symbols().size() >= 6,
+                "The built-in catalog must exercise every Milestone 4 writing workflow");
+        helper.assertTrue(SymbolCatalog.isKnown(known),
+                "The built-in Standard Terrain symbol must be server-authoritative");
+        helper.assertFalse(SymbolCatalog.isKnown(unknown),
+                "An absent data-pack symbol must remain unresolved");
+        var unresolved = SymbolCatalog.display(unknown);
+        helper.assertFalse(unresolved.resolved(),
+                "Unknown symbol display metadata must be marked unresolved");
+        helper.assertValueEqual(unresolved.id(), unknown.id(),
+                "Unresolved display metadata must preserve the original namespaced ID");
+        helper.succeed();
+    }
+
+    private static SymbolReference reference(String id) {
+        return new SymbolReference(ResourceLocation.parse(id));
+    }
+}

src/main/java/net/dnorberg/rivencraft/writing/OrderedWriting.java

@@ -0,0 +1,47 @@
+package net.dnorberg.rivencraft.writing;
+
+import com.mojang.serialization.Codec;
+import com.mojang.serialization.DataResult;
+import io.netty.buffer.ByteBuf;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+import net.minecraft.network.codec.ByteBufCodecs;
+import net.minecraft.network.codec.StreamCodec;
+
+/** Immutable ordered writing shared by pages, notebooks, desks, and books. */
+public record OrderedWriting(List<WritingEntry> entries) {
+    public static final int MAX_ENTRIES = 256;
+    public static final OrderedWriting EMPTY = new OrderedWriting(List.of());
+    public static final Codec<OrderedWriting> CODEC = WritingEntry.CODEC.listOf()
+            .validate(entries -> entries.size() <= MAX_ENTRIES
+                    ? DataResult.success(entries)
+                    : DataResult.error(() -> "Writing exceeds " + MAX_ENTRIES + " entries"))
+            .xmap(OrderedWriting::new, OrderedWriting::entries);
+    public static final StreamCodec<ByteBuf, OrderedWriting> STREAM_CODEC = StreamCodec.of(
+            OrderedWriting::encode, OrderedWriting::decode);
+
+    public OrderedWriting {
+        entries = List.copyOf(Objects.requireNonNull(entries, "entries"));
+        if (entries.size() > MAX_ENTRIES) {
+            throw new IllegalArgumentException("Writing exceeds " + MAX_ENTRIES + " entries");
+        }
+    }
+
+    private static void encode(ByteBuf buffer, OrderedWriting writing) {
+        ByteBufCodecs.VAR_INT.encode(buffer, writing.entries.size());
+        writing.entries.forEach(entry -> WritingEntry.STREAM_CODEC.encode(buffer, entry));
+    }
+
+    private static OrderedWriting decode(ByteBuf buffer) {
+        int size = ByteBufCodecs.VAR_INT.decode(buffer);
+        if (size < 0 || size > MAX_ENTRIES) {
+            throw new IllegalArgumentException("Invalid writing entry count " + size);
+        }
+        List<WritingEntry> entries = new ArrayList<>(size);
+        for (int index = 0; index < size; index++) {
+            entries.add(WritingEntry.STREAM_CODEC.decode(buffer));
+        }
+        return new OrderedWriting(entries);
+    }
+}

src/main/java/net/dnorberg/rivencraft/writing/SymbolCatalog.java

@@ -0,0 +1,67 @@
+package net.dnorberg.rivencraft.writing;
+
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import com.google.gson.JsonElement;
+import com.mojang.serialization.JsonOps;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+import net.dnorberg.rivencraft.Rivencraft;
+import net.minecraft.resources.ResourceLocation;
+import net.minecraft.server.packs.resources.ResourceManager;
+import net.minecraft.server.packs.resources.SimpleJsonResourceReloadListener;
+import net.minecraft.util.profiling.ProfilerFiller;
+import net.neoforged.neoforge.event.AddReloadListenerEvent;
+
+/** Authoritative server catalog loaded from data/<namespace>/rivencraft/symbols. */
+public final class SymbolCatalog {
+    private static final Gson GSON = new GsonBuilder().create();
+    private static final String DIRECTORY = "rivencraft/symbols";
+    private static volatile Map<ResourceLocation, SymbolDefinition> symbols = Map.of();
+
+    private SymbolCatalog() {
+    }
+
+    public static void register(AddReloadListenerEvent event) {
+        event.addListener(new Loader());
+    }
+
+    public static Optional<SymbolDefinition> find(SymbolReference reference) {
+        return Optional.ofNullable(symbols.get(reference.id()));
+    }
+
+    public static boolean isKnown(SymbolReference reference) {
+        return symbols.containsKey(reference.id());
+    }
+
+    public static SymbolDisplayMetadata display(SymbolReference reference) {
+        SymbolDefinition definition = symbols.get(reference.id());
+        return definition == null
+                ? SymbolDisplayMetadata.unresolved(reference)
+                : definition.display(reference.id());
+    }
+
+    public static Map<ResourceLocation, SymbolDefinition> symbols() {
+        return symbols;
+    }
+
+    private static final class Loader extends SimpleJsonResourceReloadListener {
+        private Loader() {
+            super(GSON, DIRECTORY);
+        }
+
+        @Override
+        protected void apply(Map<ResourceLocation, JsonElement> resources,
+                             ResourceManager resourceManager,
+                             ProfilerFiller profiler) {
+            Map<ResourceLocation, SymbolDefinition> loaded = new HashMap<>();
+            resources.forEach((id, json) -> SymbolDefinition.CODEC.parse(JsonOps.INSTANCE, json)
+                    .resultOrPartial(error -> Rivencraft.LOGGER.error(
+                            "Ignoring invalid writing symbol {}: {}", id, error))
+                    .ifPresent(definition -> loaded.put(id, definition)));
+            symbols = Map.copyOf(loaded);
+            Rivencraft.LOGGER.info("Loaded {} writing symbols", loaded.size());
+        }
+    }
+}

src/main/java/net/dnorberg/rivencraft/writing/SymbolDefinition.java

@@ -0,0 +1,47 @@
+package net.dnorberg.rivencraft.writing;
+
+import com.mojang.serialization.Codec;
+import com.mojang.serialization.DataResult;
+import com.mojang.serialization.codecs.RecordCodecBuilder;
+import java.util.Objects;
+import java.util.regex.Pattern;
+import net.minecraft.resources.ResourceLocation;
+
+/** Server-loaded, non-executable display metadata for a writing symbol. */
+public record SymbolDefinition(
+        int schemaVersion,
+        String nameTranslationKey,
+        String descriptionTranslationKey,
+        ResourceLocation category
+) {
+    public static final int CURRENT_SCHEMA_VERSION = 1;
+    private static final Pattern TRANSLATION_KEY = Pattern.compile("[a-z0-9_.-]+");
+    private static final Codec<String> TRANSLATION_KEY_CODEC = Codec.STRING.comapFlatMap(
+            value -> TRANSLATION_KEY.matcher(value).matches()
+                    ? DataResult.success(value)
+                    : DataResult.error(() -> "Invalid translation key: " + value),
+            value -> value
+    );
+    public static final Codec<SymbolDefinition> CODEC = RecordCodecBuilder.<SymbolDefinition>create(instance -> instance.group(
+            Codec.INT.fieldOf("schema_version").forGetter(SymbolDefinition::schemaVersion),
+            TRANSLATION_KEY_CODEC.fieldOf("name").forGetter(SymbolDefinition::nameTranslationKey),
+            TRANSLATION_KEY_CODEC.fieldOf("description").forGetter(SymbolDefinition::descriptionTranslationKey),
+            ResourceLocation.CODEC.fieldOf("category").forGetter(SymbolDefinition::category)
+    ).apply(instance, SymbolDefinition::new)).flatXmap(SymbolDefinition::validate, SymbolDefinition::validate);
+
+    public SymbolDefinition {
+        Objects.requireNonNull(nameTranslationKey, "nameTranslationKey");
+        Objects.requireNonNull(descriptionTranslationKey, "descriptionTranslationKey");
+        Objects.requireNonNull(category, "category");
+    }
+
+    public SymbolDisplayMetadata display(ResourceLocation id) {
+        return new SymbolDisplayMetadata(id, nameTranslationKey, descriptionTranslationKey, category, true);
+    }
+
+    private static DataResult<SymbolDefinition> validate(SymbolDefinition definition) {
+        return definition.schemaVersion == CURRENT_SCHEMA_VERSION
+                ? DataResult.success(definition)
+                : DataResult.error(() -> "Unsupported symbol schema_version " + definition.schemaVersion);
+    }
+}

src/main/java/net/dnorberg/rivencraft/writing/SymbolDisplayMetadata.java

@@ -0,0 +1,44 @@
+package net.dnorberg.rivencraft.writing;
+
+import com.mojang.serialization.Codec;
+import com.mojang.serialization.codecs.RecordCodecBuilder;
+import io.netty.buffer.ByteBuf;
+import net.dnorberg.rivencraft.Rivencraft;
+import net.minecraft.network.codec.ByteBufCodecs;
+import net.minecraft.network.codec.StreamCodec;
+import net.minecraft.resources.ResourceLocation;
+
+/** Client-safe symbol presentation selected by the authoritative server catalog. */
+public record SymbolDisplayMetadata(
+        ResourceLocation id,
+        String nameTranslationKey,
+        String descriptionTranslationKey,
+        ResourceLocation category,
+        boolean resolved
+) {
+    public static final Codec<SymbolDisplayMetadata> CODEC = RecordCodecBuilder.create(instance -> instance.group(
+            ResourceLocation.CODEC.fieldOf("id").forGetter(SymbolDisplayMetadata::id),
+            Codec.STRING.fieldOf("name").forGetter(SymbolDisplayMetadata::nameTranslationKey),
+            Codec.STRING.fieldOf("description").forGetter(SymbolDisplayMetadata::descriptionTranslationKey),
+            ResourceLocation.CODEC.fieldOf("category").forGetter(SymbolDisplayMetadata::category),
+            Codec.BOOL.fieldOf("resolved").forGetter(SymbolDisplayMetadata::resolved)
+    ).apply(instance, SymbolDisplayMetadata::new));
+    public static final StreamCodec<ByteBuf, SymbolDisplayMetadata> STREAM_CODEC = StreamCodec.composite(
+            ResourceLocation.STREAM_CODEC, SymbolDisplayMetadata::id,
+            ByteBufCodecs.STRING_UTF8, SymbolDisplayMetadata::nameTranslationKey,
+            ByteBufCodecs.STRING_UTF8, SymbolDisplayMetadata::descriptionTranslationKey,
+            ResourceLocation.STREAM_CODEC, SymbolDisplayMetadata::category,
+            ByteBufCodecs.BOOL, SymbolDisplayMetadata::resolved,
+            SymbolDisplayMetadata::new
+    );
+
+    public static SymbolDisplayMetadata unresolved(SymbolReference reference) {
+        return new SymbolDisplayMetadata(
+                reference.id(),
+                "symbol.rivencraft.unresolved",
+                "symbol.rivencraft.unresolved.description",
+                ResourceLocation.fromNamespaceAndPath(Rivencraft.MOD_ID, "unresolved"),
+                false
+        );
+    }
+}

src/main/java/net/dnorberg/rivencraft/writing/SymbolReference.java

@@ -0,0 +1,24 @@
+package net.dnorberg.rivencraft.writing;
+
+import com.mojang.serialization.Codec;
+import io.netty.buffer.ByteBuf;
+import java.util.Objects;
+import net.minecraft.network.codec.StreamCodec;
+import net.minecraft.resources.ResourceLocation;
+
+/** Stable namespaced identity for one writing symbol. */
+public record SymbolReference(ResourceLocation id) {
+    public static final Codec<SymbolReference> CODEC = ResourceLocation.CODEC.xmap(
+            SymbolReference::new, SymbolReference::id);
+    public static final StreamCodec<ByteBuf, SymbolReference> STREAM_CODEC = ResourceLocation.STREAM_CODEC.map(
+            SymbolReference::new, SymbolReference::id);
+
+    public SymbolReference {
+        Objects.requireNonNull(id, "id");
+    }
+
+    /** Remains useful when the defining data pack has been removed. */
+    public String unresolvedName() {
+        return id.toString();
+    }
+}

src/main/java/net/dnorberg/rivencraft/writing/WritingEntry.java

@@ -0,0 +1,82 @@
+package net.dnorberg.rivencraft.writing;
+
+import com.mojang.serialization.Codec;
+import com.mojang.serialization.DataResult;
+import com.mojang.serialization.codecs.RecordCodecBuilder;
+import io.netty.buffer.ByteBuf;
+import java.util.Locale;
+import java.util.Objects;
+import java.util.Optional;
+import net.minecraft.network.codec.ByteBufCodecs;
+import net.minecraft.network.codec.StreamCodec;
+
+/** One ordered unit of book writing. Interpretation belongs to Milestone 5. */
+public record WritingEntry(Kind kind, Optional<SymbolReference> symbol) {
+    private static final Codec<Kind> KIND_CODEC = Codec.STRING.comapFlatMap(
+            value -> {
+                try {
+                    return DataResult.success(Kind.valueOf(value.toUpperCase(Locale.ROOT)));
+                } catch (IllegalArgumentException exception) {
+                    return DataResult.error(() -> "Unknown writing entry kind: " + value);
+                }
+            },
+            value -> value.name().toLowerCase(Locale.ROOT)
+    );
+    private static final Codec<WritingEntry> RECORD_CODEC = RecordCodecBuilder.create(instance -> instance.group(
+            KIND_CODEC.fieldOf("kind").forGetter(WritingEntry::kind),
+            SymbolReference.CODEC.optionalFieldOf("symbol").forGetter(WritingEntry::symbol)
+    ).apply(instance, WritingEntry::new));
+    public static final Codec<WritingEntry> CODEC = RECORD_CODEC.flatXmap(
+            WritingEntry::validate, WritingEntry::validate);
+    public static final StreamCodec<ByteBuf, WritingEntry> STREAM_CODEC = StreamCodec.of(
+            WritingEntry::encode, WritingEntry::decode);
+
+    public WritingEntry {
+        Objects.requireNonNull(kind, "kind");
+        symbol = Objects.requireNonNull(symbol, "symbol");
+        if (kind == Kind.SYMBOL && symbol.isEmpty()) {
+            throw new IllegalArgumentException("Symbol writing entries require a symbol reference");
+        }
+        if (kind == Kind.LINK_PANEL && symbol.isPresent()) {
+            throw new IllegalArgumentException("Link-panel writing entries cannot contain a symbol reference");
+        }
+    }
+
+    public static WritingEntry symbol(SymbolReference symbol) {
+        return new WritingEntry(Kind.SYMBOL, Optional.of(symbol));
+    }
+
+    public static WritingEntry linkPanel() {
+        return new WritingEntry(Kind.LINK_PANEL, Optional.empty());
+    }
+
+    private static DataResult<WritingEntry> validate(WritingEntry entry) {
+        return entry.kind == Kind.SYMBOL && entry.symbol.isEmpty()
+                || entry.kind == Kind.LINK_PANEL && entry.symbol.isPresent()
+                ? DataResult.error(() -> "Writing entry contents do not match kind " + entry.kind)
+                : DataResult.success(entry);
+    }
+
+    private static void encode(ByteBuf buffer, WritingEntry entry) {
+        ByteBufCodecs.VAR_INT.encode(buffer, entry.kind.ordinal());
+        if (entry.kind == Kind.SYMBOL) {
+            SymbolReference.STREAM_CODEC.encode(buffer, entry.symbol.orElseThrow());
+        }
+    }
+
+    private static WritingEntry decode(ByteBuf buffer) {
+        int ordinal = ByteBufCodecs.VAR_INT.decode(buffer);
+        if (ordinal < 0 || ordinal >= Kind.values().length) {
+            throw new IllegalArgumentException("Unknown writing entry kind ordinal " + ordinal);
+        }
+        Kind kind = Kind.values()[ordinal];
+        return kind == Kind.SYMBOL
+                ? symbol(SymbolReference.STREAM_CODEC.decode(buffer))
+                : linkPanel();
+    }
+
+    public enum Kind {
+        SYMBOL,
+        LINK_PANEL
+    }
+}

src/main/resources/assets/rivencraft/lang/en_us.json

@@ -57,6 +57,20 @@
   "trait.rivencraft.weather.snow": "Snow",
   "trait.rivencraft.weather.storm": "Storm",
   "trait.rivencraft.day_length.stopped": "Stopped",
+  "symbol.rivencraft.unresolved": "Unresolved Symbol",
+  "symbol.rivencraft.unresolved.description": "Missing symbol: %s",
+  "symbol.rivencraft.terrain.standard": "Standard Terrain",
+  "symbol.rivencraft.terrain.standard.description": "A familiar continental terrain foundation.",
+  "symbol.rivencraft.biome.native": "Native Biomes",
+  "symbol.rivencraft.biome.native.description": "Use the terrain profile's native biome climate.",
+  "symbol.rivencraft.lighting.normal": "Normal Lighting",
+  "symbol.rivencraft.lighting.normal.description": "Use normal skylight and ambient brightness.",
+  "symbol.rivencraft.weather.normal": "Normal Weather",
+  "symbol.rivencraft.weather.normal.description": "Use the normal weather cycle.",
+  "symbol.rivencraft.celestial.normal_time": "Normal Time",
+  "symbol.rivencraft.celestial.normal_time.description": "Use a normal-length celestial cycle.",
+  "symbol.rivencraft.feature.caves": "Caves",
+  "symbol.rivencraft.feature.caves.description": "Describe underground cave features.",
   "generator.rivencraft.standard": "Standard",
   "generator.rivencraft.amplified": "Amplified",
   "generator.rivencraft.island": "Island",

src/main/resources/data/rivencraft/rivencraft/symbols/biome/native.json

@@ -0,0 +1,6 @@
+{
+  "schema_version": 1,
+  "name": "symbol.rivencraft.biome.native",
+  "description": "symbol.rivencraft.biome.native.description",
+  "category": "rivencraft:biome"
+}

src/main/resources/data/rivencraft/rivencraft/symbols/celestial/normal_time.json

@@ -0,0 +1,6 @@
+{
+  "schema_version": 1,
+  "name": "symbol.rivencraft.celestial.normal_time",
+  "description": "symbol.rivencraft.celestial.normal_time.description",
+  "category": "rivencraft:celestial"
+}

src/main/resources/data/rivencraft/rivencraft/symbols/feature/caves.json

@@ -0,0 +1,6 @@
+{
+  "schema_version": 1,
+  "name": "symbol.rivencraft.feature.caves",
+  "description": "symbol.rivencraft.feature.caves.description",
+  "category": "rivencraft:feature"
+}

src/main/resources/data/rivencraft/rivencraft/symbols/lighting/normal.json

@@ -0,0 +1,6 @@
+{
+  "schema_version": 1,
+  "name": "symbol.rivencraft.lighting.normal",
+  "description": "symbol.rivencraft.lighting.normal.description",
+  "category": "rivencraft:lighting"
+}

src/main/resources/data/rivencraft/rivencraft/symbols/terrain/standard.json

@@ -0,0 +1,6 @@
+{
+  "schema_version": 1,
+  "name": "symbol.rivencraft.terrain.standard",
+  "description": "symbol.rivencraft.terrain.standard.description",
+  "category": "rivencraft:terrain"
+}

src/main/resources/data/rivencraft/rivencraft/symbols/weather/normal.json

@@ -0,0 +1,6 @@
+{
+  "schema_version": 1,
+  "name": "symbol.rivencraft.weather.normal",
+  "description": "symbol.rivencraft.weather.normal.description",
+  "category": "rivencraft:weather"
+}