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