From d175741de3fffa75e36cafa47d36544cba4c07bf Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Sun, 4 Oct 2026 10:34:50 +0200 Subject: [PATCH 1/5] Verify native macOS client startup and framebuffer readback --- .github/workflows/ci.yml | 4 + .../metrics/ClientGraphicsIntegration.java | 63 +++++++++++++++ tools/build_mod.py | 5 +- tools/test_client_graphics.py | 79 +++++++++++++++++++ 4 files changed, 149 insertions(+), 2 deletions(-) create mode 100644 mods/horizon-lab/src/test/java/dev/horizonlab/metrics/ClientGraphicsIntegration.java create mode 100644 tools/test_client_graphics.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 47eb0697b..587298bbe 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -59,6 +59,9 @@ jobs: run: python -c "from tools.build_mod import benchmark_headers; benchmark_headers()" - name: Test pack integrity and comparisons run: python -m unittest discover -s tests -v + - name: Start native macOS clients and verify framebuffer readback + if: runner.os == 'macOS' + run: python tools/test_client_graphics.py --native-display - name: Compile the private dispatch fixture run: python -c "from tools.build_mod import build_dispatch_fixture; build_dispatch_fixture()" - name: Compile the private tick-manager state fixture @@ -123,3 +126,4 @@ jobs: dist/terrain-position-integration.json dist/quad-reuse-integration.json dist/quad-size-integration.json + dist/client-graphics-smoke.json diff --git a/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/ClientGraphicsIntegration.java b/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/ClientGraphicsIntegration.java new file mode 100644 index 000000000..1e3e3a52f --- /dev/null +++ b/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/ClientGraphicsIntegration.java @@ -0,0 +1,63 @@ +package dev.horizonlab.metrics; + +import com.google.gson.JsonObject; +import com.mojang.blaze3d.systems.RenderSystem; +import java.nio.file.Files; +import java.security.MessageDigest; +import java.util.HashSet; +import java.util.HexFormat; +import net.fabricmc.api.ClientModInitializer; +import net.fabricmc.fabric.api.client.event.lifecycle.v1.ClientTickEvents; +import net.minecraft.client.Screenshot; +import net.minecraft.client.gui.screens.TitleScreen; + +/** Private startup/readback probe. Never packaged in a playable release. */ +public final class ClientGraphicsIntegration implements ClientModInitializer { + private long titleStarted; + private int titleTicks; + private boolean requested; + + @Override public void onInitializeClient() { + ClientTickEvents.END_CLIENT_TICK.register(client -> { + if (requested || !(client.gui.screen() instanceof TitleScreen)) return; + if (titleStarted == 0) titleStarted = System.nanoTime(); + titleTicks++; + if (titleTicks < 40 || System.nanoTime() - titleStarted < 2_000_000_000L) return; + requested = true; + Screenshot.takeScreenshot(client.gameRenderer.mainRenderTarget(), image -> { + try (image) { + int width = image.getWidth(), height = image.getHeight(); + if (width < 64 || height < 64) throw new AssertionError("Incomplete title framebuffer"); + var colors = new HashSet(); + int samples = 0; + for (int y = 0; y < height; y += Math.max(1, height / 64)) { + for (int x = 0; x < width; x += Math.max(1, width / 64)) { + colors.add(image.getPixel(x, y) & 0xFFFFFF); + samples++; + } + } + if (samples < 256 || colors.size() < 8) throw new AssertionError("Uniform title readback"); + var screenshot = client.gameDirectory.toPath().resolve("client-graphics-private.png"); + image.writeToFile(screenshot); + var device = RenderSystem.getDevice().getDeviceInfo(); + var result = new JsonObject(); + result.addProperty("title_screen_observed", true); + result.addProperty("title_client_ticks", titleTicks); + result.addProperty("framebuffer_width", width); + result.addProperty("framebuffer_height", height); + result.addProperty("sampled_pixels", samples); + result.addProperty("distinct_sampled_rgb", colors.size()); + result.addProperty("gpu", device.name()); + result.addProperty("graphics_backend", device.backendName()); + result.addProperty("graphics_driver", device.driverInfo()); + result.addProperty("private_png_sha256", HexFormat.of().formatHex( + MessageDigest.getInstance("SHA-256").digest(Files.readAllBytes(screenshot)))); + System.out.println("HORIZON_CLIENT_GRAPHICS_RESULT " + result); + client.execute(client::stop); + } catch (Exception error) { + throw new AssertionError("Private client graphics readback failed", error); + } + }); + }); + } +} diff --git a/tools/build_mod.py b/tools/build_mod.py index 3c1627fb7..0f368defe 100644 --- a/tools/build_mod.py +++ b/tools/build_mod.py @@ -136,7 +136,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=(), fixture_mixins=()): +def build_integration_fixture(name, entrypoint, extra_projects=(), fixture_mixins=(), fixture_dependencies=None): """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") @@ -157,7 +157,8 @@ def build_integration_fixture(name, entrypoint, extra_projects=(), fixture_mixin 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"}} + "depends": {"horizonlab": "*", **({"distanthorizons": "3.3.4"} + if fixture_dependencies is None else fixture_dependencies)}} if fixture_mixins: metadata["mixins"] = [name + "-fixture.mixins.json"] with zipfile.ZipFile(output, "w", compression=zipfile.ZIP_DEFLATED) as archive: diff --git a/tools/test_client_graphics.py b/tools/test_client_graphics.py new file mode 100644 index 000000000..74aaf946c --- /dev/null +++ b/tools/test_client_graphics.py @@ -0,0 +1,79 @@ +#!/usr/bin/env python3 +"""Start real clients and verify a nonuniform GPU framebuffer readback.""" + +import argparse +import hashlib +import json +import os +import platform +import shutil +import sys + +try: + from . import build_mod, build_pack + from .test_culling_rays import run_fixture + from .test_dispatch import failure_summary +except ImportError: + import build_mod + import build_pack + from test_culling_rays import run_fixture + from test_dispatch import failure_summary + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--native-display', action='store_true') + parser.add_argument('--profile', action='append', choices=sorted(build_pack.PROFILES)) + args = parser.parse_args() + root = build_pack.ROOT + fixture = build_mod.build_integration_fixture('client-graphics', + 'dev.horizonlab.metrics.ClientGraphicsIntegration', fixture_dependencies={}) + version = build_pack.read_lock()['pack_version'] + mod = root / 'dist' / f'horizon-lab-{version}.jar' + original_hash = hashlib.sha256(mod.read_bytes()).hexdigest() + results = [] + for profile in args.profile or ['core-performance', 'm2-balanced', 'vulkan']: + instance = root / '.local/runtime' / ('client-graphics-' + profile) + build_pack.prepare_instance(profile, instance, mod) + shutil.copy2(fixture, instance / 'mods/client-graphics-fixture.jar') + 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] + try: + run = run_fixture(command, instance, os.environ.copy()) + except RuntimeError: + print('HORIZON_FIXTURE_FAILURE ' + json.dumps({'fixture': 'client-graphics', + 'profile': profile, 'completed': False}), flush=True) + raise RuntimeError('Graphics probe did not finish; diagnostics remain private') from None + marker = 'HORIZON_CLIENT_GRAPHICS_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: + print('HORIZON_FIXTURE_FAILURE ' + json.dumps(failure_summary(run, len(reports))), flush=True) + raise RuntimeError('Graphics probe failed; diagnostics remain private') + report = reports[0] + if report['title_screen_observed'] is not True or report['title_client_ticks'] < 40: + raise AssertionError('Client never reached the title screen') + if report['sampled_pixels'] < 256 or report['distinct_sampled_rgb'] < 8: + raise AssertionError('GPU readback was uniform') + if hashlib.sha256((instance / 'mods' / mod.name).read_bytes()).hexdigest() != original_hash: + raise AssertionError('Runtime original mod differs from the intended build') + screenshot = instance / 'client-graphics-private.png' + if not screenshot.is_file() or hashlib.sha256(screenshot.read_bytes()).hexdigest() != report['private_png_sha256']: + raise AssertionError('Private screenshot evidence is missing or changed') + report.update(profile=profile, launcher_exit_code=run.returncode) + results.append(report) + print(json.dumps(report), flush=True) + output = root / 'dist/client-graphics-smoke.json' + output.write_text(json.dumps({'schema': 1, 'platform': platform.platform(), + 'architecture': platform.machine(), 'minecraft': '26.3', + 'original_mod_sha256': original_hash, 'results': results, + 'limits': ['Title-screen startup and nonuniform framebuffer readback only.', + 'No world gameplay, visual-correctness, FPS or M2 Pro performance claim.', + 'Vulkan preference can fall back; inspect the observed backend.', + 'PNG images, assets and full logs remain in the private runtime directory.']}, indent=2) + '\n') + print('Client graphics startup/readback checks passed.', flush=True) + + +if __name__ == '__main__': + main() From ad00f1c30c238f0fedc4d6dc3413d553235426bd Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Sun, 4 Oct 2026 10:53:51 +0200 Subject: [PATCH 2/5] Trace backend initialization categories in private graphics probes --- .../fixture/GraphicsBackendTraceMixin.java | 52 +++++++++++++++++++ tools/test_client_graphics.py | 11 ++-- 2 files changed, 60 insertions(+), 3 deletions(-) create mode 100644 mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/fixture/GraphicsBackendTraceMixin.java diff --git a/mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/fixture/GraphicsBackendTraceMixin.java b/mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/fixture/GraphicsBackendTraceMixin.java new file mode 100644 index 000000000..f0ff89272 --- /dev/null +++ b/mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/fixture/GraphicsBackendTraceMixin.java @@ -0,0 +1,52 @@ +package dev.horizonlab.dispatch.fixture; + +import com.google.gson.JsonObject; +import com.mojang.renderpearl.api.device.BackendCreationException; +import com.mojang.renderpearl.api.device.GpuBackend; +import com.mojang.renderpearl.api.device.GpuDebugOptions; +import com.mojang.renderpearl.api.device.GpuDevice; +import net.minecraft.client.Minecraft; +import org.spongepowered.asm.mixin.Mixin; +import org.spongepowered.asm.mixin.injection.At; +import org.spongepowered.asm.mixin.injection.Redirect; + +/** Private diagnostic wrapper. Calls the original operations and rethrows their errors. */ +@Mixin(Minecraft.class) +public abstract class GraphicsBackendTraceMixin { + private static void trace(GpuBackend backend, String operation, Throwable failure) { + var result = new JsonObject(); + String name = backend.getName(); + result.addProperty("backend", name.equals("OpenGL") || name.equals("Vulkan") ? name : "other"); + result.addProperty("operation", operation); + result.addProperty("result", failure == null ? "success" : "failure"); + if (failure != null) result.addProperty("exception_type", failure.getClass().getName()); + if (failure instanceof BackendCreationException backendFailure) + result.addProperty("reason", backendFailure.getReason().name()); + System.out.println("HORIZON_GRAPHICS_BACKEND_ATTEMPT " + result); + } + + @Redirect(method = "", at = @At(value = "INVOKE", + target = "Lcom/mojang/renderpearl/api/device/GpuBackend;loadLibrary()V"), require = 1, allow = 1) + private void horizon$traceLibrary(GpuBackend backend) throws BackendCreationException { + try { + backend.loadLibrary(); + trace(backend, "load_library", null); + } catch (BackendCreationException | RuntimeException | LinkageError | AssertionError failure) { + trace(backend, "load_library", failure); + throw failure; + } + } + + @Redirect(method = "", at = @At(value = "INVOKE", + target = "Lcom/mojang/renderpearl/api/device/GpuBackend;createDevice(Lcom/mojang/renderpearl/api/device/GpuDebugOptions;)Lcom/mojang/renderpearl/api/device/GpuDevice;"), require = 1, allow = 1) + private GpuDevice horizon$traceDevice(GpuBackend backend, GpuDebugOptions options) throws BackendCreationException { + try { + GpuDevice device = backend.createDevice(options); + trace(backend, "create_device", null); + return device; + } catch (BackendCreationException | RuntimeException | LinkageError | AssertionError failure) { + trace(backend, "create_device", failure); + throw failure; + } + } +} diff --git a/tools/test_client_graphics.py b/tools/test_client_graphics.py index 74aaf946c..b3854d4f7 100644 --- a/tools/test_client_graphics.py +++ b/tools/test_client_graphics.py @@ -27,7 +27,8 @@ def main(): args = parser.parse_args() root = build_pack.ROOT fixture = build_mod.build_integration_fixture('client-graphics', - 'dev.horizonlab.metrics.ClientGraphicsIntegration', fixture_dependencies={}) + 'dev.horizonlab.metrics.ClientGraphicsIntegration', + fixture_mixins=['GraphicsBackendTraceMixin'], fixture_dependencies={}) version = build_pack.read_lock()['pack_version'] mod = root / 'dist' / f'horizon-lab-{version}.jar' original_hash = hashlib.sha256(mod.read_bytes()).hexdigest() @@ -48,8 +49,12 @@ def main(): raise RuntimeError('Graphics probe did not finish; diagnostics remain private') from None marker = 'HORIZON_CLIENT_GRAPHICS_RESULT ' reports = [json.loads(line.split(marker, 1)[1]) for line in run.stdout.splitlines() if marker in line] + trace_marker = 'HORIZON_GRAPHICS_BACKEND_ATTEMPT ' + attempts = [json.loads(line.split(trace_marker, 1)[1]) for line in run.stdout.splitlines() if trace_marker in line] if run.returncode or len(reports) != 1: - print('HORIZON_FIXTURE_FAILURE ' + json.dumps(failure_summary(run, len(reports))), flush=True) + diagnostics = failure_summary(run, len(reports)) + diagnostics['backend_attempts'] = attempts + print('HORIZON_FIXTURE_FAILURE ' + json.dumps(diagnostics), flush=True) raise RuntimeError('Graphics probe failed; diagnostics remain private') report = reports[0] if report['title_screen_observed'] is not True or report['title_client_ticks'] < 40: @@ -61,7 +66,7 @@ def main(): screenshot = instance / 'client-graphics-private.png' if not screenshot.is_file() or hashlib.sha256(screenshot.read_bytes()).hexdigest() != report['private_png_sha256']: raise AssertionError('Private screenshot evidence is missing or changed') - report.update(profile=profile, launcher_exit_code=run.returncode) + report.update(profile=profile, launcher_exit_code=run.returncode, backend_attempts=attempts) results.append(report) print(json.dumps(report), flush=True) output = root / 'dist/client-graphics-smoke.json' From 3858ab38b51f434ebe892b564e013c7c8bcaba45 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Sun, 4 Oct 2026 11:08:07 +0200 Subject: [PATCH 3/5] Isolate vanilla and core Vulkan startup failures on macOS --- .github/workflows/ci.yml | 28 ++++++++++++++++++- .../fixture/GraphicsBackendTraceMixin.java | 6 ++++ .../metrics/ClientGraphicsIntegration.java | 1 + tools/test_client_graphics.py | 25 +++++++++++++++-- 4 files changed, 57 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 587298bbe..f32895345 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -61,7 +61,32 @@ jobs: run: python -m unittest discover -s tests -v - name: Start native macOS clients and verify framebuffer readback if: runner.os == 'macOS' - run: python tools/test_client_graphics.py --native-display + run: | + python - <<'PY' + import json, subprocess, sys + from pathlib import Path + cases = [ + ['--profile', 'baseline', '--backend', 'vulkan'], + ['--profile', 'core-performance', '--backend', 'vulkan'], + ['--profile', 'core-performance'], + ['--profile', 'm2-balanced'], + ['--profile', 'vulkan'], + ] + failed = [] + observations = [] + for case in cases: + result = subprocess.run([sys.executable, 'tools/test_client_graphics.py', '--native-display', *case]) + observation = {'case': case, 'exit_code': result.returncode} + if result.returncode: + failed.append(case) + else: + observation['report'] = json.loads(Path('dist/client-graphics-smoke.json').read_text()) + observations.append(observation) + Path('dist/client-graphics-macos-cases.json').write_text(json.dumps(observations, indent=2) + '\n') + if failed: + print('HORIZON_MAC_GRAPHICS_FAILED_CASES', failed, flush=True) + sys.exit(1) + PY - name: Compile the private dispatch fixture run: python -c "from tools.build_mod import build_dispatch_fixture; build_dispatch_fixture()" - name: Compile the private tick-manager state fixture @@ -127,3 +152,4 @@ jobs: dist/quad-reuse-integration.json dist/quad-size-integration.json dist/client-graphics-smoke.json + dist/client-graphics-macos-cases.json diff --git a/mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/fixture/GraphicsBackendTraceMixin.java b/mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/fixture/GraphicsBackendTraceMixin.java index f0ff89272..78ba683d7 100644 --- a/mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/fixture/GraphicsBackendTraceMixin.java +++ b/mods/horizon-lab/src/test/java/dev/horizonlab/dispatch/fixture/GraphicsBackendTraceMixin.java @@ -43,6 +43,12 @@ public abstract class GraphicsBackendTraceMixin { try { GpuDevice device = backend.createDevice(options); trace(backend, "create_device", null); + var info = device.getDeviceInfo(); + var metadata = new JsonObject(); + metadata.addProperty("gpu", info.name()); + metadata.addProperty("graphics_backend", info.backendName()); + metadata.addProperty("graphics_driver", info.driverInfo()); + System.out.println("HORIZON_GRAPHICS_DEVICE_CREATED " + metadata); return device; } catch (BackendCreationException | RuntimeException | LinkageError | AssertionError failure) { trace(backend, "create_device", failure); diff --git a/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/ClientGraphicsIntegration.java b/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/ClientGraphicsIntegration.java index 1e3e3a52f..2bf27e4f6 100644 --- a/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/ClientGraphicsIntegration.java +++ b/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/ClientGraphicsIntegration.java @@ -18,6 +18,7 @@ public final class ClientGraphicsIntegration implements ClientModInitializer { private boolean requested; @Override public void onInitializeClient() { + System.out.println("HORIZON_CLIENT_GRAPHICS_INITIALIZER_READY"); ClientTickEvents.END_CLIENT_TICK.register(client -> { if (requested || !(client.gui.screen() instanceof TitleScreen)) return; if (titleStarted == 0) titleStarted = System.nanoTime(); diff --git a/tools/test_client_graphics.py b/tools/test_client_graphics.py index b3854d4f7..5421b5252 100644 --- a/tools/test_client_graphics.py +++ b/tools/test_client_graphics.py @@ -6,6 +6,7 @@ import hashlib import json import os import platform +import re import shutil import sys @@ -24,6 +25,7 @@ def main(): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument('--native-display', action='store_true') parser.add_argument('--profile', action='append', choices=sorted(build_pack.PROFILES)) + parser.add_argument('--backend', choices=['opengl', 'vulkan'], help='Override backend in these private instances only') args = parser.parse_args() root = build_pack.ROOT fixture = build_mod.build_integration_fixture('client-graphics', @@ -34,8 +36,16 @@ def main(): original_hash = hashlib.sha256(mod.read_bytes()).hexdigest() results = [] for profile in args.profile or ['core-performance', 'm2-balanced', 'vulkan']: - instance = root / '.local/runtime' / ('client-graphics-' + profile) + instance = root / '.local/runtime' / ('client-graphics-' + profile + + ('-override-' + args.backend if args.backend else '')) build_pack.prepare_instance(profile, instance, mod) + if args.backend: + options = instance / 'options.txt' + text, count = re.subn(r'^preferredGraphicsBackend:.*$', + 'preferredGraphicsBackend:' + json.dumps(args.backend), options.read_text(), flags=re.MULTILINE) + if count != 1: + raise AssertionError('Private backend preference is missing or ambiguous') + options.write_text(text) shutil.copy2(fixture, instance / 'mods/client-graphics-fixture.jar') command = [sys.executable, str(root / 'tools/runtime.py'), 'demo', '--instance', str(instance), '--heap', '3G'] @@ -53,7 +63,17 @@ def main(): attempts = [json.loads(line.split(trace_marker, 1)[1]) for line in run.stdout.splitlines() if trace_marker in line] if run.returncode or len(reports) != 1: diagnostics = failure_summary(run, len(reports)) + diagnostics['profile'] = profile + diagnostics['preferred_backend'] = args.backend or build_pack.PROFILES[profile].get('backend', 'opengl') diagnostics['backend_attempts'] = attempts + device_marker = 'HORIZON_GRAPHICS_DEVICE_CREATED ' + diagnostics['created_devices'] = [json.loads(line.split(device_marker, 1)[1]) + for line in run.stdout.splitlines() if device_marker in line] + diagnostics['client_initializer_reached'] = 'HORIZON_CLIENT_GRAPHICS_INITIALIZER_READY' in run.stdout + diagnostics['vulkan_error_codes'] = sorted(set(re.findall(r'\bVK_ERROR_[A-Z_0-9]{1,100}\b', run.stdout)))[:16] + diagnostics['java_exception_types'] = sorted(set(diagnostics['java_exception_types']) | set( + re.findall(r'\b((?:java|org\.lwjgl|com\.mojang|net\.minecraft|net\.fabricmc|org\.spongepowered|dev\.horizonlab)\.[A-Za-z_$][\w.$]{0,160}(?:Exception|Error))\b', run.stdout, re.ASCII)))[:8] + diagnostics['fatal_jvm_error'] = 'A fatal error has been detected by the Java Runtime Environment' in run.stdout print('HORIZON_FIXTURE_FAILURE ' + json.dumps(diagnostics), flush=True) raise RuntimeError('Graphics probe failed; diagnostics remain private') report = reports[0] @@ -66,7 +86,8 @@ def main(): screenshot = instance / 'client-graphics-private.png' if not screenshot.is_file() or hashlib.sha256(screenshot.read_bytes()).hexdigest() != report['private_png_sha256']: raise AssertionError('Private screenshot evidence is missing or changed') - report.update(profile=profile, launcher_exit_code=run.returncode, backend_attempts=attempts) + report.update(profile=profile, preferred_backend=args.backend or build_pack.PROFILES[profile].get('backend', 'opengl'), + launcher_exit_code=run.returncode, backend_attempts=attempts) results.append(report) print(json.dumps(report), flush=True) output = root / 'dist/client-graphics-smoke.json' From a5000edf11094e00ebef0fc362aa4adc322f2df6 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Sun, 4 Oct 2026 11:26:47 +0200 Subject: [PATCH 4/5] Check recommended Mac profiles in demo worlds and retain separate Vulkan research --- .github/workflows/ci.yml | 34 +++---------- .github/workflows/macos-vulkan-research.yml | 50 ++++++++++++++++++ .../metrics/ClientGraphicsIntegration.java | 38 ++++++++++++-- tests/test_fixtures.py | 19 +++++++ tools/test_client_graphics.py | 51 +++++++++++++------ 5 files changed, 146 insertions(+), 46 deletions(-) create mode 100644 .github/workflows/macos-vulkan-research.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f32895345..23da7622d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -59,34 +59,13 @@ jobs: run: python -c "from tools.build_mod import benchmark_headers; benchmark_headers()" - name: Test pack integrity and comparisons run: python -m unittest discover -s tests -v - - name: Start native macOS clients and verify framebuffer readback + - name: Start recommended OpenGL macOS clients and verify framebuffer readback if: runner.os == 'macOS' run: | - python - <<'PY' - import json, subprocess, sys - from pathlib import Path - cases = [ - ['--profile', 'baseline', '--backend', 'vulkan'], - ['--profile', 'core-performance', '--backend', 'vulkan'], - ['--profile', 'core-performance'], - ['--profile', 'm2-balanced'], - ['--profile', 'vulkan'], - ] - failed = [] - observations = [] - for case in cases: - result = subprocess.run([sys.executable, 'tools/test_client_graphics.py', '--native-display', *case]) - observation = {'case': case, 'exit_code': result.returncode} - if result.returncode: - failed.append(case) - else: - observation['report'] = json.loads(Path('dist/client-graphics-smoke.json').read_text()) - observations.append(observation) - Path('dist/client-graphics-macos-cases.json').write_text(json.dumps(observations, indent=2) + '\n') - if failed: - print('HORIZON_MAC_GRAPHICS_FAILED_CASES', failed, flush=True) - sys.exit(1) - PY + python tools/test_client_graphics.py --native-display + cp dist/client-graphics-smoke.json dist/client-graphics-macos-title.json + python tools/test_client_graphics.py --native-display --world + 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 tick-manager state fixture @@ -152,4 +131,5 @@ jobs: dist/quad-reuse-integration.json dist/quad-size-integration.json dist/client-graphics-smoke.json - dist/client-graphics-macos-cases.json + dist/client-graphics-macos-title.json + dist/client-graphics-macos-world.json diff --git a/.github/workflows/macos-vulkan-research.yml b/.github/workflows/macos-vulkan-research.yml new file mode 100644 index 000000000..adea87de5 --- /dev/null +++ b/.github/workflows/macos-vulkan-research.yml @@ -0,0 +1,50 @@ +name: macOS Vulkan research +on: + workflow_dispatch: +permissions: + contents: read +jobs: + native-probes: + runs-on: macos-26 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + - uses: actions/setup-java@v4 + with: + distribution: temurin + java-version: '25' + - name: Build original mod and private probe dependencies + run: python tools/build_mod.py + - name: Probe vanilla, core and distant-terrain Vulkan cases + run: | + python - <<'PY' + import json, subprocess, sys + from pathlib import Path + cases = [ + ['--profile', 'baseline', '--backend', 'vulkan'], + ['--profile', 'core-performance', '--backend', 'vulkan'], + ['--profile', 'vulkan'], + ] + observations = [] + for case in cases: + result = subprocess.run([sys.executable, 'tools/test_client_graphics.py', '--native-display', *case], capture_output=True, text=True) + print(result.stdout, end='', flush=True) + print(result.stderr, end='', flush=True) + observation = {'case': case, 'exit_code': result.returncode} + if result.returncode: + marker = 'HORIZON_FIXTURE_FAILURE ' + observation['failure'] = [json.loads(line.split(marker, 1)[1]) for line in result.stdout.splitlines() if marker in line] + else: + observation['report'] = json.loads(Path('dist/client-graphics-smoke.json').read_text()) + observations.append(observation) + Path('dist/client-graphics-vulkan-research.json').write_text(json.dumps(observations, indent=2) + '\n') + sys.exit(int(any(item['exit_code'] for item in observations))) + PY + - name: Retain selected observations including failed cases + if: always() + uses: actions/upload-artifact@v4 + with: + name: macos-vulkan-observations + path: dist/client-graphics-vulkan-research.json diff --git a/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/ClientGraphicsIntegration.java b/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/ClientGraphicsIntegration.java index 2bf27e4f6..4ec9d35bf 100644 --- a/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/ClientGraphicsIntegration.java +++ b/mods/horizon-lab/src/test/java/dev/horizonlab/metrics/ClientGraphicsIntegration.java @@ -8,23 +8,52 @@ import java.util.HashSet; import java.util.HexFormat; import net.fabricmc.api.ClientModInitializer; import net.fabricmc.fabric.api.client.event.lifecycle.v1.ClientTickEvents; +import net.fabricmc.loader.api.FabricLoader; import net.minecraft.client.Screenshot; 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 startup/readback probe. Never packaged in a playable release. */ public final class ClientGraphicsIntegration implements ClientModInitializer { private long titleStarted; private int titleTicks; private boolean requested; + private boolean opening; + private final boolean worldMode = Files.exists(FabricLoader.getInstance().getConfigDir().resolve("client-graphics-world.flag")); @Override public void onInitializeClient() { System.out.println("HORIZON_CLIENT_GRAPHICS_INITIALIZER_READY"); ClientTickEvents.END_CLIENT_TICK.register(client -> { - if (requested || !(client.gui.screen() instanceof TitleScreen)) return; + if (requested) return; + if (worldMode) { + if (!opening && client.gui.screen() instanceof TitleScreen screen) { + opening = true; + if (Files.isRegularFile(client.gameDirectory.toPath().resolve("saves/Demo_World/level.dat"))) { + client.createWorldOpenFlows().openWorld("Demo_World", () -> { + throw new AssertionError("Disposable graphics world did not open"); + }); + } else { + 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()) return; + } else if (!(client.gui.screen() instanceof TitleScreen)) return; if (titleStarted == 0) titleStarted = System.nanoTime(); titleTicks++; if (titleTicks < 40 || System.nanoTime() - titleStarted < 2_000_000_000L) return; requested = true; + System.out.println("HORIZON_CLIENT_GRAPHICS_READBACK_REQUESTED"); Screenshot.takeScreenshot(client.gameRenderer.mainRenderTarget(), image -> { try (image) { int width = image.getWidth(), height = image.getHeight(); @@ -42,8 +71,11 @@ public final class ClientGraphicsIntegration implements ClientModInitializer { image.writeToFile(screenshot); var device = RenderSystem.getDevice().getDeviceInfo(); var result = new JsonObject(); - result.addProperty("title_screen_observed", true); - result.addProperty("title_client_ticks", titleTicks); + result.addProperty("observed_mode", worldMode ? "world" : "title"); + result.addProperty("title_screen_observed", !worldMode); + result.addProperty("world_loaded", worldMode && client.level != null); + result.addProperty("ready_client_ticks", titleTicks); + result.addProperty("window_active", client.isWindowActive()); result.addProperty("framebuffer_width", width); result.addProperty("framebuffer_height", height); result.addProperty("sampled_pixels", samples); diff --git a/tests/test_fixtures.py b/tests/test_fixtures.py index e4642eb05..4b10553bc 100644 --- a/tests/test_fixtures.py +++ b/tests/test_fixtures.py @@ -3,9 +3,28 @@ import subprocess import unittest from tools.test_dispatch import failure_summary +from tools.test_client_graphics import graphics_failure_summary class FixtureDiagnosticTests(unittest.TestCase): + def test_graphics_diagnostics_separate_demo_auth_and_exclude_methods_messages(self): + output = '\n'.join([ + 'com.mojang.authlib.exceptions.InvalidCredentialsException: private-token', + ' at com.mojang.authlib.minecraft.client.MinecraftClient.buildHttpException(File.java:1)', + 'java.lang.AssertionError: /private/world/path', + 'Caused by: java.lang.RuntimeException: private-message VK_ERROR_FEATURE_NOT_PRESENT', + 'HORIZON_CLIENT_GRAPHICS_INITIALIZER_READY', + 'HORIZON_CLIENT_GRAPHICS_READBACK_REQUESTED', + ]) + result = graphics_failure_summary(subprocess.CompletedProcess([], 1, output), 0) + self.assertEqual(result['java_exception_types'], ['java.lang.AssertionError', 'java.lang.RuntimeException']) + self.assertTrue(result['expected_demo_authentication_errors_observed']) + self.assertTrue(result['client_initializer_reached']) + self.assertTrue(result['readback_requested']) + self.assertEqual(result['vulkan_error_codes'], ['VK_ERROR_FEATURE_NOT_PRESENT']) + self.assertNotIn('private', json.dumps(result)) + self.assertNotIn('buildHttpException', json.dumps(result)) + def test_only_exit_count_and_exception_types_leave_private_log(self): output = '\n'.join([ 'Exception in thread "private-thread-name" java.lang.NoClassDefFoundError: private-token', diff --git a/tools/test_client_graphics.py b/tools/test_client_graphics.py index 5421b5252..dbd86a383 100644 --- a/tools/test_client_graphics.py +++ b/tools/test_client_graphics.py @@ -21,11 +21,31 @@ except ImportError: from test_dispatch import failure_summary + +def graphics_failure_summary(run, report_count): + """Selected stages/types/codes only; messages, paths and raw logs stay private.""" + result = failure_summary(run, report_count) + pattern = r'(? Date: Sun, 4 Oct 2026 11:40:51 +0200 Subject: [PATCH 5/5] Document macOS scene checks and virtualized Vulkan limitations --- README.md | 4 + .../live-observations.json | 401 ++++++++++++++++++ docs/client-graphics-smoke.md | 79 ++++ docs/mac-first-test.md | 5 +- 4 files changed, 487 insertions(+), 2 deletions(-) create mode 100644 benchmarks/client-graphics-2026-10-04/live-observations.json create mode 100644 docs/client-graphics-smoke.md diff --git a/README.md b/README.md index 7ba6ee103..9bcb945c6 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,10 @@ Use native **Java 25 ARM64**, maximum heap **6144 MiB**, minimum **512 MiB** on If Prism is already installed, follow the [Mac import and first comparison guide](docs/mac-first-test.md). +Core and balanced also pass [macOS title/demo-world rendering probes](docs/client-graphics-smoke.md) +on the hosted ARM64 software renderer, including readback, saves and clean exits. +Physical M2 GPU performance and macOS 27 remain to be tested. + | Profile | Full-detail chunks | Distant LOD radius | Suggested maximum heap | | --- | ---: | ---: | ---: | | baseline | 12 | none | 6144 MiB | diff --git a/benchmarks/client-graphics-2026-10-04/live-observations.json b/benchmarks/client-graphics-2026-10-04/live-observations.json new file mode 100644 index 000000000..993b69812 --- /dev/null +++ b/benchmarks/client-graphics-2026-10-04/live-observations.json @@ -0,0 +1,401 @@ +{ + "schema": 1, + "measurement": "Client scene startup, framebuffer readback and clean exit; not a performance benchmark", + "release_binary": "0.20.0", + "production_mod_sha256": "e651ef49bc97486e8dacfd4b640465c442525cd645e2dba71ddea9fb64347dd8", + "macos_required_ci": { + "run": 37192178667, + "source_commit": "a5000edf11094e00ebef0fc362aa4adc322f2df6", + "all_jobs_passed": true, + "reports": { + "title": { + "schema": 1, + "platform": "macOS-26.6.2-arm64-arm-64bit", + "architecture": "arm64", + "minecraft": "26.3", + "original_mod_sha256": "e651ef49bc97486e8dacfd4b640465c442525cd645e2dba71ddea9fb64347dd8", + "results": [ + { + "observed_mode": "title", + "title_screen_observed": true, + "world_loaded": false, + "ready_client_ticks": 53, + "window_active": true, + "framebuffer_width": 1280, + "framebuffer_height": 646, + "sampled_pixels": 4160, + "distinct_sampled_rgb": 1525, + "gpu": "Apple Software Renderer", + "graphics_backend": "OpenGL", + "graphics_driver": "4.1 APPLE-23.1.1", + "private_png_sha256": "ed503082baca3a8646e7e864bf363e6e2a705a2b4aade2ec4bae6d3a108b07ab", + "profile": "core-performance", + "preferred_backend": "opengl", + "launcher_exit_code": 0, + "backend_attempts": [ + { + "backend": "OpenGL", + "operation": "load_library", + "result": "success" + }, + { + "backend": "OpenGL", + "operation": "create_device", + "result": "success" + } + ] + }, + { + "observed_mode": "title", + "title_screen_observed": true, + "world_loaded": false, + "ready_client_ticks": 55, + "window_active": true, + "framebuffer_width": 1280, + "framebuffer_height": 646, + "sampled_pixels": 4160, + "distinct_sampled_rgb": 1855, + "gpu": "Apple Software Renderer", + "graphics_backend": "OpenGL", + "graphics_driver": "4.1 APPLE-23.1.1", + "private_png_sha256": "959fe6afbe1897cd9711c083e88ccc617ee9d8669983987abda84e0f5979e82d", + "profile": "m2-balanced", + "preferred_backend": "opengl", + "launcher_exit_code": 0, + "backend_attempts": [ + { + "backend": "OpenGL", + "operation": "load_library", + "result": "success" + }, + { + "backend": "OpenGL", + "operation": "create_device", + "result": "success" + } + ] + } + ], + "limits": [ + "Short scene startup and nonuniform framebuffer readback only.", + "World mode uses the ordinary limited demo; world files remain private.", + "No exhaustive gameplay, visual-correctness, FPS or M2 Pro performance claim.", + "Vulkan preference can fall back; inspect the observed backend.", + "PNG images, assets and full logs remain in the private runtime directory." + ] + }, + "world": { + "schema": 1, + "platform": "macOS-26.6.2-arm64-arm-64bit", + "architecture": "arm64", + "minecraft": "26.3", + "original_mod_sha256": "e651ef49bc97486e8dacfd4b640465c442525cd645e2dba71ddea9fb64347dd8", + "results": [ + { + "observed_mode": "world", + "title_screen_observed": false, + "world_loaded": true, + "ready_client_ticks": 40, + "window_active": true, + "framebuffer_width": 1280, + "framebuffer_height": 646, + "sampled_pixels": 4160, + "distinct_sampled_rgb": 1537, + "gpu": "Apple Software Renderer", + "graphics_backend": "OpenGL", + "graphics_driver": "4.1 APPLE-23.1.1", + "private_png_sha256": "31be5cc8188b3494d76232cba79cf320a64523b4906ab720a38997a125eb37fa", + "profile": "core-performance", + "preferred_backend": "opengl", + "launcher_exit_code": 0, + "backend_attempts": [ + { + "backend": "OpenGL", + "operation": "load_library", + "result": "success" + }, + { + "backend": "OpenGL", + "operation": "create_device", + "result": "success" + } + ] + }, + { + "observed_mode": "world", + "title_screen_observed": false, + "world_loaded": true, + "ready_client_ticks": 40, + "window_active": true, + "framebuffer_width": 1280, + "framebuffer_height": 646, + "sampled_pixels": 4160, + "distinct_sampled_rgb": 2074, + "gpu": "Apple Software Renderer", + "graphics_backend": "OpenGL", + "graphics_driver": "4.1 APPLE-23.1.1", + "private_png_sha256": "0929c865d723fe0eea8f37bcc45e9636c6f342d04fe507f9bd592dfd30d73f42", + "profile": "m2-balanced", + "preferred_backend": "opengl", + "launcher_exit_code": 0, + "backend_attempts": [ + { + "backend": "OpenGL", + "operation": "load_library", + "result": "success" + }, + { + "backend": "OpenGL", + "operation": "create_device", + "result": "success" + } + ] + } + ], + "limits": [ + "Short scene startup and nonuniform framebuffer readback only.", + "World mode uses the ordinary limited demo; world files remain private.", + "No exhaustive gameplay, visual-correctness, FPS or M2 Pro performance claim.", + "Vulkan preference can fall back; inspect the observed backend.", + "PNG images, assets and full logs remain in the private runtime directory." + ] + } + } + }, + "earlier_vulkan_research": { + "run": 37191171799, + "source_commit": "3858ab38b51f434ebe892b564e013c7c8bcaba45", + "outcomes": [ + { + "exit_code": 1, + "result_count": 0, + "java_exception_types": [ + "java.lang.AssertionError", + "java.lang.RuntimeException" + ], + "profile": "baseline", + "preferred_backend": "vulkan", + "backend_attempts": [ + { + "backend": "Vulkan", + "operation": "load_library", + "result": "success" + }, + { + "backend": "Vulkan", + "operation": "create_device", + "result": "success" + } + ], + "created_devices": [ + { + "gpu": "Apple Paravirtual device", + "graphics_backend": "Vulkan", + "graphics_driver": "1.2.350 MoltenVK 1.4.2" + } + ], + "client_initializer_reached": true, + "vulkan_error_codes": [ + "VK_ERROR_FEATURE_NOT_PRESENT" + ], + "fatal_jvm_error": false, + "expected_demo_authentication_errors_observed": true + }, + { + "exit_code": 1, + "result_count": 0, + "java_exception_types": [ + "java.lang.AssertionError", + "java.lang.RuntimeException" + ], + "profile": "core-performance", + "preferred_backend": "vulkan", + "backend_attempts": [ + { + "backend": "Vulkan", + "operation": "load_library", + "result": "success" + }, + { + "backend": "Vulkan", + "operation": "create_device", + "result": "success" + } + ], + "created_devices": [ + { + "gpu": "Apple Paravirtual device", + "graphics_backend": "Vulkan", + "graphics_driver": "1.2.350 MoltenVK 1.4.2" + } + ], + "client_initializer_reached": true, + "vulkan_error_codes": [ + "VK_ERROR_FEATURE_NOT_PRESENT" + ], + "fatal_jvm_error": false, + "expected_demo_authentication_errors_observed": true + }, + { + "exit_code": 1, + "result_count": 0, + "java_exception_types": [ + "java.lang.AssertionError", + "java.lang.RuntimeException" + ], + "profile": "vulkan", + "preferred_backend": "vulkan", + "backend_attempts": [ + { + "backend": "Vulkan", + "operation": "load_library", + "result": "success" + }, + { + "backend": "Vulkan", + "operation": "create_device", + "result": "success" + } + ], + "created_devices": [ + { + "gpu": "Apple Paravirtual device", + "graphics_backend": "Vulkan", + "graphics_driver": "1.2.350 MoltenVK 1.4.2" + } + ], + "client_initializer_reached": true, + "vulkan_error_codes": [ + "VK_ERROR_FEATURE_NOT_PRESENT" + ], + "fatal_jvm_error": false, + "expected_demo_authentication_errors_observed": true + } + ], + "full_private_logs_uploaded": false, + "readback_request_stage_not_yet_captured": true + }, + "selected_local_software_checks": { + "linux-opengl": { + "title_screen_observed": true, + "title_client_ticks": 56, + "framebuffer_width": 1280, + "framebuffer_height": 800, + "sampled_pixels": 4288, + "distinct_sampled_rgb": 1762, + "gpu": "llvmpipe (LLVM 21.1.8, 256 bits)", + "graphics_backend": "OpenGL", + "graphics_driver": "4.5 (Core Profile) Mesa 26.0.8-1ubuntu0.3", + "private_png_sha256": "cf4eaa7d576ec8f608205258774fbd2384bf5382da86b60628d590f959145fd3", + "profile": "core-performance", + "launcher_exit_code": 0, + "backend_attempts": [ + { + "backend": "OpenGL", + "operation": "load_library", + "result": "success" + }, + { + "backend": "OpenGL", + "operation": "create_device", + "result": "success" + } + ] + }, + "linux-vulkan": { + "title_screen_observed": true, + "title_client_ticks": 56, + "framebuffer_width": 1280, + "framebuffer_height": 800, + "sampled_pixels": 4288, + "distinct_sampled_rgb": 1743, + "gpu": "llvmpipe (LLVM 21.1.8, 256 bits)", + "graphics_backend": "Vulkan", + "graphics_driver": "1.4.335 llvmpipe Mesa 26.0.8-1ubuntu0.3 (LLVM 21.1.8)", + "private_png_sha256": "edfc9b8431505c9c009da7bb8be0ed5676effb90757cd4ae4bda525e4db5da8c", + "profile": "vulkan", + "launcher_exit_code": 0, + "backend_attempts": [ + { + "backend": "Vulkan", + "operation": "load_library", + "result": "success" + }, + { + "backend": "Vulkan", + "operation": "create_device", + "result": "success" + } + ] + }, + "linux-world-core": { + "observed_mode": "world", + "title_screen_observed": false, + "world_loaded": true, + "ready_client_ticks": 51, + "window_active": true, + "framebuffer_width": 1280, + "framebuffer_height": 800, + "sampled_pixels": 4288, + "distinct_sampled_rgb": 1297, + "gpu": "llvmpipe (LLVM 21.1.8, 256 bits)", + "graphics_backend": "OpenGL", + "graphics_driver": "4.5 (Core Profile) Mesa 26.0.8-1ubuntu0.3", + "private_png_sha256": "1a8ba681681f5e37986e1b411e5ebc80d47279c54368f43f935707092b70ffd0", + "profile": "core-performance", + "preferred_backend": "opengl", + "launcher_exit_code": 0, + "backend_attempts": [ + { + "backend": "OpenGL", + "operation": "load_library", + "result": "success" + }, + { + "backend": "OpenGL", + "operation": "create_device", + "result": "success" + } + ] + }, + "linux-world-balanced": { + "observed_mode": "world", + "title_screen_observed": false, + "world_loaded": true, + "ready_client_ticks": 40, + "window_active": true, + "framebuffer_width": 1280, + "framebuffer_height": 800, + "sampled_pixels": 4288, + "distinct_sampled_rgb": 1551, + "gpu": "llvmpipe (LLVM 21.1.8, 256 bits)", + "graphics_backend": "OpenGL", + "graphics_driver": "4.5 (Core Profile) Mesa 26.0.8-1ubuntu0.3", + "private_png_sha256": "82ced9bcf7178a35063e6a7fa9049fe7cfcf26dcb92aace59de6bb022609833a", + "profile": "m2-balanced", + "preferred_backend": "opengl", + "launcher_exit_code": 0, + "backend_attempts": [ + { + "backend": "OpenGL", + "operation": "load_library", + "result": "success" + }, + { + "backend": "OpenGL", + "operation": "create_device", + "result": "success" + } + ] + } + }, + "limits": [ + "macOS OpenGL uses Apple Software Renderer; Vulkan exposes Apple Paravirtual device. No physical M2 GPU performance test.", + "World-mode checks ordinary limited-demo world startup and saved data, not exhaustive gameplay or completed LOD generation.", + "A nonuniform framebuffer does not prove pixel-correct rendering.", + "Three exploratory Vulkan cases fail with VK_ERROR_FEATURE_NOT_PRESENT after successful device creation; later stage remains to be isolated.", + "The probe uses 3 GiB; balanced can warn about low memory. The 16 GB Mac starter suggests 6 GiB.", + "No FPS, CPU/RAM reduction, statistical speedup or universal hardware-compatibility claim.", + "Raw PNGs, assets, world files and full logs remain private. Production JAR matches the published binary and excludes probe classes." + ] +} diff --git a/docs/client-graphics-smoke.md b/docs/client-graphics-smoke.md new file mode 100644 index 000000000..740f9dab9 --- /dev/null +++ b/docs/client-graphics-smoke.md @@ -0,0 +1,79 @@ +# Client startup and world-rendering probes + +Compilation does not show whether a client creates its graphics device, reaches +the menu, enters a world or reads back a rendered frame. The private graphics +probe runs the actual pinned game and performance mods to check those steps. +It is a separate test mod, excluded from production JARs and playable packs. + +The required macOS CI cases use the recommended OpenGL `core-performance` and +`m2-balanced` profiles. Each profile starts at the title screen and then, in a +separate instance, creates or opens an ordinary limited-demo world. World mode +dismisses the demo-help popup, waits for focused, unpaused gameplay, reads back +the main render target, and stops the client so its integrated server saves. +Private screenshots must have a nonuniform sample grid and a verified file hash; +world mode also checks for saved world data after a clean process exit. + +The startup wrapper observes backend library/device creation and preserves the +original calls and thrown exceptions. Selected diagnostics contain initialization +stages, bounded exception type names, Vulkan error-code identifiers and device +labels. Expected demo authentication errors are reported separately. Full log +messages, raw screenshots, assets and world files stay under gitignored `.local/`. +Nonuniform pixels are not proof of correct visuals, full LOD completion or +exhaustive gameplay equivalence. + +The [selected live observations](../benchmarks/client-graphics-2026-10-04/live-observations.json) +record passing title and demo-world readbacks for both profiles on the hosted +macOS ARM64 runner. Both world cases are focused, produce saved data and exit +cleanly. All four CI jobs pass for that source head. Its independently built +macOS production JAR matches published 0.20.0 byte-for-byte and contains neither +probe class. The observed macOS OpenGL device is **Apple Software Renderer**; +these are platform runtime checks, not physical Apple GPU performance results. + +## Run locally + +Build the original mod first, then use the platform's display: + +```sh +python3 tools/build_mod.py +python3 tools/test_client_graphics.py --native-display +python3 tools/test_client_graphics.py --native-display --world +``` + +These default to core and balanced, with a 3 GiB heap. That budget can trigger +DH's low-memory warning; the 16 GB Mac starter suggests 6 GiB. A short startup +check is not a recommendation for sustained memory or distant-generation load. +On headless Linux, omit `--native-display` to use Xvfb, or run through `vscreen` +with its display available. World mode creates private, disposable demo worlds +in its isolated runtime folders. No Microsoft credentials are needed for the +game's limited demo. It does not accept the dedicated-server EULA. + +The selected output is `dist/client-graphics-smoke.json`. Each case records the +observed backend rather than inferring it from the preference. Normal CI retains +separate title/world JSONs. Neither the fixture nor screenshots enter releases. + +## Vulkan investigation + +The manual **macOS Vulkan research** workflow separately probes vanilla, core and +the distant-terrain Vulkan profile. It runs every case, retains selected successful +and failed outcomes, and exits unsuccessfully when a case fails. Its exploratory +results do not count as passing the required OpenGL checks. + +Local Linux software OpenGL/Vulkan title readbacks passed. Early macOS OpenGL +title checks for core and balanced also passed with **Apple Software Renderer**. +The macOS runner's **Apple Paravirtual device**, using MoltenVK 1.4.2, created +Vulkan devices but all three Vulkan cases failed with `VK_ERROR_FEATURE_NOT_PRESENT`. +The failure also occurs with vanilla; these observations do not isolate an +optimization-mod fault or prove behavior on a physical M2 GPU. Later diagnostics +identify whether readback was requested before failure. + +For an isolated private preference override: + +```sh +python3 tools/test_client_graphics.py --native-display --profile baseline --backend vulkan +python3 tools/test_client_graphics.py --native-display --profile core-performance --backend vulkan +``` + +Overrides use separate runtime folders. The shipped profiles retain their +configured preferences. These probes make no FPS, CPU/RAM reduction, hardware-GPU +compatibility or M2 Pro performance claim. Actual-world performance comparisons +still use the [Mac first-test procedure](mac-first-test.md). diff --git a/docs/mac-first-test.md b/docs/mac-first-test.md index 6ab39f040..17a3076ef 100644 --- a/docs/mac-first-test.md +++ b/docs/mac-first-test.md @@ -1,7 +1,8 @@ # First test on the M2 Pro Mac -For the 16 GB M2 Pro, start with the published 0.20.0 packs. The client has been -built on Apple Silicon macOS; gameplay and FPS on this Mac remain unmeasured. +For the 16 GB M2 Pro, start with the published 0.20.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