strategy

Unreal Engine 5 Framework Strategy

Pre-Analysis Agent

This strategy declares a pre-analysis agent via the pre_analysis_agent frontmatter field. When structure-analyzer loads this strategy during Phase 1 initialization, it will invoke the declared agent (ue-deps-navigator) before per-file analysis begins. No manual invocation required — the core orchestrator handles discovery.

Framework Detection (self-declared)

This framework pack declares its own detection signatures. The core /analyze init gate scans all installed code-analysis-{framework}:strategy packs and applies each pack's framework_detection signatures to decide which framework pack(s) to load.

framework_detection:
  name: unreal
  requires_language: cpp              # framework packs may target a specific language
  min_signatures: 2                    # need this many signatures to match
  signatures:
    - kind: file_exists
      pattern: "**/*.Build.cs"
    - kind: file_exists
      pattern: "**/*.uproject"
    - kind: file_exists
      pattern: "**/*.uplugin"
    - kind: source_macro
      macros: ["UCLASS", "USTRUCT", "UENUM", "UPROPERTY", "UFUNCTION"]
    - kind: source_include
      patterns: ["GameFramework/", "Engine/GameInstance.h"]
    - kind: source_macro
      macros: ["IMPLEMENT_PRIMARY_GAME_MODULE", "IMPLEMENT_MODULE"]

Signature kinds (canonical):

• file_exists: matches if any file matches the given pattern (glob) in the repo
• source_macro: matches if any listed macro is used in source files (grep-able via GitNexus or shell)
• source_include: matches if any listed include pattern appears in source files

Additional Exclusions

Add to the C++ language strategy exclusions:

