GameCore.PlayerAndUsers

AIController 双端

命名空间 GameCore.PlayerAndUsers

public class AIController : SlotController

Represents a slot controller for an AI-controlled player.

• player — The player instance associated with this AI controller. Cannot be null.

备注

See PlayerController, which manages real player connections and states.

构造函数

AIController 双端

public AIController(Player player)

Represents a slot controller for an AI-controlled player.

• player — The player instance associated with this AI controller. Cannot be null.

备注

See PlayerController, which manages real player connections and states.

属性

Status 双端

public override PlayerStatus Status { get; set; }

EPropertyPlayerUI 双端

命名空间 GameCore.PlayerAndUsers

public enum EPropertyPlayerUI

客户端可设置的玩家UI属性枚举 警告：这些属性可能被客户端修改，不应用于游戏逻辑判断 仅用于UI状态、偏好设置等非安全关键数据

枚举值

• UIPanelCollapsed — UI面板折叠状态 - 示例属性
• ChatChannelPreference — 聊天频道设置
• KeyBindingSettings — 快捷键绑定设置
• UILayoutConfig — 界面布局配置

Player 双端

命名空间 GameCore.PlayerAndUsers

public class Player : ICooldownHost, ICooldownOwner, IPropertyOwner, ISyncIdOwner, IPropertyHost, IEventSender, IGameClass, IPropertyOwner<PropertyPlayer>, IPropertyOwner<PropertyPlayerUI>

游戏中的玩家，可以是真人用户、AI 或系统玩家。 管理队伍归属、主控单位、场景存在、玩家间关系以及网络通信。

属性

Scene 双端

public Scene Scene { get; }

玩家当前所在的场景。 客户端仅对本地玩家可靠，其他玩家可能始终返回引擎后备场景。 当原生运行时尚未将玩家关联到当前游戏模式 SceneList 中的场景时，此属性返回 IsEngineFallback 为 true 的场景。后备场景可作为不依赖地图数据的 Actor 的归属场景，但不表示客户端已加载地图。

MainUnit 双端

public Unit? MainUnit { get; }

玩家的主控单位（通常是角色或化身），服务端可读写，客户端只读。

备注

主控绑定与单位移动能力无关，静态单位也可用于默认镜头跟随。 移动指令仍要求单位具备相应的移动能力。

IsNeutral 双端

public bool IsNeutral { get; set; }

Gets or sets a value indicating whether this player is neutral.

备注

Neutral players are not considered enemies by other players and have special relationship rules. On the server, setting this property updates the underlying view player. On the client, this is synchronized from the server.

ControllerSetting 双端

public ControllerType ControllerSetting { get; }

Gets the controller type setting from the player configuration.

备注

This represents the controller setting from the player's configuration, which may differ from the actual controller type if overridden by game conditions.

Controller 双端

public ControllerType Controller { get; }

Gets the actual controller type for this player.

备注

This represents the actual controller managing this player, which determines how input and decisions are processed for the player's units and actions.

DefaultPlayer 双端

public static Player DefaultPlayer { get; }

默认系统玩家（Player 0），用于不属于任何真人玩家的实体（如中立生物、系统生成内容）。

AllPlayers 双端

public static List<Player> AllPlayers { get; }

Units 双端

public IReadOnlyCollection<Unit> Units { get; }

该玩家拥有的所有存活单位（只读视图）。单位创建时自动加入，销毁时自动移除。

Team 双端

public Team Team { get; set; }

Gets or sets the team that this player belongs to.

备注

Team membership affects player relationships, targeting rules, and shared objectives. On the server, setting this property updates the underlying view player and adds the player to the team. On the client, this is synchronized from the server.

Id 双端

public int Id { get; }

Gets the unique identifier for this player.

LocalPlayer 仅客户端

public static Player LocalPlayer { get; }

Gets the local player instance for the current client.

备注

This property provides access to the player instance representing the local client in multiplayer scenarios. It's only available on the client side.

SyncId 双端

