支持多人数对局与 AI 补位：玩法声明人数范围、匹配分队列与超时补 AI、房间玩家名册

internal/game/engine.go

@@ -26,7 +26,7 @@ type Action struct {
 
 // Event 描述「发给谁、发什么」：投递由房间完成，玩法不接触连接。
 type Event struct {
-	To      []int64 // 收件人；nil 或空表示房间内全体广播
+	To      []int64 // 收件人；nil 或空表示全体广播
 	Name    string  // 事件名，客户端据此分发
 	Payload any     // 事件内容
 }
@@ -35,7 +35,7 @@ type Event struct {
 type Finish struct {
 	Winner int64         // 获胜用户 ID，0 表示平局
 	Scores map[int64]int // 各用户得分，可为空
-	Reason string        // 结束原因：normal/opponent_leave/timeout
+	Reason string        // 结束原因：normal / opponent_leave / timeout
 }
 
 // State 是玩法私有状态：房间只做透传，具体类型由玩法在 Init 中创建。
@@ -52,6 +52,19 @@ type Game interface {
 	Snapshot(uid int64, s State) any                                 // 按观众裁剪的可见状态（重连/观战用）
 }
 
+// AIAction 是 AI 玩家要执行的一次动作：带执行者，便于房间代它调用 OnAction。
+type AIAction struct {
+	UID    int64  // 执行者（AI 的 uid）
+	Action Action // 要执行的动作
+}
+
+// AIBrain 是可选接口：玩法实现它即可支持「AI 补位」。
+// 房间在每次推进前调用一次，把返回的动作代 AI 执行；不实现该接口的玩法不会被补 AI。
+type AIBrain interface {
+	// TickAI 返回本回合所有 AI 玩家要执行的动作（含思考延迟由玩法内部决定）。
+	TickAI(now int64, s State) []AIAction
+}
+
 // Factory 创建玩法实例：每局一个新实例，保证状态隔离。
 type Factory func() Game
 
@@ -78,7 +91,7 @@ func New(gameID string) (Game, error) {
 	return f(), nil // 返回新实例
 }
 
-// LookupMeta 取已注册玩法的元信息：匹配器用它决定队列人数。
+// LookupMeta 取已注册玩法的元信息（匹配器用它决定队列人数）。
 func LookupMeta(gameID string) (Meta, error) {
 	g, err := New(gameID) // 先建实例
 	if err != nil {       // 未注册
@@ -86,3 +99,9 @@ func LookupMeta(gameID string) (Meta, error) {
 	}
 	return g.Meta(), nil // 返回元信息
 }
+
+// HasAIBrain 判断玩法是否支持 AI 补位（实现了 AIBrain 接口）。
+func HasAIBrain(g Game) bool {
+	_, ok := g.(AIBrain)
+	return ok
+}