星火 2.0 开发文档

主题

游戏模板 ​

游戏模板提供 2D 联机游戏的快速开发基类，封装了客户端-服务端分离、PropertyObject 同步、消息路由、游戏循环和 UI 管理等通用逻辑。

核心类型 ​

类型说明
Simple2DMultiplayerGame<TSelf>2D 联机游戏基类，提供完整的生命周期管理
TurnBasedGameTemplate<TSelf>回合制游戏模板，添加回合管理和计时
RealtimeActionGameTemplate<TSelf>实时动作游戏模板，添加分数和玩家状态管理
GameTemplateUtilitiesPropertyObject 查询和网格坐标工具方法

继承关系 ​

Simple2DMultiplayerGame<TSelf> : IGameClass, IThinker
 ├── TurnBasedGameTemplate<TSelf>     回合制
 └── RealtimeActionGameTemplate<TSelf> 实时动作

Simple2DMultiplayerGame&lt;TSelf&gt; ​

所有 2D 联机游戏模板的基类。通过泛型 CRTP 模式实现自动注册（无反射）。

使用方式 ​

csharp
public class MyGame : Simple2DMultiplayerGame<MyGame>
{
    protected override bool ShouldInitialize()
    {
        return Game.GameModeLink == ScopeData.GameDataGameMode.MapGameMode;
    }

#if SERVER
    protected override void OnServerInitialize()
    {
        // 初始化游戏状态
    }

    protected override void OnServerTick(float deltaTime)
    {
        // 每帧更新游戏逻辑
    }
#endif

#if CLIENT
    protected override void OnClientInitialize()
    {
        // 初始化客户端 UI
    }

    protected override void OnClientRender(float deltaTime)
    {
        // 每帧渲染
    }
#endif
}

自动处理 ​

  • OnRegisterGameClass() — 泛型自动注册，框架自动调用
  • ShouldInitialize() — 子类重写决定是否初始化
  • IThinker.Think() — 自动分发到 OnServerTick() 或 OnClientRender()
  • 玩家连接/断开事件自动注册
  • 无效 PropertyObject 自动清理

服务端 API ​

方法/属性说明
OnServerInitialize()服务端初始化回调
OnServerTick(float deltaTime)每帧游戏逻辑（~30 FPS）
OnPlayerJoined(Player)玩家加入回调
OnPlayerLeft(Player)玩家离开回调
StartServerLoop() / StopServerLoop()控制服务端循环
IsServerRunning服务端循环是否运行
GetOnlinePlayers()获取所有在线玩家
OnlinePlayerCount在线玩家数量

客户端 API ​

方法/属性说明
OnClientInitialize()客户端初始化回调
OnClientRender(float deltaTime)每帧渲染（~60-200 FPS）
SetupUI() / CreateGamePanel()创建主游戏面板
GamePanel主游戏面板实例
OnPropertyObjectCreated(PropertyObject)服务端对象同步到客户端时回调
StartClientLoop() / StopClientLoop()控制客户端循环
IsClientRunning客户端循环是否运行
LocalPlayer本地玩家
AllPropertyObjects所有 PropertyObject

PropertyObject 管理（服务端） ​

方法说明
CreateGameObject(Player owner, SyncType)创建游戏对象，自动加入管理列表
DestroyGameObject(PropertyObject)销毁并从列表移除
DestroyAllGameObjects()销毁所有游戏对象
CleanupInvalidObjects()清理无效对象（每帧自动调用）
GameObjects游戏对象列表

消息系统 ​

服务端注册处理器：

csharp
#if SERVER
protected override void OnServerInitialize()
{
    base.OnServerInitialize();
    RegisterMessageHandler(0x01, OnPlayerMove);
    RegisterJsonMessageHandler<MoveData>(0x02, OnPlayerMoveJson);
}

private void OnPlayerMove(Player player, byte[] payload) { /* ... */ }
private void OnPlayerMoveJson(Player player, MoveData data) { /* ... */ }

protected override bool OnClientMessageReceived(Player player, byte messageType, byte[] payload)
{
    // 未注册的消息类型走这里
    return false;
}
#endif

客户端发送消息：

csharp
#if CLIENT
SendMessageToServer(0x01, payloadBytes);
SendJsonMessageToServer(0x02, new MoveData { X = 100, Y = 200 });
#endif

TurnBasedGameTemplate&lt;TSelf&gt; ​

继承自 Simple2DMultiplayerGame<TSelf>，添加回合制管理。

使用方式 ​

csharp
public class MyChessGame : TurnBasedGameTemplate<MyChessGame>
{
#if SERVER
    protected override void OnPlayerTurnStart(Player player)
    {
        // 玩家回合开始
    }

    protected override void OnPlayerTurnEnd(Player player)
    {
        // 玩家回合结束
    }

    protected override void OnRoundStart(int round)
    {
        // 新一轮开始（所有玩家都行动过一次）
    }
#endif
}

服务端 API ​

方法/属性说明
CurrentTurnPlayer当前回合玩家
CurrentTurn当前回合数
PlayerOrder玩家行动顺序列表
TurnTimer当前回合计时（秒）
TurnTimeLimit回合时间限制（默认 60 秒，0 为无限制）
NextTurn()切换到下一个玩家
IsPlayerTurn(Player)检查是否是指定玩家的回合
InitializePlayerOrder()初始化玩家顺序（可重写）
OnPlayerTurnStart(Player)回合开始回调
OnPlayerTurnEnd(Player)回合结束回调
OnRoundStart(int round)新一轮回调
OnTurnBasedServerTick(float)回合制游戏循环

超时自动切换到下一个玩家。玩家离开时自动跳过其回合。

RealtimeActionGameTemplate&lt;TSelf&gt; ​

继承自 Simple2DMultiplayerGame<TSelf>，添加实时游戏状态管理。

使用方式 ​

csharp
public class MyFlappyBird : RealtimeActionGameTemplate<MyFlappyBird>
{
#if SERVER
    protected override void OnRealtimeServerTick(float deltaTime)
    {
        // 更新物理、碰撞、障碍物
    }

    protected override void OnPlayerSpawn(Player player)
    {
        // 玩家生成/重生
    }

    protected override void OnPlayerDied(Player player)
    {
        // 玩家死亡处理
    }
#endif
}

服务端 API ​

方法/属性说明
GameTime游戏时间（秒）
ServerTickCount服务端 Tick 计数
PlayerScores玩家分数字典
PlayerAliveStates玩家存活状态字典
OnRealtimeServerTick(float)实时游戏循环
OnPlayerSpawn(Player)玩家生成回调
KillPlayer(Player)击杀玩家
OnPlayerDied(Player)玩家死亡回调
AddPlayerScore(Player, int)加分
OnPlayerScoreChanged(Player, int)分数变化回调
GetPlayerScore(Player)获取分数
IsPlayerAlive(Player)检查是否存活
GetLeaderboard()获取排行榜（按分数降序）

GameTemplateUtilities ​

PropertyObject 查询和网格坐标的扩展方法。

方法说明
FindByProperty<P,V>(property, value)按属性值查找 PropertyObject
InGroup(groupId)按 GroupId 过滤
OrderByIndex()按 OrderIndex 排序
OwnedBy(player)按所有者过滤
HasProperty<P>(property)检查是否包含属性
SetGridPosition(x, y, gridWidth)设置网格位置（编码为 OrderIndex）
GetGridPosition(gridWidth)获取网格位置（解码 OrderIndex）
EncodeGridPosition(x, y, gridWidth)编码二维坐标为索引
DecodeGridPosition(index, gridWidth)解码索引为二维坐标

相关文档 ​