public int SyncId { get; }

SyncIdType 双端

public SyncIdType SyncIdType { get; }

Aggregator 双端

public EventAggregator Aggregator { get; }

AggregatorWeakReference 双端

public WeakReference<EventAggregator> AggregatorWeakReference { get; }

User 双端

public User? User { get; set; }

LocalVisionFocus 仅客户端

public Unit? LocalVisionFocus { get; set; }

本地视野遮罩渲染焦点。只有本地玩家的该属性会影响客户端视野遮罩绘制。 未主动设置时，如果当前场景开启 UseMainUnitAsLocalVisionFocus，会回退到本地玩家主控单位。 主动设置后会固定为该值；主动设置为 null 表示关闭自动回退和本地视野遮罩焦点。

IsOnline 仅服务端

public bool IsOnline { get; }

玩家是否在线（Connected 或 Unresponsive 视为在线）。AI 玩家始终在线。

IsConnectionUnresponsive 仅服务端

public bool IsConnectionUnresponsive { get; }

玩家连接当前是否处于暂时无响应状态。

UserId 仅服务端

public long? UserId { get; }

玩家对应的平台用户 ID。仅真人玩家有值，AI 玩家返回 null。

SlotController 仅服务端

public SlotController SlotController { get; set; }

方法

ToString 双端

public override string ToString()

Returns a string representation of this player including ID and team information.

返回： A formatted string describing this player.

GetRelationShip 双端

public PlayerRelationShip GetRelationShip(Player other)

获取与另一个玩家的关系。判定优先级：同一玩家(Player) → 同队(Ally) → 中立方(Neutral) → 敌人(Enemy)。 中立玩家对所有人（除自己）都视为 Neutral。

GetById 双端

public static Player? GetById(int id)

Retrieves a player by their unique identifier.

• id — The unique identifier of the player to retrieve.

返回： The player with the specified ID, or null if not found.

CanControlTo 双端

public bool CanControlTo(Entity entity, bool isRequest = false)

Determines whether this player can control the specified entity.

• entity — The entity to check control permissions for.
• isRequest — Whether this is a control request that requires additional validation.

返回： True if the player can control the entity; otherwise, false.

备注

Control permissions are based on entity ownership and the entity's ability to receive commands. Control requests have additional validation requirements compared to simple ownership checks.

IsShareControlTo 双端

public bool IsShareControlTo(Player player)

Publish 双端

public virtual void Publish<TEvent>(TEvent eventToPublish)

GetPublisher 双端

public Action<TEvent>? GetPublisher<TEvent>()

OnRegisterGameClass 双端

public static void OnRegisterGameClass()

GetProperty 双端

public TValue? GetProperty<TValue>(PropertyPlayer property)

GetUIProperty 双端

public TValue? GetUIProperty<TValue>(PropertyPlayerUI property)

获取UI属性值

ClearLocalVisionFocusOverride 仅客户端

public void ClearLocalVisionFocusOverride()

清除用户设置的本地视野遮罩渲染焦点，重新使用当前场景配置决定是否回退到本地玩家主控单位。

SwitchScene 仅服务端

public bool SwitchScene(Scene scene, bool withMainUnit = false)

Switches this player to a different scene.

• scene — The target scene to switch to.
• withMainUnit — Whether to also move the player's main unit to the new scene.

返回： True if the scene switch was successful; otherwise, false.

备注

This method handles player scene transitions, which affect what content the player can see and interact with. If withMainUnit is true, the player's main unit will also be moved to the new scene if the player switch succeeds.

Kick 仅服务端

public void Kick(string reason, string? clientMessage = null)

踢出该真人玩家。会向客户端发送踢出通知，并按服务端踢人流程清理平台注册信息。

• reason — 服务端记录的踢人原因。
• clientMessage — 发送给客户端的提示文案。

Disconnect 仅服务端

public void Disconnect()

按主动离开流程断开该真人玩家连接。

BroadcastClientMessage 仅服务端

