agame/docs/联机框架使用指南.md

# 联机框架使用指南

面向「完全没接触过联机」的开发者的入门文档。
读完你应该能做到三件事：跑起联机、给自己新做的功能加上同步、把传输层换成 Steam P2P。

---

## 0. 一句话总览

这个框架把玩家角色拆成两种身份：**一个是「我在操作的角色」，其余都是「别人在操作的角色」**。

- 我在操作的那个：读键盘鼠标、跑物理、开相机。
- 别人的那些：什么都不算，只是把「对面发过来的位置和朝向」照着摆一遍。

联机要做的全部事情，就是让每台机器对**同一份状态**达成一致。其余都是细节。

---

## 1. 先搞懂四个概念（不用懂网络）

### 1.1 对等端（peer）与 peer id

联机里的每一台机器叫一个 **peer**，各自有一个数字编号 `peer id`。
本项目用的是 ENet（客户端-服务器模型），所以：

| 角色 | peer id | 说明 |
|---|---|---|
| 主机（host） | **1** | 同时是「服务器」和「一个玩家」 |
| 第 1 个加入的人 | 随机大数（如 1334014715） | |
| 第 2 个加入的人 | 另一个随机大数 | |

> 注意：ENet 不是「人人平等」的 P2P，它是**主机当服务器**。主机退出 = 所有人掉线。
> Steam 那套才是真正的 P2P（第 5 章），但上层代码完全一样。

### 1.2 authority（中文：权威方）

**每个节点都有一个 authority，表示「谁有权说了算」。** 默认是 1（服务器）。

- `is_multiplayer_authority()` 返回 `true` → 这个节点归我管，我可以改它。
- 返回 `false` → 这个节点是别人的镜像，**我改了也会被对方的下一次同步覆盖回去**。

这是全篇最重要的一条规则。你新增任何同步逻辑前，都要先问：

> **这个值该由谁来改？**

### 1.3 复制（replication）与 RPC

两种同步手段，分工明确：

| | 复制（Replication） | RPC（远程过程调用） |
|---|---|---|
| 适合 | **持续变化的状态**：位置、朝向、血量、姓名 | **一次性事件**：开了一枪、捡到东西、发一句话 |
| 机制 | 引擎按固定频率自动把属性值发出去 | 你主动调用一个函数，它在别的机器上跑 |
| 丢包 | 丢了无所谓，下一次同步会补上最新值 | 用 `reliable` 保证必达 |
| 本项目用在哪 | `Player/Sync`（位置 + 朝向） | 目前还没用，你加功能时才会用到 |

一句话记法：**状态用复制，事件用 RPC。**

### 1.4 节点路径必须一致

RPC 和复制都是靠**节点路径**找到对面对应的节点。所以：

- 玩家节点在各端的名字必须一样（本项目用 `str(peer_id)` 当名字）。
- 别在运行时给节点随机改名，否则对端会报 `Node not found`。

---

## 2. 框架由哪些文件组成

```
E:\GD_Projects\agame\
├── autoload\
│   ├── net.tscn            ← 联机总入口（Autoload 名：Net，指向这个场景）
│   │      Net (CanvasLayer)          ← 挂 net.gd
│   │        ├─ Menu  (CenterContainer)   ← 主菜单：标题/地址框/两个按钮/状态/提示
│   │        └─ Hud   (Control)           ← 游戏内 HUD：状态 + 操作提示
│   └── net.gd              ← 管传输层、开局/加入/断开、玩家生成回收；
│                              UI 是节点配置，这里只改文字、切显隐
├── world\
│   ├── main.tscn           ← 世界根场景
│   │      Main (Node3D)
│   │        ├─ Ground / Sun / Environment
│   │        └─ MultiplayerSpawner   ← 玩家由它动态生成，场景里不再硬编码 Player
│   └── main.gd             ← 只做一件事：告诉 Spawner「生成玩家时用 player.tscn，
│                              并把那个玩家的 authority 设成对应的 peer id」
├── player\
│   ├── player.tscn         ← 玩家场景
│   │      Player (CharacterBody3D)
│   │        ├─ Collision
│   │        ├─ CameraRig → SpringArm → Camera   ← 远端玩家会被删掉这一支
│   │        ├─ Body → Mesh                      ← 视觉层，换角色模型挂这里
│   │        ├─ Sync (MultiplayerSynchronizer)   ← 负责同步位置和朝向
│   │        └─ HealthLabel (Label3D)            ← 头顶血条（3D 世界里的文字，跟着角色走）
│   ├── player.gd           ← 加了「本地 / 远端」分支
│   └── player_sync.tres    ← 同步配置：到底同步哪几个属性
└── tests\
    └── test_net_replication.gd  ← 回归测试，防止同步配置被静默改坏
```

