From 7cbe37b60594fb1631bc308f126d7925c4264a18 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Sun, 4 Oct 2026 03:32:06 +0200 Subject: [PATCH] Reuse per-instance numeric vectors in optional culling ray checks --- .github/workflows/ci.yml | 6 + README.md | 8 +- docs/culling-rays.md | 45 ++++++ .../dev/horizonlab/client/HorizonClient.java | 1 + .../mixin/CullingRayScratchMixin.java | 28 ++++ .../horizonlab/mixin/HorizonMixinPlugin.java | 18 +++ .../src/main/resources/fabric.mod.json | 2 +- .../src/main/resources/horizonlab.mixins.json | 19 ++- .../dispatch/CullingRayIntegration.java | 148 ++++++++++++++++++ .../dispatch/fixture/CullingRayAccess.java | 16 ++ packs/START-HERE.txt | 4 + packs/mods.lock.json | 2 +- tests/test_packs.py | 12 ++ tools/Compare-Benchmarks.html | 3 +- tools/build_mod.py | 22 ++- tools/build_pack.py | 5 +- tools/compare_benchmarks.py | 2 +- tools/test_culling_rays.py | 92 +++++++++++ 18 files changed, 418 insertions(+), 15 deletions(-) create mode 100644 docs/culling-rays.md create mode 100644 mods/horizon-lab/src/main/java/dev/horizonlab/mixin/CullingRayScratchMixin.java create mode 100644 mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/CullingRayIntegration.java create mode 100644 mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/fixture/CullingRayAccess.java create mode 100644 tools/test_culling_rays.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8003db66d..fa1a32c15 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -65,6 +65,8 @@ jobs: run: python -c "from tools.build_mod import build_tick_dedup_fixture; build_tick_dedup_fixture()" - name: Compile the private culling whitelist fixture run: python -c "from tools.build_mod import build_culling_empty_fixture; build_culling_empty_fixture()" + - name: Compile the private culling ray geometry fixture + run: python -c "from tools.build_mod import build_integration_fixture; build_integration_fixture('culling-rays', 'dev.horizonlab.dispatch.CullingRayIntegration', ['entityculling'], ['CullingRayAccess'])" - name: Compile the private terrain read shutdown fixture run: python -c "from tools.build_mod import build_integration_fixture; build_integration_fixture('terrain-read', 'dev.horizonlab.dispatch.TerrainReadIntegration')" - name: Install headless graphics libraries for applied-hook checks @@ -79,6 +81,9 @@ jobs: - name: Verify live culling whitelist registration and empty iteration if: runner.os == 'Linux' run: python tools/test_culling_empty.py + - name: Compare applied culling ray geometry and provider queries + if: runner.os == 'Linux' + run: python tools/test_culling_rays.py - name: Verify interrupted DH reads and preserved shared futures if: runner.os == 'Linux' run: python tools/test_terrain_read.py @@ -97,3 +102,4 @@ jobs: dist/tick-dedup-integration.json dist/culling-empty-integration.json dist/terrain-read-integration.json + dist/culling-rays-integration.json diff --git a/README.md b/README.md index 8e545f0df..8f53e2813 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.14.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.15.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. @@ -22,6 +22,7 @@ Use native **Java 25 ARM64**, maximum heap **6144 MiB**, minimum **512 MiB** on | dispatch-retry (experimental) | 12 | 128 | 6144 MiB | | tick-dedup (experimental) | 12 | 128 | 6144 MiB | | culling-empty (experimental) | 12 | 128 | 6144 MiB | +| culling-rays (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 | @@ -35,6 +36,11 @@ 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.15 adds an isolated [culling ray scratch experiment](docs/culling-rays.md) +that reuses two numeric vectors within each culling instance while retaining +upstream arithmetic and decisions. Balanced keeps it off; hardware gains remain +unmeasured. + Version 0.14 adds an isolated [empty culling whitelist experiment](docs/culling-empty.md) that avoids allocating iterators while there are no dynamic handlers. Live registration and nonempty callbacks retain upstream behavior. Balanced keeps it diff --git a/docs/culling-rays.md b/docs/culling-rays.md new file mode 100644 index 000000000..86b090074 --- /dev/null +++ b/docs/culling-rays.md @@ -0,0 +1,45 @@ +# Reuse numeric scratch vectors in visibility tests + +A game allocation profile found temporary vectors in the pinned Entity Culling +1.11.2 visibility library. Its visibility check creates a direction vector, then +normalizes it; its ray intersection creates a second vector for reciprocals. +These vectors remain within the calculation and carry only numeric values. + +The opt-in hook redirects those two constructors to separate vectors owned by +that culling instance. All three components are reset each time. Upstream +normalization, division, intersection, traversal, caches and decisions stay in +place. No approximation, ray limit, global pool or shared scratch object is added. +The instance already keeps mutable camera, target, hit-block and cache state; +the hook retains that single-caller contract. It does not make an instance safe +for concurrent or reentrant calls. Two retained numeric objects per instance +replace temporary objects on this path. + +Use `culling-rays` for an isolated comparison with `m2-balanced`. Graphics, LOD +radius, worker budget and other controller settings match. All other profiles, +including the combined foreground experiments, explicitly keep this hook off. +It only applies to Entity Culling 1.11.2. To disable, set `enabled=false` in +`config/horizon-culling-rays.properties` and restart. Frame reports record the +actual `culling_ray_scratch` state; the CLI and offline viewer disclose changes +in that state. + +`python tools/test_culling_rays.py` runs the publisher's actual geometry with the +hook disabled and enabled. It compares boolean and provider-query digests for +12,800 bounding-box checks across eight occluder patterns and two interleaved +instances. Each mode performed the same 105,239 block reads. It also checks +2,197 direct ray cases covering signed zero, tiny and large values, infinities +and NaN, unchanged input vectors, separate instance scratch objects and retained +arithmetic values. The test uses private fixture invokers; its JAR and accessors +never enter a release pack. These cases support this workload's equivalence, +rather than proving every world's rendered pixels or every mod callback. + +A local warmed loop of two million visibility checks allocated 24,318,096 bytes +with the original constructors versus 920 with scratch reuse. Single caller CPU +observations were about 167 versus 149 ms. Another unchanged run allocated only +6,259,360 bytes, illustrating how JIT compilation and escape analysis vary during +these loops. No fixed per-check allocation or statistical speedup is inferred. +This is not a whole-game FPS/RAM or Mac GPU benchmark; repeated real hardware +comparisons and live allocation profiles are required. + +The factory hook follows the upstream [Mixin constructor redirect contract](https://github.com/SpongePowered/Mixin/blob/master/src/main/java/org/spongepowered/asm/mixin/injection/Redirect.java). +Compilation uses a checksum-verified publisher JAR; the release mod contains only +original Horizon classes. Profiles without Entity Culling must still load. 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 e9e2cf095..d8cce7ae9 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 @@ -97,6 +97,7 @@ public final class HorizonClient implements ClientModInitializer { 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("culling_ray_scratch", dev.horizonlab.mixin.HorizonMixinPlugin.cullingRayScratchEnabled()); context.put("empty_culling_whitelist", dev.horizonlab.mixin.HorizonMixinPlugin.cullingEmptyEnabled()); context.put("interruptible_terrain_read", dev.horizonlab.mixin.HorizonMixinPlugin.terrainReadWaitEnabled()); context.put("adaptive_target_fps", targetFps); diff --git a/mods/horizon-lab/src/main/java/dev/horizonlab/mixin/CullingRayScratchMixin.java b/mods/horizon-lab/src/main/java/dev/horizonlab/mixin/CullingRayScratchMixin.java new file mode 100644 index 000000000..75fc84f6a --- /dev/null +++ b/mods/horizon-lab/src/main/java/dev/horizonlab/mixin/CullingRayScratchMixin.java @@ -0,0 +1,28 @@ +package dev.horizonlab.mixin; + +import com.logisticscraft.occlusionculling.util.Vec3d; +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.Redirect; + +/** Keep temporary numeric vectors on the already mutable, single-caller culling instance. */ +@Mixin(targets = "com.logisticscraft.occlusionculling.OcclusionCullingInstance", remap = false) +public abstract class CullingRayScratchMixin { + @Unique private final Vec3d horizon$rayDirection = new Vec3d(0, 0, 0); + @Unique private final Vec3d horizon$inverseDirection = new Vec3d(0, 0, 0); + + @Redirect(method = "isVisible", at = @At(value = "NEW", + target = "(DDD)Lcom/logisticscraft/occlusionculling/util/Vec3d;")) + private Vec3d horizon$direction(double x, double y, double z) { + horizon$rayDirection.set(x, y, z); + return horizon$rayDirection; + } + + @Redirect(method = "rayIntersection", at = @At(value = "NEW", + target = "(DDD)Lcom/logisticscraft/occlusionculling/util/Vec3d;")) + private Vec3d horizon$inverse(double x, double y, double z) { + horizon$inverseDirection.set(x, y, z); + return horizon$inverseDirection; + } +} 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 1a30f4a6e..5c200977e 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 @@ -18,6 +18,7 @@ public final class HorizonMixinPlugin implements IMixinConfigPlugin { private static boolean tickDedup; private static boolean cullingEmpty; private static boolean terrainReadWait; + private static boolean cullingRayScratch; @Override public void onLoad(String mixinPackage) { var loader = FabricLoader.getInstance(); @@ -114,6 +115,21 @@ public final class HorizonMixinPlugin implements IMixinConfigPlugin { } catch (Exception error) { LoggerFactory.getLogger("horizonlab").warn("Interruptible terrain read disabled: invalid configuration", error); } + try { + Properties properties = new Properties(); + var rayFile = loader.getConfigDir().resolve("horizon-culling-rays.properties"); + if (Files.exists(rayFile)) { + try (var reader = Files.newBufferedReader(rayFile)) { properties.load(reader); } + } + boolean requested = Boolean.parseBoolean(properties.getProperty("enabled", "false")); + boolean supported = loader.getModContainer("entityculling") + .map(mod -> mod.getMetadata().getVersion().getFriendlyString().equals("1.11.2")).orElse(false); + cullingRayScratch = requested && supported; + if (requested) LoggerFactory.getLogger("horizonlab").info( + "Culling ray scratch vectors: {} (requires pinned Entity Culling 1.11.2)", cullingRayScratch ? "enabled" : "unavailable"); + } catch (Exception error) { + LoggerFactory.getLogger("horizonlab").warn("Culling ray scratch vectors disabled: invalid configuration", error); + } } public static boolean workerPacingEnabled() { return workerPacing; } @@ -121,6 +137,7 @@ public final class HorizonMixinPlugin implements IMixinConfigPlugin { public static boolean dispatchRetryEnabled() { return dispatchRetry; } public static boolean tickDedupEnabled() { return tickDedup; } public static boolean cullingEmptyEnabled() { return cullingEmpty; } + public static boolean cullingRayScratchEnabled() { return cullingRayScratch; } public static boolean terrainReadWaitEnabled() { return terrainReadWait; } @Override public boolean shouldApplyMixin(String targetClassName, String mixinClassName) { if (mixinClassName.endsWith("DhWorkerPacingMixin")) return workerPacing; @@ -128,6 +145,7 @@ public final class HorizonMixinPlugin implements IMixinConfigPlugin { if (mixinClassName.endsWith("DhPriorityDispatchMixin")) return dispatchRetry; if (mixinClassName.endsWith("DhTickDedupMixin")) return tickDedup; if (mixinClassName.endsWith("CullingEmptyWhitelistMixin")) return cullingEmpty; + if (mixinClassName.endsWith("CullingRayScratchMixin")) return cullingRayScratch; if (mixinClassName.endsWith("DhTerrainReadWaitMixin")) return terrainReadWait; return true; } diff --git a/mods/horizon-lab/src/main/resources/fabric.mod.json b/mods/horizon-lab/src/main/resources/fabric.mod.json index 175a5526c..058cf4932 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.14.0", + "version": "0.15.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 bc3639af1..ae611c454 100644 --- a/mods/horizon-lab/src/main/resources/horizonlab.mixins.json +++ b/mods/horizon-lab/src/main/resources/horizonlab.mixins.json @@ -3,7 +3,20 @@ "package": "dev.horizonlab.mixin", "plugin": "dev.horizonlab.mixin.HorizonMixinPlugin", "compatibilityLevel": "JAVA_25", - "mixins": ["ServerTickMixin"], - "client": ["FrameMixin", "DhWorkerPacingMixin", "DhDebounceWaitMixin", "DhPriorityDispatchMixin", "DhTickDedupMixin", "CullingEmptyWhitelistMixin", "DhTerrainReadWaitMixin"], - "injectors": {"defaultRequire": 1} + "mixins": [ + "ServerTickMixin" + ], + "client": [ + "FrameMixin", + "DhWorkerPacingMixin", + "DhDebounceWaitMixin", + "DhPriorityDispatchMixin", + "DhTickDedupMixin", + "CullingEmptyWhitelistMixin", + "DhTerrainReadWaitMixin", + "CullingRayScratchMixin" + ], + "injectors": { + "defaultRequire": 1 + } } diff --git a/mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/CullingRayIntegration.java b/mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/CullingRayIntegration.java new file mode 100644 index 000000000..bce36d98f --- /dev/null +++ b/mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/CullingRayIntegration.java @@ -0,0 +1,148 @@ +package dev.horizonlab.dispatch; + +import com.logisticscraft.occlusionculling.DataProvider; +import com.logisticscraft.occlusionculling.OcclusionCullingInstance; +import com.logisticscraft.occlusionculling.util.Vec3d; +import dev.horizonlab.mixin.HorizonMixinPlugin; +import dev.horizonlab.dispatch.fixture.CullingRayAccess; +import java.lang.management.ManagementFactory; +import java.security.MessageDigest; +import java.util.HexFormat; +import java.util.Random; +import net.fabricmc.api.ClientModInitializer; +import net.fabricmc.fabric.api.client.event.lifecycle.v1.ClientLifecycleEvents; + +/** Private applied-hook fixture; baseline and candidate run the same publisher geometry. */ +public final class CullingRayIntegration implements ClientModInitializer { + private static volatile long checksum; + private static final class Provider implements DataProvider { + final MessageDigest digest; + final byte[] coordinates = new byte[12]; + final int pattern; + int queries; + Provider(int pattern) throws Exception { this.pattern = pattern; digest = MessageDigest.getInstance("SHA-256"); } + private void number(int offset, int value) { + for (int byteIndex = 0; byteIndex < 4; byteIndex++) coordinates[offset + byteIndex] = (byte) (value >>> (24 - 8 * byteIndex)); + } + @Override public boolean prepareChunk(int x, int z) { + number(0, x); number(4, z); number(8, 0x1122); digest.update(coordinates); return true; + } + @Override public boolean isOpaqueFullCube(int x, int y, int z) { + number(0, x); number(4, y); number(8, z); digest.update(coordinates); queries++; + return switch (pattern) { + case 0 -> false; + case 1 -> true; + case 2 -> x == 0; + case 3 -> y == 0; + case 4 -> z == 0; + case 5 -> ((x + y + z) & 1) == 0; + case 6 -> x % 3 == 0 && z % 3 == 0; + default -> Math.floorMod(x * 73856093 ^ y * 19349663 ^ z * 83492791, 7) < 2; + }; + } + } + @Override public void onInitializeClient() { + ClientLifecycleEvents.CLIENT_STARTED.register(client -> { + try { exercise(); } + catch (Exception failure) { throw new AssertionError("Culling ray fixture failed", failure); } + if (Boolean.getBoolean("horizon.fixture.exit")) System.exit(0); + }); + } + private static void bit(MessageDigest digest, boolean value) { digest.update((byte) (value ? 1 : 0)); } + private static Vec3d scratch(OcclusionCullingInstance owner, String fieldName) throws Exception { + var field = owner.getClass().getDeclaredField(fieldName); field.setAccessible(true); return (Vec3d) field.get(owner); + } + private static void same(Vec3d actual, Vec3d expected) { + if (Double.doubleToLongBits(actual.x) != Double.doubleToLongBits(expected.x) + || Double.doubleToLongBits(actual.y) != Double.doubleToLongBits(expected.y) + || Double.doubleToLongBits(actual.z) != Double.doubleToLongBits(expected.z)) + throw new AssertionError("Scratch reset or upstream arithmetic changed: actual=" + actual.x + "," + actual.y + "," + actual.z + + " expected=" + expected.x + "," + expected.y + "," + expected.z); + } + private static void exercise() throws Exception { + boolean enabled = HorizonMixinPlugin.cullingRayScratchEnabled(); + var visibility = MessageDigest.getInstance("SHA-256"); + var queries = MessageDigest.getInstance("SHA-256"); + var intersections = MessageDigest.getInstance("SHA-256"); + var random = new Random(0x4a19); + int boxes = 0, reads = 0; + for (int pattern = 0; pattern < 8; pattern++) { + var firstProvider = new Provider(pattern); var secondProvider = new Provider(pattern); + var first = new OcclusionCullingInstance(16, firstProvider); + var second = new OcclusionCullingInstance(16, secondProvider); + if (enabled) { + var direction = scratch(first, "horizon$rayDirection"); + var inverse = scratch(first, "horizon$inverseDirection"); + if (direction == inverse || direction == scratch(second, "horizon$rayDirection") + || inverse == scratch(second, "horizon$inverseDirection")) throw new AssertionError("Scratch state was shared"); + } + Vec3d camera = new Vec3d(-2.5, 0.5, 2.5), otherCamera = new Vec3d(2.5, -0.5, -2.5); + for (int index = 0; index < 800; index++) { + if (index % 17 == 0) { first.resetCache(); second.resetCache(); } + double x = random.nextInt(15) - 7 + (index % 3 == 0 ? 0 : random.nextDouble()); + double y = random.nextInt(15) - 7 + (index % 5 == 0 ? 0 : random.nextDouble()); + double z = random.nextInt(15) - 7 + (index % 7 == 0 ? 0 : random.nextDouble()); + var min = new Vec3d(x, y, z); + var max = new Vec3d(x + (index % 11 == 0 ? 0 : random.nextDouble() * 2), + y + (index % 13 == 0 ? 0 : random.nextDouble() * 2), z + (index % 19 == 0 ? 0 : random.nextDouble() * 2)); + bit(visibility, first.isAABBVisible(min, max, camera)); + bit(visibility, second.isAABBVisible(min, max, otherCamera)); + boxes += 2; + } + queries.update(firstProvider.digest.digest()); queries.update(secondProvider.digest.digest()); + reads += firstProvider.queries + secondProvider.queries; + } + var owner = new OcclusionCullingInstance(16, new Provider(1)); + var access = (CullingRayAccess) owner; + var camera = new Vec3d(-2, -2, -2); + double[] values = {0.0, -0.0, 1, -1, Double.MIN_VALUE, -Double.MIN_VALUE, 1e-300, -1e-300, + 1e300, -1e300, Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY, Double.NaN}; + int rays = 0; + for (double x : values) for (double y : values) for (double z : values) { + var input = new Vec3d(x, y, z); + bit(intersections, access.horizon$intersects(new int[]{0, 0, 0}, camera, input)); + same(input, new Vec3d(x, y, z)); + if (enabled) same(scratch(owner, "horizon$inverseDirection"), new Vec3d(1, 1, 1).div(input)); + rays++; + } + var points = new Vec3d[64]; + for (int index = 0; index < points.length; index++) points[index] = new Vec3d(4 + index * 0.001, 4, 4); + java.util.Arrays.fill(access.horizon$lastBlock(), 0); + java.util.Arrays.fill(access.horizon$cameraBlock(), -2); + var directionObject = enabled ? scratch(owner, "horizon$rayDirection") : null; + var inverseObject = enabled ? scratch(owner, "horizon$inverseDirection") : null; + for (var point : points) { + access.horizon$checks(true); + bit(intersections, access.horizon$visible(camera, new Vec3d[]{point}, 1)); + if (enabled) { + var expected = new Vec3d(camera.x - point.x, camera.y - point.y, camera.z - point.z).normalize(); + same(directionObject, expected); same(inverseObject, new Vec3d(1, 1, 1).div(expected)); + } + } + loop(access, camera, points, 200000); + var bean = (com.sun.management.ThreadMXBean) ManagementFactory.getThreadMXBean(); + bean.setThreadAllocatedMemoryEnabled(true); bean.setThreadCpuTimeEnabled(true); + long id = Thread.currentThread().threadId(), bytes = bean.getThreadAllocatedBytes(id); + long cpu = bean.getCurrentThreadCpuTime(), wall = System.nanoTime(); + loop(access, camera, points, 2000000); + long wallDelta = System.nanoTime() - wall, cpuDelta = bean.getCurrentThreadCpuTime() - cpu; + long byteDelta = bean.getThreadAllocatedBytes(id) - bytes; + if (enabled && (scratch(owner, "horizon$rayDirection") != directionObject + || scratch(owner, "horizon$inverseDirection") != inverseObject)) throw new AssertionError("Scratch object was replaced"); + System.out.println("HORIZON_CULLING_RAYS_RESULT {\"enabled\":" + enabled + ",\"public_boxes\":" + boxes + + ",\"provider_reads\":" + reads + ",\"edge_rays\":" + rays + ",\"visibility_digest\":\"" + + HexFormat.of().formatHex(visibility.digest()) + "\",\"query_digest\":\"" + + HexFormat.of().formatHex(queries.digest()) + "\",\"intersection_digest\":\"" + + HexFormat.of().formatHex(intersections.digest()) + "\",\"allocated_bytes\":" + byteDelta + + ",\"cpu_ns\":" + cpuDelta + ",\"wall_ns\":" + wallDelta + ",\"measured_checks\":2000000" + + ",\"checksum\":" + checksum + ",\"input_unchanged\":true,\"scratch_ownership_checked\":true}"); + } + private static void loop(CullingRayAccess access, Vec3d camera, Vec3d[] points, int count) { + var one = new Vec3d[1]; long sum = 0; + for (int index = 0; index < count; index++) { + one[0] = points[index & 63]; access.horizon$checks(true); + if (access.horizon$visible(camera, one, 1)) sum++; + } + checksum = sum; + } +} diff --git a/mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/fixture/CullingRayAccess.java b/mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/fixture/CullingRayAccess.java new file mode 100644 index 000000000..32fe48d74 --- /dev/null +++ b/mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/fixture/CullingRayAccess.java @@ -0,0 +1,16 @@ +package dev.horizonlab.dispatch.fixture; + +import com.logisticscraft.occlusionculling.OcclusionCullingInstance; +import com.logisticscraft.occlusionculling.util.Vec3d; +import org.spongepowered.asm.mixin.Mixin; +import org.spongepowered.asm.mixin.gen.Accessor; +import org.spongepowered.asm.mixin.gen.Invoker; + +@Mixin(value = OcclusionCullingInstance.class, remap = false) +public interface CullingRayAccess { + @Invoker("rayIntersection") boolean horizon$intersects(int[] block, Vec3d camera, Vec3d direction); + @Invoker("isVisible") boolean horizon$visible(Vec3d camera, Vec3d[] points, int count); + @Accessor("allowRayChecks") void horizon$checks(boolean value); + @Accessor("lastHitBlock") int[] horizon$lastBlock(); + @Accessor("cameraPos") int[] horizon$cameraBlock(); +} diff --git a/packs/START-HERE.txt b/packs/START-HERE.txt index eb4e1cd68..73fe1abce 100644 --- a/packs/START-HERE.txt +++ b/packs/START-HERE.txt @@ -66,6 +66,10 @@ PROFILES dynamic entity/block-entity whitelists. Registered callbacks stay upstream. Disable in config/horizon-culling-empty.properties (enabled=false), then restart. Compare against m2-balanced; no whole-game or Mac FPS gain is measured yet. +- culling-rays: same balanced settings, with two per-instance scratch vectors for + temporary visibility-ray calculations. Upstream arithmetic and decisions stay + in place. Disable in config/horizon-culling-rays.properties (enabled=false), + then restart. Compare against m2-balanced; game/Mac gains remain unmeasured. - foreground-first: combines adaptive terrain, precise pacing, wakeable queue waits, bounded rejected dispatch retries and (since 0.13) tick membership reuse. Uses OpenGL and a 120 FPS diff --git a/packs/mods.lock.json b/packs/mods.lock.json index 5b78d3184..4bb547e7b 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.14.0", + "pack_version": "0.15.0", "options_data_version": 5023, "projects": { "sodium": { diff --git a/tests/test_packs.py b/tests/test_packs.py index 9a441294d..31f947100 100644 --- a/tests/test_packs.py +++ b/tests/test_packs.py @@ -99,6 +99,18 @@ class PackTests(unittest.TestCase): "config/horizon-dispatch-retry.properties", "config/horizon-tick-dedup.properties"]: self.assertEqual(original[filename], candidate[filename]) + def test_ray_scratch_experiment_preserves_balanced_settings(self): + baseline = build_pack.overrides("m2-balanced", b"fixture") + candidate = build_pack.overrides("culling-rays", b"fixture") + for name in build_pack.PROFILES: + self.assertEqual(build_pack.overrides(name, b"fixture")["config/horizon-culling-rays.properties"], + b"enabled=true\n" if name == "culling-rays" else b"enabled=false\n") + 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", "config/horizon-tick-dedup.properties", + "config/horizon-culling-empty.properties", "config/horizon-terrain-read-wait.properties"]: + self.assertEqual(baseline[filename], candidate[filename]) + def test_terrain_read_shutdown_fix_only_requested_with_distant_terrain(self): for name, profile in build_pack.PROFILES.items(): files = build_pack.overrides(name, b"fixture") diff --git a/tools/Compare-Benchmarks.html b/tools/Compare-Benchmarks.html index 532973a93..41c103c08 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','tick_membership_dedup','empty_culling_whitelist','interruptible_terrain_read','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','empty_culling_whitelist','culling_ray_scratch','interruptible_terrain_read','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]]){ @@ -126,6 +126,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']); + if(r.kind==='frames')fields.push(['Culling ray scratch',r.culling_ray_scratch===true?'on':r.culling_ray_scratch===false?'off':'not captured']); if(r.kind==='frames')fields.push(['Empty culling whitelist',r.empty_culling_whitelist===true?'on':r.empty_culling_whitelist===false?'off':'not captured']); if(r.kind==='frames')fields.push(['Interruptible terrain read',r.interruptible_terrain_read===true?'on':r.interruptible_terrain_read===false?'off':'not captured']); for(const [label,value]of fields)target.append(text('dt',label),text('dd',value)); diff --git a/tools/build_mod.py b/tools/build_mod.py index d100325cd..e862a46a8 100644 --- a/tools/build_mod.py +++ b/tools/build_mod.py @@ -65,6 +65,9 @@ def build(): dh = lock["projects"]["distanthorizons"] jars.append(runtime.fetch(dh["url"], ROOT / ".local/pack-cache" / dh["filename"], dh["hashes"]["sha512"], "sha512")) + culling = lock["projects"]["entityculling"] + jars.append(runtime.fetch(culling["url"], ROOT / ".local/pack-cache" / culling["filename"], + culling["hashes"]["sha512"], "sha512")) api = lock["projects"]["fabric-api"] api_jar = runtime.fetch(api["url"], ROOT / ".local/pack-cache" / api["filename"], api["hashes"]["sha512"], "sha512") @@ -130,7 +133,7 @@ def build_culling_empty_fixture(): return build_integration_fixture("culling-empty", "dev.horizonlab.dispatch.CullingEmptyIntegration", ["entityculling"]) -def build_integration_fixture(name, entrypoint, extra_projects=()): +def build_integration_fixture(name, entrypoint, extra_projects=(), fixture_mixins=()): """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") @@ -144,16 +147,23 @@ def build_integration_fixture(name, entrypoint, extra_projects=()): if classes.exists(): shutil.rmtree(classes) classes.mkdir(parents=True) + fixture_sources = [SOURCE / "test/java" / (entrypoint.replace(".", "/") + ".java")] + fixture_sources.extend(SOURCE / "test/java/dev/horizonlab/dispatch/fixture" / (mixin + ".java") for mixin in fixture_mixins) subprocess.run(["javac", "--release", "25", "-proc:none", "-classpath", classpath, - "-d", str(classes), str(SOURCE / "test/java" / (entrypoint.replace(".", "/") + ".java"))], check=True) + "-d", str(classes), *map(str, fixture_sources)], check=True) output = BUILD / f"{name}-fixture.jar" + metadata = {"schemaVersion": 1, "id": "horizon_" + name.replace("-", "_") + "_fixture", + "version": "1.0.0", "environment": "client", "entrypoints": {"client": [entrypoint]}, + "depends": {"horizonlab": "*", "distanthorizons": "3.3.4"}} + if fixture_mixins: + metadata["mixins"] = [name + "-fixture.mixins.json"] with zipfile.ZipFile(output, "w", compression=zipfile.ZIP_DEFLATED) as archive: + if fixture_mixins: + archive.writestr(metadata["mixins"][0], json.dumps({"required": True, "package": "dev.horizonlab.dispatch.fixture", + "compatibilityLevel": "JAVA_25", "client": list(fixture_mixins), "injectors": {"defaultRequire": 1}})) 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_" + name.replace("-", "_") + "_fixture", - "version": "1.0.0", "environment": "client", - "entrypoints": {"client": [entrypoint]}, - "depends": {"horizonlab": "*", "distanthorizons": "3.3.4"}})) + archive.writestr("fabric.mod.json", json.dumps(metadata)) print(f"Private {name} integration fixture: {output}") return output diff --git a/tools/build_pack.py b/tools/build_pack.py index 341de862c..f3a56302e 100644 --- a/tools/build_pack.py +++ b/tools/build_pack.py @@ -26,6 +26,7 @@ PROFILES = { "dispatch-retry": {"title": "Rejected dispatch retry experiment", "mods": CORE + ["distanthorizons"], "render": 12, "lod": 128, "heap": 6144, "dispatch_retry": True}, "tick-dedup": {"title": "Terrain tick membership experiment", "mods": CORE + ["distanthorizons"], "render": 12, "lod": 128, "heap": 6144, "tick_dedup": True}, "culling-empty": {"title": "Empty culling whitelist experiment", "mods": CORE + ["distanthorizons"], "render": 12, "lod": 128, "heap": 6144, "culling_empty": True}, + "culling-rays": {"title": "Culling ray scratch experiment", "mods": CORE + ["distanthorizons"], "render": 12, "lod": 128, "heap": 6144, "culling_rays": 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}, @@ -81,7 +82,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", "tick_dedup", "culling_empty"]) + experiment = any(profile.get(key, False) for key in ["adaptive", "pacing", "queue_wait", "dispatch_retry", "tick_dedup", "culling_empty", "culling_rays"]) 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() @@ -95,6 +96,8 @@ def overrides(profile_name, mod_bytes): f"enabled={str(profile.get('tick_dedup', False)).lower()}\n").encode() files["config/horizon-culling-empty.properties"] = ( f"enabled={str(profile.get('culling_empty', False)).lower()}\n").encode() + files["config/horizon-culling-rays.properties"] = ( + f"enabled={str(profile.get('culling_rays', False)).lower()}\n").encode() files["config/horizon-terrain-read-wait.properties"] = ( f"enabled={str(bool(profile['lod'])).lower()}\n").encode() if profile["lod"]: diff --git a/tools/compare_benchmarks.py b/tools/compare_benchmarks.py index 586342d79..c9adebc9b 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", "tick_membership_dedup", "empty_culling_whitelist", "interruptible_terrain_read", "dh_thread_count", "dh_runtime_ratio"]: + "wakeable_idle_wait", "dispatch_retry_backoff", "tick_membership_dedup", "empty_culling_whitelist", "culling_ray_scratch", "interruptible_terrain_read", "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_culling_rays.py b/tools/test_culling_rays.py new file mode 100644 index 000000000..e049a9978 --- /dev/null +++ b/tools/test_culling_rays.py @@ -0,0 +1,92 @@ +#!/usr/bin/env python3 +"""Compare actual visibility geometry and per-instance numeric scratch ownership.""" + +import argparse +import hashlib +import json +import os +import platform +import shutil +import signal +import subprocess +import sys + +try: + from . import build_mod, build_pack +except ImportError: + import build_mod + import build_pack + + +def run_fixture(command, instance, environment): + # Keep all children of this private fixture in a controllable process group. + process = subprocess.Popen(command, cwd=build_pack.ROOT, env=environment, text=True, + stdout=subprocess.PIPE, stderr=subprocess.STDOUT, + start_new_session=platform.system() != "Windows") + def stop_tree(force=False): + if platform.system() == "Windows": + subprocess.run(["taskkill", "/PID", str(process.pid), "/T", "/F"], capture_output=True, check=False) + else: + try: os.killpg(process.pid, signal.SIGKILL if force else signal.SIGTERM) + except ProcessLookupError: pass + try: + output, _ = process.communicate(timeout=240) + except subprocess.TimeoutExpired: + stop_tree() + try: output, _ = process.communicate(timeout=10) + except subprocess.TimeoutExpired: + stop_tree(True); output, _ = process.communicate(timeout=10) + (instance / "fixture.log").write_text(output) + raise RuntimeError(f"Private fixture timed out; inspect {instance / 'fixture.log'}") from None + (instance / "fixture.log").write_text(output) + return subprocess.CompletedProcess(command, process.returncode, output) + + +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_integration_fixture("culling-rays", "dev.horizonlab.dispatch.CullingRayIntegration", ["entityculling"], ["CullingRayAccess"]) + mod = root / "dist" / f"horizon-lab-{build_pack.read_lock()['pack_version']}.jar" + original_sha256 = hashlib.sha256(mod.read_bytes()).hexdigest() + results = [] + for enabled in [False, True]: + instance = root / ".local/runtime" / ("culling-rays-fixture-patched" if enabled else "culling-rays-fixture-upstream") + build_pack.prepare_instance("m2-balanced", instance, mod) + if hashlib.sha256((instance / "mods" / mod.name).read_bytes()).hexdigest() != original_sha256: + raise AssertionError("Fixture runtime mod does not match the intended build") + shutil.copy2(fixture, instance / "mods/culling-rays-fixture.jar") + (instance / "config/horizon-culling-rays.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 = run_fixture(command, instance, environment) + marker = "HORIZON_CULLING_RAYS_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"Culling scratch fixture failed; inspect {instance / 'fixture.log'}") + report = reports[0] + if report["enabled"] != enabled or report["public_boxes"] != 12800 or report["edge_rays"] != 2197 or not report["input_unchanged"] or not report["scratch_ownership_checked"]: + raise AssertionError("Applied culling scratch fixture did not complete its geometry checks") + results.append(report) + print(json.dumps(report), flush=True) + for key in ["visibility_digest", "query_digest", "intersection_digest", "provider_reads", "checksum"]: + if results[0][key] != results[1][key]: + raise AssertionError(f"Scratch redirect changed upstream geometry: {key}") + output = root / "dist/culling-rays-integration.json" + output.write_text(json.dumps({"schema": 1, "platform": platform.platform(), "architecture": platform.machine(), + "minecraft": "26.3", "entity_culling": "1.11.2", "original_mod_sha256": original_sha256, "results": results, + "notes": ["Actual upstream culling methods inside Fabric; private fixture invokers do not enter production packs.", + "Two interleaved instances and several occluder patterns; matching boolean and query digests.", + "Signed zero, tiny/large values, infinities and NaN are exercised directly in ray intersection.", + "Unchanged input vectors, independent instance scratch and upstream arithmetic values are checked.", + "Allocation and CPU are single warmed caller-loop observations; JIT folding can vary.", + "Not a game FPS, visual-equivalence proof, whole-game RAM or Mac GPU benchmark."]}, indent=2) + "\n") + print(f"Applied culling scratch checks passed: {output}") + + +if __name__ == "__main__": + main()