public static void BroadcastClientMessage<T>(ref T protocol, Func<Player, bool>? filter = null) where T : unmanaged, IProtocolServerTransient<T>

Broadcasts a protocol message to all players, optionally filtered.

• protocol — The protocol message to broadcast.
• filter — An optional filter function to determine which players receive the message.

备注

This method sends messages to all players in the game, which is useful for global notifications, game state updates, or system announcements. The filter can be used to restrict the broadcast to specific players based on custom criteria.

SetShareControlTo 仅服务端

public void SetShareControlTo(Player player, bool on)

设置是否将此玩家名下所有实体的控制权共享给指定玩家（Player 级别共享）。 区别于 Entity 级别的 Boolean)。

SetShareSightTo 仅服务端

public void SetShareSightTo(Player player, bool on)

设置是否将此玩家的视野共享给指定玩家。同队玩家默认共享视野，此方法用于跨队共享。

IsShareSightTo 仅服务端

public bool IsShareSightTo(Player player)

SetProperty 仅服务端

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

AddProperty 仅服务端

public void AddProperty(PropertyPlayer property, double value)

HandleClientUIPropertyRequest 仅服务端

public void HandleClientUIPropertyRequest<TValue>(PropertyPlayerUI property, TValue value)

处理来自客户端的UI属性设置请求

事件

OnNeutralChanged 仅客户端

public event Action<bool>? OnNeutralChanged

Occurs when the player's neutral status changes.

备注

This event is fired on the client side when the player's neutral status is updated from server synchronization. Neutral players have different relationship rules.

OnTeamChanged 仅客户端

public event Action<Team>? OnTeamChanged

Occurs when the player's team assignment changes.

备注

This event is fired on the client side when the player is assigned to a different team. Team changes affect player relationships and targeting rules.

OnMainUnitChanged 仅客户端

public event Action<Unit?>? OnMainUnitChanged

Occurs when the player's main unit changes.

备注

This event is fired when the player's primary controlled unit is changed or removed. The main unit is typically the player's avatar or primary character.

字段

_viewPlayer 双端

protected internal readonly IViewPlayer _viewPlayer

Gets the underlying engine view player interface.

PlayerController 仅服务端

命名空间 GameCore.PlayerAndUsers

public class PlayerController : SlotController

管理服务器端真人玩家连接、状态和消息传输的控制器

备注

PlayerController 负责处理真人玩家的连接状态管理、用户信息维护和服务器到客户端的消息传输。 与此对应的是 AI 玩家控制器 AIController，它专门处理 AI 玩家逻辑。 它监听底层网络连接事件并将其转换为游戏层的事件，同时提供消息发送的接口。

属性

Status 仅服务端

public override PlayerStatus Status { get; set; }

获取或设置玩家的当前状态

备注

状态变化时会触发 EventPlayerStatusChanged 事件通知其他系统。 状态包括连接、暂时无响应、断开、离开等。

User 仅服务端

public User User { get; set; }

获取当前关联的用户信息。 如果指定玩家槽位未连接用户，且没有预约任何用户，则该属性对应的平台用户 Id 为 0。 在玩家连接且使用不同用户 ID 时，该属性会更新为新的用户对象。

方法

SendMessage 仅服务端

public override bool SendMessage<T>(ref T protocol, Func<Player, bool>? filter = null)

向玩家发送协议消息

• protocol — 要发送的协议消息
• filter — 可选的玩家过滤条件

返回： 如果成功发送则返回 true；否则返回 false

备注

只有在玩家状态为已连接且通过过滤条件时才会发送消息。

SendMessage 仅服务端

public override bool SendMessage(int typeHash, ReadOnlySpan<byte> data, Func<Player, bool>? filter = null)

发送原始字节消息到玩家

• typeHash — 消息类型的哈希值
• data — 消息的字节数据
• filter — 可选的玩家过滤条件

返回： 如果成功发送则返回 true；否则返回 false

备注

