FrameBridge: unique controller action names (#323 )

Scared By Squares (Unreal 4.27, OpenXR) creates two actions named "turn" (an action mapping and an axis mapping called Turn). The Frame's runtime accepts the duplicate, then vrserver fails to load the input manifest it builds ("SetXrInputConfig failed. Failed to load manifest"), drops the app's connection and treats it as exited: black, then the home environment while the game keeps running with sound. Headless the app reconnected as a plain OpenXR instance, got throttled to 10 fps and the compositor received no presents. - action_dedup (adapter setting, default on): a later duplicate action name or localized name in a set is created as "<name>_N" / "<Localized> N" (native/adapter/action_names.h, host-tested). Headless on the dev Frame: manifest loads, 72 fps, 2808 presents in 45 s (before: 10 fps, none). - input_diag logs every action set and action (escaped names). - force_render (hidden diagnostic): xrWaitFrame reports shouldRender=TRUE so headless runs exercise engines that skip layers when not visible; FrameBridge logs shouldRender changes. - Triage: space-warp-used only on the motion-vector swapchain (format 97); D24S8 (129) eye depth falsely matched. New info finding duplicate-action-renamed. - Catalog entry (status unknown, min_app 1.2.1), PLAYBOOK row.
2026-10-17 16:02:22 +02:00 · 2026-10-16 00:09:12 -04:00
17 changed files with 297 additions and 15 deletions
@@ -13,11 +13,11 @@ e8c0965c188665a4e565e4a3af983ef1866d1cf9225665cc90d8df286bc96ef3  ./arm64-v8a/li
 5432674a59d02f411cd853a5dc57e3fa547d1ac518f25bf433fc54c43677177a  ./arm64-v8a/libfpglmv.so
 8a8f6b1da8952cb3933a5b53558424a5fc56043b2527a16bb6dd62a00d2de01a  ./arm64-v8a/libframe_xrshim.so
 19ba5ed3c4b780f5ae46251f6958f552acfc5f13c8bb39f995579593fa8990c6  ./arm64-v8a/libglshim.so
-0f058921e9c1f5b9ef5847cc9e6b80a23e75028c76c1d3bb02d1610b535f81c9  ./arm64-v8a/libopenxr_loader_generic.so
+54f05223eeaa19527af26d6c2e2dd304302d712f4a8db2cd95d7536babfdf8db  ./arm64-v8a/libopenxr_loader_generic.so
 1feaeafad467c4cafdf2b018a4d84b0bee200c3f711697b4ce97e66a3ba256ca  ./arm64-v8a/libovrplatformcompat.so
 a4ed80ae45ca90758239f152ea5a2e8c127d491e1e697ea5680db6fd7f72db07  ./arm64-v8a/libvrapi.so
 a4ed80ae45ca90758239f152ea5a2e8c127d491e1e697ea5680db6fd7f72db07  ./arm64-v8a/libvrapi_foveation.so
-9e8a7ce599b62a7c607b0d3637e4ec1b1ea1974c3373a7af3f5920ad2adc5e00  ./armeabi-v7a/libopenxr_loader_generic.so
+3c4c30d31865f81360bb5ebc92dcec996eb2b3e9388085f020cc2fb460f75749  ./armeabi-v7a/libopenxr_loader_generic.so
 1871eae093432d277da4bc751bf5f3269dfcf11f9168260b0c3caadb0dedb19d  ./dex/oculusos-stubs.dex
 b634ab5640e258563c536e658cad87080553df6f34f62269a21d554844e58bfe  ./hevc/COPYING.FFmpeg
 141de01f0d40b97d4f9a720db5ab8ea442f6aa35db5272048899292884994a1c  ./hevc/libstagefrighthw.so
@@ -0,0 +1,19 @@
+package: ScaredBySquares.Game
+title: Scared By Squares
+status: unknown
+notes: 'Showed black and dropped back to the home environment while the game kept running (sound only, GitHub 323).
+  Fixed in FramePort 1.2.1 and checked on the Frame without the headset (the game runs at 72 fps and SteamVR keeps it
+  as the running game); not yet confirmed in the headset. Rebuild and reinstall the game after updating FramePort.'
+details: 'The game (Unreal 4.27, OpenXR) creates two controller actions named "turn" (an action mapping and an axis
+  mapping called Turn). The Frame''s runtime accepts the duplicate, then fails to load the input manifest it builds
+  from the actions ("SetXrInputConfig failed. Failed to load manifest") and treats the game as closed. FrameBridge''s
+  action_dedup (on by default) creates the second one as "turn_2".'
+tested_version: '2'
+engine: Unreal
+xr: OpenXR
+frame:
+- frame.hw_video_decode
+- frame.unreal_skip_obb_check
+updated: '2026-10-16'
+min_app: 1.2.1
+source_hint: Scared By Squares
@@ -173,7 +173,8 @@ signatures:
    suggest: [adapter.vk_shader_dump, adapter.zink_shader_dump]
    report: true
  - id: space-warp-used
-    pattern: 'xrCreateSwapchain \d+x\d+ format=(97|129) '
+    # space warp's motion vectors (97 = R16G16B16A16_SFLOAT); its depth (129) is also what eye depth layers use (#323)
+    pattern: 'xrCreateSwapchain \d+x\d+ format=97 '
    unless: 'per-game: hide_space_warp=1'
    severity: info
    diagnosis: The game uses Meta's space warp (it renders half of its frames plus motion vectors, and the runtime makes
@@ -181,6 +182,13 @@ signatures:
      Metro Awakening). Turning it off makes the game render every frame itself.
    question: Did textures flicker, jump or smear while you moved?
    suggest: [adapter.hide_space_warp]
