feat(hytale): add pinned adapter and reproducible build

hytale-adapter/src/main/java/dev/projectcapture/hytale/FeatureFlags.java

@@ -0,0 +1,13 @@
+package dev.projectcapture.hytale;
+
+/** Keeps unstable Hytale API features outside the stable 0.5.9 integration. */
+public record FeatureFlags(
+    boolean updateSixPersistentResources,
+    boolean updateSixCustomBattleUi,
+    boolean updateSixServerCamera
+) {
+    public static FeatureFlags stableRelease() {
+        return new FeatureFlags(false, false, false);
+    }
+}
+

hytale-adapter/src/main/java/dev/projectcapture/hytale/ProjectCapturePlugin.java

@@ -0,0 +1,37 @@
+package dev.projectcapture.hytale;
+
+import com.hypixel.hytale.server.core.plugin.JavaPlugin;
+import com.hypixel.hytale.server.core.plugin.JavaPluginInit;
+import dev.projectcapture.hytale.persistence.JsonStateStore;
+
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * Thin Hytale entry point. Domain behavior lives in {@code engine}; this class
+ * owns only Hytale lifecycle and adapter wiring.
+ */
+public final class ProjectCapturePlugin extends JavaPlugin {
+    private final JsonStateStore stateStore;
+    private final FeatureFlags featureFlags;
+
+    public ProjectCapturePlugin(JavaPluginInit init) {
+        super(init);
+        this.stateStore = new JsonStateStore(init.getDataDirectory());
+        this.featureFlags = FeatureFlags.stableRelease();
+    }
+
+    @Override
+    public CompletableFuture<Void> preLoad() {
+        stateStore.initialize();
+        return CompletableFuture.completedFuture(null);
+    }
+
+    JsonStateStore stateStore() {
+        return stateStore;
+    }
+
+    FeatureFlags featureFlags() {
+        return featureFlags;
+    }
+}
+

hytale-adapter/src/main/java/dev/projectcapture/hytale/persistence/JsonStateStore.java

@@ -0,0 +1,107 @@
+package dev.projectcapture.hytale.persistence;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.SerializationFeature;
+
+import java.io.IOException;
+import java.nio.file.AtomicMoveNotSupportedException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
+import java.util.Objects;
+
+/**
+ * Atomic JSON persistence rooted in Hytale's plugin data directory. Paths are
+ * logical save identifiers, never caller-controlled filesystem paths.
+ */
+public final class JsonStateStore {
+    public static final int CURRENT_SCHEMA_VERSION = 1;
+
+    private final Path root;
+    private final ObjectMapper mapper;
+
+    public JsonStateStore(Path pluginDataDirectory) {
+        this.root = Objects.requireNonNull(pluginDataDirectory, "pluginDataDirectory")
+            .toAbsolutePath()
+            .normalize()
+            .resolve("state");
+        this.mapper = new ObjectMapper().enable(SerializationFeature.INDENT_OUTPUT);
+    }
+
+    public void initialize() {
+        try {
+            Files.createDirectories(root);
+        } catch (IOException exception) {
+            throw new StateStoreException("Unable to initialize ProjectCapture state directory", exception);
+        }
+    }
+
+    public synchronized void write(String saveId, JsonNode payload) {
+        Path destination = resolveSaveId(saveId);
+        Path temporary = destination.resolveSibling(destination.getFileName() + ".tmp");
+        try {
+            Files.createDirectories(destination.getParent());
+            mapper.writeValue(temporary.toFile(), new StateEnvelope(CURRENT_SCHEMA_VERSION, payload));
+            try {
+                Files.move(
+                    temporary,
+                    destination,
+                    StandardCopyOption.ATOMIC_MOVE,
+                    StandardCopyOption.REPLACE_EXISTING
+                );
+            } catch (AtomicMoveNotSupportedException ignored) {
+                Files.move(temporary, destination, StandardCopyOption.REPLACE_EXISTING);
+            }
+        } catch (IOException exception) {
+            throw new StateStoreException("Unable to persist save " + saveId, exception);
+        }
+    }
+
+    public synchronized JsonNode read(String saveId) {
+        Path source = resolveSaveId(saveId);
+        if (!Files.exists(source)) {
+            return null;
+        }
+        try {
+            StateEnvelope envelope = mapper.readValue(source.toFile(), StateEnvelope.class);
+            if (envelope.schemaVersion() != CURRENT_SCHEMA_VERSION) {
+                throw new StateStoreException(
+                    "Unsupported state schema " + envelope.schemaVersion() + " for " + saveId
+                );
+            }
+            return envelope.payload();
+        } catch (IOException exception) {
+            throw new StateStoreException("Unable to read save " + saveId, exception);
+        }
+    }
+
+    private Path resolveSaveId(String saveId) {
+        if (saveId == null || !saveId.matches("[a-z0-9][a-z0-9._-]{0,63}")) {
+            throw new IllegalArgumentException("Invalid logical save id");
+        }
+        Path result = root.resolve(saveId + ".json").normalize();
+        if (!result.startsWith(root)) {
+            throw new IllegalArgumentException("Save path escapes plugin state root");
+        }
+        return result;
+    }
+
+    public record StateEnvelope(int schemaVersion, JsonNode payload) {
+        public StateEnvelope {
+            Objects.requireNonNull(payload, "payload");
+        }
+    }
+
+    public static final class StateStoreException extends RuntimeException {
+        private static final long serialVersionUID = 1L;
+
+        public StateStoreException(String message) {
+            super(message);
+        }
+
+        public StateStoreException(String message, Throwable cause) {
+            super(message, cause);
+        }
+    }
+}

hytale-adapter/src/main/java/dev/projectcapture/hytale/ports/UiPort.java

@@ -0,0 +1,12 @@
+package dev.projectcapture.hytale.ports;
+
+import java.util.UUID;
+
+/** Server-driven UI boundary; no client mod or client hook is assumed. */
+public interface UiPort {
+    void showCaptureResult(UUID playerId, UUID creatureId, boolean captured);
+
+    void showBattleCommands(UUID playerId, UUID creatureId, String basicMove, String[] commandedMoves);
+
+    void showUnofficialFanProjectNotice(UUID playerId);
+}

hytale-adapter/src/main/java/dev/projectcapture/hytale/ports/WorldPort.java

@@ -0,0 +1,20 @@
+package dev.projectcapture.hytale.ports;
+
+import java.util.List;
+import java.util.UUID;
+
+/** Stable boundary between domain services and the evolving Hytale world API. */
+public interface WorldPort {
+    void spawnWildCreature(String speciesId, SpawnPoint point, long deterministicSeed);
+
+    void despawnCreature(UUID creatureId);
+
+    void setVisibleCompanion(UUID playerId, UUID creatureId);
+
+    void clearVisibleCompanion(UUID playerId);
+
+    List<SpawnPoint> eligibleSpawnPoints(String biomeId, String timeBand);
+
+    record SpawnPoint(String worldId, double x, double y, double z, String biomeId) {}
+}
+