用于发送预序列化的消息数据，只有在玩家状态为已连接且通过过滤条件时才会发送。

事件

OnUserChanged 仅服务端

public event Action<User>? OnUserChanged

当玩家关联的用户发生变化时触发的事件

备注

当玩家重新连接且使用不同的用户 ID 时会触发此事件。

PropertyPlayerUI 双端

命名空间 GameCore.PlayerAndUsers

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

方法

ToString 双端

public override string? ToString()

operator == 双端

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

operator != 双端

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

Equals 双端

public override bool Equals(object? obj)

GetHashCode 双端

public override int GetHashCode()

OnRegisterGameClass 双端

public static void OnRegisterGameClass()

字段

InnerValue 双端

public readonly System.Enum InnerValue

UIPanelCollapsed 双端

public static readonly PropertyPlayerUI UIPanelCollapsed

UI面板折叠状态 - 示例属性

ChatChannelPreference 双端

public static readonly PropertyPlayerUI ChatChannelPreference

聊天频道设置

KeyBindingSettings 双端

public static readonly PropertyPlayerUI KeyBindingSettings

快捷键绑定设置

UILayoutConfig 双端

public static readonly PropertyPlayerUI UILayoutConfig

界面布局配置

SlotController 双端

命名空间 GameCore.PlayerAndUsers

public abstract class SlotController

玩家槽位控制器的抽象基类。根据 ControllerType 的不同，框架会创建对应的子类： PlayerController（ControllerType.User）— 管理真人玩家的连接状态和消息传输 AIController（ControllerType.Computer）— AI 玩家，始终在线，消息发送为空操作

备注

Boolean}) 的默认实现返回 false（不发送任何内容）。 仅 PlayerController 覆写了此方法以实际向客户端发送数据。 因此对 AI 玩家调用 SendMessage 不会报错，只是静默无效。

构造函数

SlotController 双端

protected SlotController(Player player)

玩家槽位控制器的抽象基类。根据 ControllerType 的不同，框架会创建对应的子类： PlayerController（ControllerType.User）— 管理真人玩家的连接状态和消息传输 AIController（ControllerType.Computer）— AI 玩家，始终在线，消息发送为空操作

备注

Boolean}) 的默认实现返回 false（不发送任何内容）。 仅 PlayerController 覆写了此方法以实际向客户端发送数据。 因此对 AI 玩家调用 SendMessage 不会报错，只是静默无效。

属性

Player 双端

public Player Player { get; }

Status 双端

public abstract PlayerStatus Status { get; set; }

方法

SendMessage 双端

public virtual bool SendMessage<T>(ref T protocol, Func<Player, bool>? filter = null) where T : unmanaged, IProtocolServerTransient<T>

向该玩家的客户端发送协议消息。默认返回 false（AI 玩家）。

SendMessage 双端

public virtual bool SendMessage(int typeHash, ReadOnlySpan<byte> data, Func<Player, bool>? filter = null)

向该玩家的客户端发送原始字节消息。默认返回 false（AI 玩家）。

User 双端

命名空间 GameCore.PlayerAndUsers

public class User

Represents a user in the game system with identification and display information.

• userId — The unique identifier for this user.

备注

This class encapsulates user information including their unique ID and optional display name. It provides string representation functionality for debugging and display purposes.

构造函数

User 双端

public User(long userId)

Represents a user in the game system with identification and display information.

• userId — The unique identifier for this user.

备注

This class encapsulates user information including their unique ID and optional display name. It provides string representation functionality for debugging and display purposes.

属性

Name 双端

public string? Name { get; set; }

Gets or sets the display name for this user. Can be null if no name is set.

UserId 双端

public long UserId { get; }

Gets the unique identifier for this user.

NameFetchStatus 仅服务端

public UserNameFetchStatus NameFetchStatus { get; set; }

方法

ToString 双端

public override string? ToString()

Returns a string representation of this user, including the name (if available) and user ID.

返回： A formatted string in the format "[Name] [User ID]" or just "[User ID]" if no name is set.