**数据流（创建主机 → 有人加入）**

```
主机                             客户端
 │ 点「创建主机」                     │ 点「加入主机」
 │ ENetMultiplayerPeer.create_server │ ENetMultiplayerPeer.create_client
 │        ↓                          │        ↓
 │ multiplayer.multiplayer_peer = peer ←── 同一个多人系统，只是 peer 不同
 │        ↓                          │
 │ 服务器收到 peer_connected(id)      │
 │ Net._spawn_player(id)             │
 │        ↓                          │
 │ MultiplayerSpawner.spawn(id) ─────→ 客户端收到「生成一个玩家」的指令
 │        ↓                          │        ↓
 │ 各端都执行 spawn_function          │ 各端都执行 spawn_function
 │        ↓                          │        ↓
 │ 设 authority = id（递归到子节点）   │ 设 authority = id（递归到子节点）
 │        ↓                          │        ↓
 │ id≠我 → 远端回放                   │ id=我 → 本地操控（读输入、开相机）
```

---

## 3. 把联机跑起来

### 3.1 方式一：编辑器里双开（最方便）

Godot 编辑器菜单 **调试 → 运行多个实例 → 2 个实例**（Debug → Run Multiple Instances），然后：

1. 第一个窗口点「创建主机」。
2. 第二个窗口地址栏填 `127.0.0.1`，点「加入主机」。
3. 两个窗口里都应该看到两个胶囊体，鼠标各自控制自己的那个。

### 3.2 方式二：命令行双开

我在 `net.gd` 里加了命令行参数入口，方便自动化测试：

```powershell
# 假设 Godot 在 E:\Godot_v4.7.2-stable_mono_win64\
$g = 'E:\Godot_v4.7.2-stable_mono_win64\Godot_v4.7.2-stable_mono_win64.exe'

# 主机
Start-Process $g -ArgumentList @('--path','E:\GD_Projects\agame','--','--host')
# 加入
Start-Process $g -ArgumentList @('--path','E:\GD_Projects\agame','--','--join','127.0.0.1')
```

想抓日志（**Godot 在 Windows 上不往重定向的 stdout 写日志，必须用 `--log-file`**）：

```powershell
Start-Process $g -ArgumentList @(
  '--headless','--log-file','C:\temp\host.log',
  '--path','E:\GD_Projects\agame','--','--host'
) -PassThru
```

### 3.3 方式三：局域网真机

1. 主机那台机器查自己的内网 IP（`ipconfig`，看 `192.168.x.x` 或 `10.x.x.x`）。
2. 客户端在地址栏填这个 IP，点加入。
3. 连不上先查 Windows 防火墙是否拦了游戏进程，以及端口 `7000`（`Net.PORT`）是否放行。

### 3.4 一切正常时你该看到什么

