跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
其他技能

ue-serialization-savegames

Use when implementing save/load, player progress persistence, slot management, or binary serialization in Unreal Engine C++. Also use when the user mentions 'save game', 'USaveGame', 'SaveGameToSlot', 'AsyncSaveGameToSlot', 'LoadGameFromSlot', 'DoesSaveGameExist', 'DeleteGameInSlot', 'ULocalPlayerSaveGame', 'UPROPERTY(SaveGame)', 'FArchive', 'FMemoryWriter', 'FCustomVersion', 'save versioning', 'migrate old saves', 'save file corrupted', 'UDeveloperSettings', or 'GConfig'. For asset references, see ue-data-assets-tables; for work off the game thread, see ue-async-threading; for streamed level state, see ue-world-level-streaming.

quodsoler · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add quodsoler/unreal-engine-skills --skill ue-serialization-savegames

技能说明


name: ue-serialization-savegames description: "Use when implementing save/load, player progress persistence, slot management, or binary serialization in Unreal Engine C++. Also use when the user mentions 'save game', 'USaveGame', 'SaveGameToSlot', 'AsyncSaveGameToSlot', 'LoadGameFromSlot', 'DoesSaveGameExist', 'DeleteGameInSlot', 'ULocalPlayerSaveGame', 'UPROPERTY(SaveGame)', 'FArchive', 'FMemoryWriter', 'FCustomVersion', 'save versioning', 'migrate old saves', 'save file corrupted', 'UDeveloperSettings', or 'GConfig'. For asset references, see ue-data-assets-tables; for work off the game thread, see ue-async-threading; for streamed level state, see ue-world-level-streaming." metadata: version: "2.0.0" engine: "5.8"

UE Serialization & Save Games

Target engine: UE 5.8. APIs below are verified against the 5.8 headers; older forms are listed under "Deprecated — do not use".

This skill covers persisting game state: USaveGame objects through UGameplayStatics, the platform ISaveGameSystem, FArchive binary serialization, UPROPERTY(SaveGame) actor snapshots, save versioning, and config/settings storage. Build.cs modules: Core, CoreUObject, Engine; add DeveloperSettings to PublicDependencyModuleNames for UDeveloperSettings, and Json + JsonUtilities to PrivateDependencyModuleNames for FJsonObjectConverter.

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
A save object, slot names, save/load/deleteUSaveGame and the Slot API
Not blocking the game thread, callbacksAsync Save and Load
Per-player saves, settings profiles, split-screenULocalPlayerSaveGame
Raw bytes, FArchive, memory buffersFArchive and Binary Serialization
Snapshotting actors, world state, transformsActor State with UPROPERTY(SaveGame)
A USTRUCT needing its own Serialize; old saves breaking after a patchUSTRUCT Custom Serialization, Versioning
Console/cloud storage, slot enumeration, save UIISaveGameSystem and Platform Storage
Project settings, user options, .ini, JSON, compressionConfig, Settings, and File Formats
Slot manager subsystem, metadata, thumbnails, checksums, encryptionSave system architecture

USaveGame and the Slot API

USaveGame is an abstract UObject declared in GameFramework/SaveGame.h:23. Subclass it, add UPROPERTY fields, and route everything through UGameplayStatics.

UGameplayStatics::SaveGameToSlot writes every non-transient UPROPERTY — it does not filter on the SaveGame flag (Kismet/GameplayStatics.h:1159). Mark fields Transient to exclude them. The SaveGame specifier only matters for archives with ArIsSaveGame set — see Actor State.

// MySaveGame.h
#pragma once

#include "CoreMinimal.h"
#include "GameFramework/SaveGame.h"
#include "UObject/SoftObjectPath.h"
#include "MySaveGame.generated.h"

USTRUCT(BlueprintType)
struct FMyInventoryItem
{
    GENERATED_BODY()

    UPROPERTY(SaveGame) FName ItemId;
    UPROPERTY(SaveGame) int32 Quantity = 0;
};

UCLASS(BlueprintType)
class MYGAME_API UMySaveGame : public USaveGame
{
    GENERATED_BODY()

public:
    UPROPERTY(SaveGame) int32 SaveVersion = 0;   // bump alongside MySaveStage::Latest
    UPROPERTY(SaveGame) float PlayerHealth = 100.f;
    UPROPERTY(SaveGame) FVector LastCheckpoint = FVector::ZeroVector;
    UPROPERTY(SaveGame) TArray<FMyInventoryItem> InventoryItems;
    UPROPERTY(SaveGame) TMap<FName, int32> AbilityLevels;

    /** Store asset references as paths; a hard pointer cannot round-trip through a file. */
    UPROPERTY(SaveGame) FSoftObjectPath LastEquippedWeapon;

    /** Excluded from SaveGameToSlot because it is Transient. */
    UPROPERTY(Transient) float RuntimeOnlyScratch = 0.f;
};

Slot functions, all static on UGameplayStatics (Kismet/GameplayStatics.h):

CallSignature
CreateSaveGameObjectUSaveGame* (TSubclassOf<USaveGame> SaveGameClass) (:1124)
SaveGameToSlotbool (USaveGame*, const FString& SlotName, const int32 UserIndex) (:1167)
LoadGameFromSlotUSaveGame* (const FString& SlotName, const int32 UserIndex) (:1211)
DoesSaveGameExistbool (const FString& SlotName, const int32 UserIndex) (:1175)
DeleteGameInSlotbool (const FString& SlotName, const int32 UserIndex) (:1231)
SaveGameToMemorybool (USaveGame*, TArray<uint8>& OutSaveData) (:1134)
LoadGameFromMemoryUSaveGame* (const TArray<uint8>& InSaveData) (:1182)
SaveDataToSlotbool (const TArray<uint8>&, const FString& SlotName, const int32 UserIndex) (:1143)
LoadDataFromSlotbool (TArray<uint8>&, const FString& SlotName, const int32 UserIndex) (:1191)

Async Save and Load

The async entry points take plain (non-dynamic) delegates, so the bound function must not be a UFUNCTION:

  • DECLARE_DELEGATE_ThreeParams(FAsyncSaveGameToSlotDelegate, const FString&, const int32, bool) (GameplayStatics.h:44)
  • DECLARE_DELEGATE_ThreeParams(FAsyncLoadGameFromSlotDelegate, const FString&, const int32, USaveGame*) (GameplayStatics.h:47)
// MySaveSubsystem.h
#pragma once

#include "CoreMinimal.h"
#include "Subsystems/GameInstanceSubsystem.h"
#include "MySaveSubsystem.generated.h"

class UMySaveGame; class USaveGame;

UCLASS()
class MYGAME_API UMySaveSubsystem : public UGameIn
阅读完整来源 ↗