• *.generated.h — UE Header Tool output
• *.gen.cpp — UE auto-generated code
• Intermediate/** — build artifacts
• Plugins/**/Binaries/** — plugin binaries

Entry Points

UE5 has no user-level int main(). Game project entry points are:

Class Type	Role	Detection
UGameInstance subclass	Game-wide lifecycle	Inheritance from UGameInstance
AGameModeBase subclass	Per-mode game logic	Inheritance from AGameModeBase
APlayerController subclass	Player input/control	Inheritance from APlayerController
AGameStateBase subclass	Shared game state	Inheritance from AGameStateBase
Module registration file	Module init	IMPLEMENT_PRIMARY_GAME_MODULE macro

Virtual Entry Points (canonical)

The following YAML block is the authoritative declaration consumed by phase3-trace. Surrounding prose is clarifying commentary only.

virtual_entry_points:
  - name: BeginPlay
    kind: lifecycle
  - name: EndPlay
    kind: lifecycle
  - name: Tick
    kind: lifecycle
  - name: PostInitializeComponents
    kind: lifecycle
  - name: OnConstruction
    kind: lifecycle
  - name: SetupInputComponent
    kind: lifecycle
  - name: OnPossess
    kind: lifecycle
  - name: OnUnPossess
    kind: lifecycle
  - name: Init
    kind: lifecycle
  - name: Shutdown
    kind: lifecycle
  - name: InitGame
    kind: lifecycle
  - name: NativeConstruct
    kind: lifecycle
  - name: NativeDestruct
    kind: lifecycle
  - name: NativeTick
    kind: lifecycle
  - name: NativeInitializeAnimation
    kind: lifecycle
  - name: NativeUpdateAnimation
    kind: lifecycle

reflection_markers:
  - UFUNCTION(BlueprintCallable)
  - UFUNCTION(BlueprintPure)
  - UFUNCTION(BlueprintImplementableEvent)
  - UFUNCTION(BlueprintNativeEvent)
  - UFUNCTION(Exec)
  - UFUNCTION(Server)
  - UFUNCTION(Client)
  - UFUNCTION(NetMulticast)

Virtual Entry Points

UE5 is event-driven. Engine-called virtual overrides are virtual entry points.

Actor / Component Lifecycle

• BeginPlay() — game start or spawn
• EndPlay(const EEndPlayReason::Type) — destruction
• Tick(float DeltaTime) — every frame
• PostInitializeComponents() — after component init
• OnConstruction() — editor/spawn construction

PlayerController

• SetupInputComponent() — input binding setup
• OnPossess(APawn*) / OnUnPossess() — pawn ownership

GameInstance

• Init() — instance initialization
• OnStart() — game start
• Shutdown() — shutdown

GameMode

• InitGame() — game initialization
• PreLogin() / PostLogin() — player connection
• HandleStartingNewPlayer() — new player handling

Widget (UMG)

• NativeConstruct() — widget creation
• NativeDestruct() — widget destruction
• NativeTick(const FGeometry&, float) — every frame

AnimInstance

• NativeInitializeAnimation() — animation init
• NativeUpdateAnimation(float) — every frame update

Event Handler Patterns

Functions registered via these patterns are virtual entry points:

Delegate Binding

• AddDynamic(this, &UClass::Handler) — dynamic delegate
• BindUObject(this, &UClass::Handler) — general delegate
• AddUObject(this, &UClass::Handler) — multicast delegate

Input Binding

• BindAction("Name", IE_Pressed, this, &UClass::Handler) — legacy input
• EnhancedInputComponent->BindAction(Action, ETriggerEvent::Triggered, this, &UClass::Handler) — Enhanced Input

Timer Callback

• GetWorldTimerManager().SetTimer(Handle, this, &UClass::Handler, Rate)
• GetWorldTimerManager().SetTimerForNextTick(this, &UClass::Handler)

Dead Code Exclusions

Do NOT flag as dead code:

UE Reflection / Blueprint

• UFUNCTION(BlueprintCallable) / UFUNCTION(BlueprintPure) — callable from Blueprint
• UFUNCTION(BlueprintImplementableEvent) — implemented in Blueprint
• UFUNCTION(BlueprintNativeEvent) — C++ default + Blueprint override
• UFUNCTION(Exec) — console command
• UPROPERTY(EditAnywhere) / UPROPERTY(BlueprintReadWrite) — editor/BP access

UE Networking (RPC)

• UFUNCTION(Server) — server RPC
• UFUNCTION(Client) — client RPC
• UFUNCTION(NetMulticast) — multicast RPC
• *_Implementation() suffix — RPC/BlueprintNativeEvent body
• *_Validate() suffix — RPC validation

UE Engine Hooks

• PostEditChangeProperty() — editor property change hook
• PostLoad() — asset load hook
• Serialize() — custom serialization
• GetLifetimeReplicatedProps() — network replication setup
• Constructor with FObjectInitializer param — CDO construction
• StartupModule() / ShutdownModule() — module lifecycle
• IMPLEMENT_MODULE / IMPLEMENT_PRIMARY_GAME_MODULE

.Build.cs Config Analysis

When file_role == "config" and file is .Build.cs:

• Parse PublicDependencyModuleNames and PrivateDependencyModuleNames
• Flag unnecessary public dependencies that should be private
• Cross-reference with mcp__ue-deps-mcp__get_module_info(name={module_name}) for module-level dependency consistency

Dependency Analysis Notes

Normal Hub Patterns

• Project-wide header (e.g., {ProjectName}.h): precompiled header, very high dependency count is normal. Exclude from hub warnings or annotate separately.
• *.generated.h: UHT output. Exclude from dependency graph.
• .Build.cs: module-level dependencies. Treat as separate layer from C++ include dependencies.

UE-Specific Coupling

• Manager classes with high dependency count is common in UE (when Subsystem pattern not used)
• Cast<>, FindComponentByClass<> — runtime type lookups invisible in static dependency graph. Flag as hidden coupling.

Phase 1 Adjustments (Headers)

Add to C++ declaration analysis:

• UCLASS / USTRUCT / UENUM specifier analysis (Blueprintable, BlueprintType, Abstract)
• UPROPERTY classification: EditAnywhere / VisibleAnywhere / BlueprintReadWrite / Replicated
• UFUNCTION call path classification: BlueprintCallable / Server / Client / NetMulticast / Exec

Phase 2 Adjustments (Implementation)

Add to C++ implementation analysis:

• Super:: call audit — lifecycle overrides missing parent call is a bug
• IsValid() / nullptr check patterns for UObject pointers
• NewObject<>() / CreateDefaultSubobject<>() usage context (constructor vs runtime)
• GetWorld() null check — nullptr possible in editor/CDO context
• GC safety: raw UObject pointers not covered by UPROPERTY() → dangling pointer risk

Hooks Provided

This plugin provides the following extension hooks. The core pipeline registers these at init time and invokes them at the corresponding pipeline stages.

Hook Point	Skill Name	Invocation Context
after-analyze-file	code-analysis-unreal:after-analyze-file	Per-file, after mirror document is written. Triggers sub-hooks: tick-audit, replication-audit
after-phase3-trace	code-analysis-unreal:after-phase3-trace	After Phase 3 flow analysis completes
phase4-docs	code-analysis-unreal:phase4-docs	During Phase 4 documentation generation

Static Tools

Supplements the code-analysis-cpp:strategy tool list — the C++ pack runs first. The UE5 pack contributes no additional static tools: ue-deps is handled exclusively by the pre_analysis_agent (ue-deps-navigator) in Step 0 of the Phase 1 pipeline, before static tool dispatch. Placing it here would cause a second redundant invocation.

static_tools:
  phase1: []
  phase2: []
  phase3: []
  phase4: []

Installation: uv tool install <plugin-root>/code-analysis-unreal/cli.