```
主机日志                              客户端日志
[Net] 主机已启动，端口 7000            [Net] 正在连接 127.0.0.1:7000
[Net] 本端 1 生成玩家 1（本地操控）      [Net] 已连接，等待主机生成角色
[Net] 本端 1 生成玩家 1334014715（远端回放）  [Net] 本端 1334014715 生成玩家 1（远端回放）
                                      [Net] 本端 1334014715 生成玩家 1334014715（本地操控）
```

两边日志**互为镜像**，而且**每一端恰好有一个「本地操控」**——这就是联机正常的标志。

游戏里：`F10` 断开，`Esc` 释放鼠标。

---

## 4. 日常开发：我新做的功能怎么同步？

### 4.0 先做决策

拿到一个需求，先按下表判断，不要一上来就写 `@rpc`。

| 你的需求 | 用什么 | 去哪看 |
|---|---|---|
| 血量、蓝量、名字、皮肤 id、瞄准方向这类**状态** | 复制 | 配方 A（4.1） |
| 开火、拾取、受击、播放某个动画、聊天这类**一次性的动作** | RPC | 配方 B（4.2） |
| 子弹、掉落物、怪物这类**运行时才出现/消失的东西** | 第二个 MultiplayerSpawner | 配方 C（4.3） |
| 刷怪规则、计分、房间设置这类**必须由一个人说了算的东西** | 服务器权威 + RPC | 配方 D（4.4） |

### 4.1 配方 A：新增一个持续同步的状态

**例子：给玩家加血量 `health`。**

**第 1 步**，在 `player/player.gd` 里声明变量。加 `@export` 是为了能在 Inspector 里看到，同步本身不要求：

```gdscript
@export var health: int = 100
```

**第 2 步**，把这个属性加进同步配置 `player/player_sync.tres`。两种改法，任选：

- **图形化**：打开 `player.tscn` → 选中 `Sync` 节点 → Inspector 里 `Replication Config` 点开那个 `.tres` → **Add property** → 选 `health` → 勾上 **Spawn** → **Replication Mode** 选 `Always`。
- **直接改文本**，在文件末尾追加三行（编号接着往下排）：

  ```
  properties/2/path = NodePath(".:health")
  properties/2/spawn = true
  properties/2/replication_mode = 1
  ```

  三个字段的含义：

  | 字段 | 含义 |
  |---|---|
  | `path` | 属性路径，相对 `Sync.root_path`（本项目是 `..`，也就是 `Player` 本级）。`.:health` = Player 自己的 health；`Body:rotation` = Player/Body 的 rotation |
  | `spawn` | 生成时是否把这个值一起带过去。**必须 true**，否则新加入的人看到的是代码里的默认值而不是当前值 |
  | `replication_mode` | `0` = 从不同步，`1` = 每帧同步，`2` = 值变了才同步 |

**第 3 步**，改血量时，**只能在权威端改**：

```gdscript
if is_multiplayer_authority():
    health -= 10
```

如果你在非权威端直接 `health -= 10`，效果会闪一下又被对端的旧值覆盖回来。

> `replication_mode = 2`（只在变化时同步）能省流量，但要注意它靠对比上一帧的值判断，对浮点数频繁微变的属性效果不好。

### 4.2 配方 B：新增一个一次性事件（RPC）

RPC 的本质是「调用一个函数，它在别的机器上也会跑一遍」。Godot 用注解 `@rpc` 标记哪些函数可以被远程调用。

```gdscript
## 三项参数的含义：
##   1. 谁可以调用： "authority"（默认，只有权威方能调）| "any_peer"（谁都能调）
##   2. 本地是否也执行："call_local"（本地也跑）| "call_remote"（只跑远程，默认）
##   3. 可靠性与顺序："reliable"（必达，默认）| "unreliable"（丢了就算）
##                  | "unreliable_ordered"（只保留最新的，位置类数据用这个）
@rpc("any_peer", "reliable")
func request_shoot(target_position: Vector3) -> void:
    # 请求会同时到达所有人，但只有权威端需要处理，其余端直接丢掉
    if not is_multiplayer_authority():
        return
    # 校验放这里：冷却、弹药、距离、视线……不通过就直接 return
    if _cooldown > 0.0:
        return
    _cooldown = 0.5
    # 校验通过，由权威端广播结果
    _broadcast_shoot.rpc(target_position)


## "authority" + "call_local" 是最常用的组合：
## 只有权威端能发起，且发起方自己也执行一遍（保证本地表现和远程一致）
@rpc("authority", "call_local", "reliable")
func _broadcast_shoot(target_position: Vector3) -> void:
    spawn_muzzle_flash()
    play_shoot_sound()
```

