ue5-cpp-gameplay ยท diff
git:20260302.11fee6c to git:20260303.c186337
76 added, 7 removed. Audit A to A.
---
name: ue5-cpp-gameplay
description: UE5.6/UE5.7 gameplay C++ implementation for Actors, Components, DataAssets, and gameplay logic. Use when requests ask to write .h/.cpp pairs, expose UPROPERTY/UFUNCTION to Blueprint, use GameplayTags, or build reusable component-based systems.
---
# Quick Start
- Confirm target class type (`AActor`, `UActorComponent`, `UObject`, `USaveGame`, etc.).
- Define required Blueprint-facing API before implementation.
- Output both header and source files together.
+ # UE5.7 API Anchors
+ - Reflection and UObject anchors:
+ - `UCLASS`, `USTRUCT`, `UENUM`, `UINTERFACE`, `GENERATED_BODY()`
+ - `UPROPERTY(...)`, `UFUNCTION(...)`
+ - Core gameplay type anchors:
+ - `AActor`, `UActorComponent`, `UDataAsset`, `UGameInstanceSubsystem`
+ - `TObjectPtr<>` in headers and `TSubclassOf<>` for class references
+ - Replication anchors:
+ - `GetLifetimeReplicatedProps(...)`
+ - `DOREPLIFETIME(...)` in `Net/UnrealNetwork.h`
+ - `ReplicatedUsing=OnRep_*`, `UFUNCTION(Server/Client/NetMulticast, ...)`
+ - Gameplay tag anchors:
+ - `FGameplayTag`, `FGameplayTagContainer`
+ - explicit tag request/match checks with safe fallback behavior
+
+ # Implementation Stage Contract
+ - Every gameplay C++ task must define:
+ - Public header API surface (Blueprint/API visibility)
+ - Private runtime implementation path (`.cpp`)
+ - Ownership/lifetime model (constructor, init, teardown)
+ - Network authority rules (single-player only or replicated flow)
+ - Validation method (compile assumptions, usage examples, edge-case behavior)
+ - If any item is missing, the implementation spec is incomplete.
+
# Workflow
+ ## 1) Type and File Shape
- Create type declarations with Unreal macros and UE5 pointer conventions (`TObjectPtr` in headers).
- - Define Blueprint API (`BlueprintCallable`, `BlueprintPure`) and categories.
- - Implement runtime logic in `.cpp` with explicit includes and safe guards.
- - Add replication hooks/RPC stubs when multiplayer behavior is requested.
- - Add `GameplayTag` usage only with explicit tag names and fallback checks.
+ - Produce paired `.h` and `.cpp` with forward declarations in header and concrete includes in source.
+ - Keep class responsibility narrow and reusable.
+ ## 2) Public API Design
+ - Define Blueprint API (`BlueprintCallable`, `BlueprintPure`, categories, metadata) before implementation.
+ - Expose minimal callable surface; keep helper methods non-UFUNCTION unless needed.
+ - Declare clear input/output contracts and failure behavior.
+
+ ## 3) Runtime Implementation
+ - Implement logic in `.cpp` with null checks, authority guards, and explicit branch behavior.
+ - Keep tick usage opt-in; prefer event-driven updates.
+ - Handle initialization order (`BeginPlay`, `InitializeComponent`, or subsystem init) explicitly.
+
+ ## 4) Replication and RPC (When Needed)
+ - Add replicated properties and `OnRep_*` handlers only for true client-visible state.
+ - Register properties in `GetLifetimeReplicatedProps(...)` with `DOREPLIFETIME(...)`.
+ - Use server-authoritative RPC entry points for client requests.
+
+ ## 5) GameplayTags and Data-Driven Hooks
+ - Use `FGameplayTag`/`FGameplayTagContainer` with explicit tag names.
+ - Validate required tags at runtime and provide fallback for missing tags.
+ - Prefer DataAsset-driven config for tunables over hard-coded constants.
+
+ ## 6) Validation Output
+ - Ensure output includes both files and required includes.
+ - Confirm Blueprint exposure, replication behavior, and error-handling paths are documented.
+ - Provide usage snippet or invocation flow when behavior is non-trivial.
+
# Constraints
- Always provide matching `.h` and `.cpp` when creating a class.
- Use non-deprecated APIs compatible with UE5.6/UE5.7.
- Keep includes minimal; use forward declarations in headers.
- Avoid hardcoded asset paths unless explicitly requested.
+ - Prefer `TObjectPtr<>` in UPROPERTY object references in headers.
+ - Keep server-authoritative checks explicit for any network-affecting gameplay action.
# Failure Handling
- - If API usage differs by minor engine patch, use the stable UE5.6/UE5.7-compatible call and document fallback.
- - If a Blueprint exposure request is ambiguous, expose minimal callable surface and mark extension points.
- - If ownership or authority is unclear in networked logic, default to server-authoritative flow.
+ - Symptom: class compiles but is missing from Blueprint.
+ - Locate: missing `BlueprintType`/`Blueprintable`/`BlueprintCallable` metadata.
+ - Fix: add required reflection specifiers and regenerate project files/build.
+ - Symptom: unresolved symbol or include cycles.
+ - Locate: header include graph and forward declaration misuse.
+ - Fix: move heavy includes to `.cpp`, keep forward declarations in headers.
+ - Symptom: replicated property does not update on clients.
+ - Locate: `GetLifetimeReplicatedProps(...)` and actor/component replication flags.
+ - Fix: register with `DOREPLIFETIME(...)`, ensure owning actor replicates.
+ - Symptom: `OnRep_*` never fires.
+ - Locate: property write path and net role.
+ - Fix: mutate on server authority path and verify property actually changes.
+ - Symptom: RPC callable but ignored at runtime.
+ - Locate: RPC specifier and call site authority.
+ - Fix: enforce client->server request path and server-side validation.
+ - Symptom: GameplayTag logic silently fails.
+ - Locate: invalid tag names or missing tag config.
+ - Fix: validate tags on startup and guard with explicit fallback behavior.
+
+ # UE5.6 / UE5.7 Compatibility Notes
+ - Reflection, replication, and GameplayTag APIs above are stable across UE5.6 and UE5.7.
+ - Favor stable core APIs over editor-only helpers when runtime behavior is required.
# Escalation
- Escalate when user asks for plugin/module-level refactor beyond a single gameplay class.
- Escalate when solution needs custom engine source modifications.