+  - id: duplicate-action-renamed
+    pattern: 'action_dedup: action .* already exists in its set'
+    severity: info
+    diagnosis: The game creates two controller actions with the same name (for example an Unreal action and axis both
+      called Turn). The Frame's runtime then can't load the game's controller setup and drops the game back to the home
+      environment while it keeps running. FramePort renamed the second one, so this is handled.
+    suggest: []
  - id: unity-runtime-msaa
    pattern: 'recommended MSAA level is [248]\. Switching to the recommended level'
    severity: info
@@ -2,7 +2,7 @@

 # Patches

-Every patch and game setting FramePort knows: 169 entries in 5 groups. A game's recipe is its chosen patches and settings; tested games get theirs from the catalog ([GAMES.md](GAMES.md)), and other games get the patches FramePort suggests from its analysis. You change them on the game page under Customize.
+Every patch and game setting FramePort knows: 170 entries in 5 groups. A game's recipe is its chosen patches and settings; tested games get theirs from the catalog ([GAMES.md](GAMES.md)), and other games get the patches FramePort suggests from its analysis. You change them on the game page under Customize.

 Each entry says what the patch does, whether it changes the APK or only the install, when FramePort suggests it, its options, the catalog games whose recipe names it and the launch-test signatures that suggest it. Patches that are on by default are on for every game, so the catalog rarely names them.