**怎么调用**：

```gdscript
_broadcast_shoot.rpc(target_position)              # 发给所有 peer（本地按 call_local 决定跑不跑）
_broadcast_shoot.rpc_id(some_peer_id, pos)         # 只发给指定 peer
```

**三个必须知道的坑**：

1. **路径一致性**：`@rpc` 函数所在节点的路径必须在所有端完全相同。所以别给节点随机改名。
2. **别用 `@rpc` 传节点引用**。传 `Vector3`、`int`、`String`、`Array`、`Dictionary` 这类纯数据。要传「哪个对象」就传它的 `name` 或你自己编的 id，对端自己查。
3. **请求（request）和结果（broadcast）要分成两个函数**。别让「客户端直接执行动作」——那样人人都能作弊。本项目现在的玩家位置是客户端权威的（简单但不安全），如果你要做多人对战，参考配方 D 把关键逻辑搬到服务器。

### 4.3 配方 C：同步运行时生成/销毁的物体

**一个 `MultiplayerSpawner` 只管一种节点。** 要加子弹，就再加一个 spawner。

**第 1 步**，在 `main.tscn` 里找个容器当子弹的父节点（也可以直接用 `Main`），挂一个新的 `MultiplayerSpawner`：

```
Main
 ├─ MultiplayerSpawner        spawn_path = ..     → 生成玩家
 ├─ Bullets (Node3D)          ← 新建，用来收纳子弹
 │   └─ BulletSpawner (MultiplayerSpawner)   spawn_path = ..  → 生成子弹
 └─ ...
```

`spawn_path` 要指向**子弹的父节点**（相对 spawner 自己）。路径在每台机器上都一样，这是硬要求。

**第 2 步**，写一个类似 `world/main.gd` 的脚本给子弹容器，注册生成函数：

```gdscript
extends Node3D

const BULLET_SCENE: PackedScene = preload("res://combat/bullet.tscn")

@onready var spawner: MultiplayerSpawner = $BulletSpawner


func _ready() -> void:
    spawner.spawn_function = _create_bullet


## 这个函数会在每一端各跑一次，参数 data 由 spawn() 的调用方决定
func _create_bullet(data: Dictionary) -> Node:
    var bullet := BULLET_SCENE.instantiate()
    bullet.name = str(data["id"])            # 名字必须各端一致，用你自己编的唯一 id
    bullet.global_position = data["position"]
    bullet.direction = data["direction"]
    return bullet


## 只允许权威端/服务器调用
func fire(position: Vector3, direction: Vector3) -> void:
    if not multiplayer.is_server():
        return
    spawner.spawn({"id": _next_id(), "position": position, "direction": direction})
```

**第 3 步**，销毁就是 `queue_free()`——spawner 会自动把「销毁」这件事同步给其他端：

```gdscript
bullet.queue_free()
```

> **别在多台机器上各自生成**。只有服务器（或该物体的权威端）能调 `spawn()`，其他人通过同步收到。

### 4.4 配方 D：把关键逻辑交给服务器

现在的模型是「每个人管自己」，好处是简单、无延迟；坏处是**玩家能改自己的客户端作弊**（比如改速度、瞬移）。

哪类必须搬给服务器：涉及胜负、资源、其他玩家的判定。

