From e091816ce06686d64d0f7a181a42701aa67e5bf7 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Sun, 4 Oct 2026 01:48:12 +0200 Subject: [PATCH 1/2] Reuse private terrain tick membership without changing published action order --- .github/workflows/ci.yml | 6 ++ README.md | 9 +- docs/foreground-first.md | 4 +- docs/tick-membership.md | 39 +++++++++ .../dev/horizonlab/client/HorizonClient.java | 1 + .../horizonlab/mixin/DhTickDedupMixin.java | 30 +++++++ .../horizonlab/mixin/HorizonMixinPlugin.java | 18 ++++ .../src/main/resources/fabric.mod.json | 2 +- .../src/main/resources/horizonlab.mixins.json | 2 +- .../dispatch/TickDedupIntegration.java | 87 +++++++++++++++++++ packs/START-HERE.txt | 7 +- packs/mods.lock.json | 2 +- tests/test_packs.py | 14 ++- tools/Compare-Benchmarks.html | 3 +- tools/build_mod.py | 20 +++-- tools/build_pack.py | 9 +- tools/compare_benchmarks.py | 2 +- tools/test_tick_dedup.py | 63 ++++++++++++++ 18 files changed, 300 insertions(+), 18 deletions(-) create mode 100644 docs/tick-membership.md create mode 100644 mods/horizon-lab/src/main/java/dev/horizonlab/mixin/DhTickDedupMixin.java create mode 100644 mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/TickDedupIntegration.java create mode 100644 tools/test_tick_dedup.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2d2b47b65..a70ab7cbc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -61,12 +61,17 @@ jobs: run: python -m unittest discover -s tests -v - name: Compile the private dispatch fixture run: python -c "from tools.build_mod import build_dispatch_fixture; build_dispatch_fixture()" + - name: Compile the private terrain tick membership fixture + run: python -c "from tools.build_mod import build_tick_dedup_fixture; build_tick_dedup_fixture()" - name: Install headless graphics libraries for applied-hook checks if: runner.os == 'Linux' run: sudo apt-get update && sudo apt-get install -y xvfb libgl1 libegl1 libvulkan1 mesa-vulkan-drivers libasound2t64 libxkbcommon0 - name: Exercise the applied dispatcher hooks and upstream rejection path if: runner.os == 'Linux' run: python tools/test_dispatch.py + - name: Verify applied tick membership transitions and allocation + if: runner.os == 'Linux' + run: python tools/test_tick_dedup.py - name: Upload original mod and pack manifests only uses: actions/upload-artifact@v4 with: @@ -79,3 +84,4 @@ jobs: dist/idle-queue-benchmark.txt dist/object-header-benchmark.txt dist/dispatch-integration.json + dist/tick-dedup-integration.json diff --git a/README.md b/README.md index a58864662..d2ff5de59 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Client-first performance research for Minecraft Java **26.3**, preserving vanill ## Play on your Mac -Download **horizon-mac-starter-0.12.0.zip** from [Releases](https://github.com/ludovic111/minecraft-optimization-lab/releases), extract it and open `Mac-Start.command`. It verifies and installs official universal Prism Launcher in `~/Applications` if needed, then opens the balanced pack import. Sign into Microsoft **inside Prism yourself**. This project needs no credentials. +Download **horizon-mac-starter-0.13.0.zip** from [Releases](https://github.com/ludovic111/minecraft-optimization-lab/releases), extract it and open `Mac-Start.command`. It verifies and installs official universal Prism Launcher in `~/Applications` if needed, then opens the balanced pack import. Sign into Microsoft **inside Prism yourself**. This project needs no credentials. Use native **Java 25 ARM64**, maximum heap **6144 MiB**, minimum **512 MiB** on your 16 GB M2 Pro. Prism can download Java automatically. Start at 1280×800 or 1920×1200; full Retina resolution is a larger GPU workload. [START-HERE.txt](packs/START-HERE.txt) has details. The same `.mrpack` files import into Prism on Windows and Linux. @@ -20,6 +20,7 @@ Use native **Java 25 ARM64**, maximum heap **6144 MiB**, minimum **512 MiB** on | queue-wait (experimental) | 12 | 128 | 6144 MiB | | adaptive-queue (experimental) | 12 | 128 | 6144 MiB | | dispatch-retry (experimental) | 12 | 128 | 6144 MiB | +| tick-dedup (experimental) | 12 | 128 | 6144 MiB | | foreground-first (combined experiment) | 12 | 128 | 6144 MiB | | foreground-vulkan (combined experiment) | 12 | 128 | 6144 MiB | | low-memory | 8 | none | 3072 MiB | @@ -33,6 +34,12 @@ Distant LOD is simplified terrain. Nearby blocks retain full detail. Initial gen The optional `queue-wait` pack yields during pending distant-terrain debounce retries; `adaptive-queue` combines it with the existing controllers. [Queue experiment and measurement limits](docs/debounce-queue.md). +Version 0.13 adds an isolated [tick membership experiment](docs/tick-membership.md) +that reuses compact storage for DH's private per-tick membership checks. The +combined foreground profiles include it too; balanced keeps it off. The applied +holder test verifies action semantics and removes repeated entry allocations; +whole-game FPS and RAM gains still need hardware measurements. + Version 0.12 captures effective distant-terrain quality, radius, worker budgets, Iris state and field of view. Start/end snapshots flag changed visual settings; [measurement details](docs/terrain-measurements.md) explain their limits. diff --git a/docs/foreground-first.md b/docs/foreground-first.md index 79da8e578..21e498f0e 100644 --- a/docs/foreground-first.md +++ b/docs/foreground-first.md @@ -2,6 +2,8 @@ `foreground-first` combines the adaptive background-terrain budget, precise worker pacing, bounded/wakeable queue waits and rejected-dispatch retries. +From version 0.13 it also includes compact per-tick membership storage; the +original action collections and their iteration order remain unchanged. `foreground-vulkan` uses the same combination with Vulkan preference and the game's OpenGL fallback. Both retain balanced mods, 12 full-detail chunks, 128-chunk LOD radius, two DH workers and simulation distance 12. @@ -17,7 +19,7 @@ Start with balanced, then compare the combined OpenGL profile at equal graphics, heap and world settings. The individual profiles remain available for isolating each hook. Compare `foreground-first` against `foreground-vulkan` only after the isolated Vulkan pack works on the device. Each combined profile explicitly -enables all four controls; changing `/horizon adaptive off` disables only the +enables these controls; changing `/horizon adaptive off` disables only the adaptive controller. Other hooks require their configuration flag and restart. Change `targetFps` in `config/horizon-adaptive.properties` to evaluate a different diff --git a/docs/tick-membership.md b/docs/tick-membership.md new file mode 100644 index 000000000..c01d01ca1 --- /dev/null +++ b/docs/tick-membership.md @@ -0,0 +1,39 @@ +# Reuse distant-terrain tick membership storage + +DH 3.3.4's tick holder clears and repopulates a private `HashSet` of nodes every +tick. Clearing retains the table but discards its entry objects, so handling the +same terrain again creates new entries. A local allocation profile identified +these entries in the `DH-ClientTickTimer` tree traversal. + +The optional hook uses the game's existing fastutil `ObjectOpenHashSet` for only +this private membership test. Its reusable array stores the references directly. +The original branches, published action sets/lists, action iteration order, +tree traversal, node identity, detail levels and render settings stay upstream. +The replacement clears at the original tick boundary, releasing member references +while retaining table capacity. It adds no node cache, global pool or renderer. + +Use `tick-dedup` for an isolated comparison with `m2-balanced`; their visual, +simulation, worker and other controller settings match. From version 0.13 the +combined `foreground-first` and `foreground-vulkan` experiments include this +hook too. Other profiles explicitly disable it. Set `enabled=false` in +`config/horizon-tick-dedup.properties` and restart to disable it. The hook only +applies to pinned DH 3.3.4. Reports record actual `tick_membership_dedup` state; +the comparison tools disclose differing state as an experiment variable. + +`python tools/test_tick_dedup.py` runs the publisher's actual holder inside two +isolated Fabric clients. Both check 6,000 deterministic randomized transitions, +including duplicate/null membership, first-action precedence, forced disable, +clear boundaries and published collection order. A warmed allocation loop uses +512 preallocated nodes, duplicate visits and the reused delete-children action +list for 20,000 ticks. It measures only the calling thread's allocated bytes, +CPU and elapsed time, keeping membership allocation separate from node creation. +The fixture JAR and full game logs remain private; the sanitized JSON result +contains no game code, credentials or launch arguments. + +The local Linux check allocated 245,760,208 bytes upstream versus 208 with the +hook. Its single CPU observation was 565 ms versus 381 ms. This establishes the +entry-allocation mechanism in that isolated loop; it does not establish a +statistical speedup, game FPS gain, whole-game RAM reduction, completed terrain +or performance on an M2 GPU. Actual game profiles and repeated Mac comparisons +are required for those conclusions. Table capacity remains proportional to the +largest tick membership, as the upstream hash table already did. diff --git a/mods/horizon-lab/src/main/java/dev/horizonlab/client/HorizonClient.java b/mods/horizon-lab/src/main/java/dev/horizonlab/client/HorizonClient.java index 5582a17a6..a3f80c882 100644 --- a/mods/horizon-lab/src/main/java/dev/horizonlab/client/HorizonClient.java +++ b/mods/horizon-lab/src/main/java/dev/horizonlab/client/HorizonClient.java @@ -96,6 +96,7 @@ public final class HorizonClient implements ClientModInitializer { context.put("debounce_queue_wait", dev.horizonlab.mixin.HorizonMixinPlugin.debounceWaitEnabled()); context.put("wakeable_idle_wait", dev.horizonlab.mixin.HorizonMixinPlugin.debounceWaitEnabled()); context.put("dispatch_retry_backoff", dev.horizonlab.mixin.HorizonMixinPlugin.dispatchRetryEnabled()); + context.put("tick_membership_dedup", dev.horizonlab.mixin.HorizonMixinPlugin.tickDedupEnabled()); context.put("adaptive_target_fps", targetFps); context.putAll(visualSettings(client)); var device = RenderSystem.getDevice().getDeviceInfo(); diff --git a/mods/horizon-lab/src/main/java/dev/horizonlab/mixin/DhTickDedupMixin.java b/mods/horizon-lab/src/main/java/dev/horizonlab/mixin/DhTickDedupMixin.java new file mode 100644 index 000000000..2a604af75 --- /dev/null +++ b/mods/horizon-lab/src/main/java/dev/horizonlab/mixin/DhTickDedupMixin.java @@ -0,0 +1,30 @@ +package dev.horizonlab.mixin; + +import com.seibel.distanthorizons.core.render.QuadTree.QuadTreeTickNodeHolder; +import it.unimi.dsi.fastutil.objects.ObjectOpenHashSet; +import java.util.HashSet; +import org.spongepowered.asm.mixin.Mixin; +import org.spongepowered.asm.mixin.Unique; +import org.spongepowered.asm.mixin.injection.At; +import org.spongepowered.asm.mixin.injection.Inject; +import org.spongepowered.asm.mixin.injection.Redirect; +import org.spongepowered.asm.mixin.injection.callback.CallbackInfo; + +/** Replace only the holder's private membership test; published action sets keep their order. */ +@Mixin(value = QuadTreeTickNodeHolder.class, remap = false) +public abstract class DhTickDedupMixin { + @Unique private final ObjectOpenHashSet horizon$presentNodes = new ObjectOpenHashSet<>(); + + @Redirect(method = {"addEnableNode", "addDisableNode", "addEnableDeleteChildrenNode", "removeEnableAndDisableNode"}, + at = @At(value = "INVOKE", target = "Ljava/util/HashSet;add(Ljava/lang/Object;)Z", ordinal = 0)) + private boolean horizon$recordPresentNode(HashSet original, Object node) { + // In pinned DH 3.3.4 each method's first add targets presentNodes. + // The original branches and action collections remain responsible for every transition. + return horizon$presentNodes.add(node); + } + + @Inject(method = "clear", at = @At("HEAD")) + private void horizon$clearPresentNodes(CallbackInfo callback) { + horizon$presentNodes.clear(); // Release references at the same boundary; retain reusable table capacity. + } +} diff --git a/mods/horizon-lab/src/main/java/dev/horizonlab/mixin/HorizonMixinPlugin.java b/mods/horizon-lab/src/main/java/dev/horizonlab/mixin/HorizonMixinPlugin.java index 81e33c998..e52e8f253 100644 --- a/mods/horizon-lab/src/main/java/dev/horizonlab/mixin/HorizonMixinPlugin.java +++ b/mods/horizon-lab/src/main/java/dev/horizonlab/mixin/HorizonMixinPlugin.java @@ -15,6 +15,7 @@ public final class HorizonMixinPlugin implements IMixinConfigPlugin { private static boolean workerPacing; private static boolean debounceWait; private static boolean dispatchRetry; + private static boolean tickDedup; @Override public void onLoad(String mixinPackage) { var loader = FabricLoader.getInstance(); @@ -63,15 +64,32 @@ public final class HorizonMixinPlugin implements IMixinConfigPlugin { } catch (Exception error) { LoggerFactory.getLogger("horizonlab").warn("Dispatch retry disabled: invalid configuration", error); } + try { + Properties properties = new Properties(); + var dedupFile = loader.getConfigDir().resolve("horizon-tick-dedup.properties"); + if (Files.exists(dedupFile)) { + try (var reader = Files.newBufferedReader(dedupFile)) { properties.load(reader); } + } + boolean requested = Boolean.parseBoolean(properties.getProperty("enabled", "false")); + boolean supported = loader.getModContainer("distanthorizons") + .map(mod -> mod.getMetadata().getVersion().getFriendlyString().equals("3.3.4")).orElse(false); + tickDedup = requested && supported; + if (requested) LoggerFactory.getLogger("horizonlab").info( + "DH tick membership deduplication: {} (requires pinned DH 3.3.4)", tickDedup ? "enabled" : "unavailable"); + } catch (Exception error) { + LoggerFactory.getLogger("horizonlab").warn("Tick membership deduplication disabled: invalid configuration", error); + } } public static boolean workerPacingEnabled() { return workerPacing; } public static boolean debounceWaitEnabled() { return debounceWait; } public static boolean dispatchRetryEnabled() { return dispatchRetry; } + public static boolean tickDedupEnabled() { return tickDedup; } @Override public boolean shouldApplyMixin(String targetClassName, String mixinClassName) { if (mixinClassName.endsWith("DhWorkerPacingMixin")) return workerPacing; if (mixinClassName.endsWith("DhDebounceWaitMixin")) return debounceWait; if (mixinClassName.endsWith("DhPriorityDispatchMixin")) return dispatchRetry; + if (mixinClassName.endsWith("DhTickDedupMixin")) return tickDedup; return true; } @Override public String getRefMapperConfig() { return null; } diff --git a/mods/horizon-lab/src/main/resources/fabric.mod.json b/mods/horizon-lab/src/main/resources/fabric.mod.json index eaf4711c6..21271d5ed 100644 --- a/mods/horizon-lab/src/main/resources/fabric.mod.json +++ b/mods/horizon-lab/src/main/resources/fabric.mod.json @@ -1,7 +1,7 @@ { "schemaVersion": 1, "id": "horizonlab", - "version": "0.12.0", + "version": "0.13.0", "name": "Horizon Lab", "description": "Client frame pacing and server tick measurements for reproducible optimization experiments.", "authors": [ diff --git a/mods/horizon-lab/src/main/resources/horizonlab.mixins.json b/mods/horizon-lab/src/main/resources/horizonlab.mixins.json index bf94e2ca2..308a9aee7 100644 --- a/mods/horizon-lab/src/main/resources/horizonlab.mixins.json +++ b/mods/horizon-lab/src/main/resources/horizonlab.mixins.json @@ -4,6 +4,6 @@ "plugin": "dev.horizonlab.mixin.HorizonMixinPlugin", "compatibilityLevel": "JAVA_25", "mixins": ["ServerTickMixin"], - "client": ["FrameMixin", "DhWorkerPacingMixin", "DhDebounceWaitMixin", "DhPriorityDispatchMixin"], + "client": ["FrameMixin", "DhWorkerPacingMixin", "DhDebounceWaitMixin", "DhPriorityDispatchMixin", "DhTickDedupMixin"], "injectors": {"defaultRequire": 1} } diff --git a/mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/TickDedupIntegration.java b/mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/TickDedupIntegration.java new file mode 100644 index 000000000..cdba3341a --- /dev/null +++ b/mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/TickDedupIntegration.java @@ -0,0 +1,87 @@ +package dev.horizonlab.dispatch; + +import com.seibel.distanthorizons.core.render.QuadTree.LodRenderSection; +import com.seibel.distanthorizons.core.render.QuadTree.QuadTreeTickNodeHolder; +import com.seibel.distanthorizons.core.util.objects.quadTree.QuadNode; +import dev.horizonlab.mixin.HorizonMixinPlugin; +import java.lang.management.ManagementFactory; +import java.util.ArrayList; +import java.util.HashSet; +import java.util.Random; +import net.fabricmc.api.ClientModInitializer; +import net.fabricmc.fabric.api.client.event.lifecycle.v1.ClientLifecycleEvents; + +/** Private Fabric fixture: semantic transitions and warmed allocation of the actual upstream holder. */ +public final class TickDedupIntegration implements ClientModInitializer { + private static volatile long checksum; + @Override public void onInitializeClient() { + ClientLifecycleEvents.CLIENT_STARTED.register(client -> { + exercise(); + if (Boolean.getBoolean("horizon.fixture.exit")) System.exit(0); + }); + } + + private static void exercise() { + ArrayList> nodes = new ArrayList<>(); + for (int index = 0; index < 512; index++) nodes.add(new QuadNode<>(index, (byte) 6)); + var holder = new QuadTreeTickNodeHolder(); + var present = new HashSet>(); + var enabled = new HashSet>(); + var disabled = new HashSet>(); + var deleteChildren = new ArrayList>(); + var random = new Random(0x4835); + for (int step = 0; step < 6000; step++) { + var node = step % 13 == 0 ? null : nodes.get(random.nextInt(nodes.size())); + switch (random.nextInt(5)) { + case 0 -> { holder.addEnableNode(node); if (present.add(node)) enabled.add(node); } + case 1 -> { holder.addDisableNode(node); if (present.add(node)) disabled.add(node); } + case 2 -> { holder.addEnableDeleteChildrenNode(node); if (present.add(node)) deleteChildren.add(node); } + case 3 -> { + holder.removeEnableAndDisableNode(node); + enabled.remove(node); deleteChildren.remove(node); present.add(node); disabled.add(node); + } + case 4 -> { holder.clear(); present.clear(); enabled.clear(); disabled.clear(); deleteChildren.clear(); } + } + // Comparing iteration order as well as membership verifies that published collections stay unchanged. + if (!new ArrayList<>(holder.getEnabledNodes()).equals(new ArrayList<>(enabled)) + || !new ArrayList<>(holder.getDisableNodes()).equals(new ArrayList<>(disabled)) + || !holder.getEnableDeleteChildrenNodes().equals(deleteChildren)) + throw new AssertionError("Action precedence or iteration order changed at step " + step); + } + var bean = (com.sun.management.ThreadMXBean) ManagementFactory.getThreadMXBean(); + bean.setThreadAllocatedMemoryEnabled(true); + bean.setThreadCpuTimeEnabled(true); + measureLoop(holder, nodes, 5000); + long id = Thread.currentThread().threadId(), bytes = bean.getThreadAllocatedBytes(id); + long cpu = bean.getCurrentThreadCpuTime(), wall = System.nanoTime(); + measureLoop(holder, nodes, 20000); + long wallDelta = System.nanoTime() - wall, cpuDelta = bean.getCurrentThreadCpuTime() - cpu; + long byteDelta = bean.getThreadAllocatedBytes(id) - bytes; + // clear must release references in the replacement too, not only empty the published collections. + holder.clear(); + if (HorizonMixinPlugin.tickDedupEnabled()) { + try { + var field = holder.getClass().getDeclaredField("horizon$presentNodes"); field.setAccessible(true); + if (!((java.util.Set) field.get(holder)).isEmpty()) throw new AssertionError("Retained tick members"); + } catch (ReflectiveOperationException failure) { throw new AssertionError("Missing applied membership hook", failure); } + } + System.out.println("HORIZON_TICK_DEDUP_RESULT {\"enabled\":" + HorizonMixinPlugin.tickDedupEnabled() + + ",\"allocated_bytes\":" + byteDelta + ",\"cpu_ns\":" + cpuDelta + ",\"wall_ns\":" + wallDelta + + ",\"nodes_per_tick\":512,\"measured_ticks\":20000,\"verified_transitions\":6000,\"checksum\":" + checksum + "}"); + } + + private static void measureLoop(QuadTreeTickNodeHolder holder, ArrayList> nodes, int repeats) { + long sum = 0; + for (int pass = 0; pass < repeats; pass++) { + holder.clear(); + for (int index = 0; index < nodes.size(); index++) { + var node = nodes.get(index); + holder.addEnableDeleteChildrenNode(node); + holder.addEnableDeleteChildrenNode(node); + } + if (holder.getEnableDeleteChildrenNodes().size() != nodes.size()) throw new AssertionError("Duplicate or lost node"); + sum += holder.getEnableDeleteChildrenNodes().size(); + } + checksum = sum; + } +} diff --git a/packs/START-HERE.txt b/packs/START-HERE.txt index a330369e3..afe0ce763 100644 --- a/packs/START-HERE.txt +++ b/packs/START-HERE.txt @@ -58,8 +58,13 @@ PROFILES This is a separate experiment: adaptive, worker-pacing and queue-wait are off. Set enabled=false in config/horizon-dispatch-retry.properties and restart to disable it. A synthetic applied-hook test checks exact task completion. +- tick-dedup: same balanced settings, with compact reusable storage for private + terrain tick membership checks. Action order and visual settings stay the same. + Set enabled=false in config/horizon-tick-dedup.properties and restart to disable. + Compare against m2-balanced for an isolated test; no Mac FPS gain is measured yet. - foreground-first: combines adaptive terrain, precise pacing, wakeable queue - waits and bounded rejected dispatch retries. Uses OpenGL and a 120 FPS + waits, bounded rejected dispatch retries and (since 0.13) tick membership reuse. + Uses OpenGL and a 120 FPS adaptive goal. This is not an FPS cap; terrain may take longer to appear. - foreground-vulkan: the same combined controls with Vulkan preference and OpenGL fallback. On Apple Silicon the game bundles a MoltenVK library. diff --git a/packs/mods.lock.json b/packs/mods.lock.json index 09f26a89a..c89996a73 100644 --- a/packs/mods.lock.json +++ b/packs/mods.lock.json @@ -3,7 +3,7 @@ "minecraft": "26.3", "java_major": 25, "fabric_loader": "0.19.5", - "pack_version": "0.12.0", + "pack_version": "0.13.0", "options_data_version": 5023, "projects": { "sodium": { diff --git a/tests/test_packs.py b/tests/test_packs.py index 38a6653e1..7aaff9586 100644 --- a/tests/test_packs.py +++ b/tests/test_packs.py @@ -66,7 +66,7 @@ class PackTests(unittest.TestCase): for name, backend in [("foreground-first", "opengl"), ("foreground-vulkan", "vulkan")]: files = build_pack.overrides(name, b"original fixture") self.assertEqual(files["config/horizon-adaptive.properties"], b"enabled=true\ntargetFps=120\n") - for key in ["worker-pacing", "queue-wait", "dispatch-retry"]: + for key in ["worker-pacing", "queue-wait", "dispatch-retry", "tick-dedup"]: self.assertEqual(files[f"config/horizon-{key}.properties"], b"enabled=true\n") options = dict(line.split(":", 1) for line in files["options.txt"].decode().splitlines()) self.assertEqual(options["simulationDistance"], "12") @@ -75,6 +75,18 @@ class PackTests(unittest.TestCase): self.assertEqual(json.loads(options["preferredGraphicsBackend"]), backend) self.assertNotIn("config/iris.properties", files) + def test_tick_membership_experiment_preserves_visual_and_worker_settings(self): + original = build_pack.overrides("m2-balanced", b"fixture") + for name in build_pack.PROFILES: + files = build_pack.overrides(name, b"fixture") + self.assertEqual(files["config/horizon-tick-dedup.properties"], + b"enabled=true\n" if name in {"tick-dedup", "foreground-first", "foreground-vulkan"} else b"enabled=false\n") + candidate = build_pack.overrides("tick-dedup", b"fixture") + for filename in ["options.txt", "config/DistantHorizons.toml", "config/horizon-adaptive.properties", + "config/horizon-worker-pacing.properties", "config/horizon-queue-wait.properties", + "config/horizon-dispatch-retry.properties"]: + self.assertEqual(original[filename], candidate[filename]) + def test_wrong_game_or_download_path_is_rejected(self): for field, value in [("game_versions", ["1.21"]), ("filename", "../bad.jar"), ("url", "http://unsafe.invalid")]: lock = copy.deepcopy(build_pack.read_lock()) diff --git a/tools/Compare-Benchmarks.html b/tools/Compare-Benchmarks.html index 892c610c3..acf36697e 100644 --- a/tools/Compare-Benchmarks.html +++ b/tools/Compare-Benchmarks.html @@ -66,7 +66,7 @@ function compareReports(a,b){ else if(JSON.stringify(a[key])!==JSON.stringify(b[key]))warnings.push('JVM '+key+' differs. Treat it as an explicit experiment variable.'); } if(a.kind==='frames'){ - for(const key of ['adaptive_budget_enabled','adaptive_target_fps','precise_worker_pacing','debounce_queue_wait','wakeable_idle_wait','dispatch_retry_backoff','dh_thread_count','dh_runtime_ratio']){ + for(const key of ['adaptive_budget_enabled','adaptive_target_fps','precise_worker_pacing','debounce_queue_wait','wakeable_idle_wait','dispatch_retry_backoff','tick_membership_dedup','dh_thread_count','dh_runtime_ratio']){ if(key in a&&key in b&&JSON.stringify(a[key])!==JSON.stringify(b[key]))warnings.push('Experiment '+key+' differs.'); } for(const [label,r] of [['Baseline',a],['Candidate',b]]){ @@ -124,6 +124,7 @@ function renderDetails(side){ } fields.push(['Rejected dispatch retry', r.dispatch_retry_backoff===true?'on':r.dispatch_retry_backoff===false?'off':'not captured']); fields.push(['Wakeable queue idle', r.wakeable_idle_wait===true?'on':r.wakeable_idle_wait===false?'off':'not captured']); + if(r.kind==='frames')fields.push(['Tick membership deduplication',r.tick_membership_dedup===true?'on':r.tick_membership_dedup===false?'off':'not captured']); for(const [label,value]of fields)target.append(text('dt',label),text('dd',value)); } async function loadFiles(side,files){ diff --git a/tools/build_mod.py b/tools/build_mod.py index ffb044250..2b1c3617e 100644 --- a/tools/build_mod.py +++ b/tools/build_mod.py @@ -119,24 +119,32 @@ def build(): def build_dispatch_fixture(): + return build_integration_fixture("dispatch", "dev.horizonlab.dispatch.DispatchIntegration") + + +def build_tick_dedup_fixture(): + return build_integration_fixture("tick-dedup", "dev.horizonlab.dispatch.TickDedupIntegration") + + +def build_integration_fixture(name, entrypoint): """Create a private integration-test mod; never include it in release packs.""" arguments = [json.loads(line) for line in (BUILD / "javac.args").read_text().splitlines()] classpath = arguments[arguments.index("-classpath") + 1] + os.pathsep + str(BUILD / "classes") - classes = BUILD / "dispatch-fixture" + classes = BUILD / f"{name}-fixture" if classes.exists(): shutil.rmtree(classes) classes.mkdir(parents=True) subprocess.run(["javac", "--release", "25", "-proc:none", "-classpath", classpath, - "-d", str(classes), str(SOURCE / "test/java/dev/horizonlab/dispatch/DispatchIntegration.java")], check=True) - output = BUILD / "dispatch-fixture.jar" + "-d", str(classes), str(SOURCE / "test/java" / (entrypoint.replace(".", "/") + ".java"))], check=True) + output = BUILD / f"{name}-fixture.jar" with zipfile.ZipFile(output, "w", compression=zipfile.ZIP_DEFLATED) as archive: for path in sorted(classes.rglob("*.class")): archive.write(path, path.relative_to(classes).as_posix()) - archive.writestr("fabric.mod.json", json.dumps({"schemaVersion": 1, "id": "horizon_dispatch_fixture", + archive.writestr("fabric.mod.json", json.dumps({"schemaVersion": 1, "id": "horizon_" + name.replace("-", "_") + "_fixture", "version": "1.0.0", "environment": "client", - "entrypoints": {"client": ["dev.horizonlab.dispatch.DispatchIntegration"]}, + "entrypoints": {"client": [entrypoint]}, "depends": {"horizonlab": "*", "distanthorizons": "3.3.4"}})) - print(f"Private dispatch integration fixture: {output}") + print(f"Private {name} integration fixture: {output}") return output diff --git a/tools/build_pack.py b/tools/build_pack.py index 27ac5dab5..c131e878d 100644 --- a/tools/build_pack.py +++ b/tools/build_pack.py @@ -24,8 +24,9 @@ PROFILES = { "queue-wait": {"title": "Debounce queue wait experiment", "mods": CORE + ["distanthorizons"], "render": 12, "lod": 128, "heap": 6144, "queue_wait": True}, "adaptive-queue": {"title": "Adaptive pacing and queue wait experiment", "mods": CORE + ["distanthorizons"], "render": 12, "lod": 128, "heap": 6144, "adaptive": True, "pacing": True, "queue_wait": True}, "dispatch-retry": {"title": "Rejected dispatch retry experiment", "mods": CORE + ["distanthorizons"], "render": 12, "lod": 128, "heap": 6144, "dispatch_retry": True}, - "foreground-first": {"title": "Foreground-first combined experiment", "mods": CORE + ["distanthorizons"], "render": 12, "lod": 128, "heap": 6144, "adaptive": True, "pacing": True, "queue_wait": True, "dispatch_retry": True, "target_fps": 120}, - "foreground-vulkan": {"title": "Foreground-first Vulkan experiment", "mods": CORE + ["distanthorizons"], "render": 12, "lod": 128, "heap": 6144, "adaptive": True, "pacing": True, "queue_wait": True, "dispatch_retry": True, "target_fps": 120, "backend": "vulkan"}, + "tick-dedup": {"title": "Terrain tick membership experiment", "mods": CORE + ["distanthorizons"], "render": 12, "lod": 128, "heap": 6144, "tick_dedup": True}, + "foreground-first": {"title": "Foreground-first combined experiment", "mods": CORE + ["distanthorizons"], "render": 12, "lod": 128, "heap": 6144, "adaptive": True, "pacing": True, "queue_wait": True, "dispatch_retry": True, "tick_dedup": True, "target_fps": 120}, + "foreground-vulkan": {"title": "Foreground-first Vulkan experiment", "mods": CORE + ["distanthorizons"], "render": 12, "lod": 128, "heap": 6144, "adaptive": True, "pacing": True, "queue_wait": True, "dispatch_retry": True, "tick_dedup": True, "target_fps": 120, "backend": "vulkan"}, "low-memory": {"title": "Low memory", "mods": CORE, "render": 8, "lod": 0, "heap": 3072}, "far-distance": {"title": "Far distance", "mods": CORE + ["distanthorizons"], "render": 12, "lod": 256, "heap": 8192}, "cinematic": {"title": "Cinematic (optional)", "mods": CORE + ["distanthorizons", "iris", "complementary-reimagined"], "render": 12, "lod": 128, "heap": 6144}, @@ -79,7 +80,7 @@ def overrides(profile_name, mod_bytes): files = {f"mods/horizon-lab-{read_lock()['pack_version']}.jar": mod_bytes, "config/horizon-profile.txt": (profile_name + "\n").encode(), "options.txt": options(profile).encode()} - experiment = any(profile.get(key, False) for key in ["adaptive", "pacing", "queue_wait", "dispatch_retry"]) + experiment = any(profile.get(key, False) for key in ["adaptive", "pacing", "queue_wait", "dispatch_retry", "tick_dedup"]) config = ROOT / "packs/config" / f"{'m2-balanced' if experiment else profile_name}.toml" files["config/horizon-adaptive.properties"] = ( f"enabled={str(profile.get('adaptive', False)).lower()}\ntargetFps={profile.get('target_fps', 60)}\n").encode() @@ -89,6 +90,8 @@ def overrides(profile_name, mod_bytes): f"enabled={str(profile.get('queue_wait', False)).lower()}\n").encode() files["config/horizon-dispatch-retry.properties"] = ( f"enabled={str(profile.get('dispatch_retry', False)).lower()}\n").encode() + files["config/horizon-tick-dedup.properties"] = ( + f"enabled={str(profile.get('tick_dedup', False)).lower()}\n").encode() if profile["lod"]: if not config.exists(): raise FileNotFoundError(f"Missing verified DH profile config: {config}") diff --git a/tools/compare_benchmarks.py b/tools/compare_benchmarks.py index 99ecaeaa5..3c2e93b9b 100644 --- a/tools/compare_benchmarks.py +++ b/tools/compare_benchmarks.py @@ -28,7 +28,7 @@ def compare(baseline, candidate): warnings = ["World, route, warm-up, shader state and LOD cache must also match; these are not verified by this tool."] if baseline["kind"] == "frames": for field in ["adaptive_budget_enabled", "adaptive_target_fps", "precise_worker_pacing", "debounce_queue_wait", - "wakeable_idle_wait", "dispatch_retry_backoff", "dh_thread_count", "dh_runtime_ratio"]: + "wakeable_idle_wait", "dispatch_retry_backoff", "tick_membership_dedup", "dh_thread_count", "dh_runtime_ratio"]: if field in baseline and field in candidate and baseline[field] != candidate[field]: warnings.append(f"Experiment {field} differs: {baseline[field]!r} vs {candidate[field]!r}.") for name, report in [("baseline", baseline), ("candidate", candidate)]: diff --git a/tools/test_tick_dedup.py b/tools/test_tick_dedup.py new file mode 100644 index 000000000..94153b614 --- /dev/null +++ b/tools/test_tick_dedup.py @@ -0,0 +1,63 @@ +#!/usr/bin/env python3 +"""Check actual DH tick transitions and allocation with the optional membership hook off/on.""" + +import argparse +import json +import os +import platform +import shutil +import subprocess +import sys + +try: + from . import build_mod, build_pack +except ImportError: + import build_mod + import build_pack + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--native-display", action="store_true") + args = parser.parse_args() + root = build_pack.ROOT + fixture = build_mod.build_tick_dedup_fixture() + mod = root / "dist" / f"horizon-lab-{build_pack.read_lock()['pack_version']}.jar" + results = [] + for enabled in [False, True]: + instance = root / ".local/runtime" / ("tick-dedup-fixture-patched" if enabled else "tick-dedup-fixture-upstream") + build_pack.prepare_instance("m2-balanced", instance, mod) + shutil.copy2(fixture, instance / "mods/tick-dedup-fixture.jar") + (instance / "config/horizon-tick-dedup.properties").write_text(f"enabled={str(enabled).lower()}\n") + command = [sys.executable, str(root / "tools/runtime.py"), "demo", "--instance", str(instance), "--heap", "3G", "--compact-headers"] + if platform.system() == "Linux" and not args.native_display: + command = ["xvfb-run", "-a", *command] + environment = os.environ.copy() + environment["_JAVA_OPTIONS"] = "-Dhorizon.fixture.exit=true" + run = subprocess.run(command, cwd=root, env=environment, text=True, stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, timeout=240) + (instance / "fixture.log").write_text(run.stdout) + marker = "HORIZON_TICK_DEDUP_RESULT " + reports = [json.loads(line.split(marker, 1)[1]) for line in run.stdout.splitlines() if marker in line] + if run.returncode or len(reports) != 1: + raise RuntimeError(f"Tick dedup fixture failed; inspect {instance / 'fixture.log'}") + report = reports[0] + if report["enabled"] != enabled or report["verified_transitions"] != 6000 or report["checksum"] != 10240000: + raise AssertionError("Applied hook or semantic outcome did not match") + results.append(report) + print(json.dumps(report), flush=True) + if results[0]["allocated_bytes"] <= 0 or results[1]["allocated_bytes"] >= results[0]["allocated_bytes"] / 20: + raise AssertionError("Membership hook did not remove repeated entry allocation") + output = root / "dist/tick-dedup-integration.json" + output.write_text(json.dumps({"schema": 1, "platform": platform.platform(), "architecture": platform.machine(), + "minecraft": "26.3", "distant_horizons": "3.3.4", "results": results, + "notes": ["Actual publisher tick holder under Fabric, warmed with preallocated nodes and a reused action list.", + "Checks duplicate/null membership, enable/disable precedence, published iteration order and clear boundaries.", + "Only private membership checks change; action collections and traversal remain upstream.", + "CPU and allocation measure the calling thread in one isolated loop; no statistical speed claim.", + "Not a game FPS, visible terrain completion, whole-game RAM or Mac GPU benchmark."]}, indent=2) + "\n") + print(f"Applied tick membership checks passed: {output}") + + +if __name__ == "__main__": + main() From f6b36854ed5d1e8abb40ac3d245160e6b3a4ffff Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Sun, 4 Oct 2026 01:52:49 +0200 Subject: [PATCH 2/2] Publish sanitized applied tick membership measurements with CI provenance --- .../linux-applied-hooks.json | 41 +++++++++++++++++++ docs/tick-membership.md | 5 +++ 2 files changed, 46 insertions(+) create mode 100644 benchmarks/tick-membership-2026-10-04/linux-applied-hooks.json diff --git a/benchmarks/tick-membership-2026-10-04/linux-applied-hooks.json b/benchmarks/tick-membership-2026-10-04/linux-applied-hooks.json new file mode 100644 index 000000000..1b5b43fa8 --- /dev/null +++ b/benchmarks/tick-membership-2026-10-04/linux-applied-hooks.json @@ -0,0 +1,41 @@ +{ + "schema": 1, + "platform": "Linux-6.17.0-1022-azure-x86_64-with-glibc2.39", + "architecture": "x86_64", + "minecraft": "26.3", + "distant_horizons": "3.3.4", + "results": [ + { + "enabled": false, + "allocated_bytes": 245760208, + "cpu_ns": 423649902, + "wall_ns": 481491629, + "nodes_per_tick": 512, + "measured_ticks": 20000, + "verified_transitions": 6000, + "checksum": 10240000 + }, + { + "enabled": true, + "allocated_bytes": 208, + "cpu_ns": 185922780, + "wall_ns": 192151484, + "nodes_per_tick": 512, + "measured_ticks": 20000, + "verified_transitions": 6000, + "checksum": 10240000 + } + ], + "notes": [ + "Actual publisher tick holder under Fabric, warmed with preallocated nodes and a reused action list.", + "Checks duplicate/null membership, enable/disable precedence, published iteration order and clear boundaries.", + "Only private membership checks change; action collections and traversal remain upstream.", + "CPU and allocation measure the calling thread in one isolated loop; no statistical speed claim.", + "Not a game FPS, visible terrain completion, whole-game RAM or Mac GPU benchmark." + ], + "provenance": { + "source_commit": "e091816ce06686d64d0f7a181a42701aa67e5bf7", + "ci_run": "https://github.com/ludovic111/minecraft-optimization-lab/actions/runs/37162939262", + "artifact": "horizon-ubuntu-latest" + } +} diff --git a/docs/tick-membership.md b/docs/tick-membership.md index c01d01ca1..fab277f19 100644 --- a/docs/tick-membership.md +++ b/docs/tick-membership.md @@ -37,3 +37,8 @@ statistical speedup, game FPS gain, whole-game RAM reduction, completed terrain or performance on an M2 GPU. Actual game profiles and repeated Mac comparisons are required for those conclusions. Table capacity remains proportional to the largest tick membership, as the upstream hash table already did. + +The [sanitized Linux CI result](../benchmarks/tick-membership-2026-10-04/linux-applied-hooks.json) +includes its source commit and workflow provenance. It independently reproduced +the same allocation counts and transition checks. Its CPU timings are another +single warmed observation, not a statistical estimate or Mac result.