GameCore.GameSystem

Game 双端

命名空间 GameCore.GameSystem

public class Game : ICooldownHost, ICooldownOwner, IPropertyOwner, ISyncIdOwner, IPropertyHost, IEventSender, IPropertyOwner<PropertyGame>

属性

SessionId 双端

public long SessionId { get; }

当前游戏会话 ID（可用于支付等需要标识游戏实例的场景）

ProjectId 双端

public string ProjectId { get; }

当前游戏的项目Id，每个星火项目拥有唯一的项目Id

IsDebugTestMode 双端

public static bool IsDebugTestMode { get; }

当前是否为编辑器调试模式。

RuntimeEnvironment 双端

public static GameRuntimeEnvironment RuntimeEnvironment { get; }

当前游戏局的运行时环境，用于区分项目自己的调试、内测和正式数据隔离环境。

备注

运行时环境描述当前游戏局的开放范围和数据隔离标签：debug 为调试环境，test 为项目内测环境， formal 为项目正式环境。它与 DeploymentEnvironment 是两个正交维度；云数据等环境侧数据按完整组合隔离。 Unknown 不代表项目的调试、内测或正式环境；客户端读到该值时应按保守兜底处理。

IsDebugRuntimeEnvironment 双端

public static bool IsDebugRuntimeEnvironment { get; }

当前游戏局是否运行在 debug 调试环境。

IsTestRuntimeEnvironment 双端

public static bool IsTestRuntimeEnvironment { get; }

当前游戏局是否运行在 test 项目内测环境。

IsFormalRuntimeEnvironment 双端

public static bool IsFormalRuntimeEnvironment { get; }

当前游戏局是否运行在 formal 项目正式环境。

DeploymentEnvironment 双端

public static GameDeploymentEnvironment DeploymentEnvironment { get; }

当前游戏 Host 所在的部署环境，用于区分官方平台和编辑器发布通道。

备注

项目开发、测试、发布和迁移流程主要需要区分 alpha 外网公开测试环境和 production 线上生产环境。 master 是部署通道保留值，不作为项目发布、测试或迁移目标。部署环境与 RuntimeEnvironment 是两个正交维度。 Unknown 不代表可发布或可运营的部署环境；客户端读到该值时应按保守兜底处理。

IsMasterDeploymentEnvironment 双端

public static bool IsMasterDeploymentEnvironment { get; }

当前游戏 Host 是否运行在 master 部署通道保留值。

IsAlphaDeploymentEnvironment 双端

public static bool IsAlphaDeploymentEnvironment { get; }

当前游戏 Host 是否运行在 alpha 外网公开测试部署环境。

IsProductionDeploymentEnvironment 双端

public static bool IsProductionDeploymentEnvironment { get; }

当前游戏 Host 是否运行在 production 线上生产部署环境。

RunMode 双端

public static GameRunMode RunMode { get; set; }

当前游戏运行模式。 Normal = 正常（有服务端），ClientOnly = 纯客户端（无服务端）。

IsClientOnly 双端

public static bool IsClientOnly { get; }

是否为纯客户端模式。纯客户端模式下 Entity/Unit/CloudData 不可用。

Instance 双端

public static Game Instance { get; }

Logger 双端

public static ILogger Logger { get; }

MinimumLogLevel 双端

public static LogLevel MinimumLogLevel { get; set; }

Minimum game log level filtered in managed code before formatting and native WASM logging. Use None to disable game logs.

ForgetRunCaptureCallerStackTrace 双端

public static bool ForgetRunCaptureCallerStackTrace { get; set; }

Gets or sets a value indicating whether the caller's StackTrace should be captured when a task is run and subsequently forgotten. Default value is false.

备注

This property can be used to control whether stack trace information is retained for diagnostic purposes when a task is executed and not awaited. Setting this to false may improve performance by avoiding the overhead of capturing the stack trace, but will lose the information of the task's caller stack.

Initialized 双端

public static bool Initialized { get; }

ScriptStarted 双端

public static bool ScriptStarted { get; }

Started 双端

public static bool Started { get; }

Scenes 双端

public static HashSet<Scene> Scenes { get; }

Ended 双端

public static bool Ended { get; }

IsActive 双端

public static bool IsActive { get; }

游戏是否处于活跃状态（已启动且未结束）。

IsTicking 双端

public static bool IsTicking { get; }

游戏 Tick 是否正在运行（活跃且未暂停）。

TickState 双端

public static GameTickState TickState { get; }

TickCurrentFrame 双端

public static int TickCurrentFrame { get; }

ElapsedTime 双端

public static TimeSpan ElapsedTime { get; }

Time 双端

public static TimeSpan Time { get; }

游戏启动后经过的时间。等价于 ElapsedTime。

TotalElapsedTickInMilliseconds 双端

public static int TotalElapsedTickInMilliseconds { get; }

ServerTickOffset 双端

public static int ServerTickOffset { get; set; }

服务端与客户端 TotalElapsedTickInMilliseconds 之间的偏移量。 服务端恒为 0；客户端在收到 ProtoServerTimeSync 后赋值。 offset = serverTime - clientTime

LocalScene 仅客户端

public static Scene LocalScene { get; }

Gets the local player's current scene.

返回： The scene that the local player is currently in.

备注

This is a convenience method that provides easy access to the local player's scene. It's equivalent to calling Player.LocalPlayer.Scene but provides a more direct and semantic way to access the local scene. When the native runtime has not associated the local player with a configured scene, this returns the engine-provided IsEngineFallback scene. A fallback scene does not mean that the client has loaded a map.

SyncId 双端

public int SyncId { get; }

SyncIdType 双端

public SyncIdType SyncIdType { get; }

AggregatorWeakReference 双端

public WeakReference<EventAggregator> AggregatorWeakReference { get; }

GameMode 双端

public GameDataGameMode GameMode { get; }

GameModeLink 双端

public static IGameLink<GameDataGameMode> GameModeLink { get; }

LobbyModeKey 仅服务端

public static string LobbyModeKey { get; }

当前游戏局由创作者中心大厅入口传入的模式 key。

备注