```gdscript
## 客户端：我要捡这个箱子
@rpc("any_peer", "reliable")
func request_pickup(item_name: String) -> void:
    if not multiplayer.is_server():
        return
    var node := get_node_or_null("../Items/" + item_name)
    if node == null or node.claimed:
        return                                        # 服务器校验：不存在或已被捡走
    node.claimed = true                               # 服务器记状态
    _play_pickup.rpc(item_name)                       # 再广播给所有人


## 服务器 → 所有人：这个箱子没了
@rpc("authority", "call_local", "reliable")
func _play_pickup(item_name: String) -> void:
    var node := get_node_or_null("../Items/" + item_name)
    if node != null:
        node.queue_free()
```

常用的判断函数：

| 函数 | 含义 |
|---|---|
| `multiplayer.is_server()` | 我是不是服务器（主机是，客户端不是） |
| `multiplayer.get_unique_id()` | 我的 peer id |
| `multiplayer.get_peers()` | 我知道的其他 peer id 列表 |
| `is_multiplayer_authority()` | 当前节点归不归我管 |

### 4.5 想让别的玩家看到我的模型/动画

好消息：**不需要任何额外工作**。`player.tscn` 是同一份场景，你只要把模型挂到 `Body` 节点下面，所有端都会看到：

```
Player
 └─ Body            ← 换角色模型就挂这里；它是一个 Node3D，本体 Player 不跟着转
     └─ Mesh / 骨骼模型
```

要注意的是**驱动方式**：

- 「转身」现在同步的是 `Body:rotation`（视觉层的朝向），**不是** `Player:rotation`。因为 `player.gd` 里本体是不旋转的（只把 `Body` 转过去）。同步错了这一项，远端玩家的朝向就会一直是初始值。
- 远端玩家的动画**不能靠输入驱动**（远端玩家读不到键盘）。正确做法：把「状态」同步出去（比如 `@export var move_speed: float`），动画机只读这个状态。

### 4.6 五个必踩的坑（收藏这一段）

| 现象 | 原因 | 修法 |
|---|---|---|
| 远端玩家僵在原地不动 | 同步配置没生效（`.tres` 键名写错 / `replication_mode` 是 0 / 没绑定） | 跑 `tests/test_net_replication.gd` |
| 远端玩家位置一改就弹回去 | 你在非权威端改了被同步的属性 | 加 `if is_multiplayer_authority():` 判断 |
| 画面里有好几个视角在打架 | 多台 `Camera3D` 抢渲染 | 远端玩家必须 `camera_rig.queue_free()` |
| 远端玩家抽搐、漂移、穿地 | 两端都在跑 `move_and_slide()` | 远端玩家 `set_physics_process(false)` |
| 报 `Node not found` / 同步完全不发 | 节点路径各端不一致 | 节点名用 `str(peer_id)` 这类确定性值，别随机命名 |

另外有一条**最阴的**：**节点 authority 不会自动继承给子节点**。所以 `set_multiplayer_authority()` 必须传第二个参数 `true`：

```gdscript
player.set_multiplayer_authority(peer_id, true)   # true = 递归设置所有子节点
```

漏了这个 `true`，`MultiplayerSynchronizer`（子节点）仍然认为自己是服务器的，同步**一条都不会发，而且不报任何错**。

---

## 5. 改成 Steam P2P

### 5.0 好消息：只需要改一个文件

`Net` 之外的所有文件（RPC、Spawner、Synchronizer、`player.gd`、`main.gd`）**一个字都不用动**。
因为它们操作的都是引擎级的抽象（`MultiplayerAPI`），跟底层用的是 ENet 还是 Steam 无关。

要改的只有 `autoload/net.gd` 里的 `host_game()` 和 `join_game()` 两个函数。

### 5.1 准备工作