@@ -12,7 +12,7 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t

 - [Patches from OVRPort](#group-overport) (25)
 - [Steam Frame patches](#group-frame) (55)
- [Game settings](#group-adapter) (68)
+- [Game settings](#group-adapter) (69)
 - [Files and settings on the Frame](#group-device) (8)
 - [PC VR (Proton and Revive)](#group-pcvr) (13)

@@ -56,7 +56,7 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [OpenGL ES: multiview shaders on flat panels (HUD, menus)](#frame-gl_multiview_fbo) | `frame.gl_multiview_fbo` | Steam Frame patches | 1 |
 | [GL shim (Mesa GLSL compatibility)](#frame-gl_shim) | `frame.gl_shim` | Steam Frame patches | 2 |
 | [Godot apps: start without a clipboard service](#frame-godot_clipboard) | `frame.godot_clipboard` | Steam Frame patches |  |
-| [Hardware video decoding (H.264, HEVC, VP9)](#frame-hw_video_decode) | `frame.hw_video_decode` | Steam Frame patches | 19 |
+| [Hardware video decoding (H.264, HEVC, VP9)](#frame-hw_video_decode) | `frame.hw_video_decode` | Steam Frame patches | 20 |
 | [Language packs from the game's files](#frame-langpacks) | `frame.langpacks` | Steam Frame patches |  |
 | [Launcher category (INFO → LAUNCHER)](#frame-launcher) | `frame.launcher` | Steam Frame patches | default |
 | [GL wrapper: OpenGL ES depth formats (Minecraft)](#frame-ltw_depth) | `frame.ltw_depth` | Steam Frame patches | default |
@@ -90,7 +90,7 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [Unreal: stand-ins for OVRPlugin functions OVRPort lacks](#frame-unreal_ovrp_entrypoints) | `frame.unreal_ovrp_entrypoints` | Steam Frame patches | 2 |
 | [Unreal: Quest controller bindings (RPOC key map)](#frame-unreal_quest_keymap) | `frame.unreal_quest_keymap` | Steam Frame patches | 3 |
 | [Unreal: don't wait for the Quest shader precompile](#frame-unreal_quest_precompile) | `frame.unreal_quest_precompile` | Steam Frame patches | 3 |
-| [Unreal: start without the OBB check](#frame-unreal_skip_obb_check) | `frame.unreal_skip_obb_check` | Steam Frame patches | 5 |
+| [Unreal: start without the OBB check](#frame-unreal_skip_obb_check) | `frame.unreal_skip_obb_check` | Steam Frame patches | 6 |
 | [Unreal: skip the OBB delivery check](#frame-unreal_skip_obb_delivery) | `frame.unreal_skip_obb_delivery` | Steam Frame patches | 1 |
 | [Unreal: bypass the stalled loading splash](#frame-unreal_splash_bypass) | `frame.unreal_splash_bypass` | Steam Frame patches | 1 |
 | [Unreal: thumb follows the capacitive touches](#frame-unreal_thumb_touch) | `frame.unreal_thumb_touch` | Steam Frame patches | 7 |
@@ -100,6 +100,7 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [VrApi → OpenXR bridge](#frame-vrapi_bridge) | `frame.vrapi_bridge` | Steam Frame patches | 3 |
 | [Quiet Meta's VrApi loader (OpenXR games)](#frame-vrapi_stub) | `frame.vrapi_stub` | Steam Frame patches | 2 |
 | [OpenGL ES: shader fixes (Vulkan layer under Zink)](#frame-zink_shader_fix) | `frame.zink_shader_fix` | Steam Frame patches | 1 |
+| [Unique controller action names](#adapter-action_dedup) | `adapter.action_dedup` | Game settings |  |
 | [Pointer start](#adapter-aim_forward) | `adapter.aim_forward` | Game settings |  |
 | [Pointer angle](#adapter-aim_pitch) | `adapter.aim_pitch` | Game settings |  |
 | [Pointer turn](#adapter-aim_yaw) | `adapter.aim_yaw` | Game settings |  |
@@ -645,7 +646,7 @@ Plays the game's videos on the Frame's video hardware, so 4K and 8K video runs s
 - `frame.hw_video_decode` · also for 2D apps
 - **Changes:** Install only: written on the Frame when the game is installed; the APK isn't changed.
 - **Suggested (on):** The game plays video through Android's decoders (MediaCodec, ExoPlayer or VLC): decode it on the Frame's hardware.
- **Catalog games (19):** 4XVR Video Player, AugmentedEmpire, Batman: Arkham Shadow, Battlemarked, Dance Central, Eye of the Temple, Fruit Ninja, Ghost Town and 11 more.
+- **Catalog games (20):** 4XVR Video Player, AugmentedEmpire, Batman: Arkham Shadow, Battlemarked, Dance Central, Eye of the Temple, Fruit Ninja, Ghost Town and 12 more.
 - **Source:** [patches/frame/hw_video_decode.py](../src/frameport/patches/frame/hw_video_decode.py)

 > Decodes the game's videos on the Frame's hardware video decoder instead of Android's software decoders, which stutter or fall behind with 4K/8K video (for example video players, Batman: Arkham Shadow's cutscenes). Adds FramePort's codec plugin (OMX.frameport.avc/hevc/vp9.decoder) to this game's container only; the APK isn't changed. When the hardware is busy (for example Steam's own hardware video decoding is on) the video is decoded in software as before.
@@ -1092,7 +1093,7 @@ Starts Unreal games without re-checking their data file (they'd seem to hang on
 - `frame.unreal_skip_obb_check` · also for 2D apps
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Unreal checks the OBB's contents before starting (bVerifyOBBOnStartUp); on the Frame a failed or slow check can't be seen and the game seems to hang.
- **Catalog games (5):** Dance Central, Kill It With Fire VR, MacacoVR, Maestro, Ragnarock.
+- **Catalog games (6):** Dance Central, Kill It With Fire VR, MacacoVR, Maestro, Ragnarock, Scared By Squares.
 - **Suggested by launch-test signatures:**
  - `unreal-obb-check-stuck` (fatal): The game stays on Unreal's OBB check screen (DownloaderActivity), which the Frame doesn't show, and never starts VR (for example Contractors, GitHub #159).
 - **Source:** [patches/frame/unreal_obb_check.py](../src/frameport/patches/frame/unreal_obb_check.py)
@@ -1228,6 +1229,20 @@ Repairs shaders that hang the graphics chip at certain effects, from the game's

 Settings of FrameBridge, FramePort's OpenXR layer inside every converted Quest game. Most can be changed on the Frame later without a rebuild (game page → Game settings).

+### <a id="adapter-action_dedup"></a>Unique controller action names
+
+Stops games from dropping back to the home environment at start because two of their controller actions share a name (for example Scared By Squares). Leave it on.
+
+- `adapter.action_dedup`
+- **Changes:** Game setting: stored in the build and on the Frame (settings.conf); can be changed without a rebuild.
+- **Suggested:** not automatically; set on the game page (Customize), by a recipe or after a launch test.
+- **Options:**
+  - Value: int, default `1`.
+  - Game settings → Troubleshooting → "Unique controller action names" (advanced).
+- **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
+
+> Gives a controller action whose name already exists in its action set a free name ("turn" -&gt; "turn_2"). The Frame's runtime accepts duplicate names but then can't load the game's input manifest and treats the game as closed: black, then the home environment while the game keeps running with sound (for example Scared By Squares, whose Unreal project has an action and an axis both called Turn; GitHub #323).
+
 ### <a id="adapter-aim_forward"></a>Pointer start

 Moves where the pointer starts, forward or back.
@@ -116,6 +116,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Video player / app finds no local videos; MediaProvider "Requested path /home/steamos/... doesn't appear under ..." | Lepton's /sdcard is a symlink to a host path, so Android's media index rejects every file | upload in the Files tab (Videos = /sdcard/Movies) and browse folders in the app |
 | Batman: Arkham Shadow closes during smoke-bomb effects; later input-tree corruption | Meta XR Audio Wwise deletes queued metadata still referenced by the current audio frame, then writes through the stale pointer | FrameBridge automatically retires metadata after current-frame references disappear, for the verified AArch64 SDK build only; see [AUDIO_METADATA.md](AUDIO_METADATA.md) |
 | Game stays on a loading or "Waiting" box although it reached FOCUSED; log `FrameBridge: xrEndFrame failed -25` then no more `pacing:` lines (for example PowerWash Simulator on some Frames, GitHub #39) | The eye image rect ends a few pixels past its swapchain (Unity rounds the swapchain width, the runtime's recommended size differs per Frame); SteamVR rejects every frame with XR_ERROR_SWAPCHAIN_RECT_INVALID | FrameBridge clamps every projection/quad image rect to its swapchain (`rect_clamp`, default on since 0.11.0; log `rect_clamp: view N image rect clamped`): rebuild + reinstall the game |
+| Black flash, then the SteamVR home environment while the game keeps running (sound plays); vrserver.txt `[OpenXR] SetXrInputConfig failed. Failed to load manifest provided by SetXrInputConfig`, then the app "has exited" and reconnects as `VRApplication_OpenXRInstance`; headless launch tests pace at 10 fps (for example Scared By Squares, GitHub #323) | Two controller actions in one action set share a name (Unreal: an action mapping and an axis mapping both called "Turn"). The Frame's runtime accepts the duplicate but can't load the input manifest it builds and drops the app as a scene app | FrameBridge gives the later duplicate a free name (`action_dedup`, default on; log `action_dedup: action "turn" ("Turn") already exists in its set: created as "turn_2"`): rebuild + reinstall the game. `input_diag=1` logs every action set and action the game creates |
 | Unity game (OVRPlugin, GLES or Vulkan) crashes ~10 s in: `FrameBridge: xrCreateSwapchain … faces=6 … result=-2`, OVRPlugin `CreateSwapchain for eye 0: 0x0, 0 stages`, then render-thread SIGSEGV in memset ← libOVRPlugin ← `ovrp_EndFrame4` (libgallium/ANR follow; for example Budget Cuts Ultimate, GitHub #107); triage `cube-swapchain-refused` | The game shows a cube-map layer (OVROverlay cubemap); the Frame's runtime has no cube layers and refuses cube swapchains (XR_ERROR_RUNTIME_FAILURE); OVRPlugin doesn't check and writes into the image list it never got | FrameBridge `cube_standin` (default on): a refused cube swapchain is served as a GL cube map in the game's context or a device-local Vulkan cube image transitioned to COLOR_ATTACHMENT_OPTIMAL, and its layers are dropped (log `cube_standin: runtime refused …`): rebuild + reinstall. Vulkan path covers UNDERDOGS (GitHub #296); host-tested, headset verification pending |
 | Game (Unity, GLES) freezes, `zink: DEVICE LOST` | multisampled render-to-texture hangs the GPU | `frame.unity_no_msaa`; if it persists: unfixable → PC version |
 | Unreal GLES game crashes ~3 s after start: `Fatal signal 11 … fault addr 0x10000 in tid … (RHIThread)`, `#01 … libgallium_dri.so` (GitHub #83 Star Wars Pinball VR, triage `unreal-msrtt-crash`) | Unreal's mobile MSAA renders through multisampled render-to-texture; Zink's `find_rp_state` then indexes `rendering_state_cache[6]` one past its end (sample count ≥ 32) and calls a junk hash function (0x10000). Mesa bug (no bounds check) | `frame.unreal_gl_shim` (GL shim with `gl_hide_msrtt`, multiview kept for Unreal: Unreal 4.25 only enables multiview with GL_OVR_multiview, GL_OVR_multiview2 **and** GL_OVR_multiview_multisampled_render_to_texture, so the shim keeps the last one visible for Unreal and maps glFramebufferTextureMultisampleMultiviewOVR to the single-sampled glFramebufferTextureMultiviewOVR; log `multiview multisampled render-to-texture (N samples) drawn single-sampled`) |
@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// action_dedup (session_fixes.c, GitHub #323): a free name for a controller action whose name or localized name is
+// already used in its action set. No OpenXR types, so the host tests can compile it.
+#pragma once
+#include <stdio.h>
+#include <string.h>
+
+static size_t action_name_len(const char *s, size_t max) {  // strnlen (not in plain C11)
+    size_t n = 0;
+    while (n < max && s[n]) ++n;
+    return n;
+}
+
+// taken(ctx, name, localized): 1 when `name` or `localized` is already used in the set.
+typedef int (*action_name_taken_fn)(void *ctx, const char *name, const char *localized);
+
+// Writes "<name>_N" / "<localized> N" (N = 2..99, the first pair not taken; cut to fit name_size/localized_size
+// including the terminator) and returns 1; 0 when the original names are free or no free pair exists.
+static int action_unique_names(const char *name, const char *localized, action_name_taken_fn taken, void *ctx,
+                               char *out_name, size_t name_size, char *out_localized, size_t localized_size) {
+    if (!taken(ctx, name, localized) || name_size < 8 || localized_size < 8) return 0;
+    for (int n = 2; n < 100; ++n) {
+        char suffix[8], lsuffix[8];
+        snprintf(suffix, sizeof(suffix), "_%d", n);
+        snprintf(lsuffix, sizeof(lsuffix), " %d", n);
+        size_t keep = action_name_len(name, name_size - 1);
+        if (keep + strlen(suffix) > name_size - 1) keep = name_size - 1 - strlen(suffix);
+        snprintf(out_name, name_size, "%.*s%s", (int)keep, name, suffix);
+        size_t lkeep = action_name_len(localized, localized_size - 1);
+        if (lkeep + strlen(lsuffix) > localized_size - 1) lkeep = localized_size - 1 - strlen(lsuffix);
+        snprintf(out_localized, localized_size, "%.*s%s", (int)lkeep, localized, lsuffix);
+        if (!taken(ctx, out_name, out_localized)) return 1;
+    }
+    return 0;
+}
@@ -113,6 +113,10 @@ static void snap_on_enumerate(XrSwapchain handle, uint32_t count, const XrSwapch
 static void snap_on_acquire(XrSwapchain handle, uint32_t index);
 static void snap_end_frame(const XrFrameEndInfo *info);
 static int frame_balance = 0;  // end a still-open frame before the next xrBeginFrame
+// diagnostics (headless launch tests, GitHub #323): report shouldRender=TRUE from xrWaitFrame. Without a worn headset the
+// session never becomes VISIBLE, the runtime answers shouldRender=FALSE and engines that honour it (Unreal's OpenXR
+// plugin) submit no layers at all, so a headless run never exercises the game's real frame submission.
+static int force_render = 0;
 static int frame_begins, frame_discarded, frame_ends, frame_balanced;  // per pacing period (layer_debug)
 static int frame_open;
 static int sc_acquires, sc_waits, sc_releases, sc_wait_fails;  // per pacing period (layer_debug)  // drop XrCompositionLayerColorScaleBiasKHR (the runtime's color pass)
@@ -120,6 +124,7 @@ static int controller_fix = 1;
 static int swapchain_fix = 1;
 static int cube_standin = 1;  // cube swapchains the runtime refuses: served by the adapter (cube_standin.c)
 static int rect_clamp = 1;
+static int action_dedup = 1;  // rename duplicate action names in a set (session_fixes.c; GitHub #323)
 static int pose_consistency = 0;  // repeat xrLocateViews queries for one display time get the same poses (GitHub #8)  // clamp submitted image rects to their swapchain (SteamVR rejects a 1 px overrun)
 static int pose_time_fix;   // poses asked for at CLOCK_MONOTONIC "now" or far in the past: at XrTime "now" (pose_time.c)
 static int pose_debug;      // diagnostics: requested pose times vs the predicted display time (pose_time.c)
@@ -178,6 +183,7 @@ static void read_settings(const char *path) {
        if (sscanf(line, "strip_color_bias=%f", &value) == 1) strip_color_bias = (int)value;
        if (sscanf(line, "fade_quad=%f", &value) == 1) fade_quad = value > 0 ? (int)value : 0;
        if (sscanf(line, "frame_balance=%f", &value) == 1) frame_balance = value != 0;
+        if (sscanf(line, "force_render=%f", &value) == 1) force_render = value != 0;
        if (sscanf(line, "snapshot=%f", &value) == 1) snapshot = value > 0 ? (int)value : 0;
        if (sscanf(line, "flip_dump=%f", &value) == 1) flip_dump = value > 0 ? (int)value : 0;
        if (sscanf(line, "gl_error_clear=%f", &value) == 1) gl_error_clear = value != 0;
@@ -185,6 +191,7 @@ static void read_settings(const char *path) {
        if (sscanf(line, "swapchain_fix=%f", &value) == 1) swapchain_fix = value != 0;
        if (sscanf(line, "cube_standin=%f", &value) == 1) cube_standin = value != 0;
        if (sscanf(line, "rect_clamp=%f", &value) == 1) rect_clamp = value != 0;
+        if (sscanf(line, "action_dedup=%f", &value) == 1) action_dedup = value != 0;
        if (sscanf(line, "pose_consistency=%f", &value) == 1) pose_consistency = value != 0;
        if (sscanf(line, "pose_debug=%f", &value) == 1) pose_debug = value != 0;
        if (sscanf(line, "pose_time_fix=%f", &value) == 1) pose_time_fix = value != 0;
@@ -277,6 +284,7 @@ static void initialize(void) {
    if (fade_quad) LOG("per-game: fade_quad=%d (colour-scale fades drawn as a black quad%s)", fade_quad,
                       fade_quad > 1 ? "; the layer's own scale removed" : "");
    if (frame_balance) LOG("per-game: frame_balance=1 (an open frame is ended before the next one begins)");
+    if (force_render) LOG("per-game: force_render=1 (xrWaitFrame reports shouldRender=TRUE; diagnostics)");
    if (eye_debug || release_wait) LOG("per-game: eye_debug=%d release_wait=%d log_file=%s", eye_debug, release_wait,
                                       log_file ? path : "none");
    if (controller_models && *process && !strchr(process, '/')) render_model_init(process);
@@ -1414,6 +1422,16 @@ XRAPI_ATTR XrResult XRAPI_CALL xrWaitFrame(XrSession session, const XrFrameWaitI
        pose_time_display(state->predictedDisplayTime);
        pose_time_note_offset((long long)(state->predictedDisplayTime - mono));
        if (layer_debug) debug_aim_vs_grip(state->predictedDisplayTime);
+        // shouldRender changes (a few): a game that submits no layers while the runtime says not to render shows
+        // nothing, e.g. Unreal's OpenXR plugin in a headless launch test
+        static int last_should_render = -1, should_render_logged;
+        if ((int)state->shouldRender != last_should_render && should_render_logged < 12) {
+            ++should_render_logged;
+            LOG("xrWaitFrame: shouldRender=%d period=%.2f ms%s", (int)state->shouldRender,
+                state->predictedDisplayPeriod / 1e6, force_render && !state->shouldRender ? " (force_render: reported as 1)" : "");
+        }
+        last_should_render = (int)state->shouldRender;
+        if (force_render) state->shouldRender = XR_TRUE;
    }
    return result;
 }
@@ -2199,7 +2217,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetInstanceProcAddr(XrInstance instance, const
    if (layer_debug) HOOK_AS(xrGetActionStateBoolean, hook_xrGetActionStateBoolean)
    if (layer_debug || aim_correction_on() || profile_remap || input_diag || proximity_emul)
        HOOK_AS(xrSuggestInteractionProfileBindings, hook_xrSuggestInteractionProfileBindings)
-    if (proximity_emul) HOOK_AS(xrCreateAction, hook_xrCreateAction)
+    if (action_dedup || proximity_emul || input_diag) HOOK_AS(xrCreateAction, hook_xrCreateAction)
    if (layer_debug || aim_correction_on()) {
        HOOK_AS(xrCreateActionSpace, hook_xrCreateActionSpace)
    }
@@ -107,8 +107,6 @@ static const char *diag_perf_detail(XrPerfSettingsDomainEXT domain, XrPerfSettin
 }
 DIAG_CHECKED(xrStringToPath, (XrInstance instance, const char *path, XrPath *out), (instance, path, out),
             diag_name_detail(path))
-DIAG_CHECKED(xrCreateAction, (XrActionSet set, const XrActionCreateInfo *info, XrAction *action), (set, info, action),
-             diag_name_detail(info ? info->actionName : NULL))
 DIAG_CHECKED(xrAttachSessionActionSets, (XrSession session, const XrSessionActionSetsAttachInfo *info),
             (session, info), NULL)
 DIAG_CHECKED(xrPerfSettingsSetPerformanceLevelEXT,
@@ -116,11 +114,46 @@ DIAG_CHECKED(xrPerfSettingsSetPerformanceLevelEXT,
             (session, domain, level), diag_perf_detail(domain, level))
 #undef DIAG_CHECKED

+// Every action set and action the game creates, with its localized name: SteamVR turns them into an input manifest and
+// drops a game whose manifest it can't load ("SetXrInputConfig failed. Failed to load manifest" in vrserver.txt; the
+// app then counts as exited: home environment while the game keeps running, GitHub #323). Bytes outside printable
+// ASCII and the JSON specials " and \ are written as \xNN.
+static const char *diag_escaped(const char *in, char *out, size_t size) {
+    size_t used = 0;
+    for (const unsigned char *c = (const unsigned char *)(in ? in : "(null)"); *c && used + 5 < size; ++c) {
+        int special = *c < 0x20 || *c > 0x7e || *c == '"' || *c == '\\';
+        used += (size_t)(special ? snprintf(out + used, size - used, "\\x%02x", *c)
+                                 : snprintf(out + used, size - used, "%c", *c));
+    }
+    out[used] = 0;
+    return out;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL diag_xrCreateActionSet(XrInstance instance, const XrActionSetCreateInfo *info,
+        XrActionSet *set) {
+    PFN_xrCreateActionSet fn = (PFN_xrCreateActionSet)lookup(instance, "xrCreateActionSet");
+    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
+    XrResult result = fn(instance, info, set);
+    char a[XR_MAX_ACTION_SET_NAME_SIZE * 4 + 8], b[XR_MAX_LOCALIZED_ACTION_SET_NAME_SIZE * 4 + 8];
+    if (info)
+        LOG("input_diag: action set \"%s\" (\"%s\") priority %u -> %d", diag_escaped(info->actionSetName, a, sizeof(a)),
+            diag_escaped(info->localizedActionSetName, b, sizeof(b)), info->priority, (int)result);
+    return result;
+}
+// Called by session_fixes.c's hook_xrCreateAction (hooked whenever input_diag is on), with the names it created.
+static void diag_log_action(const XrActionCreateInfo *info, XrResult result) {
+    char a[XR_MAX_ACTION_NAME_SIZE * 4 + 8], b[XR_MAX_LOCALIZED_ACTION_NAME_SIZE * 4 + 8];
+    if (info)
+        LOG("input_diag: action \"%s\" (\"%s\") type %d, %u subaction path(s) -> %d",
+            diag_escaped(info->actionName, a, sizeof(a)), diag_escaped(info->localizedActionName, b, sizeof(b)),
+            (int)info->actionType, info->countSubactionPaths, (int)result);
+    if (XR_FAILED(result)) diag_call_failed("xrCreateAction", result, diag_name_detail(info ? info->actionName : NULL));
+}
+
 // xrGetInstanceProcAddr: our wrapper for `name`, NULL if it isn't one of ours.
 static PFN_xrVoidFunction input_diag_hook(const char *name) {
 #define DIAG(fn) if (!strcmp(name, #fn)) return (PFN_xrVoidFunction)diag_##fn;
    DIAG(xrStringToPath)
-    DIAG(xrCreateAction)
+    DIAG(xrCreateActionSet)
    DIAG(xrAttachSessionActionSets)
    DIAG(xrPerfSettingsSetPerformanceLevelEXT)
 #undef DIAG
@@ -328,12 +328,68 @@ static int touch_has(const char *path) {
 // rest touched; index (proximity_emul=2) = trigger touched. Only when the runtime lacks the extension itself.
 static XrAction thumb_proximity_action, trigger_proximity_action;

+// ---------------------------------------------------------------- duplicate action names (action_dedup)
+// OpenXR requires action names and localized names to be unique within an action set (XR_ERROR_NAME_DUPLICATED), but
+// the Frame's runtime accepts duplicates and then can't load the input manifest it builds from them: vrserver logs
+// "SetXrInputConfig failed. Failed to load manifest", drops the app's connection and treats it as exited, so the
+// headset goes back to the home environment while the game keeps running with sound (GitHub #323, Scared By Squares:
+// Unreal's OpenXR plugin creates "turn" twice, from an action mapping and an axis mapping of the same name). The
+// game only uses the handles, so a later duplicate is created under a free name ("turn_2", "Turn 2").
+#include "action_names.h"
+#define DEDUP_MAX 512
+static struct { XrActionSet set; char name[XR_MAX_ACTION_NAME_SIZE]; char localized[XR_MAX_LOCALIZED_ACTION_NAME_SIZE]; }
+    dedup_seen[DEDUP_MAX];
+static int dedup_count;
+static pthread_mutex_t dedup_lock = PTHREAD_MUTEX_INITIALIZER;
+
+static int dedup_taken(void *ctx, const char *name, const char *localized) {  // caller holds dedup_lock
+    XrActionSet set = *(XrActionSet *)ctx;
+    for (int i = 0; i < dedup_count; ++i)
+        if (dedup_seen[i].set == set && (!strcmp(dedup_seen[i].name, name) || !strcmp(dedup_seen[i].localized, localized)))
+            return 1;
+    return 0;
+}
+
+// Fills `out` (a copy of `info`) with free names when `info`'s are taken in `set`; 1 if it did.
+static int dedup_rename(XrActionSet set, const XrActionCreateInfo *info, XrActionCreateInfo *out,
+                        char name[XR_MAX_ACTION_NAME_SIZE], char localized[XR_MAX_LOCALIZED_ACTION_NAME_SIZE]) {
+    if (!action_unique_names(info->actionName, info->localizedActionName, dedup_taken, &set, name,
+                             XR_MAX_ACTION_NAME_SIZE, localized, XR_MAX_LOCALIZED_ACTION_NAME_SIZE))
+        return 0;
+    *out = *info;
+    memcpy(out->actionName, name, XR_MAX_ACTION_NAME_SIZE);
+    memcpy(out->localizedActionName, localized, XR_MAX_LOCALIZED_ACTION_NAME_SIZE);
+    return 1;
+}
+
+static void dedup_note(XrActionSet set, const XrActionCreateInfo *info) {  // caller holds dedup_lock
+    if (dedup_count >= DEDUP_MAX) return;
+    dedup_seen[dedup_count].set = set;
+    snprintf(dedup_seen[dedup_count].name, XR_MAX_ACTION_NAME_SIZE, "%s", info->actionName);
+    snprintf(dedup_seen[dedup_count].localized, XR_MAX_LOCALIZED_ACTION_NAME_SIZE, "%s", info->localizedActionName);
+    ++dedup_count;
+}
+
 static XRAPI_ATTR XrResult XRAPI_CALL hook_xrCreateAction(XrActionSet set, const XrActionCreateInfo *info,
        XrAction *action) {
    PFN_xrCreateAction fn = (PFN_xrCreateAction)lookup(active_instance, "xrCreateAction");
    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
-    XrResult r = fn(set, info, action);
-    if (XR_SUCCEEDED(r) && info && action) {  // OVRPlugin's action names
+    XrActionCreateInfo renamed;
+    char name[XR_MAX_ACTION_NAME_SIZE], localized[XR_MAX_LOCALIZED_ACTION_NAME_SIZE];
+    const XrActionCreateInfo *use = info;
+    if (action_dedup && info) pthread_mutex_lock(&dedup_lock);
+    if (action_dedup && info && dedup_rename(set, info, &renamed, name, localized)) {
+        LOG("action_dedup: action \"%s\" (\"%s\") already exists in its set: created as \"%s\" (\"%s\")",
+            info->actionName, info->localizedActionName, name, localized);
+        use = &renamed;
+    }
+    XrResult r = fn(set, use, action);
+    if (action_dedup && info) {
+        if (XR_SUCCEEDED(r)) dedup_note(set, use);
+        pthread_mutex_unlock(&dedup_lock);
+    }
+    if (input_diag) diag_log_action(use, r);
+    if (proximity_emul && XR_SUCCEEDED(r) && info && action) {  // OVRPlugin's action names
        if (!strcmp(info->actionName, "hand_thumb_proximity")) thumb_proximity_action = *action;
        else if (!strcmp(info->actionName, "hand_trigger_proximity")) trigger_proximity_action = *action;
        else return r;
@@ -1,4 +1,9 @@
 {
+ "adapter.action_dedup": {
+  "anchor": "adapter-action_dedup",
+  "title": "Unique controller action names",
+  "group": "Game settings"
+ },
 "adapter.aim_forward": {
  "anchor": "adapter-aim_forward",
  "title": "Pointer start",
@@ -638,6 +638,7 @@
 "Getting FramePort ready": "",
 "GiB": "",
 "GitHub issue opened": "",
+ "Gives a controller action whose name already exists in its action set a free name (\"turn\" -> \"turn_2\"). The Frame's runtime accepts duplicate names but then can't load the game's input manifest and treats the game as closed: black, then the home environment while the game keeps running with sound (for example Scared By Squares, whose Unreal project has an action and an axis both called Turn; GitHub #323).": "",
 "Gives older Quest games a newer version of Meta's VR plugin that can be converted.": "",
 "GL shim (frame.gl_shim): shader inputs declared as integers (int/uint, ivecN/uvecN) whose vertex data the game set up with glVertexAttribPointer (as floats) are set up again with glVertexAttribIPointer before each draw. Qualcomm's Quest driver read the raw integers anyway; the Frame's GL driver converts them to floats, so skinned models using bone indices vanish (for example BlazeRush's car bodies and controllers; Klownicle's guide, GitHub #57). Comes from a game's recipe.": "",
 "GL shim (frame.gl_shim): vertex shaders whose source contains every '|'-separated text compute in highp: whole-word mediump becomes highp on every line without the words in, out or uniform (the shader's interface keeps its precision). For effects that draw streaks or flashes from mediump rounding on the Frame (for example BlazeRush's particles: in uvec2 inBoneIndices;|uniform InstanceData|void main()). Pair it with a new shader cache name if the game caches compiled programs. Comes from a game's recipe.": "",
@@ -1483,6 +1484,7 @@
 "Stops a start-up crash in Stress Level Zero games (for example BONELAB).": "",
 "Stops bHaptics from asking for a Bluetooth permission the Frame doesn't have (the game would freeze on its loading screen).": "",
 "Stops Epic Online Services from retrying its login keychain forever (the game would never finish starting).": "",
+ "Stops games from dropping back to the home environment at start because two of their controller actions share a name (for example Scared By Squares). Leave it on.": "",
 "Stops games from hanging when their eye picture is a little too big (for example PowerWash Simulator). Leave it on.": "",
 "Stops Meta's audio library from reporting to Meta (only matters on PC emulators).": "",
 "Stops Meta's old VR library from closing the game at start (for example Jurassic World Aftermath).": "",
@@ -1672,6 +1674,7 @@
 "Uninstall. ": "",
 "Uninstalled {title}": "",
 "Uninstalled {title} and deleted its files on this PC ({size})": "",
+ "Unique controller action names": "",
 "Unity frame loop: wait for skipped frames": "",
 "Unity's built-in Oculus frame loop (frame.unity_oculus_check): before each frame wait, wait up to 50 ms for the last waited frame to begin and skip the wait if it doesn't. Fixes a freeze at the first scene switch (for example Sniper Elite VR); in other games it can make loading screens stutter.": "",
 "Unity's built-in Oculus frame loop (frame.unity_oculus_check): don't pass Unity's physics-step pose update on, so the hands use the frame's display-time poses. Fixes hands trailing the controllers in some games (for example Sniper Elite VR); in others it makes the hands lag (for example BattleSisters).": "",
@@ -174,6 +174,11 @@ SETTINGS = [
     "Keeps every submitted image rect inside its swapchain. Unity can size the eye area a few pixels past the image "
     "on some Frames; SteamVR then rejects every frame (xrEndFrame -25, XR_ERROR_SWAPCHAIN_RECT_INVALID) and the game "
     "stops drawing (for example PowerWash Simulator stuck at \"Waiting\")."),
+    ("action_dedup", "int", 1, "Unique controller action names",
+     "Gives a controller action whose name already exists in its action set a free name (\"turn\" -> \"turn_2\"). "
+     "The Frame's runtime accepts duplicate names but then can't load the game's input manifest and treats the game "
+     "as closed: black, then the home environment while the game keeps running with sound (for example Scared By "
+     "Squares, whose Unreal project has an action and an axis both called Turn; GitHub #323)."),
    ("swap_eyes", "int", 0, "Swap eyes", "Swap left/right views (diagnostic)."),
    ("strip_depth", "int", 0, "Strip depth layers", "Remove XR_KHR_composition_layer_depth chains (diagnostic)."),
    ("mutable_fix", "int", 0, "Mutable swapchain fix", "Experimental Vulkan mutable-format workaround."),
@@ -395,6 +400,10 @@ UI: dict[str, dict] = {
    "rect_clamp": dict(group="troubleshooting", level="advanced", label="Keep pictures in bounds",
                help="Stops games from hanging when their eye picture is a little too big (for example "
                     "PowerWash Simulator). Leave it on.", control=("switch",)),
+    "action_dedup": dict(group="troubleshooting", level="advanced", label="Unique controller action names",
+                help="Stops games from dropping back to the home environment at start because two of their "
+                     "controller actions share a name (for example Scared By Squares). Leave it on.",
+                control=("switch",)),
    "gl_hide_msrtt": dict(group="troubleshooting", level="advanced", label="Hide fast anti-aliasing (OpenGL ES)",
                help="For Unity games that crash when they turn on anti-aliasing (for example The Room "
                     "VR).", control=("switch",)),
@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// action_dedup (native/adapter/action_names.h, GitHub #323): free names for duplicate controller actions.
+#include <assert.h>
+#include <string.h>
+#include "action_names.h"
+
+static const char *used[8][2];
+static int nused;
+
+static int taken(void *ctx, const char *name, const char *localized) {
+    (void)ctx;
+    for (int i = 0; i < nused; ++i)
+        if (!strcmp(used[i][0], name) || !strcmp(used[i][1], localized)) return 1;
+    return 0;
+}
+
+int main(void) {
+    char name[64], localized[128];
+    used[nused][0] = "turn"; used[nused++][1] = "Turn";   // Scared By Squares: action mapping "Turn"...
+    assert(!action_unique_names("jump", "Jump", taken, NULL, name, sizeof(name), localized, sizeof(localized)));
+    // ...and an axis mapping "Turn": same action name and localized name
+    assert(action_unique_names("turn", "Turn", taken, NULL, name, sizeof(name), localized, sizeof(localized)));
+    assert(!strcmp(name, "turn_2") && !strcmp(localized, "Turn 2"));
+    // only the localized name clashes: still renamed (the runtime's manifest needs both unique)
+    assert(action_unique_names("turn_axis", "Turn", taken, NULL, name, sizeof(name), localized, sizeof(localized)));
+    assert(!strcmp(name, "turn_axis_2") && !strcmp(localized, "Turn 2"));
+    // the next free number
+    used[nused][0] = "turn_2"; used[nused++][1] = "Turn 2";
+    assert(action_unique_names("turn", "Turn", taken, NULL, name, sizeof(name), localized, sizeof(localized)));
+    assert(!strcmp(name, "turn_3") && !strcmp(localized, "Turn 3"));
+    // a name at the length limit is cut so the suffix fits
+    char longname[64];
+    memset(longname, 'a', 63);
+    longname[63] = 0;
+    used[nused][0] = longname; used[nused++][1] = "Long";
+    assert(action_unique_names(longname, "Long", taken, NULL, name, sizeof(name), localized, sizeof(localized)));
+    assert(strlen(name) == 63 && !strcmp(name + 61, "_2") && !strcmp(localized, "Long 2"));
+    return 0;
+}
@@ -0,0 +1,33 @@
+"""action_dedup (FrameBridge, GitHub #323): duplicate controller action names get a free name."""
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from frameport.patches import base
+from frameport.patches.settings import UI, adapter_settings
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_duplicate_action_names_get_free_names(tmp_path):
+    cc = shutil.which("cc") or shutil.which("gcc") or shutil.which("clang")
+    if not cc or os.name == "nt":
+        pytest.skip("needs a POSIX host C compiler")
+    binary = tmp_path / "action-names-test"
+    subprocess.run([cc, "-std=c11", "-Wall", "-Wextra", "-Werror", "-I", str(ROOT / "native/adapter"),
+                    str(ROOT / "tests/fixtures/src/action_names_test.c"), "-o", str(binary)], check=True)
+    subprocess.run([str(binary)], check=True)
+
+
+def test_action_dedup_is_on_by_default():
+    base.load_all()
+    p = base.REGISTRY["adapter.action_dedup"]
+    assert p.default == 1  # the Frame's runtime drops a game with duplicate names: always fix it
+    assert adapter_settings({"adapter.action_dedup": {"value": 0}})["action_dedup"] == 0
+    assert UI["action_dedup"]["control"] == ("switch",)
+    src = (ROOT / "native/adapter/frame_adapter.c").read_text()
+    assert 'sscanf(line, "action_dedup=%f"' in src
+    assert "if (action_dedup || proximity_emul || input_diag) HOOK_AS(xrCreateAction, hook_xrCreateAction)" in src
@@ -111,6 +111,14 @@ def test_space_warp_is_a_question_not_an_automatic_fix():
    assert "space-warp-used" not in {f.id for f in triage(off + log, "RUNNING", PKG).findings}


+def test_eye_depth_swapchain_is_not_space_warp():
+    # GitHub #323: Unreal's OpenXR plugin submits eye depth (XR_KHR_composition_layer_depth) in a D24S8 (129)
+    # swapchain of the eye size; only space warp's motion-vector swapchain (97) shows that space warp is used
+    log = START + fb("17:39:02", "xrCreateSwapchain 1728x1728 format=129 samples=1 array=2 faces=1 usage=0x22 "
+                                 "flags=0x0 result=0")
+    assert "space-warp-used" not in {f.id for f in triage(log, "RUNNING", PKG).findings}
+
+
 def test_gpu_hang_from_kernel_lines():
    kernel = "kernel: 1790000000.0 steamos kernel: msm_dpu: [drm:a6xx_hangcheck] hangcheck detected gpu lockup\n"
    r = triage(START, "UNKNOWN", PKG, kernel=kernel)