Keep Xray markers out of OBS Game Capture on Windows

NOTICE.md

@@ -18,6 +18,11 @@ Fabric Loader and Fabric API are external dependencies, not bundled in the Lumen
 JAR. Their authors retain their rights; Fabric's projects are available at
 https://github.com/FabricMC under their respective licenses.
 
+Windows Stream mode uses JNA and JNA-platform 5.17.0, supplied by Minecraft's
+runtime, to call Windows APIs for its separate overlay. Lumen does not package
+JNA or JNA-platform binaries. JNA's [license](https://github.com/java-native-access/jna/blob/5.17.0/LICENSE)
+allows LGPL-2.1-or-later or Apache-2.0, at the user's option.
+
 The Gradle wrapper is generated by Gradle and carries its Apache-2.0 notices.
 JUnit is used only for development tests. Minecraft is a separate proprietary
 product of Mojang/Microsoft. Lumen is not an official Minecraft product and is

README.md

@@ -4,9 +4,9 @@
 
 A client-only Fabric edition of Lumen by Auron Network. English interface, dark
 translucent panels and yellow accents. Current Java test build:
-**1.0.0-beta.3**; Java and Bedrock use separate binaries and version numbers.
+**1.0.0-beta.4**; Java and Bedrock use separate binaries and version numbers.
 