1. **装 Steam 客户端并登录**。不登录，`steamInitEx` 会返回 `{ "status": 1, ... }`。
2. **拿到真实 AppID**。当前代码里是 `480`，这是 Valve 的 Spacewar 测试 AppID，只能本机/好友小范围测试，大厅搜索、邀请等功能受限。把 `autoload/steamworks.gd` 第一行的 `steam_app_id` 改成你自己的 AppID。
3. **在项目根目录放一个 `steam_appid.txt`**（不是 `res://` 里面，是 `.godot` 同级的真实路径），内容就是 AppID 数字。
   > 这个是 Steamworks SDK 的调试机制，只在编辑器/本地调试时需要；正式打包发布**不要**带上它。
4. 启动游戏看日志，确认出现 `Did Steam initialize?: { "status": 0, ... }`（`0` = 成功）。

`status` 的含义：`0` OK、`1` 找不到 Steam 客户端、`2` 没有 AppID、`3` 版本不匹配。

### 5.2 最小改法：SteamID 直连（约 20 行）

跟现在的 ENet 版几乎一模一样——地址栏从「IP」变成「主机的 SteamID」。

```gdscript
## 创建主机
func host_game() -> void:
	var peer := SteamMultiplayerPeer.new()
	peer.set_no_delay(true)              # 实时游戏必备，关掉 Nagle 攒包
	var err := peer.create_host(0)       # 参数是虚拟端口，0 = 默认
	if err != OK:
		_set_status("创建主机失败：%s" % error_string(err))
		return
	multiplayer.multiplayer_peer = peer
	_show_game_ui()
	print("[Net] 主机已启动。你的 SteamID = %d，把它发给队友" % Steam.getSteamID())
	call_deferred("_spawn_player", 1)


## 加入主机。这里的 address 传的是主机的 SteamID（纯数字）
func join_game(address: String = "") -> void:
	var target := address.strip_edges()
	if not target.is_valid_int():
		_set_status("请填主机的 SteamID（纯数字）")
		return
	var peer := SteamMultiplayerPeer.new()
	peer.set_no_delay(true)
	var err := peer.create_client(int(target), 0)
	if err != OK:
		_set_status("连接失败：%s" % error_string(err))
		return
	multiplayer.multiplayer_peer = peer
	_set_status("正在连接 SteamID %s …" % target)
```

配套的小调整：
- 菜单里的提示文字改成「填主机的 SteamID」，地址栏默认值 `127.0.0.1` 改成空。
- 主机的 SteamID 建议显示在 HUD 上，方便念给队友。

**代价**：得手动交换 SteamID（截图、复制粘贴）。想让玩家自己搜房间，用 5.3。

### 5.3 完整改法：Steam 大厅（官方推荐）

思路：**先用 Steam 大厅找人，再把大厅 id 交给 `SteamMultiplayerPeer`**。

```
主机                                   客户端
 createLobby(PUBLIC, 4)               requestLobbyList() → lobby_match_list
      ↓ 信号 lobby_created                  ↓ 从列表里挑一个
 host_with_lobby(lobby_id)            joinLobby(lobby_id)
      ↓                                    ↓ 信号 lobby_joined
 multiplayer.multiplayer_peer = peer  connect_to_lobby(lobby_id)
                                           ↓
                                      multiplayer.multiplayer_peer = peer
```

