GameInstance#

概述#

【重点】GameInstance 是 Unreal Engine 中用于管理游戏全局状态和跨关卡数据的核心类。

使用了单例的设计模式，整个游戏运行期间只有一个实例
在 Unreal 中不存在 Unity 的 DontDestroyOnLoad 概念
当需要信息跨越关卡时，就需要使用 GameInstance
更常用的功能是管理玩家的信息和存档等功能

核心概念#

生命周期#

【重点】GameInstance 的生命周期贯穿整个游戏进程：

创建时机：游戏启动时创建，比任何关卡都早
销毁时机：游戏完全退出时才会销毁
跨关卡持久化：切换关卡时不会被销毁，数据得以保留

与 Unity 的对比#

Unity	Unreal Engine
`DontDestroyOnLoad`	`GameInstance`
场景切换时手动设置	自动跨关卡持久化
需要手动管理单例	引擎自动管理单例

主要职责#

1. 跨关卡数据管理#

【重点】GameInstance 最常见的用途是保存需要在多个关卡之间共享的数据：

玩家信息（等级、经验、装备等）
游戏设置（音效、画质等）
存档数据
网络会话信息
全局游戏状态

2. 游戏初始化#

初始化游戏系统
加载配置文件
设置全局参数

3. 网络会话管理#

管理多人游戏的会话
处理网络连接状态
管理服务器列表

结构层级图#

使用方式#

创建自定义 GameInstance#

【技巧】在项目设置中指定自定义的 GameInstance 类：

编辑 -> 项目设置 -> 游戏 -> Game Instance Class
选择或创建继承自 UGameInstance 的 C++ 类或 Blueprint 类

C++ 实现示例#

1
UCLASS()
2
class MYGAME_API UMyGameInstance : public UGameInstance
3
{
4
    GENERATED_BODY()
5

6
public:
7
    UMyGameInstance();
8

9
    // 玩家数据
10
    UPROPERTY(BlueprintReadWrite, Category = "Player")
11
    int32 PlayerLevel = 1;
12

13
    UPROPERTY(BlueprintReadWrite, Category = "Player")
14
    int32 PlayerExperience = 0;
15

16
    // 游戏设置
17
    UPROPERTY(BlueprintReadWrite, Category = "Settings")
18
    float MasterVolume = 1.0f;
19

20
    // 初始化函数
21
    virtual void Init() override;
22
    virtual void Shutdown() override;
23
};

1
void UMyGameInstance::Init()
2
{
3
    Super::Init();
4

5
    // 初始化游戏系统
6
    // 加载存档数据
7
    // 设置全局参数
8
}
9

10
void UMyGameInstance::Shutdown()
11
{
12
    // 保存数据
13
    // 清理资源
14

15
    Super::Shutdown();
16
}

在代码中访问 GameInstance#

【技巧】通过 GetGameInstance() 方法获取 GameInstance 实例：

1
// 在任何 Actor 或 Component 中
2
UMyGameInstance* GameInstance = Cast<UMyGameInstance>(GetGameInstance());
3
if (GameInstance)
4
{
5
    // 访问或修改 GameInstance 的数据
6
    GameInstance->PlayerLevel = 10;
7
    GameInstance->PlayerExperience += 100;
8
}

Blueprint 中使用#

在 Blueprint 中可以通过以下节点访问 GameInstance：

Get Game Instance 节点
直接访问自定义的变量和函数

常见用途#

1. 玩家数据管理#

1
// 保存玩家数据
2
UPROPERTY(BlueprintReadWrite, Category = "Player Data")
3
FPlayerSaveData PlayerData;
4

5
// 加载玩家数据
6
void UMyGameInstance::LoadPlayerData()
7
{
8
    // 从文件或服务器加载数据
9
}
10

11
// 保存玩家数据
12
void UMyGameInstance::SavePlayerData()
13
{
14
    // 保存数据到文件或服务器
15
}

2. 游戏设置管理#

1
// 音效设置
2
UPROPERTY(BlueprintReadWrite, Category = "Settings")
3
float MasterVolume = 1.0f;
4

5
UPROPERTY(BlueprintReadWrite, Category = "Settings")
6
float MusicVolume = 1.0f;
7

8
// 图形设置
9
UPROPERTY(BlueprintReadWrite, Category = "Settings")
10
int32 GraphicsQuality = 2;

3. 关卡切换管理#

1
// 切换关卡时保存当前状态
2
void UMyGameInstance::TravelToLevel(const FString& LevelName)
3
{
4
    // 保存当前关卡的状态
5
    SaveCurrentLevelState();
6

7
    // 切换关卡
8
    GetWorld()->ServerTravel(LevelName);
9
}

生命周期函数#

Init#

【重点】在游戏启动时调用，早于任何关卡的 BeginPlay：

1
virtual void Init() override;

用途：

初始化游戏系统
加载配置文件
设置全局参数
初始化网络会话

Shutdown#

【重点】在游戏完全退出时调用：

1
virtual void Shutdown() override;

用途：

保存游戏数据
清理资源
关闭网络连接

与其他系统的关系#

GameInstance vs GameMode#

特性	GameInstance	GameMode
生命周期	整个游戏进程	单个关卡
数量	全局唯一	每个关卡一个
用途	跨关卡数据	关卡内游戏规则
销毁时机	游戏退出	关卡切换

GameInstance vs GameState#

特性	GameInstance	GameState
作用域	客户端和服务器各自独立	服务器权威，同步到客户端
用途	本地数据管理	游戏状态同步
网络	不参与网络同步	参与网络同步

最佳实践#

1. 数据管理#

【重点】将需要跨关卡的数据放在 GameInstance 中：

✅ 玩家进度、存档数据
✅ 游戏设置（音效、画质）
✅ 全局配置
❌ 关卡特定的数据（应放在 GameMode 或 GameState）

2. 初始化顺序#

【注意】GameInstance 的 Init() 在关卡加载之前调用，注意初始化顺序：

1
void UMyGameInstance::Init()
2
{
3
    Super::Init();
4

5
    // 1. 先初始化基础系统
6
    InitializeCoreSystems();
7

8
    // 2. 再加载数据
9
    LoadGameData();
10

11
    // 3. 最后初始化依赖系统
12
    InitializeDependentSystems();
13
}

3. 内存管理#

【技巧】GameInstance 会一直存在，注意避免内存泄漏：

及时清理不需要的引用
使用弱引用（TWeakPtr）避免循环引用
在 Shutdown() 中清理资源

4. 网络游戏注意事项#

【注意】在多人游戏中：

GameInstance 在客户端和服务器上各自独立
不要将需要同步的数据放在 GameInstance 中
使用 GameState 进行服务器权威的状态管理

调试技巧#

查看 GameInstance#

【技巧】在编辑器中查看当前 GameInstance：

窗口 -> 世界场景设置 -> 游戏实例
或在代码中使用 GetGameInstance() 获取

日志输出#

1
void UMyGameInstance::Init()
2
{
3
    Super::Init();
4

5
    UE_LOG(LogTemp, Warning, TEXT("GameInstance Initialized"));
6
}