Home › Unreal Engine (C++) › Unreal Engine 5 C++ gameplay rules

Unreal Engine 5 C++ gameplay rules

Cursor rules for Unreal Engine 5 gameplay C++: UObject reflection, TObjectPtr, Enhanced Input, components, and Blueprint APIs.

CursorUnreal Engine (C++)

Copy unreal-gameplay.mdc

How to use

Save this as .cursor/rules/unreal-gameplay.mdc in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

---
description: Unreal Engine 5 C++ gameplay conventions
globs: ["Source/**/*.{h,cpp}","**/*.Build.cs"]
alwaysApply: false
---

# Unreal Engine 5 gameplay (C++)

- Reflection macros on everything the engine or Blueprints touch: `UCLASS()`, `USTRUCT(BlueprintType)`, `UPROPERTY(EditAnywhere, BlueprintReadOnly, Category="Combat")`, `UFUNCTION(BlueprintCallable)`. Include `"X.generated.h"` last.
- UObject pointers in headers are `TObjectPtr<T>` members marked `UPROPERTY()` so GC tracks them; use `TWeakObjectPtr` for non-owning references that may die. Never raw `new`/`delete` UObjects; create with `CreateDefaultSubobject` (constructor) or `NewObject`/`SpawnActor`.
- Prefer composition with `UActorComponent`s over deep actor inheritance.
- Input with Enhanced Input: `UInputAction`/`UInputMappingContext` assets, bound in `SetupPlayerInputComponent` via `UEnhancedInputComponent::BindAction`.
- Expose tuning values as `EditDefaultsOnly` properties or Data Assets; designers tune in Blueprint subclasses, C++ owns logic.
- Use `BlueprintImplementableEvent`/`BlueprintNativeEvent` for designer hooks.
- Tick: disable (`PrimaryActorTick.bCanEverTick = false`) unless needed; use timers (`GetWorldTimerManager().SetTimer`) or events.
- Use `UE_LOG(LogMyGame, Warning, TEXT("..."))` with a declared log category; `check`/`ensure` for invariants.
- Gameplay Ability System for abilities/attributes if the project uses it; don't build a parallel system.
- Keep includes minimal in headers (forward declare), include what you use in `.cpp`.

## Done when
The editor target builds (`Build.bat <Project>Editor Win64 Development` or via IDE) with no new warnings, and Live Coding/hot reload is not relied on for header changes (restart the editor).