```gdscript
# ---------------- 主机：建大厅 ----------------

func host_game_lobby(max_members: int = 4) -> void:
	Steam.lobby_created.connect(_on_lobby_created, CONNECT_ONE_SHOT)
	Steam.createLobby(Steam.LOBBY_TYPE_PUBLIC, max_members)   # 人数上限由大厅决定


func _on_lobby_created(connect_result: int, lobby_id: int) -> void:
	if connect_result != 1:                     # 1 = 成功
		_set_status("创建大厅失败：%d" % connect_result)
		return
	Steam.setLobbyData(lobby_id, "game", "agame")   # 给大厅打标签，方便筛选
	print("[Net] 大厅已创建：%d" % lobby_id)

	var peer := SteamMultiplayerPeer.new()
	peer.set_no_delay(true)
	peer.host_with_lobby(lobby_id)              # 大厅绑到 peer 上
	multiplayer.multiplayer_peer = peer
	_show_game_ui()
	call_deferred("_spawn_player", 1)


# ---------------- 客户端：找大厅 + 加入 ----------------

func refresh_lobby_list() -> void:
	Steam.lobby_match_list.connect(_on_lobby_match_list, CONNECT_ONE_SHOT)
	Steam.requestLobbyList()


func _on_lobby_match_list(lobbies: Array) -> void:
	# lobbies 是 lobby id 的数组，拿去做列表 UI
	for lobby_id in lobbies:
		print("大厅 %s，人数 %d" % [lobby_id, Steam.getNumLobbyMembers(lobby_id)])


func join_game_lobby(lobby_id: int) -> void:
	Steam.lobby_joined.connect(_on_lobby_joined)
	Steam.joinLobby(lobby_id)


func _on_lobby_joined(lobby_id: int, _permissions: int, _locked: bool, response: int) -> void:
	if response != 1:                           # 1 = 成功
		_set_status("加入大厅失败：%d" % response)
		return
	var peer := SteamMultiplayerPeer.new()
	peer.set_no_delay(true)
	peer.connect_to_lobby(lobby_id)
	multiplayer.multiplayer_peer = peer
	_show_game_ui()
```

上面用到的 Steam 接口（已在本项目安装的 GodotSteam 版本上逐个校验过签名，照抄即可）：

| 接口 | 说明 |
|---|---|
| `Steam.createLobby(type, max_members)` | 建大厅。**返回值是 void**，结果通过 `lobby_created` 信号回来 |
| `Steam.lobby_created(connect_result, lobby_id)` | 信号，`connect_result == 1` 为成功 |
| `Steam.joinLobby(lobby_id)` | 加入大厅，结果通过 `lobby_joined` 信号回来 |
| `Steam.lobby_joined(lobby_id, permissions, locked, response)` | 信号，`response == 1` 为成功 |
| `Steam.requestLobbyList()` | 请求大厅列表，结果通过 `lobby_match_list(lobbies: Array)` 信号回来 |
| `Steam.setLobbyData` / `getLobbyData` / `getLobbyOwner` / `getNumLobbyMembers` / `getLobbyMemberByIndex` | 读写大厅信息 |
| `Steam.getSteamID()` | 取自己的 SteamID |
| `SteamMultiplayerPeer.create_host(port=0)` | 当主机 |
| `SteamMultiplayerPeer.create_client(steam_id, port=0)` | 按 SteamID 直连 |
| `SteamMultiplayerPeer.host_with_lobby(lobby_id)` | 当主机并绑定大厅 |
| `SteamMultiplayerPeer.connect_to_lobby(lobby_id)` | 按大厅 id 加入 |
| `peer.set_no_delay(true)` | 关掉攒包延迟，实时游戏必须开 |

> `lobby_id` 是 Steam 给的 64 位整数，显示给玩家时可以转成字符串再转回来，别自己改类型。

### 5.4 换成 Steam 之后要注意

- **主机仍然是服务器**。Steam P2P 只是把「怎么找到对方」换掉了，连接拓扑没变（仍然是主机=服务器、客户端之间的流量由主机中继）。所以「主机退出 = 全员掉线」这一点不变。
- **握手是异步的**。点加入后要等 1~3 秒才会真正建连；期间 `multiplayer.connected_to_server` 信号才触发。UI 上要有「连接中」状态。
- **不要用 SteamID 当玩家名字**，一长串数字没法看。加一个同步字段传昵称：`@export var nickname: String`，加入 `player_sync.tres` 同步即可。
- **AppID 480 的坑**：第三方账号没有 Spacewar 的话，连不上或大厅搜不到。本机双开测试没问题。
- **打包发布**：删掉 `steam_appid.txt`，AppID 写死在代码/配置里。