这是后台大厅配置使用的模式 key，不是项目数编的 GameModeLink。 调试或未通过大厅入口创建的游戏局可能没有模式 key，此时返回空字符串。

IsPaused 仅服务端

public static bool IsPaused { get; }

IsUserCloudDataServiceInitialized 仅服务端

public static bool IsUserCloudDataServiceInitialized { get; }

获取用户云数据服务是否已经初始化完成。

备注

初始化完成后，OnUserCloudDataServiceInitialization 会触发，云数据查询和事务接口才会开始接受请求。

IsSessionResident 仅服务端

public static bool IsSessionResident { get; }

Gets whether the current game session is protected from its automatic lifetime limit and all-players-offline cleanup.

备注

Residence does not prevent explicit game termination, administrative termination, platform safety termination, or server shutdown.

方法

CoreActorReplicateHandler 仅客户端

protected internal void CoreActorReplicateHandler(int coreActorId, bool isCoreActor, int linkHash)

TestInvokeHostOnce 双端

public static void TestInvokeHostOnce()

TestInvokedByHost 双端

public static void TestInvokedByHost(int count)

GetService 双端

public static T GetService<T>() where T : class

SetUpServices 双端

public static void SetUpServices(ServiceProvider services)

SendServerMessage 仅客户端

public static bool SendServerMessage<T>(ref T obj) where T : unmanaged, IProtocolClientTransient<T>

SendServerMessage 仅客户端

public static bool SendServerMessage(int typeHash, ReadOnlySpan<byte> bytes)

SetMinimumLogLevel 双端

public static void SetMinimumLogLevel(LogLevel minimumLevel)

FlushLogs 双端

public static void FlushLogs()

Flush log output owned by the current runtime. This is intended for diagnostics and tests, not per-frame use.

Delay 双端

public static Delay Delay(TimeSpan delay, CancellationToken? token = null, int adjustment = 0)

Creates a new Delay instance with the specified delay duration, optional cancellation token, and adjustment value.

• delay — The duration of the delay.
• token — An optional CancellationToken that can be used to cancel the delay. If null, the delay cannot be canceled.
• adjustment — An optional adjustment value, in milliseconds, to modify the delay duration. The final delay duration is calculated as plus .

返回： A new Delay instance configured with the specified parameters.

Delay 双端

public static Delay Delay(int delayInMilliseconds, CancellationToken? token = null, int adjustment = 0)

Creates a new Delay instance with the specified delay duration in milliseconds, optional cancellation token, and adjustment value.

• delayInMilliseconds — The duration of the delay in milliseconds.
• token — An optional CancellationToken that can be used to cancel the delay. If null, the delay cannot be canceled.
• adjustment — An optional adjustment value, in milliseconds, to modify the delay duration. The final delay duration is calculated as plus .

返回： A new Delay instance configured with the specified parameters.

DelaySimulateRealTime 双端

public static Delay DelaySimulateRealTime(TimeSpan delay, CancellationToken? token = null, int adjustment = 0)

Creates a delay that simulates real-time progression, with optional cancellation and adjustment.

• delay — The duration of the delay to simulate.
• token — An optional CancellationToken to cancel the delay.
• adjustment — An optional adjustment value, in milliseconds, to modify the delay duration.

返回： A Delay instance configured to simulate real-time progression.

DelaySimulateRealTime 双端

public static Delay DelaySimulateRealTime(int delayInMilliseconds, CancellationToken? token = null, int adjustment = 0)

Creates a delay that simulates real-time progression with the specified duration in milliseconds, with optional cancellation and adjustment.

• delayInMilliseconds — The duration of the delay to simulate in milliseconds.
• token — An optional CancellationToken to cancel the delay.
• adjustment — An optional adjustment value, in milliseconds, to modify the delay duration.

返回： A Delay instance configured to simulate real-time progression.

NextTick 双端

public static NextTick NextTick(CancellationToken? token = null)

ServerToClientTime 双端

public static int ServerToClientTime(int serverTime)

将服务端时间戳转换为客户端本地时间坐标。

• serverTime — 服务端的 TotalElapsedTickInMilliseconds 时间戳

返回： 对应的客户端 TotalElapsedTickInMilliseconds 时间

RegisterThinker 双端

public static bool RegisterThinker(IThinker thinker)

UnregisterThinker 双端

public static bool UnregisterThinker(IThinker thinker)

RegisterTickFinalizer 双端

public static bool RegisterTickFinalizer(ITickFinalizer finalizer)

Initialization 双端

public static void Initialization()

RegisterGameClass 双端

public static void RegisterGameClass<TClass>() where TClass : IGameClass

GetProperty 双端

public TValue? GetProperty<TValue>(PropertyGame property)

Subscribe 双端

public static Trigger<TEvent> Subscribe<TEvent>(TriggerEventHandle<TEvent> handler, bool keepReference = true) where TEvent : class, ITriggerEvent<TEvent>

创建触发器并注册到全局事件总线（Instance）。

• handler — 事件处理器委托
• keepReference — 是否保持硬引用防止 GC，默认为 true

返回： 创建的触发器对象

Subscribe 双端

public static Trigger<TEvent> Subscribe<TEvent>(Func<object, TEvent, Task> handler, bool keepReference = true) where TEvent : class, ITriggerEvent<TEvent>

创建触发器并注册到全局事件总线（简化版，无需返回布尔值）。

• handler — 事件处理器委托
• keepReference — 是否保持硬引用防止 GC，默认为 true

返回： 创建的触发器对象

InvokeTest 仅服务端

public static Task InvokeTest(int count)

RequestSessionEnd 仅服务端

public static void RequestSessionEnd()

请求 Host 结束当前游戏局。

备注

此方法只发起结束请求。游戏局实际结束并收到引擎通知后，才会触发 OnGameEnd。

Pause 仅服务端

public static void Pause(TimeSpan? timeOut = null)

Pauses the game for the specified duration or indefinitely if no timeout is provided.

• timeOut — An optional TimeSpan specifying the duration to pause the game. If null, the game will pause indefinitely.

备注

The pause duration is determined by the parameter, with a default behavior of pausing indefinitely.

Resume 仅服务端

public static void Resume()

