Lua 模组开发

01加载与生命周期

游戏内的那一层是一组 Lua 文件，由 BeamNG 的扩展机制加载。它做三件事：

• 通信：把本机车辆状态发出去，把别人的状态接进来。
• 规则：按玩法决定玩家现在能做什么、不能做什么。
• 显示：画一层很薄的游戏内 HUD。

加载过程有明确的先后顺序，理解它比记住函数名重要得多：

1. 按顺序加载文件每个文件被执行一遍，顶层代码只在此时运行一次。
2. 注册到主模块各文件把自己的能力挂到主模块导出的表上。
3. 桥接绑定主模块连上本地桥，开始收发消息。
4. 进入帧循环每帧、每秒的回调开始被周期调用。

02文件划分与依赖

模组按功能拆成多个文件，每个文件管一块，互不越界：

Mods/
  startride_mod.lua        桥接层：与启动器 / 中继通信、游戏内 HUD
  startrideMode.lua        玩法状态机：阶段切换、回合管理
  startrideSpawn.lua       出生点与就位
  startrideInput.lua       输入策略：按阶段限制玩家能做什么
  startrideScore.lua       计分账本
  startrideHideSeek.lua    捉迷藏玩法
  startrideModeHud.lua     玩法专用 HUD 渲染

文件之间怎么交互

• 每个文件是一个模块，末尾 return M，把自己那张表交出去。
• 子模块要借用主模块提供的东西，必须挂到模块表上导出，不能去抓主模块的局部变量。
• 导出动作要早于桥接绑定；晚一步，子模块拿到的就是 nil。
• 不要在两个文件之间共享一份可变状态。谁拥有状态，谁提供读写函数。

03硬上限一：每函数 60 个上值

「上值」指的是函数体里用到、但不是自己参数也不是自己局部变量的那些外部变量。下面这段就把 4 个外部变量都抓了：

local cfg, state, send, now = ...   -- 4 个外部变量

local function tick()                -- 这个函数捕获了 4 个上值
  if state.on then send(cfg.id, now()) end
end

几条能救命的经验

• 不要在一个闭包里抓一堆零散的外部变量。把相关状态打包成一张表，只抓那一个表 —— 60 个零散变量和 1 个表，省下来的是 59 个名额。
• 桥接层通常常年贴着上限跑。加字段之前，先确认当前用了多少个。
• 实在不够用就拆函数：把一部分逻辑挪到一个显式的、只吃参数的纯函数里，纯函数不产生额外上值。
• 不确定有没有超，就写个脚本数一遍：解析函数体，统计它引用的、在函数外定义的局部变量个数。

04硬上限二：顶层 200 个局部变量

local a, b, c = 1, 2, 3     -- 3 个顶层局部变量
local S = {}                -- 1 个（表内部的字段不算）
-- 顶层总共 4 个 ✓

做法

• 顶层不要堆状态。状态放进表里，一张表只算 1 个 local。
• 临时变量一律 local 进函数，不要为了「少打字」提到顶层。
• 文件末尾保持 return M 的模块写法，别搞全局变量。
• 和上值一样，把这个计数做成静态检查，而不是靠自觉。

05导出与注册顺序

加载顺序决定了很多东西能不能用。这张表是实践中最容易踩的几种顺序错误：

06帧循环与性能

每帧回调会被调用很多次，它是掉帧的头号嫌疑人。

07车辆状态读写

读

• 取当前玩家车辆的对象，读它的位置、朝向、速度、是否报废。
• 别每帧重新查找车辆对象，查一次缓存起来，车辆切换时再刷新。

写

• 本机车：正常通过游戏的车辆 API 操作，不要硬写物理状态。
• 远程车：把目标位姿转成每个节点上的力，逐节点施加。
• 误差是必然的，靠持续的修正节奏收敛，不要指望一次到位。

08输入策略

「这个人现在能不能动」这个问题，必须只有一个答案来源。所有阶段判断都收敛到一个函数里：

-- 输入策略：所有限制的单一入口
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

三条纪律

1. 新增限制只往这个函数里加。散落在别处的判断迟早会互相打架。
2. 「车报废」必须同时管住输入和伤害归属：只限制输入、不管伤害，会出现「撞残骸的人自己掉血」这种诡异规则。
3. 会话结束时阶段必须收回大厅，否则上面的第一行永远返回 false，玩家的传送、复位、换车就再也恢复不了了。

09游戏内 HUD

StartRide 在游戏里只加一层很薄的 HUD，显示房间与网络状态。

• HUD 不接收任何鼠标或键盘输入，不会挡到你开车。
• 绘制成本随每帧重建的控件数量上升。值没变就别重建，复用已有的绘制对象。
• 把「渲染」和「数据」分开：数据更新在逻辑里做，绘制只读现成的值。

10计分与幂等

计分是一本本地账本：每个人都自己算自己的分数，故意不通过网络同步。

阶段状态清零清单

进入新阶段（尤其是换房、重开一局）时，下面这些必须逐项清零。漏一项，它就会跨局存活：

• 本局累计的分数与击倒 / 撞击计数
• 本局的就位确认记录
• 本局的事件幂等键缓存
• 本局临时缓存的车辆对象引用

11与启动器 / 中继通信

游戏内 Lua 不自己开 socket。所有网络细节都在启动器那一侧，Lua 只做两件事：发一条 JSON、收一条 JSON。

运行环境差异（照搬桌面脚本必踩）

• math.atan2 这个运行时里已经被移除，要自己用 atan 拼一个出来，别直接调。
• 不要依赖 utf8 库，它不一定存在。
• loadstring 不一定可用，别把动态代码生成当成常规手段。
• 这个 table 相关的辅助函数可能有参数顺序上的差异，别假设和标准 Lua 一致 —— 传进去的顺序不对，结果会悄悄反过来。

12静态自检三件套

这三项都在进游戏之前跑，能省掉大量「启动 → 加载 → 发现没用 → 退出」的时间。

• 三项都是纯静态的，不需要启动游戏。
• 把它们接进改动流程里：改完 Lua 就跑，跑不过不提交。
• 计数不是「差不多就行」。59 和 60 之间没有任何缓冲 —— 撞线是断崖，不是斜坡。

13常见错误对照表