星火 2.0 开发文档

主题

TriggerEncapsulation.GameTemplates ​

GameTemplateUtilities 双端 ​

命名空间 TriggerEncapsulation.GameTemplates

csharp
public static class GameTemplateUtilities

游戏模板实用工具

方法 ​

FindByProperty 双端 ​

csharp
public static IEnumerable<PropertyObject> FindByProperty<TProperty, TValue>(this IEnumerable<PropertyObject> objects, TProperty property, TValue value) where TProperty : struct, IExtendableEnum where TValue : IEquatable<TValue>

在 PropertyObject 列表中查找符合条件的对象

  • objects — PropertyObject 列表
  • property — 属性
  • value — 要匹配的值

返回： 符合条件的 PropertyObject 列表

InGroup 双端 ​

csharp
public static IEnumerable<PropertyObject> InGroup(this IEnumerable<PropertyObject> objects, int groupId)

按 GroupId 过滤

OrderByIndex 双端 ​

csharp
public static IEnumerable<PropertyObject> OrderByIndex(this IEnumerable<PropertyObject> objects)

按 OrderIndex 排序

OwnedBy 双端 ​

csharp
public static IEnumerable<PropertyObject> OwnedBy(this IEnumerable<PropertyObject> objects, Player player)

获取指定玩家拥有的所有对象

HasProperty 双端 ​

csharp
public static bool HasProperty<TProperty>(this PropertyObject obj, TProperty property) where TProperty : struct, IExtendableEnum

检查 PropertyObject 是否包含特定属性

  • obj — PropertyObject
  • property — 属性

返回： 如果包含返回 true

EncodeGridPosition 双端 ​

csharp
public static int EncodeGridPosition(int x, int y, int gridWidth = 100)

编码二维坐标为单个索引

  • x — X 坐标
  • y — Y 坐标
  • gridWidth — 网格宽度（默认 100）

返回： 编码后的索引

DecodeGridPosition 双端 ​

csharp
public static (int x, int y) DecodeGridPosition(int index, int gridWidth = 100)

解码索引为二维坐标

  • index — 编码的索引
  • gridWidth — 网格宽度（默认 100）

返回： 解码后的 (x, y) 坐标

SetGridPosition 双端 ​

csharp
public static void SetGridPosition(this PropertyObject obj, int x, int y, int gridWidth = 100)

设置网格位置（自动编码为 OrderIndex）

GetGridPosition 双端 ​

csharp
public static (int x, int y) GetGridPosition(this PropertyObject obj, int gridWidth = 100)

获取网格位置（自动解码 OrderIndex）

PropertyObjectWrapper 双端 ​

命名空间 TriggerEncapsulation.GameTemplates

csharp
public abstract class PropertyObjectWrapper

PropertyObject 包装器基类

备注

为 PropertyObject 提供强类型包装，简化属性访问。 子类只需定义属性，无需重复编写 GetPropertyGeneric/SetPropertyGeneric。 使用示例： public class PlayerBird : PropertyObjectWrapper { public PlayerBird(Player owner) : base(owner, SyncType.All) { } public float BirdY { get => GetProperty<PropertyBird, float>(PropertyBird.BirdY); set => SetProperty<PropertyBird, float>(PropertyBird.BirdY, value); } public void Jump() { BirdVelocity = -600f; } }

构造函数 ​

PropertyObjectWrapper 双端 ​

csharp
protected PropertyObjectWrapper(PropertyObject propertyObject)

构造函数（仅客户端）

  • propertyObject — 复制的 PropertyObject

PropertyObjectWrapper 仅服务端 ​

csharp
protected PropertyObjectWrapper(Player owner, SyncType syncType = SyncType.All)

构造函数（仅服务端）

  • owner — 对象所有者
  • syncType — 同步类型

属性 ​

PropertyObject 双端 ​

csharp
protected PropertyObject PropertyObject { get; }

底层 PropertyObject 实例

Owner 双端 ​

csharp
public Player Owner { get; }

对象所有者

IsValid 双端 ​

csharp
public bool IsValid { get; }

对象是否有效

Id 双端 ​

