ue-gameplay-framework
Use when writing or fixing Unreal Engine gameplay framework classes — GameMode, GameState, PlayerController, PlayerState, Pawn, Character, HUD, GameInstance — and the flows they own: player join, pawn spawning, match state, travel and non-GAS damage. Also use when the user mentions 'AGameModeBase', 'PostLogin', 'OnPostLogin', 'RestartPlayer', 'SpawnDefaultPawnFor', 'ChoosePlayerStart', 'match state', 'PossessedBy', 'seamless travel', 'ServerTravel', 'DrawHUD', 'TakeDamage', 'ApplyRadialDamage' or 'create session'. For replication, see ue-networking-replication; for CharacterMovementComponent, see ue-character-movement; for cameras, see ue-gameplay-cameras; for input, see ue-input-system.
quodsoler · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add quodsoler/unreal-engine-skills --skill ue-gameplay-framework技能说明
name: ue-gameplay-framework description: "Use when writing or fixing Unreal Engine gameplay framework classes — GameMode, GameState, PlayerController, PlayerState, Pawn, Character, HUD, GameInstance — and the flows they own: player join, pawn spawning, match state, travel and non-GAS damage. Also use when the user mentions 'AGameModeBase', 'PostLogin', 'OnPostLogin', 'RestartPlayer', 'SpawnDefaultPawnFor', 'ChoosePlayerStart', 'match state', 'PossessedBy', 'seamless travel', 'ServerTravel', 'DrawHUD', 'TakeDamage', 'ApplyRadialDamage' or 'create session'. For replication, see ue-networking-replication; for CharacterMovementComponent, see ue-character-movement; for cameras, see ue-gameplay-cameras; for input, see ue-input-system." metadata: version: "2.0.0" engine: "5.8"
UE Gameplay Framework
Target engine: UE 5.8. APIs below are verified against the 5.8 headers; older forms are listed under "Deprecated — do not use".
The gameplay framework is the set of classes the engine spawns for you — AGameModeBase, AGameStateBase, APlayerController, APlayerState, APawn, ACharacter, AHUD, UGameInstance — plus the join, spawn, match-state, travel and damage flows that wire them together. All of it ships in the Engine module (Classes/GameFramework, Classes/Engine, Classes/Kismet), so Build.cs needs "Core", "CoreUObject", "Engine". Add "EnhancedInput" when binding input, and "OnlineSubsystem" + "OnlineSubsystemUtils" (or "OnlineServicesInterface") only when touching sessions.
Context
Read .agents/ue-project-context.md if it exists (module names, conventions, enabled plugins, GAS/networking setup). Do not stop if it is missing.
Identify the area from the request and the codebase. Ask only when two plausible readings would produce different code.
| Request is about… | Go to |
|---|---|
| Which class holds which data; server vs client presence | Class Responsibility Map |
| Join flow, player starts, pawn spawning, match state | GameMode |
| Replicated scores, timers, connected-player list | GameState |
| Per-player input, RPC bridge, possession, input mode | PlayerController |
| Per-player replicated stats, team, name | PlayerState |
Possessable bodies, PossessedBy, character setup | Pawn and Character |
Canvas overlay, hit boxes, showdebug | HUD |
| Health and damage without Gameplay Abilities | Damage without GAS |
| Data that survives level load, subsystems, accessors | GameInstance |
| Hosting, finding and joining online sessions | Sessions |
ServerTravel, ClientTravel, seamless travel | Travel |
Presence/authority matrix, the full class declarations these snippets come from, lifecycle order and inherited-property tables: references/framework-class-map.md.
Class Responsibility Map
| Class | Lives on | Owns | Never put here |
|---|---|---|---|
AGameModeBase / AGameMode | Server and standalone only; nullptr on clients | Rules, join approval, spawn selection, match state | Anything a client must read |
AGameStateBase / AGameState | Everywhere, replicated | Global replicated state, PlayerArray, server clock | Server-only decisions |
APlayerController | Server holds all; each client holds only its own | Input, RPC bridge, possession, input mode, view target | Data other clients need |
APlayerState | Everywhere (bAlwaysRelevant = true) | Per-player replicated stats, team, name, ping | Input handling, UI state |
APawn / ACharacter | Server plus all clients | The body: collision, mesh, movement | Rules, scoring |
AHUD | Local players only; never on a dedicated server | Canvas overlay, hit boxes, debug display | Replicated data |
UGameInstance | One per process, survives every level load | Session handles, cross-level state, subsystems | Per-match state |
APlayerState sets bReplicates = true and bAlwaysRelevant = true in its constructor, which is why scoreboards work at any distance.
GameMode (Server Only)
AGameModeBase is the minimal base. AGameMode adds the match state machine — use it when you need MatchState::EnteringMap → WaitingToStart → InProgress → WaitingPostMatch → LeavingMap (plus Aborted on failure).
Join sequence (server only)
| Order | Signature to override | Notes |
|---|---|---|
| 1 | virtual void InitGame(const FString& MapName, const FString& Options, FString& ErrorMessage) | Before any player joins; also virtual void InitGameState() |
| 2 | virtual void PreLogin(const FString& Options, const FString& Address, const FUniqueNetIdRepl& UniqueId, FString& ErrorMessage) | Set ErrorMessage non-empty to reject. For a non-blocking credential check override PreLoginAsync(..., const FOnPreLoginCompleteDelegate& OnComplete) (GameModeBase.h:303) instead; it must always call OnComplete (empty string = accept) or the connection hangs, and it must still run the PreLogin checks |
| 3 | virtual APlayerController* Login(UPlayer* NewPlayer, ENetRole InRemoteRole, const FString& Portal, const FString& Options, const FUniqueNetIdRepl& UniqueId, FString& ErrorMessage) | Spawns the APlayerController and its APlayerState |
| 4 | virtual void PostLogin(APlayerController* NewPlayer) | First point where server→client RPCs are safe |
| 5 | virtual void OnPostLogin(AController* NewPlayer) | Protected; runs at the end of PostLogin, last hook before the pawn spawns |
| 6 | virtual void HandleStartingNewPlayer_Implementation(APlayerController* NewPlayer) | BlueprintNativeEvent; calls RestartPlayer unless the player must spectate |
| 7 | virtual void RestartPlayer(AController* NewPlayer) | FindPlayerStart → SpawnDefaultPawnFor → |