From 25cfc7f5b3037fa976a56f606afd59edea1ed61e Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Sun, 4 Oct 2026 07:02:12 +0200 Subject: [PATCH 1/3] Measure applied quad reuse shallow retention with a private agent --- .github/workflows/ci.yml | 6 ++ .../shallow-size-observations.json | 69 ++++++++++++++ docs/quad-reuse.md | 33 +++++++ .../dispatch/QuadSizeIntegration.java | 31 +++++++ .../horizonlab/metrics/ObjectSizeAgent.java | 7 ++ tools/test_quad_sizes.py | 92 +++++++++++++++++++ 6 files changed, 238 insertions(+) create mode 100644 benchmarks/quad-reuse-2026-10-04/shallow-size-observations.json create mode 100644 mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/QuadSizeIntegration.java create mode 100644 mods/horizon-lab/src/test/java/dev/horizonlab/metrics/ObjectSizeAgent.java create mode 100644 tools/test_quad_sizes.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index dfb106f3c..f9d188eb1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -71,6 +71,8 @@ jobs: run: python -c "from tools.build_mod import build_integration_fixture; build_integration_fixture('terrain-position', 'dev.horizonlab.dispatch.PositionIntegration')" - name: Compile the private terrain quad reuse fixture run: python -c "from tools.build_mod import build_integration_fixture; build_integration_fixture('quad-reuse', 'dev.horizonlab.dispatch.QuadReuseIntegration')" + - name: Compile the private object-size agent and terrain quad fixture + run: python -c "from tools.test_quad_sizes import build_agent; from tools.build_mod import build_integration_fixture; build_agent(); build_integration_fixture('quad-size', 'dev.horizonlab.dispatch.QuadSizeIntegration')" - 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 @@ -94,6 +96,9 @@ jobs: - name: Verify actual terrain quad geometry and allocation if: runner.os == 'Linux' run: python tools/test_quad_reuse.py + - name: Measure actual builder and quad shallow sizes in both header modes + if: runner.os == 'Linux' + run: python tools/test_quad_sizes.py - name: Verify interrupted DH reads and preserved shared futures if: runner.os == 'Linux' run: python tools/test_terrain_read.py @@ -115,3 +120,4 @@ jobs: dist/culling-rays-integration.json dist/terrain-position-integration.json dist/quad-reuse-integration.json + dist/quad-size-integration.json diff --git a/benchmarks/quad-reuse-2026-10-04/shallow-size-observations.json b/benchmarks/quad-reuse-2026-10-04/shallow-size-observations.json new file mode 100644 index 000000000..67751d28b --- /dev/null +++ b/benchmarks/quad-reuse-2026-10-04/shallow-size-observations.json @@ -0,0 +1,69 @@ +{ + "schema": 1, + "measurement": "Instrumentation.getObjectSize inside four private applied Fabric clients", + "platform": "Linux-7.0.0-31-generic-x86_64-with-glibc2.43", + "architecture": "x86_64", + "java_vendor": "Ubuntu", + "java_runtime_version": "25.0.4.1+1-1-26.04.4-Ubuntu", + "original_mod_sha256": "2196637c5b2180a33fa5b926ab51069ab480618c1186b8a02872c7e758be0a70", + "production_source_commit": "24c65f512dece83b153b206e33cd4c4294b42de2", + "results": [ + { + "enabled": false, + "compact_headers": false, + "builder_shallow_bytes": 48, + "quad_shallow_bytes": 56, + "pending_scratch_shallow_bytes": 0, + "geometry_quads": 1 + }, + { + "enabled": true, + "compact_headers": false, + "builder_shallow_bytes": 48, + "quad_shallow_bytes": 56, + "pending_scratch_shallow_bytes": 56, + "geometry_quads": 1 + }, + { + "enabled": false, + "compact_headers": true, + "builder_shallow_bytes": 40, + "quad_shallow_bytes": 48, + "pending_scratch_shallow_bytes": 0, + "geometry_quads": 1 + }, + { + "enabled": true, + "compact_headers": true, + "builder_shallow_bytes": 48, + "quad_shallow_bytes": 48, + "pending_scratch_shallow_bytes": 48, + "geometry_quads": 1 + } + ], + "differences": [ + { + "compact_headers": false, + "additional_builder_shallow_bytes": 0, + "additional_builder_and_scratch_bytes": 56 + }, + { + "compact_headers": true, + "additional_builder_shallow_bytes": 8, + "additional_builder_and_scratch_bytes": 56 + } + ], + "provenance": { + "protocol": "Initial private size agent and corrected system-loader reflection probe; metadata was later expanded in the reusable source.", + "agent_source_sha256": "4783850bf80e9eb0379570bb7794a610406b48bddd7fe36ff499222d01e789b1", + "fixture_source_sha256": "842514f97116a1e9cf5eb9a4b951657c90f7639effdfd526357831e2424282bf" + }, + "notes": [ + "Shallow object sizes only, not a heap walk or whole-game memory measurement.", + "Four north-facing adjacent quads produce one retained geometry quad in every process.", + "Header modes use separate upstream/patched JVMs.", + "Layouts can differ with JVM, architecture, compressed references and object alignment.", + "The hook remains optional; these sizes do not establish an FPS or RAM improvement.", + "No test agent binaries, game binaries, private worlds, full logs or JFR recordings are published." + ] +} diff --git a/docs/quad-reuse.md b/docs/quad-reuse.md index 896728e51..87d2fde0e 100644 --- a/docs/quad-reuse.md +++ b/docs/quad-reuse.md @@ -66,3 +66,36 @@ and exited with code zero; the control saved, closed its terrain databases and exited with code zero. Actual JSON/CSV comparison and mobile layout checks pass. The hook remains an optional experiment, disabled in combined profiles. + +The [initial shallow-size observations](../benchmarks/quad-reuse-2026-10-04/shallow-size-observations.json) +measure the actual hooked classes with `Instrumentation.getObjectSize` inside +four separate Fabric demo clients on local Linux x64 Java 25. They use four +adjacent north-facing quads, which premerge to one geometry quad in every mode. + +| Compact headers | Hook | Builder bytes | Quad bytes | Pending scratch bytes | +| --- | --- | ---: | ---: | ---: | +| Off | Off | 48 | 56 | 0 | +| Off | On | 48 | 56 | 56 | +| On | Off | 40 | 48 | 0 | +| On | On | 48 | 48 | 48 | + +Without compact headers, the extra reference fits the measured builder's existing +alignment padding. With compact headers, the builder itself grows by eight bytes. +In this workload both modes add 56 shallow bytes per builder including the pending +scratch. This excludes existing pools, referenced lists and every other game +object. JVM alignment and compressed-reference settings or other architectures +can change layouts. It is not a deep heap, residency, RSS, unified RAM or Mac +measurement, and does not demonstrate a net game memory benefit. + +The reusable probe keeps both test binaries outside playable packs and records +JVM runtime, alignment and compressed-reference settings. With Java 25 and the +usual build prerequisites, reproduce it using: + +```sh +python3 tools/build_mod.py +python3 tools/test_quad_sizes.py +``` + +Linux uses Xvfb by default; `--native-display` uses an existing screen. The output +is gitignored `dist/quad-size-integration.json`; game logs and the test agent/fixture +remain in `.local/`. No account or world is needed for this demo-mode probe. diff --git a/mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/QuadSizeIntegration.java b/mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/QuadSizeIntegration.java new file mode 100644 index 000000000..66aafcf75 --- /dev/null +++ b/mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/QuadSizeIntegration.java @@ -0,0 +1,31 @@ +package dev.horizonlab.dispatch; +import com.seibel.distanthorizons.core.dataObjects.render.bufferBuilding.LodQuadBuilder; +import com.seibel.distanthorizons.core.dataObjects.render.bufferBuilding.BufferQuad; +import com.seibel.distanthorizons.core.enums.EDhDirection; +import java.lang.management.ManagementFactory; +import com.sun.management.HotSpotDiagnosticMXBean; +import net.fabricmc.api.ClientModInitializer; +import net.fabricmc.fabric.api.client.event.lifecycle.v1.ClientLifecycleEvents; +public final class QuadSizeIntegration implements ClientModInitializer { + static long size(Object value)throws Exception { return ((Long)ClassLoader.getSystemClassLoader().loadClass("dev.horizonlab.metrics.ObjectSizeAgent").getMethod("size",Object.class).invoke(null,value)).longValue(); } + public void onInitializeClient() { ClientLifecycleEvents.CLIENT_STARTED.register(client -> { + try { + var b=LodQuadBuilder.getBuilder(false,null); + for(int x=0;x<4;x++) b.addQuadAdj(EDhDirection.NORTH,(short)x,(short)0,(short)0,(short)1,(short)1,0xff113355,(short)3,(byte)2,(byte)15,(byte)4); + long scratch=0;boolean hook=false; + for(var f:LodQuadBuilder.class.getDeclaredFields())if(f.getName().contains("horizon$discardedQuad")) { hook=true;f.setAccessible(true);Object v=f.get(b);if(v==null)throw new AssertionError("Missing merged scratch");scratch=size(v); } + boolean headers=Boolean.parseBoolean(ManagementFactory.getPlatformMXBean(HotSpotDiagnosticMXBean.class).getVMOption("UseCompactObjectHeaders").getValue()); + var vm=ManagementFactory.getPlatformMXBean(HotSpotDiagnosticMXBean.class); + var result=new java.util.LinkedHashMap(); + result.put("enabled",hook);result.put("compact_headers",headers); + result.put("builder_shallow_bytes",size(b));result.put("quad_shallow_bytes",size(new BufferQuad())); + result.put("pending_scratch_shallow_bytes",scratch);result.put("geometry_quads",b.getCurrentOpaqueQuadsCount()); + result.put("java_vendor",System.getProperty("java.vendor"));result.put("java_runtime_version",System.getProperty("java.runtime.version")); + result.put("object_alignment_bytes",Integer.parseInt(vm.getVMOption("ObjectAlignmentInBytes").getValue())); + result.put("compressed_oops",Boolean.parseBoolean(vm.getVMOption("UseCompressedOops").getValue())); + result.put("compressed_class_pointers",Boolean.parseBoolean(vm.getVMOption("UseCompressedClassPointers").getValue())); + System.out.println("HORIZON_SIZE_RESULT "+new com.google.gson.Gson().toJson(result)); + b.close();System.exit(0); + } catch(Exception e) { throw new AssertionError("Private size probe failed",e); } + }); } +} diff --git a/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/ObjectSizeAgent.java b/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/ObjectSizeAgent.java new file mode 100644 index 000000000..3bd56f0ff --- /dev/null +++ b/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/ObjectSizeAgent.java @@ -0,0 +1,7 @@ +package dev.horizonlab.metrics; +import java.lang.instrument.Instrumentation; +public final class ObjectSizeAgent { + private static Instrumentation instrumentation; + public static void premain(String args, Instrumentation value) { instrumentation=value; } + public static long size(Object value) { return instrumentation.getObjectSize(value); } +} diff --git a/tools/test_quad_sizes.py b/tools/test_quad_sizes.py new file mode 100644 index 000000000..507a42abf --- /dev/null +++ b/tools/test_quad_sizes.py @@ -0,0 +1,92 @@ +#!/usr/bin/env python3 +"""Measure shallow quad-reuse retention in private Fabric clients, not whole-game RAM.""" + +import argparse +import hashlib +import json +import os +import platform +import shutil +import subprocess +import sys +import zipfile + +try: + from . import build_mod, build_pack + from .test_culling_rays import run_fixture +except ImportError: + import build_mod + import build_pack + from test_culling_rays import run_fixture + + +def build_agent(): + output = build_mod.BUILD / "size-agent" + classes = output / "classes" + classes.mkdir(parents=True, exist_ok=True) + source = build_mod.SOURCE / "test/java/dev/horizonlab/metrics/ObjectSizeAgent.java" + subprocess.run(["javac", "--release", "25", "-d", str(classes), str(source)], check=True) + agent = output / "size-agent.jar" + with zipfile.ZipFile(agent, "w", compression=zipfile.ZIP_DEFLATED) as archive: + archive.writestr("META-INF/MANIFEST.MF", "Manifest-Version: 1.0\n" + "Premain-Class: dev.horizonlab.metrics.ObjectSizeAgent\n\n") + for path in sorted(classes.rglob("*.class")): + archive.write(path, path.relative_to(classes).as_posix()) + return agent + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--native-display", action="store_true") + args = parser.parse_args() + root = build_pack.ROOT + agent = build_agent() + fixture = build_mod.build_integration_fixture("quad-size", "dev.horizonlab.dispatch.QuadSizeIntegration") + mod = root / "dist" / f"horizon-lab-{build_pack.read_lock()['pack_version']}.jar" + mod_hash = hashlib.sha256(mod.read_bytes()).hexdigest() + results = [] + for headers in [False, True]: + for enabled in [False, True]: + instance = root / ".local/runtime" / f"quad-size-{headers}-{enabled}" + build_pack.prepare_instance("m2-balanced", instance, mod) + assert hashlib.sha256((instance / "mods" / mod.name).read_bytes()).hexdigest() == mod_hash + shutil.copy2(fixture, instance / "mods/quad-size-fixture.jar") + (instance / "config/horizon-quad-reuse.properties").write_text(f"enabled={str(enabled).lower()}\n") + environment = os.environ.copy() + header_option = "-XX:" + ("+" if headers else "-") + "UseCompactObjectHeaders" + environment["_JAVA_OPTIONS"] = f"-javaagent:{agent} {header_option} -Dhorizon.fixture.exit=true" + command = [sys.executable, str(root / "tools/runtime.py"), "demo", "--instance", str(instance), "--heap", "3G"] + if platform.system() == "Linux" and not args.native_display: + command = ["xvfb-run", "-a", *command] + run = run_fixture(command, instance, environment) + marker = "HORIZON_SIZE_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("Private quad-size fixture failed; diagnostics remain in its fixture.log") + report = reports[0] + if report["enabled"] != enabled or report["compact_headers"] != headers or report["geometry_quads"] != 1: + raise AssertionError("Size probe did not measure the requested hook/header combination") + if bool(report["pending_scratch_shallow_bytes"]) != enabled: + raise AssertionError("Size probe retained an unexpected scratch object") + results.append(report) + print(json.dumps(report), flush=True) + differences = [] + for control, candidate in zip(results[::2], results[1::2]): + differences.append({"compact_headers": candidate["compact_headers"], + "additional_builder_shallow_bytes": candidate["builder_shallow_bytes"] - control["builder_shallow_bytes"], + "additional_builder_and_scratch_bytes": candidate["builder_shallow_bytes"] - control["builder_shallow_bytes"] + candidate["pending_scratch_shallow_bytes"]}) + output = root / "dist/quad-size-integration.json" + output.write_text(json.dumps({"schema": 1, "platform": platform.platform(), "architecture": platform.machine(), + "minecraft": "26.3", "distant_horizons": "3.3.4", "original_mod_sha256": mod_hash, + "results": results, "differences": differences, + "notes": ["Instrumentation.getObjectSize measures shallow object sizes inside real applied Fabric clients.", + "Four adjacent north-facing quads premerge to one retained geometry quad in each combination.", + "Builder plus pending scratch difference excludes referenced lists, existing pools and every other game object.", + "Object alignment/header/compressed-reference settings can differ on other JVMs or architectures.", + "Not deep heap, GC residency, whole-game RSS/unified RAM, FPS or Apple Silicon performance.", + "The agent and fixture are private test binaries excluded from playable packs."]}, indent=2) + "\n") + print(f"Quad object-size observations: {output}") + + +if __name__ == "__main__": + main() From 1243e148d455cd83f18b66f70bcfe2b8a4b746c9 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Sun, 4 Oct 2026 07:08:19 +0200 Subject: [PATCH 2/3] Quote instrumentation agent paths with spaces --- tools/test_quad_sizes.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tools/test_quad_sizes.py b/tools/test_quad_sizes.py index 507a42abf..485f5af6f 100644 --- a/tools/test_quad_sizes.py +++ b/tools/test_quad_sizes.py @@ -54,7 +54,9 @@ def main(): (instance / "config/horizon-quad-reuse.properties").write_text(f"enabled={str(enabled).lower()}\n") environment = os.environ.copy() header_option = "-XX:" + ("+" if headers else "-") + "UseCompactObjectHeaders" - environment["_JAVA_OPTIONS"] = f"-javaagent:{agent} {header_option} -Dhorizon.fixture.exit=true" + if '"' in str(agent) or "\n" in str(agent): + raise ValueError("Instrumentation agent path contains an unsupported quote or newline") + environment["_JAVA_OPTIONS"] = f'-javaagent:"{agent}" {header_option} -Dhorizon.fixture.exit=true' command = [sys.executable, str(root / "tools/runtime.py"), "demo", "--instance", str(instance), "--heap", "3G"] if platform.system() == "Linux" and not args.native_display: command = ["xvfb-run", "-a", *command] From 8052fb0fbb95aa96e9dca19b4ba17978e21ca2cf Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Sun, 4 Oct 2026 07:11:40 +0200 Subject: [PATCH 3/3] Record reproducible local quad size results and JVM layout --- .../local-shallow-size-applied.json | 87 +++++++++++++++++++ docs/quad-reuse.md | 5 ++ 2 files changed, 92 insertions(+) create mode 100644 benchmarks/quad-reuse-2026-10-04/local-shallow-size-applied.json diff --git a/benchmarks/quad-reuse-2026-10-04/local-shallow-size-applied.json b/benchmarks/quad-reuse-2026-10-04/local-shallow-size-applied.json new file mode 100644 index 000000000..bcf0cc93c --- /dev/null +++ b/benchmarks/quad-reuse-2026-10-04/local-shallow-size-applied.json @@ -0,0 +1,87 @@ +{ + "schema": 1, + "platform": "Linux-7.0.0-31-generic-x86_64-with-glibc2.43", + "architecture": "x86_64", + "minecraft": "26.3", + "distant_horizons": "3.3.4", + "original_mod_sha256": "2196637c5b2180a33fa5b926ab51069ab480618c1186b8a02872c7e758be0a70", + "results": [ + { + "enabled": false, + "compact_headers": false, + "builder_shallow_bytes": 48, + "quad_shallow_bytes": 56, + "pending_scratch_shallow_bytes": 0, + "geometry_quads": 1, + "java_vendor": "Ubuntu", + "java_runtime_version": "25.0.4.1+1-1-26.04.4-Ubuntu", + "object_alignment_bytes": 8, + "compressed_oops": true, + "compressed_class_pointers": true + }, + { + "enabled": true, + "compact_headers": false, + "builder_shallow_bytes": 48, + "quad_shallow_bytes": 56, + "pending_scratch_shallow_bytes": 56, + "geometry_quads": 1, + "java_vendor": "Ubuntu", + "java_runtime_version": "25.0.4.1+1-1-26.04.4-Ubuntu", + "object_alignment_bytes": 8, + "compressed_oops": true, + "compressed_class_pointers": true + }, + { + "enabled": false, + "compact_headers": true, + "builder_shallow_bytes": 40, + "quad_shallow_bytes": 48, + "pending_scratch_shallow_bytes": 0, + "geometry_quads": 1, + "java_vendor": "Ubuntu", + "java_runtime_version": "25.0.4.1+1-1-26.04.4-Ubuntu", + "object_alignment_bytes": 8, + "compressed_oops": true, + "compressed_class_pointers": true + }, + { + "enabled": true, + "compact_headers": true, + "builder_shallow_bytes": 48, + "quad_shallow_bytes": 48, + "pending_scratch_shallow_bytes": 48, + "geometry_quads": 1, + "java_vendor": "Ubuntu", + "java_runtime_version": "25.0.4.1+1-1-26.04.4-Ubuntu", + "object_alignment_bytes": 8, + "compressed_oops": true, + "compressed_class_pointers": true + } + ], + "differences": [ + { + "compact_headers": false, + "additional_builder_shallow_bytes": 0, + "additional_builder_and_scratch_bytes": 56 + }, + { + "compact_headers": true, + "additional_builder_shallow_bytes": 8, + "additional_builder_and_scratch_bytes": 56 + } + ], + "notes": [ + "Instrumentation.getObjectSize measures shallow object sizes inside real applied Fabric clients.", + "Four adjacent north-facing quads premerge to one retained geometry quad in each combination.", + "Builder plus pending scratch difference excludes referenced lists, existing pools and every other game object.", + "Object alignment/header/compressed-reference settings can differ on other JVMs or architectures.", + "Not deep heap, GC residency, whole-game RSS/unified RAM, FPS or Apple Silicon performance.", + "The agent and fixture are private test binaries excluded from playable packs." + ], + "provenance": { + "source_commit": "1243e148d455cd83f18b66f70bcfe2b8a4b746c9", + "four_processes_exited_successfully": true, + "agent_path_with_spaces_verified_separately": true + } +} diff --git a/docs/quad-reuse.md b/docs/quad-reuse.md index 87d2fde0e..f26938a59 100644 --- a/docs/quad-reuse.md +++ b/docs/quad-reuse.md @@ -99,3 +99,8 @@ python3 tools/test_quad_sizes.py Linux uses Xvfb by default; `--native-display` uses an existing screen. The output is gitignored `dist/quad-size-integration.json`; game logs and the test agent/fixture remain in `.local/`. No account or world is needed for this demo-mode probe. + +The [reusable local applied probe](../benchmarks/quad-reuse-2026-10-04/local-shallow-size-applied.json) +reproduces the initial sizes and records eight-byte object alignment and compressed +references. All four processes exit successfully. A separate Java source-launcher +check verifies agent loading from a quoted path containing spaces.