FetchNameAsync 仅服务端

public Task<bool> FetchNameAsync()

Asynchronously fetches the platform username from cloud data and updates the Name property.

返回： A task that represents the asynchronous operation. The task result contains: true if the name was successfully fetched and updated; otherwise, false.

备注

This method queries the cloud data system to retrieve the user's platform username. The NameFetchStatus property will be updated to reflect the current state of the operation: InProgress: While the fetch operation is in progress Succeeded: If the name was successfully retrieved Failed: If the operation failed or the name could not be retrieved If a fetch operation is already in progress or has already succeeded, this method will return immediately without starting a new fetch.

FetchNameAsyncForAllLivingUsers 仅服务端

public static Task<UserCloudDataResult> FetchNameAsyncForAllLivingUsers()

批量获取所有存活玩家的平台用户名。跳过已成功、进行中或已确认不存在的用户。

事件

OnNameFetched 仅服务端

public event Action<User, string>? OnNameFetched

GameDataPlayerSettings 双端

命名空间 GameCore.PlayerAndUsers.Data

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

玩家全局设置，如队伍配置等。

构造函数

GameDataPlayerSettings 双端

public GameDataPlayerSettings(GameLink<GameDataPlayerSettings, GameDataPlayerSettings> link)

GameDataPlayerSettings 双端

public GameDataPlayerSettings(IGameLink<GameDataPlayerSettings> link)

属性

PlayerTeamData 双端

public List<TeamSettings> PlayerTeamData { get; set; }

各队伍的配置列表，索引对应队伍 ID。

TeamSettings 双端

命名空间 GameCore.PlayerAndUsers.Data.Struct

public class TeamSettings : IEnumerable<PlayerData>, IEnumerable

构造函数

TeamSettings 双端

public TeamSettings()

属性

DisplayName 双端

public LocalizedString? DisplayName { get; set; }

Players 双端

public List<PlayerData> Players { get; set; }

方法

Add 双端

public void Add(PlayerData player)

GetEnumerator 双端

public IEnumerator<PlayerData> GetEnumerator()

索引器

this[] 双端

PlayerRelationShip 双端

命名空间 GameCore.PlayerAndUsers.Enum

public enum PlayerRelationShip

玩家间的关系类型，由 Player) 根据队伍和中立状态自动判定。 判定优先级：同一玩家(Player) → 同队(Ally) → 任一方中立(Neutral) → 敌对(Enemy)。

枚举值

• Enemy — 敌对关系。双方处于不同队伍且都不是中立玩家。
• Neutral — 中立关系。当任一方 为 时， 双方关系最低为 Neutral（不会被判定为 Enemy），但仍可能因同队返回 Ally 或因同一玩家返回 Player。
• Ally — 同盟关系。双方处于同一队伍（但不是同一玩家）。
• Player — 自身。 返回此值。

PlayerStatus 双端

命名空间 GameCore.PlayerAndUsers.Enum

public enum PlayerStatus

Defines the connection and activity status of a player in the game.

备注

This enum tracks the current state of a player's connection and participation in the game session. It helps manage player lifecycle and determine appropriate game behavior based on player availability.

枚举值

• Open — The player slot is available but no player has connected yet.
• Connected — The player is actively connected and participating in the game.
• Unresponsive — The player's connection is temporarily unresponsive.
• Disconnected — The player has lost connection but may reconnect.
• Left — The player has permanently left the game session.

PlayerUnitRelationShip 双端

命名空间 GameCore.PlayerAndUsers.Enum

public enum PlayerUnitRelationShip

Relationship between a player and a unit

枚举值

• MainUnit — If the unit is the main unit of the player.
• Player — If the unit owned by the player.
• Alliance
• Enemy
• Neutral

UserNameFetchStatus 双端

命名空间 GameCore.PlayerAndUsers.Enum

public enum UserNameFetchStatus

枚举值

• NotStarted
• InProgress
• Succeeded
• Failed
• NotFound