csharp
public int Id { get; }

对象 ID

OrderIndex 双端 ​

csharp
public int? OrderIndex { get; }

OrderIndex（使用 PropertyObject 内置属性）

GroupId 双端 ​

csharp
public int? GroupId { get; }

GroupId（使用 PropertyObject 内置属性）

方法 ​

GetProperty 双端 ​

csharp
protected TValue GetProperty<TProperty, TValue>(TProperty property) where TProperty : struct, IExtendableEnum

获取属性（泛型辅助）

ToString 双端 ​

csharp
public override string ToString()

返回对象的字符串表示

SetProperty 仅服务端 ​

csharp
protected void SetProperty<TProperty, TValue>(TProperty property, TValue value) where TProperty : struct, IExtendableEnum

设置属性（泛型辅助）

Destroy 仅服务端 ​

csharp
public virtual void Destroy()

销毁对象

RealtimeActionGameTemplate 双端 ​

命名空间 TriggerEncapsulation.GameTemplates

csharp
public abstract class RealtimeActionGameTemplate<TSelf> : Simple2DMultiplayerGame<TSelf> where TSelf : RealtimeActionGameTemplate<TSelf>, new()

实时动作游戏模板基类。 ⚠️ 已弃用，不推荐新项目使用。 实时连续运动的联机游戏改用 node 位置 + PropertyHostComponent： 位置走 replicated Node 的 transform，客户端 SmoothedTransform 原生平滑，无需手写外插。 见 code_sample/HybridFlappyBird、docs/systems/PropertyHostComponentSystem.md。

备注