---

## 6. 调试工具箱

| 手段 | 怎么用 |
|---|---|
| 看日志 | 编辑器里跑 → Output 面板；命令行跑 → 加 `--log-file 路径`（Windows 上重定向 stdout 抓不到输出，这是 Godot 的已知行为） |
| 看同步有没有生效 | 在 `_ready()` 里 `print(is_multiplayer_authority())`，每端应该只有一个是 `true` |
| 看玩家有没有生成 | 装了这个项目有 godot-ai 插件，可以让 AI 用 `game_manage.get_scene_tree` 看运行时节点树（注意：它看不到 autoload 下的 UI） |
| 防配置被改坏 | `tests/test_net_replication.gd` 会验证 `player_sync.tres` 真的有同步字段且 `replication_mode == Always`。**这个配置写错不会报错，只会让角色僵在原地**，所以值得用测试钉住 |
| 主动断言 | 也可以让它跑一遍：让 AI 执行 `test_run`，或者自己写更多 `res://tests/test_*.gd`（继承 `McpTestSuite`，方法名以 `test_` 开头，用 `assert_eq` 之类） |

---

## 7. 已知限制 / 下一步可以做什么

现在的实现是**能跑通、够用、但不适合正式对战**的基础版。按重要性排：

1. **没有插值，远端玩家会一跳一跳**。
   同步是按固定节奏发位置，两端节奏不一致就会卡顿。修法二选一：
   - 简单：把 `Sync` 的 `Replication Interval`（`replication_interval`）调小，或保持默认每帧发。
   - 正规：自己写插值——远端玩家在 `_process` 里朝「最新收到的位置」做 `lerp` 平滑，而不是直接赋值。

2. **没有服务器校验，玩家可以作弊**。
   现在位置是客户端权威的，改客户端就能瞬移。要防作弊得走配方 D：客户端只发输入，服务器算位置再同步回来。

3. **没有断线重连**。目前主机掉线 = 其他人全部回主菜单。要做重连需要改成「场景常驻 + 玩家按 session 恢复」。

4. **没有大厅/房间列表**（ENet 版）。换 Steam 后自带。

5. **人数上限是 8**（`Net.MAX_PLAYERS`）。ENet 提升这个数字要同时考虑带宽；Steam 版上限由大厅的 `max_members` 决定。

6. **没有玩家昵称**。节点名现在就是 `str(peer_id)`，UI 上显示的是数字。按 5.4 的建议加同步字段即可。

---

## 附：一页速查

```gdscript
# 传输层（只在 net.gd 里出现）
var peer := ENetMultiplayerPeer.new()
peer.create_server(7000, 8)          # 主机
peer.create_client("192.168.1.5", 7000)   # 客户端
multiplayer.multiplayer_peer = peer

# 判断我是谁
multiplayer.is_server()              # 我是不是服务器
multiplayer.get_unique_id()          # 我的 peer id
multiplayer.get_peers()              # 其他 peer 的 id 列表
is_multiplayer_authority()           # 当前节点归不归我管

# 状态同步（改 player_sync.tres）
properties/N/path = NodePath(".:health")
properties/N/spawn = true
properties/N/replication_mode = 1    # 0 从不同步 1 每帧 2 变化时

# 事件同步（RPC）
@rpc("any_peer", "reliable")          func request_xxx(...) -> void:   # 谁都能发起
@rpc("authority", "call_local", "reliable") func do_xxx(...) -> void:  # 只有权威方发起 + 本地也跑
rpc(...) / rpc_id(peer_id, ...)

# 动态生成/销毁
spawner.spawn(data)                   # 只能在服务器/权威端调用
node.queue_free()                     # 销毁自动同步

# 授权（第二参数漏了就静默失效）
player.set_multiplayer_authority(peer_id, true)
```