From 357cc903266b26372d13d938b316e3e03db08800 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Sun, 4 Oct 2026 14:09:19 +0200 Subject: [PATCH 1/2] Capture shared client graphics in integrated-server reports --- .github/workflows/ci.yml | 6 ++ README.md | 4 +- docs/mac-first-test.md | 10 +-- docs/server-graphics-context.md | 32 +++++++++ .../main/java/dev/horizonlab/HorizonLab.java | 9 ++- .../dev/horizonlab/client/HorizonClient.java | 2 +- .../dev/horizonlab/metrics/ServerContext.java | 27 ++++++++ .../src/main/resources/fabric.mod.json | 2 +- .../dev/horizonlab/metrics/MetricsTest.java | 10 +++ .../metrics/ServerGraphicsIntegration.java | 69 +++++++++++++++++++ packs/mods.lock.json | 2 +- tests/test_packs.py | 20 ++++++ tools/Compare-Benchmarks.html | 14 +++- tools/build_mod.py | 2 +- tools/compare_benchmarks.py | 18 ++++- tools/test_server_graphics.py | 69 +++++++++++++++++++ 16 files changed, 283 insertions(+), 13 deletions(-) create mode 100644 docs/server-graphics-context.md create mode 100644 mods/horizon-lab/src/main/java/dev/horizonlab/metrics/ServerContext.java create mode 100644 mods/horizon-lab/src/test/java/dev/horizonlab/metrics/ServerGraphicsIntegration.java create mode 100644 tools/test_server_graphics.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 23da7622d..7df85d008 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -68,6 +68,8 @@ jobs: cp dist/client-graphics-smoke.json dist/client-graphics-macos-world.json - name: Compile the private dispatch fixture run: python -c "from tools.build_mod import build_dispatch_fixture; build_dispatch_fixture()" + - name: Compile the private integrated-server graphics fixture + run: python -c "from tools.build_mod import build_integration_fixture; build_integration_fixture('server-graphics', 'dev.horizonlab.metrics.ServerGraphicsIntegration', fixture_dependencies={})" - name: Compile the private tick-manager state fixture run: python -c "from tools.build_mod import build_integration_fixture; build_integration_fixture('tick-state', 'dev.horizonlab.metrics.TickStateIntegration')" - name: Compile the private terrain tick membership fixture @@ -87,6 +89,9 @@ jobs: - 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: Verify integrated-server graphics report against the actual device + if: runner.os == 'Linux' || runner.os == 'macOS' + run: python tools/test_server_graphics.py ${{ runner.os == 'macOS' && '--native-display' || '' }} - name: Exercise the applied dispatcher hooks and upstream rejection path if: runner.os == 'Linux' run: python tools/test_dispatch.py @@ -130,6 +135,7 @@ jobs: dist/terrain-position-integration.json dist/quad-reuse-integration.json dist/quad-size-integration.json + dist/server-graphics-smoke.json dist/client-graphics-smoke.json dist/client-graphics-macos-title.json dist/client-graphics-macos-world.json diff --git a/README.md b/README.md index 5d7bea3dc..809990868 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.20.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.21.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. @@ -216,3 +216,5 @@ python3 tools/check_public_tree.py --history CI checks offline tools/Rust and compiles the original mod/builds packs on Linux, Windows and Apple Silicon macOS. Game dependencies download to ephemeral `.local/`; CI uploads only our original JAR and packs. Compilation is not Mac GPU gameplay testing. Publication checks allow Java only under our original `dev/horizonlab` namespace; review diffs as well. [MIT](LICENSE) covers only our original tracked work. Dependencies retain their licenses. Mojang [removed obfuscation](https://www.minecraft.net/en-us/article/removing-obfuscation-in-java-edition) without changing [Minecraft's EULA](https://www.minecraft.net/en-us/eula). Decompiled game source remains local; published code implements independent tooling and instrumentation. + +Integrated-server reports record the shared graphics backend at recording start; see [the context and comparison limits](docs/server-graphics-context.md). diff --git a/docs/mac-first-test.md b/docs/mac-first-test.md index 17a3076ef..e361ac809 100644 --- a/docs/mac-first-test.md +++ b/docs/mac-first-test.md @@ -1,16 +1,16 @@ # First test on the M2 Pro Mac -For the 16 GB M2 Pro, start with the published 0.20.0 packs. Core and balanced +For the 16 GB M2 Pro, start with the published 0.21.0 packs. Core and balanced pass title/demo-world rendering and save/exit probes on the hosted macOS ARM64 software renderer. Gameplay and FPS on this physical Mac remain unmeasured. The Linux software-rendering observations do not predict an M2 speedup. ## Import after installing Prism -1. Download [horizon-mac-starter-0.20.0.zip](https://github.com/ludovic111/minecraft-optimization-lab/releases/download/v0.20.0/horizon-mac-starter-0.20.0.zip) +1. Download [horizon-mac-starter-0.21.0.zip](https://github.com/ludovic111/minecraft-optimization-lab/releases/download/v0.21.0/horizon-mac-starter-0.21.0.zip) and extract it in Finder. 2. In Prism, choose **Add Instance > Import**, then select - `horizon-m2-balanced-0.20.0.mrpack` from the extracted folder. The individual + `horizon-m2-balanced-0.21.0.mrpack` from the extracted folder. The individual `.mrpack` is the import file; the starter ZIP contains several different packs. [Prism's import guide](https://prismlauncher.org/wiki/help-pages/zip-import/) describes the supported archive formats. @@ -38,8 +38,8 @@ experiments to try after this first launch succeeds. ## Measure performance at the same view distance -Import `horizon-baseline-0.20.0.mrpack` and -`horizon-core-performance-0.20.0.mrpack` from the same starter folder. Both use +Import `horizon-baseline-0.21.0.mrpack` and +`horizon-core-performance-0.21.0.mrpack` from the same starter folder. Both use 12 full-detail chunks, 12 simulation chunks and no distant LOD or shaders. Core adds the pinned performance mods; all original experimental controllers are off. Comparing these two isolates the core stack more closely than comparing baseline diff --git a/docs/server-graphics-context.md b/docs/server-graphics-context.md new file mode 100644 index 000000000..0b30e131b --- /dev/null +++ b/docs/server-graphics-context.md @@ -0,0 +1,32 @@ +# Integrated-server graphics context + +Client rendering competes with the integrated server for CPU time. Version 0.21 +copies GPU, backend and driver into the tick report when F8 or `/horizon bench` +starts a single-player recording. The values come from the client/render thread +and are copied into immutable metadata; server ticks never access GPU APIs. + +Reports identify `server_runtime_kind` as integrated, dedicated or unknown. +`client_graphics_capture_status` is `captured_at_recording_start` only when all +three graphics fields are supplied for an integrated server. The server-only +command does not inspect client graphics. Old callers retain their compatible +four-argument recording entrypoint and report unknown runtime context. + +The offline viewer and CLI flag differing runtime kinds, graphics backends and +drivers. Legacy reports remain readable, with unknown-context warnings. A +matched start snapshot does not establish unchanged graphics throughout the +recording, equivalent client quality, world work or scheduling. Rendering changes +still require paired frame reports and an explicitly controlled experiment. +This metadata change makes no FPS, TPS or RAM improvement claim. + +```sh +python3 tools/build_mod.py +python3 tools/test_server_graphics.py --native-display --backend opengl +# Separate fresh private instance; Linux software renderer research only: +python3 tools/test_server_graphics.py --native-display --backend vulkan +``` + +The private fixture starts a normal 10-second frame/tick recording through the +client recorder, checks both reports against the actual device, saves the demo +world and exits. It does not change simulation rate or gameplay rules. Windows +compiles the fixture; Linux and hosted macOS run the OpenGL check. Full logs, +worlds and fixture JARs remain private and outside playable downloads. diff --git a/mods/horizon-lab/src/main/java/dev/horizonlab/HorizonLab.java b/mods/horizon-lab/src/main/java/dev/horizonlab/HorizonLab.java index 010610e09..e2fe279e4 100644 --- a/mods/horizon-lab/src/main/java/dev/horizonlab/HorizonLab.java +++ b/mods/horizon-lab/src/main/java/dev/horizonlab/HorizonLab.java @@ -31,7 +31,8 @@ public final class HorizonLab implements ModInitializer { .then(Commands.argument("seconds", IntegerArgumentType.integer(10, 600)) .executes(command -> { boolean started = startTicks(StringArgumentType.getString(command, "label"), - IntegerArgumentType.getInteger(command, "seconds"), Path.of("horizon-benchmarks"), "server"); + IntegerArgumentType.getInteger(command, "seconds"), Path.of("horizon-benchmarks"), "server", + command.getSource().getServer().isDedicatedServer() ? "dedicated" : "integrated", Map.of()); command.getSource().sendSuccess(() -> Component.literal(started ? "Horizon: recording tick times; run the intended workload now." : "Horizon: a tick recording is already active."), false); @@ -42,10 +43,16 @@ public final class HorizonLab implements ModInitializer { } public static synchronized boolean startTicks(String label, int seconds, Path output, String profile) { + return startTicks(label, seconds, output, profile, "unknown", Map.of()); + } + + public static synchronized boolean startTicks(String label, int seconds, Path output, String profile, + String runtimeKind, Map clientContext) { if (ticks != null) return false; Map context = dev.horizonlab.metrics.SoftwareContext.capture(); context.put("profile", profile); context.put("minecraft", "26.3"); + context.putAll(dev.horizonlab.metrics.ServerContext.capture(runtimeKind, clientContext)); ticks = new Recording(label, "ticks", output, seconds, context); return true; } 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 0b0c55436..3c60211f0 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 @@ -111,7 +111,7 @@ public final class HorizonClient implements ClientModInitializer { context.putAll(dev.horizonlab.metrics.SoftwareContext.capture()); frames = new Recording(label, "frames", output, seconds, context); previousStart = 0; - if (client.getSingleplayerServer() != null) HorizonLab.startTicks(label, seconds, output, profile); + if (client.getSingleplayerServer() != null) HorizonLab.startTicks(label, seconds, output, profile, "integrated", context); message("Recording " + seconds + " seconds. Close chat, keep the game focused, and run your route."); return 1; } diff --git a/mods/horizon-lab/src/main/java/dev/horizonlab/metrics/ServerContext.java b/mods/horizon-lab/src/main/java/dev/horizonlab/metrics/ServerContext.java new file mode 100644 index 000000000..870f6f4aa --- /dev/null +++ b/mods/horizon-lab/src/main/java/dev/horizonlab/metrics/ServerContext.java @@ -0,0 +1,27 @@ +package dev.horizonlab.metrics; + +import java.util.LinkedHashMap; +import java.util.Map; + +/** Copies a recording-start snapshot; never accesses a graphics device on a server thread. */ +public final class ServerContext { + private ServerContext() {} + + public static Map capture(String runtimeKind, Map clientContext) { + Map result = new LinkedHashMap<>(); + String kind = switch (runtimeKind) { + case "integrated", "dedicated" -> runtimeKind; + default -> "unknown"; + }; + result.put("server_runtime_kind", kind); + boolean captured = kind.equals("integrated") && clientContext != null; + for (String key : new String[]{"gpu", "graphics_backend", "graphics_driver"}) { + Object value = clientContext == null ? null : clientContext.get(key); + if (!(value instanceof String text) || text.isBlank()) captured = false; + } + result.put("client_graphics_capture_status", captured ? "captured_at_recording_start" : "not_supplied"); + if (captured) for (String key : new String[]{"gpu", "graphics_backend", "graphics_driver"}) + result.put(key, clientContext.get(key)); + return Map.copyOf(result); + } +} diff --git a/mods/horizon-lab/src/main/resources/fabric.mod.json b/mods/horizon-lab/src/main/resources/fabric.mod.json index 08a680b30..6a5f561be 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.20.0", + "version": "0.21.0", "name": "Horizon Lab", "description": "Client frame pacing and server tick measurements for reproducible optimization experiments.", "authors": [ diff --git a/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/MetricsTest.java b/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/MetricsTest.java index 18d040507..c92508e34 100644 --- a/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/MetricsTest.java +++ b/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/MetricsTest.java @@ -5,6 +5,16 @@ import java.util.Map; public final class MetricsTest { public static void main(String[] args) { + var sourceContext = new java.util.LinkedHashMap(); + sourceContext.putAll(Map.of("gpu", "GPU", "graphics_backend", "OpenGL", "graphics_driver", "Driver", "private_path", "secret")); + var serverContext = ServerContext.capture("integrated", sourceContext); + sourceContext.put("graphics_backend", "Vulkan"); + check(serverContext.get("graphics_backend").equals("OpenGL"), "graphics snapshot does not track later mutations"); + check(!serverContext.containsKey("private_path"), "server context only copies graphics allowlist"); + check(serverContext.get("client_graphics_capture_status").equals("captured_at_recording_start"), "integrated graphics captured"); + check(!ServerContext.capture("dedicated", sourceContext).containsKey("gpu"), "dedicated server does not claim client graphics"); + check(ServerContext.capture("integrated", Map.of("gpu", "GPU")).get("client_graphics_capture_status").equals("not_supplied"), "partial graphics snapshot is unavailable"); + check(ServerContext.capture("unrecognized", Map.of()).get("server_runtime_kind").equals("unknown"), "legacy server kind unknown"); SampleStats empty = SampleStats.of(new long[0], 0); check(empty.count() == 0 && empty.meanRate() == 0, "empty recording"); SampleStats fixed = SampleStats.of(new long[]{10_000_000, 10_000_000, 10_000_000}, 3); diff --git a/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/ServerGraphicsIntegration.java b/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/ServerGraphicsIntegration.java new file mode 100644 index 000000000..29d0aa3ba --- /dev/null +++ b/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/ServerGraphicsIntegration.java @@ -0,0 +1,69 @@ +package dev.horizonlab.metrics; + +import com.google.gson.JsonParser; +import com.mojang.blaze3d.systems.RenderSystem; +import java.nio.file.Files; +import java.nio.file.Path; +import net.fabricmc.api.ClientModInitializer; +import net.fabricmc.fabric.api.client.event.lifecycle.v1.ClientTickEvents; +import net.minecraft.client.gui.screens.TitleScreen; +import net.minecraft.network.chat.contents.TranslatableContents; +import net.minecraft.server.MinecraftServer; +import net.minecraft.world.level.levelgen.WorldOptions; +import net.minecraft.world.level.levelgen.presets.WorldPresets; + +/** Private metadata fixture; ordinary disposable demo, no simulation changes. */ +public final class ServerGraphicsIntegration implements ClientModInitializer { + private boolean opening, finished; + private long ready, started; + + @Override public void onInitializeClient() { + ClientTickEvents.END_CLIENT_TICK.register(client -> { + if (finished || client.gui.overlay() != null) return; + if (!opening && client.gui.screen() instanceof TitleScreen screen) { + opening = true; + client.createWorldOpenFlows().createFreshLevel("Demo_World", MinecraftServer.DEMO_SETTINGS, + WorldOptions.DEMO_OPTIONS, WorldPresets::createNormalWorldDimensions, screen); + return; + } + if (client.gui.screen() != null && client.gui.screen().getTitle().getContents() instanceof TranslatableContents title + && title.getKey().equals("demo.help.title")) { client.gui.setScreen(null); return; } + if (client.level == null || client.player == null || client.gui.screen() != null || client.isPaused() + || !client.isWindowActive()) { ready = 0; return; } + long now = System.nanoTime(); + if (ready == 0) ready = now; + if (started == 0 && now - ready >= 2_000_000_000L) { + try { + var method = Class.forName("dev.horizonlab.client.HorizonClient").getDeclaredMethod("start", String.class, int.class); + method.setAccessible(true); + if (!method.invoke(null, "server-graphics-fixture", 10).equals(1)) throw new AssertionError("Recording failed to start"); + started = now; + } catch (ReflectiveOperationException error) { throw new AssertionError("Private recorder start failed", error); } + } + if (started == 0 || now - started < 14_000_000_000L) return; + Path output = client.gameDirectory.toPath().resolve("horizon-benchmarks"); + try (var paths = Files.list(output)) { + var reports = paths.filter(p -> p.toString().endsWith(".json") && p.getFileName().toString().startsWith("server-graphics-fixture-")).toList(); + if (reports.size() != 2) throw new AssertionError("Expected completed frame and tick reports"); + var device = RenderSystem.getDevice().getDeviceInfo(); + var result = new com.google.gson.JsonObject(); + for (Path path : reports) { + var report = JsonParser.parseString(Files.readString(path)).getAsJsonObject(); + if (!report.get("gpu").getAsString().equals(device.name()) + || !report.get("graphics_backend").getAsString().equals(device.backendName()) + || !report.get("graphics_driver").getAsString().equals(device.driverInfo())) + throw new AssertionError("Report graphics differ from actual device"); + if (report.get("kind").getAsString().equals("ticks")) { + if (!report.get("server_runtime_kind").getAsString().equals("integrated") + || !report.get("client_graphics_capture_status").getAsString().equals("captured_at_recording_start")) + throw new AssertionError("Integrated graphics status missing"); + for (String key : new String[]{"server_runtime_kind", "client_graphics_capture_status", "gpu", "graphics_backend", "graphics_driver"}) result.add(key, report.get(key)); + } + } + finished = true; + System.out.println("HORIZON_SERVER_GRAPHICS_RESULT " + result); + client.stop(); + } catch (Exception error) { throw new AssertionError("Private server graphics fixture failed", error); } + }); + } +} diff --git a/packs/mods.lock.json b/packs/mods.lock.json index f795380af..4c9a303d6 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.20.0", + "pack_version": "0.21.0", "options_data_version": 5023, "projects": { "sodium": { diff --git a/tests/test_packs.py b/tests/test_packs.py index 99528723a..9b2e80b1e 100644 --- a/tests/test_packs.py +++ b/tests/test_packs.py @@ -256,6 +256,26 @@ class ComparisonTests(unittest.TestCase): "stats": {"count": 1000, "meanRate": 100, "lowOnePercentRate": 50, "meanMs": 10, "p95Ms": 15, "p99Ms": 20, "maxMs": 30}} + def test_integrated_tick_graphics_and_server_kind(self): + baseline = self.tick_report() + baseline.update(server_runtime_kind="integrated", client_graphics_capture_status="captured_at_recording_start", + gpu="GPU", graphics_backend="OpenGL", graphics_driver="Driver") + candidate = copy.deepcopy(baseline) + candidate["graphics_backend"] = "Vulkan" + result = compare_benchmarks.compare(baseline, candidate) + self.assertTrue(any("graphics_backend" in item for item in result["mismatches"])) + self.assertFalse(any("were not captured" in item for item in compare_benchmarks.server_context_warnings(baseline, candidate))) + candidate["server_runtime_kind"] = "dedicated" + self.assertTrue(any("server_runtime_kind" in item for item in compare_benchmarks.compare(baseline, candidate)["mismatches"])) + + def test_legacy_and_missing_integrated_graphics_are_unknown(self): + legacy = self.tick_report() + self.assertTrue(any("runtime kind was not captured" in item for item in compare_benchmarks.server_context_warnings(legacy, legacy))) + legacy.update(server_runtime_kind="integrated", client_graphics_capture_status="captured_at_recording_start", gpu="GPU", graphics_backend="OpenGL") + self.assertTrue(any("client graphics were not captured" in item for item in compare_benchmarks.server_context_warnings(legacy, legacy))) + dedicated = {"server_runtime_kind": "dedicated", "client_graphics_capture_status": "not_supplied"} + self.assertFalse(any("were not captured" in item for item in compare_benchmarks.server_context_warnings(dedicated, dedicated))) + def test_rate_improvement_and_setting_mismatch(self): baseline = self.report() candidate = copy.deepcopy(baseline) diff --git a/tools/Compare-Benchmarks.html b/tools/Compare-Benchmarks.html index b50ec649d..0faa4358b 100644 --- a/tools/Compare-Benchmarks.html +++ b/tools/Compare-Benchmarks.html @@ -30,7 +30,7 @@