Display-vs-value custom dropdown options + UI mode parity docs
Extend the EditableInterface with two new BlueprintNativeEvents so property combos can show human-friendly labels while storing technical values: - GetCustomOptionsWithValuesForProperty returns TArray<FPS_Editor_PropertyOption> where each pair carries a DisplayName (shown in the combo) and a Value (written to the property via ImportText). Wins over the legacy flat-string variant when non-empty. Ideal for TSubclassOf / TSoftClassPtr properties driven by a DataTable lookup where the stored value is a class path. - GetCurrentDisplayForProperty lets the actor authoritatively resolve the DisplayName from the current stored value, for cases where the automatic reverse lookup (normalize class path, exact-match) isn't reliable — e.g. several Values collapse to the same label, or the format is user-specific. UI refresh now asks the actor first, then falls back to a normalized match (strips the `TypeName'...'` wrapper from ExportText output so it compares apples to apples with a plain /Game/Path.X_C string). Same logic duplicated across both widget implementations (MainWidget and MainWidget_Legacy) since the project can switch UI mode at runtime. The new CLAUDE.md rule makes that requirement explicit. Also documented in CLAUDE.md: - Editor-vs-gameplay execution boundary: which interface methods fire where, including the gotcha that OnEditorPropertyChanged *does* fire in gameplay on the server when the timeline animates a property. - UI modes: keep all MainWidget* implementations in lockstep to avoid the "I edited the file but nothing changed" class of bug. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
62
CLAUDE.md
62
CLAUDE.md
@@ -10,6 +10,68 @@ Unreal Engine 5.5 project with runtime editor plugin (PS_Editor). The plugin ena
|
||||
- **Serialization**: JSON via Json/JsonUtilities modules (FJsonObjectConverter)
|
||||
- **Input**: Enhanced Input system (AZERTY: arrows + A/Q movement, E/R/T modes)
|
||||
|
||||
## Editor vs. Gameplay execution boundary — CRITICAL
|
||||
|
||||
The plugin runs in two distinct modes and it's essential never to leak editor-only code
|
||||
into the gameplay runtime loaded via `UPS_Editor_SceneLoader::LoadScene` (standalone).
|
||||
|
||||
### Editor runtime mode
|
||||
Activated when the `APS_Editor_PlayerController` + `APS_Editor_HUD` + `UPS_Editor_MainWidget*`
|
||||
stack is created (typical during authoring — the user is in the runtime editor).
|
||||
- `UPS_Editor_SceneLoader::bIsEditorModeActive == true`
|
||||
- The HUD widget drives property editing, catalogue spawn, save/load, simulate, timeline
|
||||
- Interface methods called **only** by the widget (never in gameplay):
|
||||
- `GetCustomOptionsForProperty` / `GetCustomOptionsWithValuesForProperty` / `GetCurrentDisplayForProperty`
|
||||
- `OnEditorModeChanged`, `OnEditorTick`
|
||||
- `OnEditorNeedsReinit`, `OnEditorNeedsRespawn`
|
||||
|
||||
### Gameplay mode
|
||||
The project (PROSERVE) loads a scenario via `UPS_Editor_SceneLoader::LoadScene` from a GameMode
|
||||
BeginPlay, without ever instantiating the editor PlayerController / HUD / widget.
|
||||
- `UPS_Editor_SceneLoader::bIsEditorModeActive == false`
|
||||
- Actors spawn, their properties are applied from JSON, `OnPropertiesLoaded` fires once
|
||||
- The timeline subsystem auto-plays if the scenario has tracks, driven **server-side only**
|
||||
|
||||
### Interface methods that fire in BOTH modes
|
||||
- `OnPropertiesLoaded` — after every scene load, editor or gameplay (applied once post-spawn)
|
||||
- `OnEditorPropertyChanged` — fires both in editor (on UI edit via `ApplyPropertyFromUI`) AND
|
||||
in gameplay (on server when the timeline applies a new keyframe value via
|
||||
`TimelineSubsystem::ApplyTrackAtTime`). Despite the name, the "Editor" refers to the
|
||||
PS_Editor plugin — the event is the canonical hook for "a property changed at runtime".
|
||||
In gameplay only the **server** invokes it; client-side reaction must go through
|
||||
`ReplicatedUsing=OnRep_X` RepNotify on the replicated property.
|
||||
|
||||
### Rule when adding new features
|
||||
- Anything tied to property panel UI (new interface method, new widget logic, dropdown
|
||||
helpers, etc.) lives in the widget only — no extra work to scope it out of gameplay
|
||||
- Anything added to the `SceneLoader::LoadScene` path runs in gameplay and must handle
|
||||
`NM_Client`, replication, and server-authority correctly (the timeline subsystem is the
|
||||
reference pattern)
|
||||
- Expensive BP implementations of editor-UI interface methods (DataTable lookups, class
|
||||
resolution, etc.) can stay expensive — they never run outside the authoring session
|
||||
|
||||
### How to guard code that could run in either mode
|
||||
```cpp
|
||||
if (UPS_Editor_SceneLoader::IsInEditorMode())
|
||||
{
|
||||
// editor-only behaviour
|
||||
}
|
||||
```
|
||||
or gate on `bIsCurrentlyLoading` to skip BP init during JSON restore.
|
||||
|
||||
## UI Modes — IMPORTANT for widget changes
|
||||
|
||||
The runtime editor ships with **multiple widget implementations** that must all stay in sync:
|
||||
- `PS_Editor_MainWidget.cpp/.h` — modern UMG-based widget (primary target long-term)
|
||||
- `PS_Editor_MainWidget_Legacy.cpp/.h` — Slate-only legacy widget (**currently active** as of April 2026)
|
||||
- `PS_Editor_MainWidget_UMG.cpp/.h` — UMG variant
|
||||
|
||||
The user can switch between them via a `UIMode` setting. At any given time only one is running, but the project keeps all three compiled.
|
||||
|
||||
**Rule:** when changing any behavior inside a widget (new interface calls, new property row logic, new UI controls, bug fixes in RebuildDynamicProperties / ApplyPropertyFromUI / RefreshDynamicPropertyValues, etc.), **apply the change to ALL widget implementations at the same time**. Otherwise the user's current UIMode gets the fix and the others don't — the "it's like you didn't change anything" bug.
|
||||
|
||||
Symptom that the wrong widget was edited: logs you added don't appear in the Output Log despite the build being clean and the DLL being correctly loaded. Always grep for the function name across all `PS_Editor_MainWidget*.cpp` files before assuming a single edit is sufficient.
|
||||
|
||||
## Naming Conventions
|
||||
- All plugin files and classes use the `PS_Editor_` prefix (e.g., `PS_Editor_GameMode`, `PS_Editor_Pawn`)
|
||||
- Code and comments in English
|
||||
|
||||
Reference in New Issue
Block a user