feat(hytale): add pinned adapter and reproducible build

2026-08-15 08:50:58 +02:00
parent 098ce5caa4
commit ce313d372a
17 changed files with 824 additions and 0 deletions
@@ -0,0 +1,65 @@
+plugins {
+    `java-library`
+}
+
+dependencies {
+    api(project(":engine"))
+    implementation(project(":content-pokemon"))
+
+    compileOnly("com.hypixel.hytale:Server:0.5.9")
+    implementation("com.fasterxml.jackson.core:jackson-databind:2.20.0")
+
+    testImplementation(platform("org.junit:junit-bom:6.0.0"))
+    testImplementation("org.junit.jupiter:junit-jupiter")
+    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
+    testImplementation("org.assertj:assertj-core:3.27.6")
+}
+
+tasks.jar {
+    enabled = false
+}
+
+val fanModJar = tasks.register<Jar>("fanModJar") {
+    group = "build"
+    description = "Packages the unofficial non-commercial fan plugin and embedded asset pack."
+    dependsOn(configurations.runtimeClasspath)
+    archiveBaseName.set("ProjectCapture")
+    archiveClassifier.set("fan-dev")
+    duplicatesStrategy = DuplicatesStrategy.EXCLUDE
+
+    from(sourceSets.main.get().output)
+    from({
+        configurations.runtimeClasspath.get()
+            .filter { it.exists() }
+            .map { if (it.isDirectory) it else zipTree(it) }
+    })
+
+    exclude("META-INF/*.SF", "META-INF/*.DSA", "META-INF/*.RSA")
+    manifest {
+        attributes["Implementation-Title"] = "ProjectCapture Unofficial Fan Project"
+        attributes["Implementation-Version"] = project.version
+        attributes["ProjectCapture-Distribution"] = "UNOFFICIAL-NONCOMMERCIAL"
+    }
+}
+
+tasks.assemble {
+    dependsOn(fanModJar)
+}
+
+tasks.register<Copy>("installToDevMods") {
+    group = "development"
+    description = "Copies the fan mod only into an explicitly configured isolated dev Mods directory."
+    dependsOn(fanModJar)
+
+    val configuredModsDir = providers.gradleProperty("projectCapture.devModsDir")
+    onlyIf {
+        if (!configuredModsDir.isPresent) {
+            logger.lifecycle("Skipping install: set -PprojectCapture.devModsDir=<isolated Mods directory>.")
+            false
+        } else {
+            true
+        }
+    }
+    from(fanModJar.flatMap { it.archiveFile })
+    into(configuredModsDir)
+}
@@ -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);
+    }
+}
+
@@ -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;
+    }
+}
+
@@ -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);
+        }
+    }
+}
@@ -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);
+}
@@ -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) {}
+}
+
@@ -0,0 +1,10 @@
+{
+  "schemaVersion": 1,
+  "namespace": "projectcapture",
+  "distribution": "UNOFFICIAL_NONCOMMERCIAL_FAN_PROJECT",
+  "unofficialFanContent": true,
+  "nonCommercial": true,
+  "rightsReviewRequired": true,
+  "contentModule": "content-pokemon",
+  "notes": "Runtime-facing index only. Definitions are original ProjectCapture production files; Pokemon ownership remains with the respective rights holders."
+}
@@ -0,0 +1,17 @@
+{
+  "Group": "dev.projectcapture",
+  "Name": "ProjectCapture",
+  "Version": "0.1.0",
+  "Description": "Unofficial, open-source and non-commercial Pokemon fan mod",
+  "Authors": [
+    {
+      "Name": "Christian Schindler"
+    }
+  ],
+  "ServerVersion": "0.5.9",
+  "Dependencies": {},
+  "OptionalDependencies": {},
+  "DisabledByDefault": false,
+  "IncludesAssetPack": true,
+  "Main": "dev.projectcapture.hytale.ProjectCapturePlugin"
+}
@@ -0,0 +1,45 @@
+package dev.projectcapture.hytale.persistence;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import java.nio.file.Path;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+class JsonStateStoreTest {
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+
+    @TempDir
+    Path temporaryDirectory;
+
+    @Test
+    void roundTripsVersionedState() {
+        JsonStateStore store = new JsonStateStore(temporaryDirectory);
+        store.initialize();
+        store.write("player-01", MAPPER.createObjectNode().put("partySize", 6));
+
+        assertThat(store.read("player-01").path("partySize").asInt()).isEqualTo(6);
+    }
+
+    @Test
+    void rejectsFilesystemPathsAsSaveIds() {
+        JsonStateStore store = new JsonStateStore(temporaryDirectory);
+        store.initialize();
+
+        assertThatThrownBy(() -> store.write("../../launcher", MAPPER.createObjectNode()))
+            .isInstanceOf(IllegalArgumentException.class)
+            .hasMessageContaining("Invalid logical save id");
+    }
+
+    @Test
+    void missingStateReturnsNull() {
+        JsonStateStore store = new JsonStateStore(temporaryDirectory);
+        store.initialize();
+
+        assertThat(store.read("missing")).isNull();
+    }
+}
+