object cleanup

core/src/main/java/art/arcane/iris/core/SettingsHotloadWatch.java

@@ -0,0 +1,294 @@
+package art.arcane.iris.core;
+
+import art.arcane.iris.core.localization.IrisLanguage;
+import art.arcane.iris.spi.IrisLogging;
+import art.arcane.volmlib.util.hotload.ConfigHotloadEngine;
+
+import java.io.File;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.ByteBuffer;
+import java.nio.charset.CharacterCodingException;
+import java.nio.charset.CodingErrorAction;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.NoSuchFileException;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Objects;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.function.BiConsumer;
+import java.util.function.Consumer;
+
+public final class SettingsHotloadWatch implements AutoCloseable {
+    public static final long POLL_PERIOD_MILLIS = 500L;
+    public static final long HOTLOAD_COOLDOWN_MILLIS = 3_000L;
+    private static final int MAX_HOTLOAD_BYTES = 2 * 1024 * 1024;
+    private static final Timing PRODUCTION_TIMING = new Timing(
+            POLL_PERIOD_MILLIS,
+            HOTLOAD_COOLDOWN_MILLIS,
+            ConfigHotloadEngine.DEFAULT_FULL_WATCH_SCAN_WINDOW_MS,
+            ConfigHotloadEngine.DEFAULT_SIGNATURE_SCAN_WINDOW_MS
+    );
+
+    private final File settingsFile;
+    private final File localeOverrideFolder;
+    private final ConfigHotloadEngine hotloadEngine;
+    private final Map<String, String> reportedCaptureFailures = new ConcurrentHashMap<>();
+    private final Consumer<ConfigHotloadEngine.StableContentSnapshot> beforeSnapshotApply;
+    private final BiConsumer<File, String> manualReloadListener;
+    private volatile boolean closed;
+
+    public SettingsHotloadWatch(File settingsFile) {
+        this(settingsFile, PRODUCTION_TIMING);
+    }
+
+    SettingsHotloadWatch(File settingsFile, Timing timing) {
+        this(settingsFile, timing, snapshot -> {
+        });
+    }
+
+    SettingsHotloadWatch(
+            File settingsFile,
+            Timing timing,
+            Consumer<ConfigHotloadEngine.StableContentSnapshot> beforeSnapshotApply
+    ) {
+        this.settingsFile = Objects.requireNonNull(settingsFile, "Settings file cannot be null").getAbsoluteFile();
+        File dataFolder = Objects.requireNonNull(this.settingsFile.getParentFile(), "Settings data folder cannot be null");
+        localeOverrideFolder = new File(dataFolder, "languages/overrides").getAbsoluteFile();
+        Timing resolvedTiming = Objects.requireNonNull(timing, "Hotload timing cannot be null");
+        this.beforeSnapshotApply = Objects.requireNonNull(beforeSnapshotApply, "Snapshot apply observer cannot be null");
+        manualReloadListener = this::acknowledgeManualLocaleReload;
+        hotloadEngine = new ConfigHotloadEngine(
+                this::isManagedFile,
+                this::knownFiles,
+                this::readContent,
+                this::normalizeContent,
+                resolvedTiming.fullScanWindowMillis(),
+                resolvedTiming.signatureScanWindowMillis()
+        );
+        hotloadEngine.configure(
+                resolvedTiming.pollPeriodMillis(),
+                resolvedTiming.cooldownMillis(),
+                List.of(this.settingsFile),
+                List.of(localeOverrideFolder)
+        );
+        IrisLanguage.addManualReloadListener(manualReloadListener);
+    }
+
+    public synchronized void checkConfigHotload() {
+        if (closed) {
+            return;
+        }
+        synchronized (IrisLanguage.class) {
+            try {
+                for (ConfigHotloadEngine.StableContentSnapshot snapshot : hotloadEngine.pollTouchedSnapshots()) {
+                    beforeSnapshotApply.accept(snapshot);
+                    hotloadEngine.processSnapshotChange(snapshot, this::applySnapshot, this::reportApplied);
+                }
+            } catch (RuntimeException failure) {
+                IrisLogging.error("Iris settings and locale hotload watcher failed: " + failureDetail(failure));
+                IrisLogging.reportError(failure);
+                failure.printStackTrace();
+            }
+        }
+    }
+
+    @Override
+    public synchronized void close() {
+        if (closed) {
+            return;
+        }
+        closed = true;
+        IrisLanguage.removeManualReloadListener(manualReloadListener);
+        hotloadEngine.clear();
+        reportedCaptureFailures.clear();
+    }
+
+    boolean applySnapshot(ConfigHotloadEngine.StableContentSnapshot snapshot) {
+        File file = snapshot.file();
+        boolean missing = "missing".equals(snapshot.signature());
+        if (isSettingsFile(file)) {
+            if (missing) {
+                IrisLogging.warn("settings.json was removed; retaining the last valid runtime settings.");
+                return true;
+            }
+            if (snapshot.normalizedContent() == null) {
+                reportUnavailableSnapshot(file);
+                return false;
+            }
+            return applySettingsSnapshot(file, snapshot.normalizedContent());
+        }
+        if (!isLocaleOverrideFile(file) || !IrisLanguage.isActiveOverrideFile(file)) {
+            return true;
+        }
+        if (!missing && snapshot.normalizedContent() == null) {
+            reportUnavailableSnapshot(file);
+            return false;
+        }
+        return applyLocaleSnapshot(file, missing ? null : snapshot.normalizedContent());
+    }
+
+    boolean isSettingsFile(File file) {
+        return file != null && settingsFile.equals(file.getAbsoluteFile());
+    }
+
+    boolean isLocaleOverrideFile(File file) {
+        if (file == null || !file.getName().toLowerCase(Locale.ROOT).endsWith(".json")) {
+            return false;
+        }
+        File parent = file.getAbsoluteFile().getParentFile();
+        return localeOverrideFolder.equals(parent);
+    }
+
+    private boolean isManagedFile(File file) {
+        return isSettingsFile(file) || isLocaleOverrideFile(file);
+    }
+
+    private Collection<File> knownFiles() {
+        List<File> files = new ArrayList<>();
+        files.add(settingsFile);
+        File[] overrides = localeOverrideFolder.listFiles();
+        if (overrides == null) {
+            return files;
+        }
+        for (File override : overrides) {
+            if (isLocaleOverrideFile(override) && override.isFile()) {
+                files.add(override.getAbsoluteFile());
+            }
+        }
+        return files;
+    }
+
+    private String readContent(File file) {
+        if (file == null) {
+            return null;
+        }
+        if (!file.isFile()) {
+            clearCaptureFailure(file);
+            return null;
+        }
+        try (InputStream input = Files.newInputStream(file.toPath())) {
+            byte[] content = input.readNBytes(MAX_HOTLOAD_BYTES + 1);
+            if (content.length > MAX_HOTLOAD_BYTES) {
+                throw new IOException("Hotload file exceeds " + MAX_HOTLOAD_BYTES + " bytes: " + file);
+            }
+            String decoded = decodeUtf8(content, file);
+            clearCaptureFailure(file);
+            return decoded;
+        } catch (NoSuchFileException missing) {
+            clearCaptureFailure(file);
+            return null;
+        } catch (IOException | SecurityException failure) {
+            reportCaptureFailure(file, failure);
+            return null;
+        }
+    }
+
+    private String normalizeContent(String content) {
+        return content == null ? null : content.replace("\r\n", "\n").trim();
+    }
+
+    private String decodeUtf8(byte[] content, File file) throws IOException {
+        try {
+            return StandardCharsets.UTF_8.newDecoder()
+                    .onMalformedInput(CodingErrorAction.REPORT)
+                    .onUnmappableCharacter(CodingErrorAction.REPORT)
+                    .decode(ByteBuffer.wrap(content))
+                    .toString();
+        } catch (CharacterCodingException failure) {
+            throw new IOException("Hotload file is not valid UTF-8: " + file, failure);
+        }
+    }
+
+    private boolean applySettingsSnapshot(File file, String content) {
+        try {
+            return IrisSettings.applyHotloadSnapshot(content, IrisLanguage::reload);
+        } catch (RuntimeException failure) {
+            IrisLogging.error("Rejected invalid settings hotload from " + file.getAbsolutePath() + ": " + failureDetail(failure));
+            IrisLogging.reportError(failure);
+            failure.printStackTrace();
+            return false;
+        }
+    }
+
+    private boolean applyLocaleSnapshot(File file, String content) {
+        try {
+            return IrisLanguage.reloadOverride(file, content);
+        } catch (RuntimeException failure) {
+            IrisLogging.error("Rejected invalid locale hotload from " + file.getAbsolutePath() + ": " + failureDetail(failure));
+            IrisLogging.reportError(failure);
+            failure.printStackTrace();
+            return false;
+        }
+    }
+
+    private void acknowledgeManualLocaleReload(File file, String content) {
+        if (closed) {
+            return;
+        }
+        hotloadEngine.noteSelfWrite(file, content);
+        clearCaptureFailure(file);
+    }
+
+    private void reportUnavailableSnapshot(File file) {
+        if (file.isFile() && file.length() > MAX_HOTLOAD_BYTES) {
+            reportCaptureFailure(
+                    file,
+                    new IOException("Hotload file exceeds " + MAX_HOTLOAD_BYTES + " bytes: " + file)
+            );
+        }
+    }
+
+    private void reportCaptureFailure(File file, Throwable failure) {
+        String path = file.getAbsolutePath();
+        String failureKey = failure.getClass().getName() + ":" + failureDetail(failure);
+        if (Objects.equals(reportedCaptureFailures.put(path, failureKey), failureKey)) {
+            return;
+        }
+        IrisLogging.error("Failed to read watched Iris file " + path + ": " + failureDetail(failure));
+        IrisLogging.reportError(failure);
+        failure.printStackTrace();
+    }
+
+    private void clearCaptureFailure(File file) {
+        reportedCaptureFailures.remove(file.getAbsolutePath());
+    }
+
+    private void reportApplied(ConfigHotloadEngine.ContentDelta delta) {
+        File file = delta.file();
+        if (isSettingsFile(file)) {
+            if (delta.after() != null) {
+                IrisLogging.info("Hotloaded settings.json");
+            }
+            return;
+        }
+        if (IrisLanguage.isActiveOverrideFile(file)) {
+            IrisLogging.info("Hotloaded locale override " + file.getName());
+        }
+    }
+
+    private String failureDetail(Throwable failure) {
+        String message = failure.getMessage();
+        return failure.getClass().getSimpleName() + (message == null || message.isBlank() ? "" : " - " + message);
+    }
+
+    record Timing(
+            long pollPeriodMillis,
+            long cooldownMillis,
+            long fullScanWindowMillis,
+            long signatureScanWindowMillis
+    ) {
+        Timing {
+            if (pollPeriodMillis <= 0L
+                    || cooldownMillis <= 0L
+                    || fullScanWindowMillis <= 0L
+                    || signatureScanWindowMillis <= 0L) {
+                throw new IllegalArgumentException("Hotload timing values must be positive");
+            }
+        }
+    }
+}