Resumes the game from paused state.

PauseAllUnits 仅服务端

public static void PauseAllUnits(TimeSpan? timeOut = null)

Pauses all units in the game (time stop effect). The game logic continues running but all unit actions, movement, and abilities are frozen.

• timeOut — Optional duration after which units automatically resume. If null, units stay paused until ResumeAllUnits is called.

ResumeAllUnits 仅服务端

public static void ResumeAllUnits()

Resumes all units from time-stop state.

SetPropertyHashGlobalDefault 仅服务端

public static void SetPropertyHashGlobalDefault(int propertyHash, SyncType type)

SetProperty 仅服务端

public void SetProperty<TValue>(PropertyGame property, TValue value)

AddProperty 仅服务端

public void AddProperty(PropertyGame property, double value)

FilterSensitiveWords 仅服务端

public static SensitiveWordFilterResult FilterSensitiveWords(string text)

Replaces sensitive words in the specified text using the Host word list.

• text — The text to filter.

返回： A SensitiveWordFilterResult containing the filtered text and whether any sensitive words were replaced.

备注

This API is available only in server code. The replacement rules and word list are managed by the Host. The input string is not modified.

SetSessionResident 仅服务端

public static SessionResidenceResult SetSessionResident(bool resident)

Changes whether the current game session remains resident after all players leave. Explicit game termination and platform safety shutdowns still end a resident session.

• resident — true to request residence; otherwise, to release it.

返回： The result of applying the requested state.

备注

A project can have at most three resident sessions. If the limit has been reached, the method returns ProjectLimitReached and the current session does not become resident. A resident session ignores its automatic lifetime limit and all-players-offline cleanup, but explicit game termination, administrative termination, platform safety termination, and server shutdown still take precedence. Resident sessions are unavailable in the debug runtime environment because debug servers are ephemeral and do not provide all required platform services. Debug calls log a warning, return InvalidSessionState, and do not reach the host. Publish the project to at least the test runtime environment before validating this feature. Before enabling residence, implement an authenticated server-state control path that can drain work, persist state, and explicitly end an old resident session. Without that path, an old service version can remain active and block normal upgrades until an administrator force-closes every game session for the project and environment.

事件

TaskUnhandledException 双端

public static event TaskUnhandledExceptionEventHandler? TaskUnhandledException

OnRegisterGameClasses 双端

public static event Action? OnRegisterGameClasses

Requires manually unregistering the event. When the game starts, the events happens in the following order: OnRegisterAssemblySetup OnGameDataInitialization OnGameplaySettingsInitialization OnGameInstanceInitialization EventGameStart

OnGameDataInitialization 双端

public static event Action? OnGameDataInitialization

Requires manually unregistering the event. When the game starts, the events happens in the following order: OnRegisterAssemblySetup OnGameDataInitialization OnGameplaySettingsInitialization OnGameInstanceInitialization EventGameStart

OnGameplaySettingsInitialization 双端

public static event Action<GameDataGameMode>? OnGameplaySettingsInitialization

Requires manually unregistering the event. When the game starts, the events happens in the following order: OnRegisterAssemblySetup OnGameDataInitialization OnGameplaySettingsInitialization OnGameInstanceInitialization EventGameStart

OnGameSceneListInitialization 双端

public static event Action<GameDataGameMode>? OnGameSceneListInitialization

OnGameTriggerInitialization 双端

public static event Action? OnGameTriggerInitialization

OnGameInstanceInitialization 双端

public static event Action? OnGameInstanceInitialization

Requires manually unregistering the event. When the game starts, the events happens in the following order: OnRegisterAssemblySetup OnGameDataInitialization OnGameplaySettingsInitialization OnGameInstanceInitialization EventGameStart

OnGameUIInitialization 仅客户端

public static event Action? OnGameUIInitialization

The game won't be able to create GameUI before this event is triggered. Only make sense in client.

OnGameStart 双端

public static event Action? OnGameStart

OnGameEnd 双端

public static event Action? OnGameEnd

游戏结束时触发。这是 WASM 沙箱销毁前 C# 侧最后的清理窗口。 订阅此事件可释放通过底层 API（如 GameGraph）创建的原生资源。

OnServerDisconnected 仅客户端

public static event Action? OnServerDisconnected

Fired when the client loses an established connection to the game Host. It is unavailable on old client binaries whose capability version is unknown.

OnApplicationWillEnterBackground 仅客户端

public static event Action? OnApplicationWillEnterBackground

Called when the mobile application is about to enter the background.

OnApplicationDidEnterBackground 仅客户端

public static event Action? OnApplicationDidEnterBackground

Called after the mobile application has entered the background.

OnApplicationWillEnterForeground 仅客户端

public static event Action? OnApplicationWillEnterForeground

Called when the mobile application is about to return to the foreground.

OnApplicationDidEnterForeground 仅客户端

public static event Action? OnApplicationDidEnterForeground

Called after the mobile application has returned to the foreground.

OnApplicationLowMemory 仅客户端

public static event Action? OnApplicationLowMemory

Called when the mobile operating system reports memory pressure.

OnCanLoadDefaultScene 仅服务端

public static event Action? OnCanLoadDefaultScene

Occurs when the application determines that the default scene can be loaded.

备注

This event is triggered to signal that the conditions for loading the default scene have been met. Subscribers can use this event to initiate actions related to loading the default scene.

OnUserCloudDataServiceInitialization 仅服务端

public static event Action? OnUserCloudDataServiceInitialization

字段

FramePerSecond 双端

public const int FramePerSecond

This is not the real frame rate, but the target frame rate for the game loop on client side.

MillisecondsPerFrame 双端

public const int MillisecondsPerFrame

GameRunMode 双端

命名空间 GameCore.GameSystem

public enum GameRunMode

游戏运行模式。

枚举值

• Normal — 正常模式：客户端连接服务端，完整游戏流程。
• ClientOnly — 纯客户端模式：无服务端连接，Entity/Unit/CloudData 不可用。 适用于 GameGraph 游戏、UI 测试、纯客户端原型验证。 通过命令行参数 -client_only 启动。

SensitiveWordFilterResult 仅服务端

