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/delete | USaveGame and the Slot API |
| Not blocking the game thread, callbacks | Async Save and Load |
| Per-player saves, settings profiles, split-screen | ULocalPlayerSaveGame |
Raw bytes, FArchive, memory buffers | FArchive and Binary Serialization |
| Snapshotting actors, world state, transforms | Actor State with UPROPERTY(SaveGame) |
A USTRUCT needing its own Serialize; old saves breaking after a patch | USTRUCT Custom Serialization, Versioning |
| Console/cloud storage, slot enumeration, save UI | ISaveGameSystem and Platform Storage |
Project settings, user options, .ini, JSON, compression | Config, Settings, and File Formats |
| Slot manager subsystem, metadata, thumbnails, checksums, encryption | Save 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):
| Call | Signature |
|---|---|
CreateSaveGameObject | USaveGame* (TSubclassOf<USaveGame> SaveGameClass) (:1124) |
SaveGameToSlot | bool (USaveGame*, const FString& SlotName, const int32 UserIndex) (:1167) |
LoadGameFromSlot | USaveGame* (const FString& SlotName, const int32 UserIndex) (:1211) |
DoesSaveGameExist | bool (const FString& SlotName, const int32 UserIndex) (:1175) |
DeleteGameInSlot | bool (const FString& SlotName, const int32 UserIndex) (:1231) |
SaveGameToMemory | bool (USaveGame*, TArray<uint8>& OutSaveData) (:1134) |
LoadGameFromMemory | USaveGame* (const TArray<uint8>& InSaveData) (:1182) |
SaveDataToSlot | bool (const TArray<uint8>&, const FString& SlotName, const int32 UserIndex) (:1143) |
LoadDataFromSlot | bool (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
阅读完整来源 ↗