-[Download the Java beta](https://github.com/AuronNetwork/Lumen-Java/releases/tag/v1.0.0-beta.3)
+[Download the Java beta](https://github.com/AuronNetwork/Lumen-Java/releases/tag/v1.0.0-beta.4)
  · [Report an issue](https://github.com/AuronNetwork/Lumen-Java/issues)
  · [Test coverage and limits](TESTING.md)
  · [Bedrock edition](https://github.com/AuronNetwork/Lumen)
@@ -15,7 +15,7 @@ translucent panels and yellow accents. Current Java test build:
 
 1. Install [Fabric Loader](https://fabricmc.net/use/installer/) **0.19.5 or newer**
    for **Minecraft Java 26.3** and select that profile in your launcher.
-2. Place `lumen-java-1.0.0-beta.3.jar` and
+2. Place `lumen-java-1.0.0-beta.4.jar` and
    [Fabric API for 26.3](https://modrinth.com/mod/fabric-api/versions?g=26.3)
    in that profile's `mods` folder. This build uses Fabric API **0.161.0+26.3**.
    For the standard launcher the default folder is `%APPDATA%\.minecraft\mods`.
@@ -24,20 +24,25 @@ translucent panels and yellow accents. Current Java test build:
 Minecraft 26.3 requires Java 25; the official launcher supplies its game runtime.
 Install this mod on the client only. No Lumen EXE, DLL, Latite or server mod is
 required. Remove older Lumen Java JARs from the same profile before updating.
+Stream mode needs no additional mod: it uses JNA and JNA-platform **5.17.0**
+already provided by Minecraft, without bundling those libraries in the Lumen JAR.
 
 In Prism Launcher, right-click the instance, choose **Folder**, and use its
 `minecraft/mods` folder. Close that instance before replacing the Lumen JAR.
 
 ### Iris shader compatibility
 
-Beta 2 fixes through-wall markers disappearing with Iris shader packs. Ore and
-chest outlines are drawn after shader composition, with the current world camera
-projection, and remain below menus and the HUD. No extra compatibility mod or
-shader setting is required. Turning **Through walls** off retains normal depth
-occlusion. F1 hides the through-wall marker overlay together with the HUD.
-
-Verified with Iris **1.11.6**, Sodium **0.9.3-alpha.1**, and Complementary Reimagined
-**r5.9.3** on Minecraft 26.3, including toggling shaders off/on during play.
+In normal mode, the rendering introduced in beta 2 fixes through-wall markers
+disappearing with Iris shader packs. Ore and chest outlines are drawn after shader
+composition, with the current world camera projection, and remain below menus
+and the HUD. No extra compatibility mod or shader setting is required. Turning
+**Through walls** off retains normal depth occlusion. F1 hides the through-wall
+marker overlay together with the HUD.
+
+Beta 4 passed the full client and OBS Game Capture tests with Iris **1.11.6**,
+Sodium **0.9.2**, and Complementary Reimagined **r5.9.3** on Minecraft 26.3,
+including shaders off/on and Stream mode off/on. See [TESTING.md](TESTING.md)
+for the verified scope.
 Other shader packs and rendering mods need separate testing. Shader packs can
 provide their own lighting, so Fullbright's lightmap setting may not brighten
 their rendered scene.
@@ -54,17 +59,19 @@ their rendered scene.
 
 Keys are rebindable in Minecraft's Controls / Key Binds / Lumen category.
 The menu releases the cursor, consumes its own clicks and does not pause the world.
-The **Features**, **Ore Filters** and **Chest Filters** tabs provide:
+The **Features**, **Ore Filters**, **Chest Filters** and **Streaming** tabs provide:
 
 - Xray with a 4-24 block radius and 32-512 nearest markers.
 - Ten ore categories, including deepslate variants, nether gold, quartz and ancient debris.
 - Normal chests, trapped chests and ender chests as independent filters.
 - Optional visibility through walls. Double chests have two marked block positions.
 - 2x-20x hold-to-zoom and local Fullbright.
 - **No Attack Cooldown**: optional full melee attack strength in singleplayer.
+- Optional Windows Stream mode for Xray markers with OBS Game Capture.
 
-Fresh settings start with Xray, Fullbright and No Attack Cooldown off, Zoom enabled, a 16-block radius,
-192 markers, 4x zoom, selected valuable ores and all chest filters off.
+Fresh settings start with Xray, Fullbright, No Attack Cooldown and Stream mode off,
+Zoom enabled, a 16-block radius, 192 markers, 4x zoom, selected valuable ores and
+all chest filters off.
 Settings are saved in the profile's `config/lumen.properties`.
 Bedrock's INI settings are not automatically imported.
 
@@ -75,6 +82,39 @@ Zoom and Fullbright modify the rendered view, without overwriting Minecraft's
 FOV/brightness options or adding potion effects. Modpack compatibility and
 additional rendering backends require separate testing.
 
+### Stream mode for OBS Game Capture
+
+1. Use **Windows 10 version 2004 or newer, or Windows 11**, with Minecraft in
+   **windowed or borderless fullscreen** mode. Exclusive fullscreen hides the overlay.
+2. Open **Insert → Streaming → Stream mode** and set it to **ON**. Enable Xray
+   and select the desired ore/chest filters as usual, then close the menu.
+3. In OBS, add a **Game Capture** source and select **only the Minecraft game window**.
+   Check an OBS preview or test recording before streaming.
+
+Stream mode defaults to **OFF** and is saved in `config/lumen.properties`,
+including across Minecraft restarts. When enabled, Xray marker pixels are drawn
+in a separate transparent, click-through Windows overlay. They are never drawn
+into Minecraft's captured frame. Only the Xray markers move to this overlay:
+the Lumen menu, Zoom and Fullbright remain visible in Game Capture.
+
+The overlay uses Windows `SetWindowDisplayAffinity` with
+`WDA_EXCLUDEFROMCAPTURE` (`0x11`) and verifies that setting before showing markers.
+If the overlay or capture exclusion fails, markers stay hidden; Lumen does not
+fall back to drawing them in the Minecraft frame. Capture exclusion applies to
+specific public Windows capture APIs. It is not a guarantee for every recording
+method, screen-sharing tool or capture card. The setup described here is OBS
+**Game Capture** selecting the Minecraft window. See [TESTING.md](TESTING.md) for
+which runtime and capture checks have actually been completed for this beta.
+
+External markers hide while any menu is open, with F1, when Minecraft is
+minimized or loses focus (including Alt+Tab), and on disconnect. With
+**Through walls OFF**, the external overlay checks block line of sight from the
+camera; it cannot use Minecraft's world depth buffer, so its occlusion can differ
+from normal marker rendering.
+
+Stream mode is unavailable on non-Windows systems. Leave it **OFF** there to use
+the existing normal marker rendering.
+
 ### No Attack Cooldown
 
 Open **Insert → Features → No Attack Cooldown** to turn the feature on or off.

TESTING.md

@@ -1,12 +1,73 @@
 # Java 26.3 validation
 
-Tested September 29, 2026: Lumen Java 1.0.0-beta.3, Minecraft 26.3,
+Tested October 15, 2026: Lumen Java 1.0.0-beta.4, Minecraft 26.3,
 Fabric Loader 0.19.5, Fabric API 0.161.0+26.3, Java 25, Windows x64.
 Rendering backend used by the automated game test: OpenGL on NVIDIA hardware.
 
+## Stream mode and OBS Game Capture
+
+Lumen 1.0.0-beta.4 was tested in the actual Minecraft 26.3 client with a
+separate portable **OBS Studio 32.2.2** instance. That OBS instance used a fresh
+profile and scene collection; it never streamed, recorded or started a virtual
+camera. The user's running OBS profile and personal Minecraft instance were not
+modified.
+
+The same full test passed twice: first without Iris, then with **Iris 1.11.6**,
+**Sodium 0.9.2** and **Complementary Reimagined r5.9.3**. Fixture downloads were
+SHA-512 verified against official Modrinth metadata. Capture checks used real
+OBS `game_capture` output returned by `GetSourceScreenshot`, rather than a mock
+capture or a Minecraft screenshot alone.
+
+| OBS checkpoint | Diamond | Chest | Trapped chest | Ender chest |
+| --- | ---: | ---: | ---: | ---: |
+| Stream mode OFF, normal rendering | present | present | present | present |
+| Stream mode ON, external overlay visible | 0 pixels | 0 pixels | 0 pixels | 0 pixels |
+| Stream mode OFF again | present | present | present | present |
+
+All four colors must have at least 100 matching pixels in each normal-rendering
+capture, and exactly zero in the stream-mode capture. The image must still
+contain the Minecraft scene/HUD, so a blank source cannot pass. Independent
+sidecar color counts agree with the in-game assertions. Screenshot matching
+accounts for HUD vignette brightness and integer color rounding.
+
+Additional checks completed:
+
+- The actual Streaming menu toggle defaults OFF, saves ON and restores normal
+  rendering when switched OFF. Settings tests also cover older/malformed files.
+- The native window is visible while the game remains foreground, with Windows
+  reporting capture affinity `0x11`. Its input styles are click-through and
+  non-activating. The Minecraft game framebuffer contains no marker pixels.
+- A test-only copy of the completed native GDI surface contains all four marker
+  colors. Capture exclusion remains `0x11` during inspection; no screenshot code
+  is included in the production mod.
+- Resizing to 1280x720 keeps the external window aligned to the Minecraft client
+  dimensions. Zoom retains external markers and a clean game framebuffer.
+- Xray OFF, F1, opening the menu, looking behind the camera, and occluded blocks
+  with Through walls OFF hide the external markers. Normal rendering returns
+  after Stream mode is disabled, and closing destroys the native window.
+- The existing filter, Fullbright, mouse/slider, combat damage, configuration,
+  block removal and world exit/re-entry checks still pass.
+
+A preliminary test correctly hid the overlay when Windows kept another window
+in the foreground. The test fixture now explicitly focuses only its own game
+window. Production overlay code never focuses Minecraft or steals activation.
+
+The Windows overlay is limited to 60 updates per second and batches marker
+edges by color. If the native window or verified capture exclusion is unavailable,
+Stream mode suppresses both ordinary game-rendering paths. It never falls back to
+putting markers in the recorded framebuffer. Frames older than 250 ms are hidden.
+With Through walls OFF, the external renderer uses block line of sight, which
+can differ from normal depth-buffer occlusion.
+
+This validates **OBS Game Capture of the Minecraft window** on Windows/OpenGL.
+It does not validate every OBS source method, capture card, third-party recorder,
+Windows version, multi-monitor/DPI combination, or a live Twitch broadcast.
+Exclusive fullscreen is not supported. The Lumen menu, zoom and Fullbright remain
+part of the normal game image and remain visible to the recording.
+
 ## Completed
 
-- `gradlew build`: successful; eleven JUnit tests pass with no failures.
+- `gradlew build`: successful; twelve JUnit tests pass with no failures.
 - `gradlew runClientGameTest`: successful in a separate Fabric development
   instance. Its own test world was created, closed and reopened.
 - All production mixins loaded in the actual game without missing-target errors.
@@ -73,7 +134,7 @@ Normal depth-tested outlines still use vanilla gizmos. There is no Iris dependen
 or shader modification in the production mod.
 
 The full client game test also passed with Iris **1.11.6+mc26.3**, Sodium
-**0.9.3-alpha.1+mc26.3**, and **Complementary Reimagined r5.9.3** at default shader
+**0.9.2+mc26.3**, and **Complementary Reimagined r5.9.3** at default shader
 settings. Fixtures were read from local files and copied only into the disposable
 test instance; no personal Prism profile, mod or world was changed.
 
@@ -87,7 +148,7 @@ test instance; no personal Prism profile, mod or world was changed.
   that the Lumen menu draws above the outlines.
 - The existing filter, zoom release, lightmap restoration, mouse/menu, slider,
   persistence, block removal and world re-entry checks also pass with Iris.
-- The beta 3 integrated-server combat damage and restoration checks also pass
+- The beta 4 integrated-server combat damage and restoration checks also pass
   with this shader configuration.
 
 The three projection tests cover viewport clipping, near-plane crossings,
@@ -103,7 +164,7 @@ ordering, read/marker/radius limits, removal/replacement, teleport and reset.
 
 These are automated development-client tests plus visual inspection of the
 captured game frames. User acceptance in a normal installed Fabric profile is
-still pending for beta 3. Other shader packs, the rest of the user's Prism modpack
+still pending for beta 4. Other shader packs, the rest of the user's Prism modpack
 (including Distant Horizons and Freecam), Vulkan, non-Windows platforms and
 multiplayer compatibility were not tested. The Java release remains a beta.
 Fullbright's lightmap state restores correctly with Iris, but a shader pack's
@@ -124,3 +185,7 @@ rapid attacks on separate targets, then turn it off to restore normal charging.
 Repeated hits on one target still respect its damage immunity.
 Report the Lumen version and that profile's `logs/latest.log` if a
 problem occurs. Do not install the development test mod or source JAR.
+
+For Stream mode, use **Insert → Streaming → Stream mode ON**, close the menu,
+and compare the game with the OBS Game Capture preview or a short local recording.
+Use windowed/borderless mode and verify the full OBS scene before going live.

build.gradle

@@ -48,4 +48,7 @@ tasks.named('runClientGameTest') {
     if (providers.gradleProperty('shaderTestPack').isPresent()) {
         systemProperty 'lumen.test.shaderPack', providers.gradleProperty('shaderTestPack').get()
     }
+    if (providers.gradleProperty('obsTestDir').isPresent()) {
+        systemProperty 'lumen.test.obsDir', providers.gradleProperty('obsTestDir').get()
+    }
 }

gradle.properties

@@ -3,4 +3,4 @@ org.gradle.parallel=true
 minecraft_version=26.3
 loader_version=0.19.5
 fabric_version=0.161.0+26.3
-mod_version=1.0.0-beta.3
+mod_version=1.0.0-beta.4

src/gametest/java/net/auronnetwork/lumen/LumenGameTest.java

@@ -15,7 +15,7 @@ private static void check(boolean value, String description) {
         if (!value) throw new AssertionError(description);
     }
     private static final BlockKind[] TEST_MARKERS = {BlockKind.DIAMOND, BlockKind.CHEST, BlockKind.TRAPPED_CHEST, BlockKind.ENDER_CHEST};
-    private static void checkMarkerImage(java.nio.file.Path path, boolean visible) {
+    static void checkMarkerImage(java.nio.file.Path path, boolean visible) {
         try {
             var image = javax.imageio.ImageIO.read(path.toFile());
             for (var kind : TEST_MARKERS) {
@@ -55,6 +55,7 @@ private static void setShaders(ClientGameTestContext context, boolean enabled) {
         });
     }
     @Override public void runTest(ClientGameTestContext context) {
+        LumenStreamTest.prepareWindow(context);
         if (FabricLoader.getInstance().isModLoaded("iris")) {
             context.runOnClient(mc -> {
                 try {
@@ -150,6 +151,7 @@ private static void setShaders(ClientGameTestContext context, boolean enabled) {
                 check(Math.abs(mc.gameRenderer.mainCamera().getFov() - normal) < 0.01f, "C release restores FOV");
                 check(mc.options.gamma().get() == gamma && mc.options.fov().get() == fov, "Original game settings unchanged");
             });
+            LumenStreamTest.run(context);
             context.getInput().pressKey(LumenClient.menuKey);
             context.waitForScreen(LumenScreen.class);
             context.runOnClient(mc -> {