命名空间 GameCore.GameSystem

public readonly struct SensitiveWordFilterResult

Represents the result of filtering sensitive words from text.

构造函数

SensitiveWordFilterResult 仅服务端

public SensitiveWordFilterResult(bool wasFiltered, string filteredText)

Initializes a new sensitive-word filter result.

• wasFiltered — true when one or more sensitive words were replaced; otherwise, false.
• filteredText — The text produced by the filter.

属性

WasFiltered 仅服务端

public bool WasFiltered { get; }

Gets a value indicating whether one or more sensitive words were replaced.

FilteredText 仅服务端

public string FilteredText { get; }

Gets the filtered text. This is equivalent to the input text when WasFiltered is false.

方法

Deconstruct 仅服务端

public void Deconstruct(out bool wasFiltered, out string filteredText)

Deconstructs the result into its replacement state and filtered text.

• wasFiltered — true when one or more sensitive words were replaced.
• filteredText — The text produced by the filter.

UserSessionHandoff 仅服务端

命名空间 GameCore.GameSystem

public static class UserSessionHandoff

注册同一用户切换到同游戏其他游戏局前的服务端清理逻辑。

备注

当同一平台用户准备进入同一游戏的另一个游戏局时，当前旧游戏局会获得一次短时间、尽力而为的清理机会。 典型用途是提交用户云数据、释放临时占用或写入离线快照。该 API 不提供进房准入或业务回滚语义； 清理逻辑应保持简短、可重复执行，并优先使用 UserId 定位用户数据。 在这段清理窗口内，用户尚未正式完成新游戏局连入，新游戏局的玩家连入事件也不会先于旧局清理完成触发； 清理完成或等待超时后，框架会在发送完成回执前断开旧局玩家，平台随后继续后续连入流程。

属性

DefaultRequestTimeout 仅服务端

public static TimeSpan DefaultRequestTimeout { get; set; }

单次切换清理请求的默认总时间预算。

备注

默认值为 3500 毫秒，也是当前允许设置的最大值。项目可以把该值调小，让旧游戏局更快结束清理等待； 超过该时间后，尚未运行的清理处理器会被跳过，正在等待的异步处理器会收到取消信号。 该值只表示 WasiCore 旧游戏局清理预算；超时后平台仍会继续后续连入流程，且平台外层还有独立保护超时， 因此它不提供业务排队或进房准入语义，也不能用于延长平台切换等待。

方法

RegisterCleanup 仅服务端

public static IDisposable RegisterCleanup(Func<UserSessionHandoffContext, Task> handler, UserSessionHandoffOptions? options = null)

注册一个同用户游戏局切换清理处理器。

• handler — 短时间、可重复执行的清理逻辑。写入云数据时优先使用 UserId。
• options — 可选的处理器名称、执行顺序和单处理器超时配置。

返回： 注册句柄；调用 Dispose 后会取消后续清理请求中的该处理器。

备注

处理器只在服务端运行。框架会捕获单个处理器异常并继续执行后续处理器；如果需要观察结果， 可以订阅 CleanupCompleted。

事件

CleanupCompleted 仅服务端

public static event Action<UserSessionHandoffReport>? CleanupCompleted

清理请求完成、超时或部分处理器失败后触发的诊断事件。

备注

该事件适合写日志、上报指标或在调试时观察清理耗时；不要在这里继续执行耗时的云数据写入。

UserSessionHandoffContext 仅服务端

命名空间 GameCore.GameSystem

public sealed class UserSessionHandoffContext

同一用户切换到同游戏其他游戏局前，传递给清理处理器的上下文。

属性

RequestId 仅服务端

public long RequestId { get; }

本次清理请求的诊断标识。

备注

项目代码通常不需要使用该值；它主要用于日志、指标和问题排查。

UserId 仅服务端

public long UserId { get; }

平台用户的全局唯一标识。

备注

该值始终可用，也是云数据读写、离线快照和跨局用户数据清理的首选用户标识。 不要使用当局玩家槽位编号作为云数据用户标识。

User 仅服务端

public User User { get; }

当前用户对象。

备注

如果旧游戏局中仍能找到对应玩家，该属性来自本局玩家；否则框架会根据 UserId 创建一个轻量用户对象，方便项目代码继续按用户标识完成清理。

Player 仅服务端

public Player? Player { get; }

旧游戏局中仍然存在的玩家对象。

备注

当玩家对象已被移除或旧游戏局只收到用户级清理请求时，该值为 null。 清理云数据时应优先依赖 UserId，不要假设一定存在玩家对象。

HasLocalPlayer 仅服务端

public bool HasLocalPlayer { get; }

是否在旧游戏局中找到了对应的玩家对象。

Reason 仅服务端

public UserSessionHandoffReason Reason { get; }

本次清理请求的原因。

TimeBudget 仅服务端

public TimeSpan TimeBudget { get; }

本次清理请求的总时间预算。

备注

该预算用于帮助项目代码主动收敛清理耗时。清理处理器应尽快完成，避免在这里执行长时间后台任务。

CancellationToken 仅服务端

public CancellationToken CancellationToken { get; }

当本次清理请求时间预算耗尽时会被取消的令牌。

Items 仅服务端

public IDictionary<string, object?> Items { get; }

本次清理请求内多个处理器共享的临时数据。

备注

该字典只在当前清理请求内有效，适合传递一次性查询结果或轻量状态，不会被框架持久化。

UserSessionHandoffHandlerReport 仅服务端

命名空间 GameCore.GameSystem

public sealed class UserSessionHandoffHandlerReport : IEquatable<UserSessionHandoffHandlerReport>

一个清理处理器的执行摘要。

• HandlerName — 处理器名称。
• Status — 处理器执行状态。
• StartedAt — 处理器开始时间。
• FinishedAt — 处理器结束时间。
• Exception — 处理器抛出的异常；没有异常时为 null。

构造函数

UserSessionHandoffHandlerReport 仅服务端

public UserSessionHandoffHandlerReport(string HandlerName, UserSessionHandoffHandlerStatus Status, DateTimeOffset StartedAt, DateTimeOffset FinishedAt, Exception? Exception = null)

