From 98de4dff6f60377c6cd2d29b2664ba7809b6359a Mon Sep 17 00:00:00 2001
From: "j.foucher" <j.foucher@polymorph.fr>
Date: Mon, 27 Apr 2026 12:38:03 +0200
Subject: [PATCH] Document PIE-only nav quirk: AI testing requires Standalone
 Game
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Several attempts were made to fix a PIE-specific RecastNavMesh registration
failure that occurs when the editor's "Play" button calls OpenLevel(BaseLevel)
from inside a PIE session — the level's RecastNavMesh ends up pending-kill
and UE silently substitutes an empty AbstractNavData fallback, breaking AI
pathfinding. Workarounds tried (and reverted): cascading re-registrations
through RegisterNavData / OnInitializeActors / AddNavigationSystemToWorld /
Build / SpawnMissingNavigationData; intermediate transition map; duplicated
BaseLevel sublevel suffixed _default. None worked — the cause is internal
to PIE's OpenLevel handling.

Standalone Game and packaged builds initialize the nav system correctly,
so production is unaffected. Document the workflow so future contributors
don't waste time chasing this PIE-only bug.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 747e34e..d228123 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -57,6 +57,29 @@ if (UPS_Editor_SceneLoader::IsInEditorMode())
     // editor-only behaviour
 }
 ```
+
+### Known PIE-only AI quirk — use Standalone for AI testing
+
+When the editor's "Play" button calls `UGameplayStatics::OpenLevel(BaseLevel)` from a PIE
+session, the BaseLevel's `RecastNavMesh` actor ends up pending-kill at registration time
+(UE logs `RegistrationFailed_DataPendingKill` ×2 and silently spawns an empty
+`AbstractNavData-Default` as fallback). All `FindPathAsync` / `ProjectPointToNavigation`
+queries return empty after that — pathfinding looks broken with no error.
+
+This is **PIE-specific**:
+- Standalone Game (Window → Standalone) — works correctly
+- Packaged builds — work correctly
+- PIE direct on BaseLevel (no editor map / OpenLevel involved) — works correctly
+- PIE on editor map → click Play (OpenLevel transition inside PIE) — broken
+
+Multiple workaround attempts have all failed (cascading re-registrations through
+`RegisterNavData` / `OnInitializeActors` / `AddNavigationSystemToWorld` / `Build` /
+`SpawnMissingNavigationData`; transition map; duplicated sublevel suffixed `_default`).
+The cause is internal to PIE's OpenLevel handling and cannot be fixed from the plugin
+side without engine modifications.
+
+**Workflow:** for AI iteration, run **Standalone Game** instead of PIE. It exercises the
+exact same code path as packaged builds.
 or gate on `bIsCurrentlyLoading` to skip BP init during JSON restore.
 
 ## UI Modes — IMPORTANT for widget changes