ue5-cpp-gameplay

---
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."
license: "MIT"
---

# 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).
- 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
- 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.