一个清理处理器的执行摘要。

• HandlerName — 处理器名称。
• Status — 处理器执行状态。
• StartedAt — 处理器开始时间。
• FinishedAt — 处理器结束时间。
• Exception — 处理器抛出的异常；没有异常时为 null。

属性

HandlerName 仅服务端

public string HandlerName { get; init; }

处理器名称。

Status 仅服务端

public UserSessionHandoffHandlerStatus Status { get; init; }

处理器执行状态。

StartedAt 仅服务端

public DateTimeOffset StartedAt { get; init; }

处理器开始时间。

FinishedAt 仅服务端

public DateTimeOffset FinishedAt { get; init; }

处理器结束时间。

Exception 仅服务端

public Exception? Exception { get; init; }

处理器抛出的异常；没有异常时为 null。

Duration 仅服务端

public TimeSpan Duration { get; }

该处理器的实际耗时。

方法

ToString 仅服务端

public override string ToString()

operator != 仅服务端

public static bool operator !=(UserSessionHandoffHandlerReport? left, UserSessionHandoffHandlerReport? right)

operator == 仅服务端

public static bool operator ==(UserSessionHandoffHandlerReport? left, UserSessionHandoffHandlerReport? right)

GetHashCode 仅服务端

public override int GetHashCode()

Equals 仅服务端

public override bool Equals(object? obj)

Equals 仅服务端

public bool Equals(UserSessionHandoffHandlerReport? other)

Deconstruct 仅服务端

public void Deconstruct(out string HandlerName, out UserSessionHandoffHandlerStatus Status, out DateTimeOffset StartedAt, out DateTimeOffset FinishedAt, out Exception? Exception)

UserSessionHandoffHandlerStatus 仅服务端

命名空间 GameCore.GameSystem

public enum UserSessionHandoffHandlerStatus

枚举值

• Completed — 处理器已完成。
• TimedOut — 处理器执行超时。
• Failed — 处理器执行失败。

UserSessionHandoffOptions 仅服务端

命名空间 GameCore.GameSystem

public sealed class UserSessionHandoffOptions

同用户游戏局切换清理处理器的注册选项。

构造函数

UserSessionHandoffOptions 仅服务端

public UserSessionHandoffOptions()

属性

Name 仅服务端

public string? Name { get; init; }

处理器名称，用于日志和诊断报告。

备注

默认值为 null，框架会使用自动生成的处理器名称。 建议填写能说明业务含义的名称，例如 SaveArchive、FlushTradeState。

Order 仅服务端

public int Order { get; init; }

处理器执行顺序，数值越小越早执行。

备注

默认值为 0。多个处理器的顺序值相同时，会按注册顺序执行。

Timeout 仅服务端

public TimeSpan? Timeout { get; init; }

单个处理器的可选超时时间。

备注

默认值为 null，表示不设置单处理器独立超时。即使没有设置该值，单次清理请求仍会受到 DefaultRequestTimeout 的总时间预算限制。

UserSessionHandoffReason 仅服务端

命名空间 GameCore.GameSystem

public enum UserSessionHandoffReason

同用户游戏局切换清理请求的触发原因。

枚举值

• JoiningAnotherSessionOfSameGame — 同一平台用户正在进入同一游戏的另一个游戏局。

UserSessionHandoffReport 仅服务端

命名空间 GameCore.GameSystem

public sealed class UserSessionHandoffReport : IEquatable<UserSessionHandoffReport>

一次同用户游戏局切换清理请求的执行摘要。

• RequestId — 本次清理请求的诊断标识。
• UserId — 本次清理对应的平台用户标识。
• StartedAt — 清理请求开始时间。
• FinishedAt — 清理请求结束时间。
• TimedOut — 本次清理请求是否耗尽了总时间预算。
• Handlers — 各个已注册处理器的执行结果。

构造函数

UserSessionHandoffReport 仅服务端

public UserSessionHandoffReport(long RequestId, long UserId, DateTimeOffset StartedAt, DateTimeOffset FinishedAt, bool TimedOut, IReadOnlyList<UserSessionHandoffHandlerReport> Handlers)

一次同用户游戏局切换清理请求的执行摘要。

• RequestId — 本次清理请求的诊断标识。
• UserId — 本次清理对应的平台用户标识。
• StartedAt — 清理请求开始时间。
• FinishedAt — 清理请求结束时间。
• TimedOut — 本次清理请求是否耗尽了总时间预算。
• Handlers — 各个已注册处理器的执行结果。

属性

RequestId 仅服务端

public long RequestId { get; init; }

本次清理请求的诊断标识。

UserId 仅服务端

public long UserId { get; init; }

本次清理对应的平台用户标识。

StartedAt 仅服务端

public DateTimeOffset StartedAt { get; init; }

清理请求开始时间。

FinishedAt 仅服务端

public DateTimeOffset FinishedAt { get; init; }

清理请求结束时间。

TimedOut 仅服务端

public bool TimedOut { get; init; }

本次清理请求是否耗尽了总时间预算。

Handlers 仅服务端

public IReadOnlyList<UserSessionHandoffHandlerReport> Handlers { get; init; }

各个已注册处理器的执行结果。

Duration 仅服务端

public TimeSpan Duration { get; }

本次清理请求的实际耗时。

方法

ToString 仅服务端

public override string ToString()

operator != 仅服务端

public static bool operator !=(UserSessionHandoffReport? left, UserSessionHandoffReport? right)

operator == 仅服务端

public static bool operator ==(UserSessionHandoffReport? left, UserSessionHandoffReport? right)

GetHashCode 仅服务端

public override int GetHashCode()

Equals 仅服务端

public override bool Equals(object? obj)

Equals 仅服务端

public bool Equals(UserSessionHandoffReport? other)

Deconstruct 仅服务端

public void Deconstruct(out long RequestId, out long UserId, out DateTimeOffset StartedAt, out DateTimeOffset FinishedAt, out bool TimedOut, out IReadOnlyList<UserSessionHandoffHandlerReport> Handlers)

GameDataGameMode 双端

命名空间 GameCore.GameSystem.Data