core/src/main/java/art/arcane/iris/core/localization/IrisLanguage.java

@@ -45,15 +45,13 @@ import java.util.List;
 import java.util.Map;
 import java.util.Objects;
 import java.util.concurrent.ConcurrentHashMap;
-import java.util.concurrent.TimeUnit;
+import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.BiConsumer;
 import java.util.regex.Pattern;
 
 public final class IrisLanguage {
     private static final long MAX_LOCALE_BYTES = 2L * 1024L * 1024L;
-    private static final long HOTLOAD_CONTENT_STABILITY_NANOS = TimeUnit.MILLISECONDS.toNanos(250L);
-    private static final long HOTLOAD_DELETION_GRACE_NANOS = TimeUnit.SECONDS.toNanos(3L);
-    private static final long HOTLOAD_COOLDOWN_NANOS = TimeUnit.SECONDS.toNanos(3L);
     private static final int MAX_REPORTED_ISSUES = 12;
     private static final Pattern LOCALE_NAME = Pattern.compile("[A-Za-z0-9_-]+");
     private static final Pattern LEGACY_COLOR = Pattern.compile("(?i)\\u00a7[0-9A-FK-ORX]");
@@ -68,17 +66,9 @@ public final class IrisLanguage {
      * new snapshot and the whole memo is discarded. Bounded by the catalog size.
      */
     private static final AtomicReference<PlainMemo> PLAIN_MEMO = new AtomicReference<>(null);
-    private static final LocaleHotloadGate HOTLOAD_GATE = new LocaleHotloadGate(
-            new LocaleHotloadGate.Timing(
-                    HOTLOAD_CONTENT_STABILITY_NANOS,
-                    HOTLOAD_DELETION_GRACE_NANOS,
-                    HOTLOAD_COOLDOWN_NANOS
-            )
-    );
-
+    private static final CopyOnWriteArrayList<BiConsumer<File, String>> MANUAL_RELOAD_LISTENERS =
+            new CopyOnWriteArrayList<>();
     private static volatile File dataFolder;
-    private static volatile String lastCaptureFailureKey;
-    private static volatile String lastInvalidHotloadLocale;
     private static volatile String activeLocale = CATALOG.englishLocale();
 
     private IrisLanguage() {
@@ -113,10 +103,22 @@ public final class IrisLanguage {
         }
         IrisSettings.IrisSettingsGeneral general = resolvedCandidate.getGeneral();
         String locale = general == null ? CATALOG.englishLocale() : general.getLanguage();
-        return reload(root, locale);
+        return reloadResolved(root, locale, false);
     }
 
     public static synchronized boolean reload(File root, String locale) {
+        return reloadResolved(root, locale, true);
+    }
+
+    public static void addManualReloadListener(BiConsumer<File, String> listener) {
+        MANUAL_RELOAD_LISTENERS.add(Objects.requireNonNull(listener, "Manual reload listener cannot be null"));
+    }
+
+    public static void removeManualReloadListener(BiConsumer<File, String> listener) {
+        MANUAL_RELOAD_LISTENERS.remove(listener);
+    }
+
+    private static boolean reloadResolved(File root, String locale, boolean notifyManualReload) {
         File resolvedRoot = root == null ? null : root.getAbsoluteFile();
         if (resolvedRoot == null) {
             throw new IllegalArgumentException("Iris locale data folder cannot be null");
@@ -126,7 +128,6 @@ public final class IrisLanguage {
             requestedLocale = normalizeLocale(locale);
         } catch (RuntimeException exception) {
             dataFolder = resolvedRoot;
-            HOTLOAD_GATE.reset(null);
             IrisLogging.error("Rejected locale setting '" + locale + "'; continuing with " + activeLocale + ".");
             IrisLogging.reportError(exception);
             exception.printStackTrace();
@@ -135,17 +136,77 @@ public final class IrisLanguage {
 
         File override = overrideFile(resolvedRoot, requestedLocale);
         SnapshotCapture capture = captureForReload(override, requestedLocale);
+        boolean applied = applyReload(resolvedRoot, requestedLocale, capture);
+        if (applied && notifyManualReload) {
+            notifyManualReload(capture.snapshot());
+        }
+        return applied;
+    }
+
+    public static synchronized boolean reloadOverride(File override, String rawContent) {
+        File root = dataFolder;
+        if (root == null && IrisPlatforms.isBound()) {
+            root = IrisPlatforms.get().dataFolder();
+        }
+        if (root == null || override == null) {
+            return false;
+        }
+
+        String configured = configuredLocale();
+        String requestedLocale;
+        try {
+            requestedLocale = normalizeLocale(configured);
+        } catch (RuntimeException exception) {
+            IrisLogging.error("Rejected locale setting '" + configured + "'; continuing with " + activeLocale + ".");
+            IrisLogging.reportError(exception);
+            exception.printStackTrace();
+            return false;
+        }
+
+        File expected = overrideFile(root, requestedLocale);
+        if (!expected.equals(override.getAbsoluteFile())) {
+            return true;
+        }
+
+        LocaleHotloadSnapshot snapshot = rawContent == null
+                ? LocaleHotloadSnapshot.missing(expected, requestedLocale)
+                : LocaleHotloadSnapshot.present(
+                        expected,
+                        requestedLocale,
+                        rawContent,
+                        sha256(rawContent.getBytes(StandardCharsets.UTF_8))
+                );
+        return applyReload(root.getAbsoluteFile(), requestedLocale, new SnapshotCapture(snapshot, null));
+    }
+
+    public static boolean isActiveOverrideFile(File file) {
+        if (file == null) {
+            return false;
+        }
+        File root = dataFolder;
+        if (root == null && IrisPlatforms.isBound()) {
+            root = IrisPlatforms.get().dataFolder();
+        }
+        if (root == null) {
+            return false;
+        }
+        try {
+            return overrideFile(root, configuredLocale()).equals(file.getAbsoluteFile());
+        } catch (RuntimeException ignored) {
+            return false;
+        }
+    }
+
+    private static boolean applyReload(File root, String requestedLocale, SnapshotCapture capture) {
         LocalizationReloadResult result;
         if (capture.failure() == null) {
-            result = MANAGER.reload(() -> loadCandidate(resolvedRoot, requestedLocale, capture.snapshot()));
+            result = MANAGER.reload(() -> loadCandidate(root, requestedLocale, capture.snapshot()));
         } else {
             result = MANAGER.reload(() -> {
                 throw capture.failure();
             });
         }
-        dataFolder = resolvedRoot;
-        HOTLOAD_GATE.reset(capture.snapshot());
-        lastCaptureFailureKey = null;
+        dataFolder = root;
         if (!result.applied()) {
             reportRejectedReload(requestedLocale, result);
             return false;
@@ -158,56 +219,18 @@ public final class IrisLanguage {
         return true;
     }
 
-    public static synchronized boolean update() {
-        File root = dataFolder;
-        if (root == null) {
-            return initialize();
-        }
-        String locale;
-        try {
-            locale = normalizeLocale(configuredLocale());
-        } catch (RuntimeException exception) {
-            String invalidLocale = configuredLocale();
-            if (Objects.equals(lastInvalidHotloadLocale, invalidLocale)) {
-                return false;
+    private static void notifyManualReload(LocaleHotloadSnapshot snapshot) {
+        for (BiConsumer<File, String> listener : MANUAL_RELOAD_LISTENERS) {
+            try {
+                listener.accept(snapshot.file(), snapshot.content());
+            } catch (RuntimeException failure) {
+                IrisLogging.error("Failed to acknowledge a manual locale reload: "
+                        + failure.getClass().getSimpleName()
+                        + (failure.getMessage() == null ? "" : " - " + failure.getMessage()));
+                IrisLogging.reportError(failure);
+                failure.printStackTrace();
             }
-            lastInvalidHotloadLocale = invalidLocale;
-            return reload(root, invalidLocale);
         }
-        lastInvalidHotloadLocale = null;
-        File expected = overrideFile(root, locale);
-        LocaleHotloadSnapshot snapshot;
-        try {
-            snapshot = captureHotloadSnapshot(expected, locale);
-        } catch (IOException | RuntimeException failure) {
-            HOTLOAD_GATE.unavailable();
-            reportCaptureFailure(expected, failure);
-            return false;
-        }
-        if (snapshot == null) {
-            HOTLOAD_GATE.unavailable();
-            return true;
-        }
-        lastCaptureFailureKey = null;
-
-        LocaleHotloadGate.Attempt attempt = HOTLOAD_GATE.observe(snapshot, System.nanoTime());
-        if (attempt == null) {
-            return true;
-        }
-
-        LocalizationReloadResult result = MANAGER.reload(() -> loadCandidate(root, locale, attempt.snapshot()));
-        boolean applied = result.applied();
-        HOTLOAD_GATE.complete(attempt, System.nanoTime(), applied);
-        if (!applied) {
-            reportRejectedReload(locale, result);
-            return false;
-        }
-
-        activeLocale = locale;
-        int warnings = result.validation().warnings().size();
-        IrisLogging.info("Loaded locale " + locale + " with " + warnings + " fallback "
-                + (warnings == 1 ? "entry" : "entries") + ".");
-        return true;
     }
 
     public static String activeLocale() {
@@ -606,18 +629,6 @@ public final class IrisLanguage {
         }
     }
 
-    private static void reportCaptureFailure(File file, Exception failure) {
-        String detail = failure.getMessage() == null ? failure.getClass().getSimpleName() : failure.getMessage();
-        String failureKey = file.getAbsolutePath() + ":" + failure.getClass().getName() + ":" + detail;
-        if (Objects.equals(failureKey, lastCaptureFailureKey)) {
-            return;
-        }
-        lastCaptureFailureKey = failureKey;
-        IrisLogging.error("Failed to capture stable locale override " + file.getPath() + ": " + detail);
-        IrisLogging.reportError(failure);
-        failure.printStackTrace();
-    }
-
     private static void reportRejectedReload(String locale, LocalizationReloadResult result) {
         IrisLogging.error("Rejected locale reload for " + locale + "; continuing with " + activeLocale + ".");
         List<LocalizationIssue> issues = result.validation().errors();

core/src/main/java/art/arcane/iris/core/localization/LocaleHotloadGate.java

@@ -1,100 +0,0 @@
-package art.arcane.iris.core.localization;
-
-import java.util.Objects;
-
-final class LocaleHotloadGate {
-    private final Timing timing;
-
-    private long generation;
-    private LocaleHotloadSnapshot baseline;
-    private LocaleHotloadSnapshot observed;
-    private long observedSinceNanos;
-    private LocaleHotloadSnapshot pending;
-    private Attempt inFlight;
-    private long lastCompletedAtNanos;
-    private boolean hasCompleted;
-
-    LocaleHotloadGate(Timing timing) {
-        this.timing = Objects.requireNonNull(timing, "Locale hotload timing cannot be null");
-    }
-
-    synchronized Attempt observe(LocaleHotloadSnapshot snapshot, long nowNanos) {
-        LocaleHotloadSnapshot current = Objects.requireNonNull(snapshot, "Locale hotload snapshot cannot be null");
-        if (!current.equals(observed)) {
-            observed = current;
-            observedSinceNanos = nowNanos;
-            return null;
-        }
-
-        long stabilityNanos = current.missing()
-                ? timing.deletionGraceNanos()
-                : timing.contentStabilityNanos();
-        if (!elapsed(nowNanos, observedSinceNanos, stabilityNanos)) {
-            return null;
-        }
-
-        pending = current.equals(baseline) ? null : current;
-        if (pending == null || inFlight != null || !pending.equals(observed)) {
-            return null;
-        }
-        if (hasCompleted && !elapsed(nowNanos, lastCompletedAtNanos, timing.cooldownNanos())) {
-            return null;
-        }
-
-        Attempt attempt = new Attempt(generation, pending);
-        inFlight = attempt;
-        return attempt;
-    }
-
-    synchronized void unavailable() {
-        observed = null;
-        observedSinceNanos = 0L;
-    }
-
-    synchronized void complete(Attempt attempt, long nowNanos, boolean applied) {
-        if (attempt == null || inFlight == null || !inFlight.equals(attempt) || attempt.generation() != generation) {
-            return;
-        }
-
-        inFlight = null;
-        lastCompletedAtNanos = nowNanos;
-        hasCompleted = true;
-        if (!applied) {
-            return;
-        }
-
-        baseline = attempt.snapshot();
-        if (attempt.snapshot().equals(pending)) {
-            pending = null;
-        }
-    }
-
-    synchronized void reset(LocaleHotloadSnapshot snapshot) {
-        generation++;
-        baseline = snapshot;
-        observed = snapshot;
-        observedSinceNanos = 0L;
-        pending = null;
-        inFlight = null;
-        lastCompletedAtNanos = 0L;
-        hasCompleted = false;
-    }
-
-    private boolean elapsed(long nowNanos, long startNanos, long durationNanos) {
-        return nowNanos - startNanos >= durationNanos;
-    }
-
-    record Timing(long contentStabilityNanos, long deletionGraceNanos, long cooldownNanos) {
-        Timing {
-            if (contentStabilityNanos < 0L || deletionGraceNanos < 0L || cooldownNanos < 0L) {
-                throw new IllegalArgumentException("Locale hotload timing cannot be negative");
-            }
-        }
-    }
-
-    record Attempt(long generation, LocaleHotloadSnapshot snapshot) {
-        Attempt {
-            snapshot = Objects.requireNonNull(snapshot, "Locale hotload attempt snapshot cannot be null");
-        }
-    }
-}

core/src/main/java/art/arcane/iris/engine/object/IrisObjectPlacementRunner.java

@@ -39,6 +39,7 @@ import art.arcane.volmlib.util.math.Position2;
 import art.arcane.volmlib.util.math.RNG;
 import art.arcane.volmlib.util.matter.MatterMarker;
 
+import java.util.Objects;
 import java.util.Optional;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.function.BiConsumer;
@@ -61,10 +62,14 @@ final class IrisObjectPlacementRunner {
     }
 
     int place(int x, int yv, int z, IObjectPlacer oplacer, IrisObjectPlacement config, RNG rng, BiConsumer<BlockPosition, PlatformBlockState> listener, CarveResult c, IrisData rdata) {
+        Objects.requireNonNull(oplacer, "Object placer is required.");
+        Objects.requireNonNull(config, "Object placement config is required.");
+        Objects.requireNonNull(rng, "Object placement RNG is required.");
+        Objects.requireNonNull(rdata, "Object placement data is required.");
         IObjectPlacer placer = config.getHeightmap() != null ? new HeightmapObjectPlacer(rng, x, yv, z, config, oplacer) : oplacer;
 
         boolean evaluateSlopeCondition = !config.isForcePlace() && !config.getSlopeCondition().isDefault();
-        if (rdata != null && (evaluateSlopeCondition || config.isRotateTowardsSlope())) {
+        if (evaluateSlopeCondition || config.isRotateTowardsSlope()) {
             Engine placementEngine = requireSlopeEngine(placer);
             if (evaluateSlopeCondition &&
                     !config.getSlopeCondition().isValid(placementEngine.getComplex().getSlopeStream().get(x, z))) {
@@ -108,7 +113,7 @@ final class IrisObjectPlacementRunner {
         }
 
         if (config.isSmartBore()) {
-            IrisObjectShaping.ensureSmartBored(self, placer.isDebugSmartBore());
+            IrisObjectShaping.ensureSmartBored(self);
         }
 
         boolean warped = !config.getWarp().isFlat();
@@ -148,6 +153,8 @@ final class IrisObjectPlacementRunner {
         int xx, zz;
         int yrand = config.getTranslate().getYRandom();
         yrand = yrand > 0 ? rng.i(0, yrand) : yrand < 0 ? rng.i(yrand, 0) : yrand;
+        int warpMargin = warped ? (int) Math.ceil(Math.abs(config.getWarp().getMultiplier()) / 2D) : 0;
+        TransformedBounds placementBounds = transformedBounds(spin, translating, translateOffset, ceilingHang, warpMargin);
         boolean bail = false;
 
         if (config.isFromBottom()) {
@@ -168,14 +175,10 @@ final class IrisObjectPlacementRunner {
                     }
                 }
             } else if (config.getMode().equals(ObjectPlaceMode.MAX_HEIGHT) || config.getMode().equals(ObjectPlaceMode.STILT)) {
-                IrisBlockVector offset = new IrisBlockVector(config.getTranslate().getX(), config.getTranslate().getY(), config.getTranslate().getZ());
-                IrisBlockVector rotatedDimensions = config.getRotation().rotate(new IrisBlockVector(self.getW(), self.getH(), self.getD()), spinx, spiny, spinz).clone();
-                int xLength = (rotatedDimensions.getBlockX() / 2) + offset.getBlockX();
-                int minX = Math.min(x - xLength, x + xLength);
-                int maxX = Math.max(x - xLength, x + xLength);
-                int zLength = (rotatedDimensions.getBlockZ() / 2) + offset.getBlockZ();
-                int minZ = Math.min(z - zLength, z + zLength);
-                int maxZ = Math.max(z - zLength, z + zLength);
+                int minX = x + placementBounds.minX();
+                int maxX = x + placementBounds.maxX();
+                int minZ = z + placementBounds.minZ();
+                int maxZ = z + placementBounds.maxZ();
                 for (int i = minX; i <= maxX; i++) {
                     for (int ii = minZ; ii <= maxZ; ii++) {
                         int h = placer.getHighest(i, ii, self.getLoader(), config.isUnderwater()) + rty;
@@ -190,17 +193,12 @@ final class IrisObjectPlacementRunner {
                     }
                 }
             } else if (config.getMode().equals(ObjectPlaceMode.FAST_MAX_HEIGHT) || config.getMode().equals(ObjectPlaceMode.FAST_STILT)) {
-                IrisBlockVector offset = new IrisBlockVector(config.getTranslate().getX(), config.getTranslate().getY(), config.getTranslate().getZ());
-                IrisBlockVector rotatedDimensions = config.getRotation().rotate(new IrisBlockVector(self.getW(), self.getH(), self.getD()), spinx, spiny, spinz).clone();
-
-                int xRadius = (rotatedDimensions.getBlockX() / 2);
-                int xLength = xRadius + offset.getBlockX();
-                int minX = Math.min(x - xLength, x + xLength);
-                int maxX = Math.max(x - xLength, x + xLength);
-                int zRadius = (rotatedDimensions.getBlockZ() / 2);
-                int zLength = zRadius + offset.getBlockZ();
-                int minZ = Math.min(z - zLength, z + zLength);
-                int maxZ = Math.max(z - zLength, z + zLength);
+                int minX = x + placementBounds.minX();
+                int maxX = x + placementBounds.maxX();
+                int minZ = z + placementBounds.minZ();
+                int maxZ = z + placementBounds.maxZ();
+                int xRadius = Math.max(0, (maxX - minX) / 2);
+                int zRadius = Math.max(0, (maxZ - minZ) / 2);
 
                 for (int i = minX; i <= maxX; i += Math.abs(xRadius) + 1) {
                     for (int ii = minZ; ii <= maxZ; ii += Math.abs(zRadius) + 1) {
@@ -216,16 +214,11 @@ final class IrisObjectPlacementRunner {
                     }
                 }
             } else if (config.getMode().equals(ObjectPlaceMode.MIN_HEIGHT) || config.getMode() == ObjectPlaceMode.MIN_STILT) {
-                y = rdata.getEngine().getHeight() + 1;
-                IrisBlockVector offset = new IrisBlockVector(config.getTranslate().getX(), config.getTranslate().getY(), config.getTranslate().getZ());
-                IrisBlockVector rotatedDimensions = config.getRotation().rotate(new IrisBlockVector(self.getW(), self.getH(), self.getD()), spinx, spiny, spinz).clone();
-
-                int xLength = (rotatedDimensions.getBlockX() / 2) + offset.getBlockX();
-                int minX = Math.min(x - xLength, x + xLength);
-                int maxX = Math.max(x - xLength, x + xLength);
-                int zLength = (rotatedDimensions.getBlockZ() / 2) + offset.getBlockZ();
-                int minZ = Math.min(z - zLength, z + zLength);
-                int maxZ = Math.max(z - zLength, z + zLength);
+                y = requireDataEngine(rdata, "minimum-height mode").getHeight() + 1;
+                int minX = x + placementBounds.minX();
+                int maxX = x + placementBounds.maxX();
+                int minZ = z + placementBounds.minZ();
+                int maxZ = z + placementBounds.maxZ();
                 for (int i = minX; i <= maxX; i++) {
                     for (int ii = minZ; ii <= maxZ; ii++) {
                         int h = placer.getHighest(i, ii, self.getLoader(), config.isUnderwater()) + rty;
@@ -241,18 +234,13 @@ final class IrisObjectPlacementRunner {
                     }
                 }
             } else if (config.getMode().equals(ObjectPlaceMode.FAST_MIN_HEIGHT) || config.getMode() == ObjectPlaceMode.FAST_MIN_STILT) {
-                y = rdata.getEngine().getHeight() + 1;
-                IrisBlockVector offset = new IrisBlockVector(config.getTranslate().getX(), config.getTranslate().getY(), config.getTranslate().getZ());
-                IrisBlockVector rotatedDimensions = config.getRotation().rotate(new IrisBlockVector(self.getW(), self.getH(), self.getD()), spinx, spiny, spinz).clone();
-
-                int xRadius = (rotatedDimensions.getBlockX() / 2);
-                int xLength = xRadius + offset.getBlockX();
-                int minX = Math.min(x - xLength, x + xLength);
-                int maxX = Math.max(x - xLength, x + xLength);
-                int zRadius = (rotatedDimensions.getBlockZ() / 2);
-                int zLength = zRadius + offset.getBlockZ();
-                int minZ = Math.min(z - zLength, z + zLength);
-                int maxZ = Math.max(z - zLength, z + zLength);
+                y = requireDataEngine(rdata, "fast minimum-height mode").getHeight() + 1;
+                int minX = x + placementBounds.minX();
+                int maxX = x + placementBounds.maxX();
+                int minZ = z + placementBounds.minZ();
+                int maxZ = z + placementBounds.maxZ();
+                int xRadius = Math.max(0, (maxX - minX) / 2);
+                int zRadius = Math.max(0, (maxZ - minZ) / 2);
 
                 for (int i = minX; i <= maxX; i += Math.abs(xRadius) + 1) {
                     for (int ii = minZ; ii <= maxZ; ii += Math.abs(zRadius) + 1) {
@@ -352,18 +340,23 @@ final class IrisObjectPlacementRunner {
             return -1;
         }
 
-        int warpMargin = warped ? (int) Math.ceil(Math.abs(config.getWarp().getMultiplier()) / 2D) : 0;
         if (!rawStructurePiece && nativeStructureVetoes(placer, config, spin, translating, translateOffset, ceilingHang,
                 yv < 0 && config.getMode() == ObjectPlaceMode.PAINT, warpMargin, x, y + yrand, z)) {
             return -1;
         }
 
+        boolean paint = yv < 0 && config.getMode() == ObjectPlaceMode.PAINT;
+        WorldBounds worldBounds = null;
+        if (config.isBore() || (!config.isForcePlace() && !rawStructurePiece
+                && (!config.getAllowedCollisions().isEmpty() || !config.getForbiddenCollisions().isEmpty()))) {
+            worldBounds = resolveWorldBounds(placer, config, placementBounds, paint, x, y + yrand, z);
+        }
+
         if (!config.isForcePlace() && !rawStructurePiece && (!config.getAllowedCollisions().isEmpty() || !config.getForbiddenCollisions().isEmpty())) {
-            Engine engine = rdata.getEngine();
-            IrisBlockVector offset = new IrisBlockVector(config.getTranslate().getX(), config.getTranslate().getY(), config.getTranslate().getZ());
-            for (int i = x - Math.floorDiv(self.w, 2) + (int) offset.getX(); i <= x + Math.floorDiv(self.w, 2) - (self.w % 2 == 0 ? 1 : 0) + (int) offset.getX(); i++) {
-                for (int j = y - Math.floorDiv(self.h, 2)  + (int) offset.getY(); j <= y + Math.floorDiv(self.h, 2) - (self.h % 2 == 0 ? 1 : 0) + (int) offset.getY(); j++) {
-                    for (int k = z - Math.floorDiv(self.d, 2) + (int) offset.getZ(); k <= z + Math.floorDiv(self.d, 2) - (self.d % 2 == 0 ? 1 : 0) + (int) offset.getZ(); k++) {
+            Engine engine = requireDataEngine(rdata, "collision settings");
+            for (int i = worldBounds.minX(); i <= worldBounds.maxX(); i++) {
+                for (int j = worldBounds.minY(); j <= worldBounds.maxY(); j++) {
+                    for (int k = worldBounds.minZ(); k <= worldBounds.maxZ(); k++) {
                         PlacedObject p = engine.getObjectPlacement(i, j, k);
                         if (p == null) continue;
                         IrisObject o = p.getObject();
@@ -379,11 +372,12 @@ final class IrisObjectPlacementRunner {
             }
         }
 
+        y += yrand;
+
         if (config.isBore()) {
-            IrisBlockVector offset = new IrisBlockVector(config.getTranslate().getX(), config.getTranslate().getY(), config.getTranslate().getZ());
-            for (int i = x - Math.floorDiv(self.w, 2) + (int) offset.getX(); i <= x + Math.floorDiv(self.w, 2) - (self.w % 2 == 0 ? 1 : 0) + (int) offset.getX(); i++) {
-                for (int j = y - Math.floorDiv(self.h, 2) - config.getBoreExtendMinY() + (int) offset.getY(); j <= y + Math.floorDiv(self.h, 2) + config.getBoreExtendMaxY() - (self.h % 2 == 0 ? 1 : 0) + (int) offset.getY(); j++) {
-                    for (int k = z - Math.floorDiv(self.d, 2) + (int) offset.getZ(); k <= z + Math.floorDiv(self.d, 2) - (self.d % 2 == 0 ? 1 : 0) + (int) offset.getZ(); k++) {
+            for (int i = worldBounds.minX(); i <= worldBounds.maxX(); i++) {
+                for (int j = worldBounds.minY() - config.getBoreExtendMinY(); j <= worldBounds.maxY() + config.getBoreExtendMaxY(); j++) {
+                    for (int k = worldBounds.minZ(); k <= worldBounds.maxZ(); k++) {
                         placer.set(i, j, k, IrisObject.States.AIR);
                     }
                 }
@@ -394,7 +388,6 @@ final class IrisObjectPlacementRunner {
         int topLayer = Integer.MIN_VALUE;
         int vacuumLowest = Integer.MAX_VALUE;
         int vacuumHighest = Integer.MIN_VALUE;
-        y += yrand;
         self.readLock.lock();
 
         KMap<IrisBlockVector, String> markers = null;
@@ -407,7 +400,7 @@ final class IrisObjectPlacementRunner {
 
             if (config.getMarkers().isNotEmpty() && placer.getEngine() != null) {
                 markers = new KMap<>();
-                var list = StreamSupport.stream(blocks.keys().spliterator(), false)
+                KList<IrisBlockVector> list = StreamSupport.stream(blocks.keys().spliterator(), false)
                         .collect(KList.collector());
                 // Marker selection persists into the mantle, so it must be seed-deterministic.
                 // Derive a side stream keyed on the placement position instead of consuming the
@@ -476,6 +469,10 @@ final class IrisObjectPlacementRunner {
                     d = IrisObject.States.AIR;
                 }
 
+                if (placer.isDebugSmartBore() && IrisObject.States.VAIR.equals(d)) {
+                    d = IrisObject.States.VAIR_DEBUG;
+                }
+
                 PlatformBlockState data = d;
                 IrisBlockVector i = g.clone();
                 spin.rotate(i);
@@ -536,18 +533,6 @@ final class IrisObjectPlacementRunner {
                     yy = (int) Math.round(i.getY()) + Math.floorDiv(self.h, 2) + placer.getHighest(xx, zz, self.getLoader(), config.isUnderwater());
                 }
 
-                if (heightmap != null) {
-                    Position2 pos = new Position2(xx, zz);
-
-                    if (!heightmap.containsKey(pos)) {
-                        heightmap.put(pos, yy);
-                    }
-
-                    if (heightmap.get(pos) < yy) {
-                        heightmap.put(pos, yy);
-                    }
-                }
-
                 if (config.isMeld() && !rawStructurePiece && !placer.isSolid(xx, yy, zz)) {
                     continue;
                 }
@@ -569,6 +554,13 @@ final class IrisObjectPlacementRunner {
 
                 if (data.isCustom() || place) {
                     placer.set(xx, yy, zz, data);
+                    if (heightmap != null) {
+                        Position2 pos = new Position2(xx, zz);
+                        Integer currentHeight = heightmap.get(pos);
+                        if (currentHeight == null || currentHeight < yy) {
+                            heightmap.put(pos, yy);
+                        }
+                    }
                     if (tile != null) {
                         placer.setTile(xx, yy, zz, tile);
                     }
@@ -586,9 +578,6 @@ final class IrisObjectPlacementRunner {
                     }
                 }
             }
-        } catch (Throwable e) {
-            e.printStackTrace();
-            IrisLogging.reportError(e);
         } finally {
             self.readLock.unlock();
         }
@@ -832,14 +821,8 @@ final class IrisObjectPlacementRunner {
         }
 
         if (vacuuming && vacuumLowest != Integer.MAX_VALUE && placer.getEngine() != null) {
-            IrisBlockVector rotDim = config.getRotation().rotate(new IrisBlockVector(self.getW(), self.getH(), self.getD()), spinx, spiny, spinz).clone();
-            int lowX = IrisObjectVacuum.footprintLow(rotDim.getBlockX());
-            int highX = IrisObjectVacuum.footprintHigh(rotDim.getBlockX());
-            int lowZ = IrisObjectVacuum.footprintLow(rotDim.getBlockZ());
-            int highZ = IrisObjectVacuum.footprintHigh(rotDim.getBlockZ());
-            int centerX = x + config.getTranslate().getX();
-            int centerZ = z + config.getTranslate().getZ();
-            vacuumTerrain(placer, config, centerX, centerZ, lowX, highX, lowZ, highZ, vacuumLowest, vacuumHighest);
+            vacuumTerrain(placer, config, x, z, placementBounds.minX(), placementBounds.maxX(),
+                    placementBounds.minZ(), placementBounds.maxZ(), vacuumLowest, vacuumHighest);
         }
 
         if (heightmap != null) {
@@ -864,10 +847,91 @@ final class IrisObjectPlacementRunner {
         return !wouldReplace && (rawStructurePiece || !air);
     }
 
+    private TransformedBounds transformedBounds(SpinKernel spin, boolean translating, IrisBlockVector translateOffset,
+                                                boolean ceilingHang, int margin) {
+        int sourceMinX = -self.getCenter().getBlockX();
+        int sourceMaxX = self.getW() - self.getCenter().getBlockX() - 1;
+        int sourceMinY = -self.getCenter().getBlockY();
+        int sourceMaxY = self.getH() - self.getCenter().getBlockY() - 1;
+        int sourceMinZ = -self.getCenter().getBlockZ();
+        int sourceMaxZ = self.getD() - self.getCenter().getBlockZ() - 1;
+        int minX = Integer.MAX_VALUE;
+        int maxX = Integer.MIN_VALUE;
+        int minY = Integer.MAX_VALUE;
+        int maxY = Integer.MIN_VALUE;
+        int minZ = Integer.MAX_VALUE;
+        int maxZ = Integer.MIN_VALUE;
+
+        for (int xCorner = 0; xCorner < 2; xCorner++) {
+            int sourceX = xCorner == 0 ? sourceMinX : sourceMaxX;
+            for (int yCorner = 0; yCorner < 2; yCorner++) {
+                int sourceY = yCorner == 0 ? sourceMinY : sourceMaxY;
+                for (int zCorner = 0; zCorner < 2; zCorner++) {
+                    int sourceZ = zCorner == 0 ? sourceMinZ : sourceMaxZ;
+                    IrisBlockVector corner = new IrisBlockVector(sourceX, sourceY, sourceZ);
+                    spin.rotate(corner);
+                    if (ceilingHang) {
+                        corner.setY(-corner.getBlockY());
+                    }
+                    if (translating) {
+                        corner.add(translateOffset);
+                    }
+                    int transformedX = (int) Math.round(corner.getX());
+                    int transformedY = (int) Math.round(corner.getY());
+                    int transformedZ = (int) Math.round(corner.getZ());
+                    minX = Math.min(minX, transformedX);
+                    maxX = Math.max(maxX, transformedX);
+                    minY = Math.min(minY, transformedY);
+                    maxY = Math.max(maxY, transformedY);
+                    minZ = Math.min(minZ, transformedZ);
+                    maxZ = Math.max(maxZ, transformedZ);
+                }
+            }
+        }
+
+        return new TransformedBounds(minX - margin, maxX + margin, minY, maxY, minZ - margin, maxZ + margin);
+    }
+
+    private WorldBounds resolveWorldBounds(IObjectPlacer placer, IrisObjectPlacement config, TransformedBounds bounds,
+                                           boolean paint, int x, int y, int z) {
+        int minX = x + bounds.minX();
+        int maxX = x + bounds.maxX();
+        int minZ = z + bounds.minZ();
+        int maxZ = z + bounds.maxZ();
+        if (!paint) {
+            return new WorldBounds(minX, maxX, y + bounds.minY(), y + bounds.maxY(), minZ, maxZ);
+        }
+
+        int minimumSurface = Integer.MAX_VALUE;
+        int maximumSurface = Integer.MIN_VALUE;
+        for (int worldX = minX; worldX <= maxX; worldX++) {
+            for (int worldZ = minZ; worldZ <= maxZ; worldZ++) {
+                int surface = placer.getHighest(worldX, worldZ, self.getLoader(), config.isUnderwater());
+                minimumSurface = Math.min(minimumSurface, surface);
+                maximumSurface = Math.max(maximumSurface, surface);
+            }
+        }
+        int paintOffset = Math.floorDiv(self.h, 2);
+        return new WorldBounds(minX, maxX, minimumSurface + bounds.minY() + paintOffset,
+                maximumSurface + bounds.maxY() + paintOffset, minZ, maxZ);
+    }
+
     private static Engine requireSlopeEngine(IObjectPlacer placer) {
+        return requirePlacementEngine(placer, "slope settings");
+    }
+
+    private static Engine requirePlacementEngine(IObjectPlacer placer, String feature) {
         Engine engine = placer.getEngine();
         if (engine == null) {
-            throw new IllegalStateException("Object placement slope settings require an active Iris engine for the target world.");
+            throw new IllegalStateException("Object placement requires an active Iris engine for " + feature + ".");
+        }
+        return engine;
+    }
+
+    private static Engine requireDataEngine(IrisData data, String feature) {
+        Engine engine = data.getEngine();
+        if (engine == null) {
+            throw new IllegalStateException("Object placement requires active Iris data for " + feature + ".");
         }
         return engine;
     }
@@ -1229,4 +1293,10 @@ final class IrisObjectPlacementRunner {
             }
         }
     }
+
+    private record TransformedBounds(int minX, int maxX, int minY, int maxY, int minZ, int maxZ) {
+    }
+
+    private record WorldBounds(int minX, int maxX, int minY, int maxY, int minZ, int maxZ) {
+    }
 }

core/src/main/java/art/arcane/iris/engine/object/IrisObjectShaping.java

@@ -41,7 +41,7 @@ final class IrisObjectShaping {
     private IrisObjectShaping() {
     }
 
-    static void ensureSmartBored(IrisObject self, boolean debug) {
+    static void ensureSmartBored(IrisObject self) {
         if (self.smartBored) {
             return;
         }
@@ -53,15 +53,15 @@ final class IrisObjectShaping {
             if (self.smartBored) {
                 return;
             }
-            ensureSmartBoredLocked(self, debug);
+            ensureSmartBoredLocked(self);
         } finally {
             self.writeLock.unlock();
         }
     }
 
-    private static void ensureSmartBoredLocked(IrisObject self, boolean debug) {
+    private static void ensureSmartBoredLocked(IrisObject self) {
         PrecisionStopwatch p = PrecisionStopwatch.start();
-        PlatformBlockState vair = debug ? IrisObject.States.VAIR_DEBUG : IrisObject.States.VAIR;
+        PlatformBlockState vair = IrisObject.States.VAIR;
         AtomicInteger applied = new AtomicInteger();
         IrisBlockVector max = new IrisBlockVector(Double.MIN_VALUE, Double.MIN_VALUE, Double.MIN_VALUE);
         IrisBlockVector min = new IrisBlockVector(Double.MAX_VALUE, Double.MAX_VALUE, Double.MAX_VALUE);