Merge remote-tracking branch 'origin/main' into core-performance-profile

This commit is contained in:
Ludovic Marie
2026-10-04 07:20:12 +02:00
7 changed files with 332 additions and 0 deletions
+6
View File
@@ -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
@@ -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
}
}
@@ -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."
]
}
+38
View File
@@ -66,3 +66,41 @@ 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.
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.
@@ -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<String,Object>();
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); }
}); }
}
@@ -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); }
}
+94
View File
@@ -0,0 +1,94 @@
#!/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"
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]
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()