public class GameDataGameMode : GameDataCategory<GameDataGameMode>, IGameDataCategory<GameDataGameMode>, IGameData<GameDataGameMode>, IGameData

游戏模式配置，定义一种玩法所需的全部规则、UI、场景和玩家设置

构造函数

GameDataGameMode 双端

public GameDataGameMode(GameLink<GameDataGameMode, GameDataGameMode> link)

GameDataGameMode 双端

public GameDataGameMode(IGameLink<GameDataGameMode> link)

属性

AbilityTestArena 双端

public IGameLink<GameDataSkillTestArena>? AbilityTestArena { get; set; }

Default ability test arena available only during editor debug games.

AbilityTestArenas 双端

public List<IGameLink<GameDataSkillTestArena>> AbilityTestArenas { get; set; }

Other project-owned ability test arenas available in the same debug game.

SkillTestArena 双端

public IGameLink<GameDataSkillTestArena>? SkillTestArena { get; set; }

Legacy spelling retained so existing project data can migrate without losing its arena.

SkillTestArenas 双端

public List<IGameLink<GameDataSkillTestArena>> SkillTestArenas { get; set; }

Legacy spelling retained for existing project data.

Gameplay 双端

public IGameLink<GameDataGameplay> Gameplay { get; set; }

游戏玩法规则配置

GameUI 双端

public IGameLink<IGameDataGameUI>? GameUI { get; set; }

此游戏模式使用的 UI 界面配置

PlayerSettings 双端

public IGameLink<GameDataPlayerSettings> PlayerSettings { get; set; }

玩家设置配置（如队伍分配等）

ExperienceGrant 双端

public IGameLink<GameDataRuleExperienceGrant> ExperienceGrant { get; set; }

经验分配规则

DisplayInfo 双端

public IGameLink<GameDataRuleDisplayInfo> DisplayInfo { get; set; }

显示信息规则（如属性名称、描述的显示方式）

SceneList 双端

public List<IGameLink<GameDataScene>> SceneList { get; set; }

此游戏模式包含的场景列表

DefaultScene 双端

public IGameLink<GameDataScene>? DefaultScene { get; set; }

默认场景。服务器启动时自动加载此场景，所有玩家默认进入此场景

AutoLoadDefaultSceneInClientOnly 双端

public bool AutoLoadDefaultSceneInClientOnly { get; set; }

纯客户端模式启动后是否自动加载 DefaultScene 对应的客户端场景资产。

备注

默认为 false，避免 UI、GameGraph 原型或本地工具调试时产生不必要的地图加载成本。 只影响 GameRunMode.ClientOnly；正常客户端/服务端流程仍由服务端驱动场景切换。

PreloadResourcesOnStartup 双端

public bool PreloadResourcesOnStartup { get; set; }

客户端启动时是否预加载资源统计清单中的资源，默认为开启。

备注

关闭后，资源在场景加载或实际使用时按需加载，首次使用可能产生等待。 此设置不影响资源统计、项目打包或开局前的资源下载。

RenderConfig 双端

public IGameLink<GameDataRenderConfig>? RenderConfig { get; set; }

客户端渲染配置（阴影、场景渲染、管线、性能等）

GameDataGameplay 双端

命名空间 GameCore.GameSystem.Data

public class GameDataGameplay : GameDataCategory<GameDataGameplay>, IGameDataCategory<GameDataGameplay>, IGameData<GameDataGameplay>, IGameData

定义游戏核心玩法规则和全局配置，包含游戏运行时的关键参数和系统配置。

备注

此类作为游戏玩法的中央配置中心，包含影响整个游戏体验的全局设置。 通过此配置类可以统一管理各种游戏系统的默认行为和规则参数。

构造函数

GameDataGameplay 双端

public GameDataGameplay(GameLink<GameDataGameplay, GameDataGameplay> link)

GameDataGameplay 双端

public GameDataGameplay(IGameLink<GameDataGameplay> link)

属性

DefaultWaveAI 双端

public required IGameLink<GameDataWaveAI> DefaultWaveAI { get; set; }

获取或设置默认的波次AI配置，用于控制游戏中敌方单位的自动行为模式。

备注

此配置定义了游戏中AI单位的默认决策逻辑，包括移动模式、攻击策略、编队行为等。 所有未明确指定AI配置的敌方单位将使用此默认配置。

ItemQualityList 双端

public List<IGameLink<GameDataItemQuality>>? ItemQualityList { get; set; }

获取或设置全局物品品质配置列表，定义游戏中所有品质等级的视觉表现和特效规则。

备注

此列表按品质等级顺序排列，物品的Quality值用作索引来查找对应的品质配置： Quality = 0：使用列表中第一个品质配置（索引0） Quality = 1：使用列表中第二个品质配置（索引1），以此类推 如果Quality超出列表范围，则使用最后一个品质配置 如果列表为空或null，物品将不应用任何品质相关的视觉效果 品质配置影响物品在UI中的显示效果、地面掉落时的特效表现等视觉元素， 是实现物品稀有度系统的核心配置。建议按从低到高的品质顺序排列配置项。

GameDataGlobalConfig 双端

命名空间 GameCore.GameSystem.Data

public static class GameDataGlobalConfig

Represents the global configuration for game data, including available game modes and testing settings.

备注

This class provides a centralized configuration for managing game modes and testing parameters. It includes a dictionary of available game modes, a default game mode for testing, and settings for single-player testing.

属性

AvailableGameModes 双端

public static Dictionary<string, IGameLink<GameDataGameMode>> AvailableGameModes { get; set; }

Register the game mod for the game system. in non-testing (online) mode, the server will send game mode strings to the engine, and the engine will use this to determine which game mode to use.

TestGameMode 双端

public static IGameLink<GameDataGameMode> TestGameMode { get; set; }

The game mode to use when testing the game remotely or locally.

SinglePlayerTestSlotId 双端

public static int SinglePlayerTestSlotId { get; set; }

The player slot ID the local player will use in single-player testing mode.

GameDataRenderConfig 双端

命名空间 GameCore.GameSystem.Data

public class GameDataRenderConfig : GameDataCategory<GameDataRenderConfig>, IGameDataCategory<GameDataRenderConfig>, IGameData<GameDataRenderConfig>, IGameData

