Known Issues

Tracked footguns the bridge plugin currently has. Each entry lists the platform / UE version where it bites, the symptom, and the recommended workaround.

UE 5.8

The plugin is compile-verified on both UE 5.7 and 5.8. The UE version field below marks where each issue was observed (mostly 5.7). Status of the two macOS engine regressions on UE 5.8 (PIE-tested 2026-06-25 on UE 5.8.0):

• Transparent pixels render opaque — still broken on 5.8 (not fixed; the Slate/Metal compositor still drops CEF surface transparency). See Transparent HUD.
• CEF keyboard focus — not yet re-tested on 5.8; assume still present until confirmed.

To re-check on 5.8, run ./launch-project.sh (the SampleProject defaults to 5.8). Issues whose cause is architectural (Slate clip, content-only Live Coding) are assumed to persist on 5.8.

• Mac UE 5.7 chat keyboard cannot focus
  • Symptom
  • Cause
  • Workaround
• macOS runtime-mounted display-only HUD steals focus
  • Symptom
  • Cause
  • Workaround
• Slate clip cannot round-corner the CEF layer
  • Symptom
  • Cause
  • Workaround
• SampleProject Live Coding fails
  • Symptom
  • Workaround
• useUnrealState envelope auto-unwrap
  • Symptom
  • Cause
  • Workaround

Mac UE 5.7 chat keyboard cannot focus

• Platform: macOS
• UE version: 5.7
• Tags: mac, ue57, keyboard, chat, focus

Symptom

Pressing a key while the CEF browser layer is focused does not produce keystrokes inside the HUD. Both Slate-focus injection and Carbon window capture fail.

Cause

Engine regression in 5.7's WebBrowser widget on macOS. Slate focus is not forwarded to CEF; the focused element does not receive WM_CHAR equivalents.

Workaround

Use click-to-type: route a button/click event from BP to the React side, then have React open an <input> with autoFocus. Do not invest in Keyboard Binding wiring on Mac UE 5.7 — it will not work.

macOS runtime-mounted display-only HUD steals focus

• Platform: macOS
• UE version: 5.7
• Tags: mac, ue57, focus, wasd, runtime, display-only, cursor

Symptom

Mounting a display-only Web HUD layer (bInteractive = false) at runtime in a possessed game world — e.g. opening a panel on a keypress — makes the OS mouse cursor appear and drops held movement keys: WASD stop registering until you release and re-press. Layers mounted at BeginPlay are unaffected.

Cause

On macOS the native web view (SAppleWebBrowserWidget, an SViewport subclass) grabs Slate keyboard focus to itself once, on its first Tick after construction ("to keep parity with CEF"). This is engine behavior and bypasses bInteractive = false, which only governs the Slate/UMG layer — SupportsKeyboardFocus() on the native widget is hardcoded true and it is not ours to subclass. The game viewport losing focus runs PlayerController->FlushPressedKeys() (held WASD drop) and shows the cursor. BeginPlay mounts escape it because pawn possession re-focuses the viewport right after; a runtime add has no such re-focus.

Workaround

Don't Add/Remove a display-only layer at runtime. Mount it once at BeginPlay (its one-time grab is absorbed under possession), then show/hide it with Set Web HUD Visible — toggling visibility reuses the existing browser, so the native grab never re-fires. (Before Set Web HUD Visible existed, the same effect came from resizing the same-Name layer to ~0 via an in-place Add Web HUD update — no reconstruction.) Tracked under #65.

Slate clip cannot round-corner the CEF layer

• Platform: all
• UE version: 5.7
• Tags: ui, rounded, clip, slate, css

Symptom

Wrapping WBP_WebHUD in a Retainer Box / Clip to Bounds with a rounded mask does not produce rounded HUD corners — the CEF texture renders square inside the clip.

Cause

CEF texture is composited outside the Slate clip mask.

Workaround

Apply border-radius in HTML/CSS on the root element of your React app. The CEF layer is already transparent by default, so a rounded root naturally produces rounded HUD corners.

SampleProject Live Coding fails

• Platform: macOS
• UE version: 5.7
• Tags: sampleproject, live-coding, content-only, build

Symptom

Live Coding > Compile fails immediately in SampleProject because the project itself is content-only (no Source/ directory of its own).

Workaround

Build the plugin headlessly and relaunch the Editor:

UBT_PATH=/path/to/UnrealBuildTool
"$UBT_PATH" UnrealReactBridge Mac Development -Project="$(pwd)/SampleProject/SampleProject.uproject"
# then restart UnrealEditor

useUnrealState envelope auto-unwrap

• Platform: all
• UE version: any
• Tags: sdk, useUnrealState, envelope, typed-payload

Symptom

Plain window.addEventListener('player:hp', e => …) receives e.detail = { value: 75 }, but useUnrealState('player:hp', 0) returns 75 directly. Mixing the two confuses readers.

Cause

useUnrealState unwraps the typed-payload envelope { value: T } automatically. Raw listeners do not.

Workaround

Prefer useUnrealState for streamed scalar values; reserve raw listeners for events whose payload is not a {value} envelope (e.g. PushMap, PushRaw).