开发概览与技术栈

01技术栈与版本

StartRide 由五块组成，各自用最合适的技术，边界划得很清楚。没有引入任何重型框架 —— 整套东西的依赖加起来，一只手数得完。

依赖原则

• 启动器不引入 UI 框架。界面用原生 WPF + XAML，样式集中在几个 .xaml 资源字典里。
• 游戏内模组只依赖游戏自带的 API，不打包任何第三方 Lua 库 —— 多一个依赖就多一个加载失败的理由。
• 服务器零第三方依赖（除了 WebSocket 这一层），能自己写的不引包。依赖越少，线上越不容易因为一次 `npm update` 出事。
• 官网没有构建步骤：改完文件直接传，不存在「本地是好的、线上是旧的」这种问题。

02架构分层

从游戏里的车到别人的屏幕，数据要穿过四层。每层只依赖它下面一层，上层改了不会影响下层。

游戏内 Lua ──┬─ 本地桥 127.0.0.1:4444 ─→ 启动器 ─┬─ 中继 TCP :7777 ─→ 服务器 ─→ 同房间其它客户端
             │                                    └─ 中继 WS  /relay/ ─┘
             └─ 直接读写本机车辆状态（物理、HUD、输入策略）

03进程与线程模型

启动器同时至少有三条并发路径在跑，它们碰到的东西不一样，混用就会出难查的问题。

共享状态怎么处理

• 玩家列表是跨线程读写的。改动它必须加锁，读它必须先取快照 —— 直接遍历共享集合，轻则界面闪一下，重则抛异常崩掉。
• 取快照要复制成新表再交给 UI 线程，不要传引用。
• 帧回调里不要做文件 IO 和阻塞网络请求。一次磁盘卡顿就是一次可见的掉帧。

// 后台线程：先加锁取快照，再回 UI 线程写控件
List<Player> snap;
lock (_playersLock) { snap = CopyPlayers(); }
Dispatcher.Invoke(() => {
    Players.Clear();
    foreach (var q in snap) Players.Add(q);
});

04仓库与目录结构

整个项目分成四个互不干扰的目录，改哪块就在哪块里动手：

StartRide/                        启动器（C# / .NET 8 / WPF）
  App.xaml / AppSettings.cs       入口与本地设置读写
  Services/                       启动游戏、模组安装、Steam 时长同步、中继客户端
  Views/  ViewModels/             页面与视图模型
  Styles/                         XAML 资源字典（颜色、圆角、控件模板）
  Setup/                          安装 / 卸载程序（打包进安装器）
  Mods/                           随包分发的游戏内 Lua 模组
  Strings.resx / Strings.cs       全部界面文案（两者必须同步）
  bin/Release/net8.0-windows/     构建产物 —— 用户实际运行的那一份

_sr_server_ref/relay-server.js    联机服务器源码（线上跑的就是它）
startride-top/                    官网（纯静态，无构建）
_sr_shots/                        探针与截图脚本
_sr_test_score.py                 计分模块的桩测试

05构建、产物与同步

启动器用 dotnet CLI 构建，产物落在 bin/Release/net8.0-windows/：

dotnet build StartRide.csproj -c Release

1. 改代码在 StartRide/ 里改 C# 或 XAML。
2. 构建跑上面的命令。XAML 和 C# 一起编译进程序集。
3. 同步产物把构建出来的主程序集与 3 个资源程序集复制到安装目录（覆盖同名文件）。
4. 重启程序关掉正在运行的旧进程再启动，否则你看到的还是旧界面。

06一次联机的完整链路

启动器                 中继服务器                游戏内模组
  │  连接 :7777            │                        │
  ├───────────────────────▶│                        │
  │  创建 / 加入房间        │                        │
  ├───────────────────────▶│                        │
  │  拉起游戏进程（注入 SteamAppId）                  │
  ├────────────────────────────────────────────────▶│
  │                        │   本地桥 :4444 握手     │
  │◀────────────────────────────────────────────────┤
  │  上行：本机车辆位姿 / 输入                        │
  │◀────────────────────────────────────────────────┤
  │  转发给同房间其它客户端  │                        │
  ├───────────────────────▶├───────────────────────▶│
  │  下行：别人的车辆状态    │                        │
  ├───────────────────────▶├───────────────────────▶│

1. 启动器读本地配置游戏路径、账户、内存上限、模组隔离开关等。
2. 连上中继与联机服务器建立长连接，拿到自己的会话标识。
3. 加入房间建房或加房，服务器把这条会话挂到对应的房间作用域。
4. 拉起游戏进程注入 Steam 身份变量，游戏以为自己是 Steam 启动的。
5. 模组接管游戏内的 Lua 通过本地桥接上会话，开始收发消息。
6. 广播位姿每个客户端把自己的车辆状态发出去，服务器转给同房间其他人。
7. 玩法推进阶段切换、就位确认、计分这些消息在玩法模块之间流转。
8. 退出清理通知服务器摘除会话，并把本机状态机复位回大厅。

07状态机与阶段

一局游戏的生命周期由几个阶段串起来。搞清楚「现在处于哪个阶段」，一半以上的联机 bug 就不用查了。

三条纪律

1. 输入限制只由阶段决定。任何新的限制都要写进输入策略函数，不要在别的地方零散加判断 —— 散落的判断迟早会互相打架。
2. 进入新阶段时逐项清零上一局的临时状态。漏一项，它就会跨局存活：下一局开始时还带着上一局的数据，现象诡异且极难复现。
3. 会话结束时把阶段收回大厅。这是硬性要求，不是可选项。

-- 输入策略：所有限制的单一入口
local function inputPolicy(player)
  if not S.sessionAlive then return false end   -- 会话没了，什么都别动
  if S.phase == "staging"  then return false end -- 就位期冻结
  if S.phase == "ended"    then return false end
  if player.wrecked        then return false end -- 车已经报废
  return true
end

08静默失败清单

这个项目里最难查的一类问题不是报错，而是什么都不发生。下面每一行都是真实踩过的，而且它们的共同点是：不报错、不进日志。

09一个真实案例：玩几分钟就崩

这个案例值得单独写一节，因为它演示了「按现象 → 假设 → 用证据排除」的完整过程，而且结论和直觉完全相反。

现象

• 联机进去以后一切正常，但玩到 40 ~ 60 秒左右，游戏突然消失。
• 不是掉线，是整个游戏进程没了，没有报错窗口。
• 单人模式完全正常，只有联机才会。

排错过程

真因

启动器把游戏进程放进了一个作业对象（Job Object），并且给它设了内存上限。默认值 4096 MB。BeamNG 联机时内存占用轻松超过这个数，于是被作业对象判定超限、整个进程被直接终止 —— 这就是「活 40 ~ 60 秒」的来源。

修法

1. 把上限改成自适应：按机器物理内存算出安全值，并钳在 6144 ~ 32768 MB 之间，别让低配机被钳成一个过小的值。
2. 默认不启用内存限制。需要限制的场景（比如演示机、教学机）再手动开。

10从哪开始读

11改完必跑的自检

每个人都会忘记跑检查。所以这里不做「建议」，直接列成表 —— 改了什么就跑什么，跑不过不许提交。