客户端渲染配置，控制阴影、场景渲染、渲染管线和性能相关的全局参数。

构造函数

GameDataRenderConfig 双端

public GameDataRenderConfig(GameLink<GameDataRenderConfig, GameDataRenderConfig> link)

GameDataRenderConfig 双端

public GameDataRenderConfig(IGameLink<GameDataRenderConfig> link)

属性

EnableBakedShadow 双端

public bool EnableBakedShadow { get; set; }

是否启用烘焙阴影。默认值：true。 烘焙阴影为 StaticMesh 在创建时预计算一次阴影贴图，之后不再更新，开销低于实时阴影。 适用于使用骨骼动画模型（Prefab/AnimatedModel）渲染角色的游戏——骨骼模型自带实时阴影， 而场景中的静态物体（地形、建筑等）可借助烘焙阴影降低渲染开销。 若游戏通过 GameGraph 底层 API 用 StaticMesh 基本形状拼装会移动的物体（角色、障碍物等）， 则必须设为 false，否则这些物体的阴影会固定在初始位置不随物体移动。 关闭后所有阴影改为实时计算。

ShadowRenderDistance 双端

public float ShadowRenderDistance { get; set; }

阴影渲染距离。0 表示不限制。默认值：0。

ShadowCameraOffset 双端

public float ShadowCameraOffset { get; set; }

阴影相机偏移距离，单位 cm。默认值：1000。

ScenePartitionDepth 双端

public int ScenePartitionDepth { get; set; }

场景空间分区深度（八叉树）。默认值：16。

RenderDistance 双端

public float RenderDistance { get; set; }

渲染距离。0 表示不限制。默认值：0。

TerrainDataEnabled 双端

public bool TerrainDataEnabled { get; set; }

是否启用地形数据（云阴影、云雾、GAO 等）。默认值：true。

WeatherEffectEnabled 双端

public bool WeatherEffectEnabled { get; set; }

是否启用天气效果。默认值：false。

TextureScale 双端

public float TextureScale { get; set; }

全局纹理缩放系数，范围 [0, 1]。默认值：1.0。

OcclusionCullingMode 双端

public OcclusionCullingMode OcclusionCullingMode { get; set; }

遮挡剔除模式。默认值：Distance。

CustomRenderPath 双端

public string? CustomRenderPath { get; set; }

自定义渲染管线路径。为 null 时使用默认管线。默认值：null。

ReduceFpsWhenOffscreen 双端

public bool ReduceFpsWhenOffscreen { get; set; }

窗口超出屏幕范围时是否降低帧率。默认值：true。

OffscreenFpsThreshold 双端

public float OffscreenFpsThreshold { get; set; }

触发降帧的屏幕外范围阈值，以屏幕宽度为计量单位。默认值：0.2。

GameDataRule 双端

命名空间 GameCore.GameSystem.Data

public abstract class GameDataRule : GameDataCategory<GameDataRule>, IGameDataCategory<GameDataRule>, IGameData<GameDataRule>, IGameData

Represents the abstract base class for all game rule configurations, defining how game systems behave and interact.

备注

This class serves as the foundation for all rule-based game logic, including victory conditions, gameplay mechanics, resource management rules, and behavioral constraints. Derived classes implement specific rule types that govern different aspects of gameplay, allowing for flexible and configurable game systems that can be modified without code changes.

构造函数

GameDataRule 双端

public GameDataRule(GameLink<GameDataRule, GameDataRule> link)

GameDataRule 双端

public GameDataRule(IGameLink<GameDataRule> link)

IGameDataGameUI 双端

命名空间 GameCore.GameSystem.Data

public interface IGameDataGameUI : IGameData<IGameDataGameUI>, IGameData

属性

UseTopLeftContentAlignmentDefaults 双端

public bool UseTopLeftContentAlignmentDefaults { get; }

新创建的 GameUI 控件是否默认使用左上内容对齐。

方法

GetStandardUIZIndex 双端

int? GetStandardUIZIndex(StandardUIType uiType)

CreateDefaultUI 仅客户端

IEnumerable<object>? CreateDefaultUI()

OcclusionCullingMode 双端

命名空间 GameCore.GameSystem.Data

public enum OcclusionCullingMode

遮挡剔除模式，对应引擎 OccludingCameraClipMode 枚举。

枚举值

• Distance — 按 Prefab 配置的距离进行剔除
• Focus — 按焦点到相机的遮挡进行剔除

EStandardUIType 双端

命名空间 GameCore.GameSystem.Enum

public enum EStandardUIType

标准UI类型枚举，按照传统游戏UI渲染优先级排序 数值越小的元素渲染层级越低（越靠后），数值越大的元素渲染层级越高（越靠前）

备注

渲染优先级从低到高的分层逻辑：

1. 基础游戏控制层：摇杆、地图等基础交互元素
2. 信息面板层：背包、角色面板、任务等游戏信息界面
3. 系统功能层：设置、排行榜等系统级功能
4. 交互反馈层：聊天、对话等即时交互
5. 顶层通知层：通知、主菜单等最高优先级UI

枚举值

• Joystick — 虚拟摇杆控制 - 基础移动控制，应在最底层
• Map — 游戏地图界面 - 基础导航信息
• CharacterSheet — 角色属性面板 - 角色基础信息
• Inventory — 物品背包界面 - 物品管理
• Quest — 任务追踪显示 - 当前活跃任务
• QuestLog — 任务日志面板 - 完整任务列表
• Crafting — 制作合成界面 - 物品制作
• TalentTree — 技能天赋树 - 角色成长
• Leaderboards — 排行榜界面 - 竞技信息
• Settings — 游戏设置面板 - 系统配置
• Chat — 聊天系统界面 - 玩家交流
• Dialogue — NPC对话界面 - 剧情交互，需要较高优先级
• Notifications — 系统通知提示 - 重要信息通知
• MainMenu — 主菜单界面 - 最高优先级的模态界面
• Minimap — 小地图/雷达 - 局部区域导航，通常固定显示
• Hotbar — 快捷栏/技能栏 - 快速访问技能和物品
• StatusBar — 血条/状态栏 - 角色生命值、法力值等关键状态。 注意这是指 UI 中的血条/状态栏，而非实体组件中的血条（位于场景中）。
• Shop — 商店/交易界面 - 商品购买和交易
• Party — 团队/组队界面 - 多人游戏团队管理
• Social — 好友/社交面板 - 社交功能管理
• Achievement — 成就系统界面 - 成就展示和追踪
• Tutorial — 教程/引导界面 - 新手引导和帮助
• Reward — 奖励选择面板 - 游戏中的升级/奖励选择界面，需要暂停游戏并强制选择
• ConfirmDialog — 确认对话框 - 重要操作确认，需要最高优先级
• ErrorDialog — 系统错误提示 - 错误信息显示，最高优先级
• Loading — 加载界面 - 场景切换时的加载提示