专为实时动作游戏设计的模板，提供： 高频物理更新（30 FPS） 客户端预测和插值 碰撞检测辅助 分数和排行榜 适用游戏类型： 多人 FlappyBird / 跑酷游戏 2D 多人射击游戏 实时躲避游戏 多人竞速游戏 使用示例： public class MyFlappyBird : RealtimeActionGameTemplate { protected override void OnRealtimeServerTick(float deltaTime) { // 更新所有玩家物理 UpdateAllPlayers(deltaTime); // 更新障碍物 UpdateObstacles(deltaTime); // 检测碰撞 CheckCollisions(); } }

构造函数 ​

RealtimeActionGameTemplate 双端 ​

csharp
protected RealtimeActionGameTemplate()

属性 ​

GameTime 仅服务端 ​

csharp
protected float GameTime { get; }

游戏时间（秒）

ServerTickCount 仅服务端 ​

csharp
protected int ServerTickCount { get; }

服务端 Tick 计数（用于客户端同步）

方法 ​

OnServerInitialize 仅服务端 ​

csharp
protected override void OnServerInitialize()

OnPlayerJoined 仅服务端 ​

csharp
protected override void OnPlayerJoined(Player player)

OnPlayerLeft 仅服务端 ​

csharp
protected override void OnPlayerLeft(Player player)

OnServerTick 仅服务端 ​

csharp
protected override void OnServerTick(float deltaTime)

OnRealtimeServerTick 仅服务端 ​

csharp
protected virtual void OnRealtimeServerTick(float deltaTime)

子类重写：实时游戏逻辑（每帧调用）

  • deltaTime — 帧时间（秒）

OnPlayerSpawn 仅服务端 ​

csharp
protected virtual void OnPlayerSpawn(Player player)

子类重写：玩家生成/重生

  • player — 玩家

KillPlayer 仅服务端 ​

csharp
protected void KillPlayer(Player player)

玩家死亡

  • player — 死亡的玩家

OnPlayerDied 仅服务端 ​

csharp
protected virtual void OnPlayerDied(Player player)

子类重写：玩家死亡

  • player — 死亡的玩家

AddPlayerScore 仅服务端 ​

csharp
protected void AddPlayerScore(Player player, int points)

玩家加分

  • player — 玩家
  • points — 分数

OnPlayerScoreChanged 仅服务端 ​

csharp
protected virtual void OnPlayerScoreChanged(Player player, int newScore)

子类重写：玩家分数变化

  • player — 玩家
  • newScore — 新分数

GetPlayerScore 仅服务端 ​

csharp
protected int GetPlayerScore(Player player)

获取玩家分数

  • player — 玩家

返回： 分数

IsPlayerAlive 仅服务端 ​

csharp
protected bool IsPlayerAlive(Player player)

检查玩家是否存活

  • player — 玩家

返回： 如果存活返回 true

GetLeaderboard 仅服务端 ​

csharp
protected List<(Player player, int score)> GetLeaderboard()

获取排行榜（按分数降序）

返回： 玩家和分数列表

字段 ​

PlayerScores 仅服务端 ​

csharp
protected readonly Dictionary<int, int> PlayerScores

玩家分数字典

PlayerAliveStates 仅服务端 ​

csharp
protected readonly Dictionary<int, bool> PlayerAliveStates

玩家状态字典（存活/死亡）

Simple2DMultiplayerGame 双端 ​

命名空间 TriggerEncapsulation.GameTemplates

csharp
public abstract class Simple2DMultiplayerGame<TSelf> : IGameClass, IThinker where TSelf : Simple2DMultiplayerGame<TSelf>, new()

简化的 2D 联机游戏基类（泛型自注册版本）。 ⚠️ 已弃用，不推荐新项目使用。 这套重模板存在感低，且其「PropertyObject 同步全部 + 客户端手搓插值」 的做法对连续运动已被更优范式取代：连续运动的联机游戏改用 node 位置 + PropertyHostComponent （客户端原生平滑、零外插，见 code_sample/HybridFlappyBird、docs/systems/PropertyHostComponentSystem.md）； 离散/回合制直接用 PropertyObject。被弃用的是本模板基类，不是 PropertyObject。

备注

此基类自动处理： 游戏类自动注册（泛型，无反射） 客户端-服务端分离 PropertyObject 自动管理 消息路由和处理 UI 事件订阅 游戏循环管理 AI 开发者只需： 继承此基类并传入自身类型 定义属性枚举（可选使用 [PropertyObjectWrapper] 自动生成包装器） 实现游戏逻辑方法 实现 UI 渲染方法 使用示例： public class MyFlappyBird : Simple2DMultiplayerGame<MyFlappyBird> { protected override bool ShouldInitialize() { return Game.GameModeLink == MyGameMode; } protected override void OnServerTick(float deltaTime) { // 更新游戏逻辑 } protected override void OnClientRender() { // 渲染 UI } }

构造函数 ​

Simple2DMultiplayerGame 双端 ​

csharp
protected Simple2DMultiplayerGame()

属性 ​

IsClientRunning 仅客户端 ​

csharp
protected bool IsClientRunning { get; }

客户端是否运行中

GamePanel 仅客户端 ​

csharp
protected Panel? GamePanel { get; }

主游戏面板

GameName 双端 ​

csharp
protected virtual string GameName { get; }

游戏名称（子类可重写）

LocalPlayer 仅客户端 ​

csharp
protected Player LocalPlayer { get; }

获取本地玩家

AllPropertyObjects 仅客户端 ​

csharp
protected IEnumerable<PropertyObject> AllPropertyObjects { get; }

获取所有 PropertyObject

IsServerRunning 仅服务端 ​

csharp
protected bool IsServerRunning { get; }

服务端是否运行中

OnlinePlayerCount 仅服务端 ​

csharp
protected int OnlinePlayerCount { get; }

获取在线玩家数量

方法 ​

OnRegisterGameClass 双端 ​

csharp
public static void OnRegisterGameClass()

游戏类注册（框架自动调用）

备注

使用泛型约束自动注册，完全消除反射开销。 每个游戏类只会注册一次，确定性100%。

ShouldInitialize 双端 ​

csharp
protected virtual bool ShouldInitialize()

检查是否应该初始化此游戏（子类可重写）

返回： 如果应该初始化返回 true，否则返回 false

Initialize 双端 ​

csharp
protected virtual void Initialize()

初始化游戏

Think 双端 ​

csharp
public void Think(int deltaInMs)

IThinker 接口实现（游戏循环）

备注

服务端和客户端都使用引擎的原生 IThinker 更新频率：

  • 服务端：约 30 FPS（游戏逻辑）
  • 客户端：约 60 -200 FPS（渲染）

InitializeClient 仅客户端 ​

csharp
protected virtual void InitializeClient()

客户端初始化

StartClientLoop 仅客户端 ​

csharp
protected void StartClientLoop()

启动客户端循环（使用 IThinker）

StopClientLoop 仅客户端 ​

csharp
protected void StopClientLoop()

停止客户端循环

SetupUI 仅客户端 ​

csharp
protected virtual void SetupUI()

设置 UI

CreateGamePanel 仅客户端 ​

csharp
protected virtual Panel? CreateGamePanel()

创建游戏面板（子类可重写）

返回： 游戏面板实例

OnClientInitialize 仅客户端 ​

csharp
protected virtual void OnClientInitialize()

子类重写：客户端初始化

OnClientRender 仅客户端 ​

csharp
protected virtual void OnClientRender(float deltaTime)

子类重写：客户端渲染（每帧调用）

  • deltaTime — 帧时间（秒）

OnPropertyObjectCreated 仅客户端 ​

csharp
protected virtual void OnPropertyObjectCreated(PropertyObject obj)

子类重写：PropertyObject 被创建时

  • obj — 被创建的 PropertyObject

SendMessageToServer 仅客户端 ​

csharp
protected void SendMessageToServer(byte messageType, byte[]? payload = null)

发送消息到服务端

  • messageType — 消息类型
  • payload — 消息载荷（可选）

SendJsonMessageToServer 仅客户端 ​

csharp
protected void SendJsonMessageToServer<T>(byte messageType, T data)

发送JSON消息到服务端

  • messageType — 消息类型
  • data — 消息数据

Dispose 双端 ​

csharp
public virtual void Dispose()

释放资源

InitializeServer 仅服务端 ​

csharp
protected virtual void InitializeServer()

服务端初始化

StartServerLoop 仅服务端 ​

csharp
protected void StartServerLoop()

启动服务端游戏循环

StopServerLoop 仅服务端 ​

csharp
protected void StopServerLoop()

停止服务端游戏循环

OnServerInitialize 仅服务端 ​

csharp
protected virtual void OnServerInitialize()

子类重写：服务端初始化

OnServerTick 仅服务端 ​

csharp
protected virtual void OnServerTick(float deltaTime)

子类重写：服务端游戏循环（每帧调用）

  • deltaTime — 帧时间（秒）

OnPlayerJoined 仅服务端 ​

csharp
protected virtual void OnPlayerJoined(Player player)

子类重写：处理玩家加入

  • player — 加入的玩家

OnPlayerLeft 仅服务端 ​

csharp
protected virtual void OnPlayerLeft(Player player)

子类重写：处理玩家离开

  • player — 离开的玩家

RegisterMessageHandlers 仅服务端 ​

csharp
protected virtual void RegisterMessageHandlers()

注册消息处理器

RegisterMessageHandler 仅服务端 ​

csharp
protected void RegisterMessageHandler(byte messageType, Action<Player, byte[]> handler)

注册消息处理器

  • messageType — 消息类型
  • handler — 处理器函数

RegisterJsonMessageHandler 仅服务端 ​

csharp
protected void RegisterJsonMessageHandler<T>(byte messageType, Action<Player, T> handler)

注册JSON消息处理器

  • messageType — 消息类型
  • handler — 处理器函数

OnClientMessageReceived 仅服务端 ​

csharp
protected virtual bool OnClientMessageReceived(Player player, byte messageType, byte[] payload)

子类重写：处理客户端消息

  • player — 发送消息的玩家
  • messageType — 消息类型
  • payload — 消息载荷

返回： 如果消息被处理返回 true

CreateGameObject 仅服务端 ​

csharp
protected PropertyObject CreateGameObject(Player owner, SyncType syncType = SyncType.All)

创建游戏对象

  • owner — 对象所有者
  • syncType — 同步类型

返回： 创建的 PropertyObject

DestroyGameObject 仅服务端 ​

csharp
protected void DestroyGameObject(PropertyObject obj)

销毁游戏对象

  • obj — 要销毁的对象

CleanupInvalidObjects 仅服务端 ​

csharp
protected virtual void CleanupInvalidObjects()

清理无效对象

DestroyAllGameObjects 仅服务端 ​

csharp
protected void DestroyAllGameObjects()

销毁所有游戏对象

GetOnlinePlayers 仅服务端 ​

csharp
protected IEnumerable<Player> GetOnlinePlayers()

获取所有在线玩家

返回： 在线玩家列表

字段 ​

GameObjects 仅服务端 ​

csharp
protected readonly List<PropertyObject> GameObjects

游戏对象列表

TurnBasedGameTemplate 双端 ​

命名空间 TriggerEncapsulation.GameTemplates

csharp
public abstract class TurnBasedGameTemplate<TSelf> : Simple2DMultiplayerGame<TSelf> where TSelf : TurnBasedGameTemplate<TSelf>, new()

回合制游戏模板基类。 ⚠️ 已弃用，不推荐新项目使用。 回合制/离散状态的联机游戏直接用 PropertyObject 同步数据 （见 docs/Simple2DMultiplayer/PropertyObject.md），无需此重模板基类。

备注

专为回合制游戏设计的模板，自动处理： 回合顺序管理 玩家行动限制 回合计时器 游戏阶段控制 适用游戏类型： 多人卡牌对战（炉石传说类） 在线棋类游戏（五子棋、围棋、象棋） 回合制策略游戏（火焰纹章类） 使用示例： public class MyChessGame : TurnBasedGameTemplate { protected override void OnPlayerTurnStart(Player player) { // 玩家回合开始时的逻辑 } protected override void OnPlayerAction(Player player, byte[] actionData) { // 处理玩家行动 } }

构造函数 ​

TurnBasedGameTemplate 双端 ​

csharp
protected TurnBasedGameTemplate()

属性 ​

CurrentTurnPlayer 仅服务端 ​

csharp
protected Player? CurrentTurnPlayer { get; }

当前回合玩家

CurrentTurn 仅服务端 ​

csharp
protected int CurrentTurn { get; }

当前回合数

TurnTimer 仅服务端 ​

csharp
protected float TurnTimer { get; }

回合计时器（秒）

TurnTimeLimit 仅服务端 ​

csharp
protected virtual float TurnTimeLimit { get; }

回合时间限制（秒，0表示无限制）

方法 ​

OnServerInitialize 仅服务端 ​

csharp
protected override void OnServerInitialize()

InitializePlayerOrder 仅服务端 ​

csharp
protected virtual void InitializePlayerOrder()

初始化玩家顺序

OnPlayerJoined 仅服务端 ​

csharp
protected override void OnPlayerJoined(Player player)

OnPlayerLeft 仅服务端 ​

csharp
protected override void OnPlayerLeft(Player player)

OnServerTick 仅服务端 ​

csharp
protected override void OnServerTick(float deltaTime)

NextTurn 仅服务端 ​

csharp
protected void NextTurn()

下一回合

IsPlayerTurn 仅服务端 ​

csharp
protected bool IsPlayerTurn(Player player)

检查是否是玩家的回合

  • player — 要检查的玩家

返回： 如果是该玩家的回合返回 true

OnTurnBasedServerTick 仅服务端 ​

csharp
protected virtual void OnTurnBasedServerTick(float deltaTime)

子类重写：回合制游戏循环

  • deltaTime — 帧时间（秒）

OnPlayerTurnStart 仅服务端 ​

csharp
protected virtual void OnPlayerTurnStart(Player player)

子类重写：玩家回合开始

  • player — 回合玩家

OnPlayerTurnEnd 仅服务端 ​

csharp
protected virtual void OnPlayerTurnEnd(Player player)

子类重写：玩家回合结束

  • player — 回合玩家

OnRoundStart 仅服务端 ​

csharp
protected virtual void OnRoundStart(int round)

子类重写：新一轮开始（所有玩家都行动过一次）

  • round — 轮数

字段 ​

PlayerOrder 仅服务端 ​

csharp
protected readonly List<Player> PlayerOrder

玩家顺序列表