PropertyGame 双端

命名空间 GameCore.GameSystem.Enum

public readonly struct PropertyGame : IGameClass, IExtendableEnum<PropertyGame>, IExtendableEnum, IExtendedEnum, ISyncIdOwner

方法

ToString 双端

public override string? ToString()

operator == 双端

public static bool operator ==(PropertyGame left, PropertyGame right)

operator != 双端

public static bool operator !=(PropertyGame left, PropertyGame right)

Equals 双端

public override bool Equals(object? obj)

GetHashCode 双端

public override int GetHashCode()

OnRegisterGameClass 双端

public static void OnRegisterGameClass()

字段

InnerValue 双端

public readonly System.Enum InnerValue

StandardUIType 双端

命名空间 GameCore.GameSystem.Enum

public readonly struct StandardUIType : IGameClass, IExtendableEnum<StandardUIType>, IExtendableEnum, IExtendedEnum, ISyncIdOwner

属性

ExpectedZIndex 双端

public int? ExpectedZIndex { get; }

获取当前标准UI类型的期望ZIndex值

返回： 根据当前游戏模式的UI配置计算得出的ZIndex值，如果无法获取配置则返回null

备注

此属性会自动从当前游戏模式的 GameDataGameUI 配置中获取ZIndex值。 计算公式：ZIndex = BaseZIndex + (在渲染顺序数组中的索引 × ZIndexStep) 如果满足以下任一条件，将返回null： 游戏模式未初始化 游戏模式数据为空 UI配置未设置 当前UI类型不在渲染顺序配置中 建议在使用前检查返回值是否为null，并提供合适的默认值。

方法

ToString 双端

public override string? ToString()

operator == 双端

public static bool operator ==(StandardUIType left, StandardUIType right)

operator != 双端

public static bool operator !=(StandardUIType left, StandardUIType right)

Equals 双端

public override bool Equals(object? obj)

GetHashCode 双端

public override int GetHashCode()

OnRegisterGameClass 双端

public static void OnRegisterGameClass()

字段

InnerValue 双端

public readonly System.Enum InnerValue

Joystick 双端

public static readonly StandardUIType Joystick

虚拟摇杆控制 - 基础移动控制，应在最底层

Map 双端

public static readonly StandardUIType Map

游戏地图界面 - 基础导航信息

CharacterSheet 双端

public static readonly StandardUIType CharacterSheet

角色属性面板 - 角色基础信息

Inventory 双端

public static readonly StandardUIType Inventory

物品背包界面 - 物品管理

Quest 双端

public static readonly StandardUIType Quest

任务追踪显示 - 当前活跃任务

QuestLog 双端

public static readonly StandardUIType QuestLog

任务日志面板 - 完整任务列表

Crafting 双端

public static readonly StandardUIType Crafting

制作合成界面 - 物品制作

TalentTree 双端

public static readonly StandardUIType TalentTree

技能天赋树 - 角色成长

Leaderboards 双端

public static readonly StandardUIType Leaderboards

排行榜界面 - 竞技信息

Settings 双端

public static readonly StandardUIType Settings

游戏设置面板 - 系统配置

Chat 双端

public static readonly StandardUIType Chat

聊天系统界面 - 玩家交流

Dialogue 双端

public static readonly StandardUIType Dialogue

NPC对话界面 - 剧情交互，需要较高优先级

Notifications 双端

public static readonly StandardUIType Notifications

系统通知提示 - 重要信息通知

MainMenu 双端

public static readonly StandardUIType MainMenu

主菜单界面 - 最高优先级的模态界面

Minimap 双端

public static readonly StandardUIType Minimap

小地图/雷达 - 局部区域导航，通常固定显示

Hotbar 双端

public static readonly StandardUIType Hotbar

快捷栏/技能栏 - 快速访问技能和物品

StatusBar 双端

public static readonly StandardUIType StatusBar

血条/状态栏 - 角色生命值、法力值等关键状态。 注意这是指 UI 中的血条/状态栏，而非实体组件中的血条（位于场景中）。

Shop 双端

public static readonly StandardUIType Shop

商店/交易界面 - 商品购买和交易

Party 双端

public static readonly StandardUIType Party

团队/组队界面 - 多人游戏团队管理

Social 双端

public static readonly StandardUIType Social

好友/社交面板 - 社交功能管理

Achievement 双端

public static readonly StandardUIType Achievement

成就系统界面 - 成就展示和追踪

Tutorial 双端

public static readonly StandardUIType Tutorial

教程/引导界面 - 新手引导和帮助

Reward 双端

public static readonly StandardUIType Reward

奖励选择面板 - 游戏中的升级/奖励选择界面，需要暂停游戏并强制选择

备注

类似《吸血鬼幸存者》等游戏中的升级选择面板，具有以下特点：

• 模态交互，暂停游戏进行
• 阻止其他UI操作
• 要求玩家必须做出选择才能继续
• 优先级应高于一般UI但低于系统确认对话框

ConfirmDialog 双端

public static readonly StandardUIType ConfirmDialog

确认对话框 - 重要操作确认，需要最高优先级

ErrorDialog 双端

public static readonly StandardUIType ErrorDialog

系统错误提示 - 错误信息显示，最高优先级

Loading 双端

public static readonly StandardUIType Loading

加载界面 - 场景切换时的加载提示