Roblox Luau 工程实践:基于 skills 仓库 scenario-roblox-luau 技能的调度、类型、内存与并行优化指南

原创2026-11-06 15:20:491,822 阅读
文章标签:AI 技能人工智能媒体生成多模态3D建模3D渲染游戏开发

Roblox Luau 工程实践:基于 skills 仓库 scenario-roblox-luau 技能的调度、类型、内存与并行优化指南

本文以 skills 仓库中的 Roblox Luau 专家技能为骨架,讲清楚在 2026 年的 Roblox 运行环境下,如何写出在 Deferred 事件与 task 调度器下仍然正确、能在新旧两套类型求解器上都通过检查、能释放自己创建的每一个对象、并且每一次性能优化都有实测数字支撑的 Luau 代码。读完后你将掌握一套可执行的工作流:先用静态审计与类型门禁排除已知陷阱,再用探针在真实数据模型里取证,最后用 A/B 基准和 1 对 N 的 Actor 对比决定是否保留优化。

技能的定位与前置条件

该技能的 frontmatter 直接把适用场景写成了"问题清单":task.spawn / task.defer / task.wait 的取舍、替换 wait() 与 spawn()、Deferred 事件与 SignalBehavior、处理器顺序错乱或根本不执行、attempt to yield across metamethod/C-call boundary、--!strict 与新类型求解器、类型化类与元表、Destroy 与清理、"服务器内存持续增长"、带 Actor 与 SharedTable 的 Parallel Luau、not safe to write in parallel、--!native 与"让这个脚本更快"、buffers 以及协程。

它的执行环境约定得非常具体:Roblox Studio(2026 年 10 月构建)在 macOS 上,通过 scenario-roblox-expert 工具链驱动。技能声明了强制前置背景——scenario-roblox-expert 提供的执行通道、评审循环、工具链与当前 Roblox 陷阱。若同级技能缺失,技能文件给出的处理方式是让用户安装(npx skills add scenario-labs/skills --skill <name>),无人值守场景下则依据工具 schema 继续并在结论中标注这个缺口。

这里的关键判断标准是:"专家级 Luau"不是写法花哨,而是在 Deferred 与调度器下仍然正确、双求解器都通过类型检查、释放自己创建的一切、且每个优化都能给出在本机构建上量出来的数字。

八条专家判据(Stance)

技能把"专家差值"压缩成八条可检验的立场,每一条都附带反直觉的结论。下面逐条展开,并给出仓库中对应的实现或验证代码。

1. task.spawn 不是并发

task.spawn 会同步执行函数体直到第一个 yield 才把控制权交回调用者。因此它不是并发,只是"先跑一段"。真正表达"在当前步骤之后执行"的语义应该用 task.defer——它是一个保持调用顺序的队列。

task.wait() 与 task.delay(0) 在下一次 Heartbeat 恢复:从 PreSimulation 调用时是同一帧,从 Heartbeat 调用时是下一帧。技能给出的实测值是 0.07 ms 与 16.4 ms。

这个结论在仓库里有可复现的探针,见 Probe.luau:

function Probe.scheduler()
	local log = {}
	local function mark(tag)
		table.insert(log, tag)
	end
	task.spawn(function()
		mark("spawn:body")
		task.wait()
		mark("spawn:afterWait")
	end)
	mark("caller:afterSpawn")
	task.defer(mark, "defer:1")
	task.defer(mark, "defer:2")
	task.delay(0, mark, "delay0")
	mark("caller:end")
	frames(4)
	return { order = table.concat(log, ",") }
end

spawn:body 必须出现在 caller:afterSpawn 之前,这就是"同步执行到第一个 yield"的直接证据。实测顺序记录在 procedures.md 中:spawn:body, caller:afterSpawn, caller:end, defer:1, defer:2, spawn:afterWait, delay0。

延迟计时同样被单独拆出来测,见 Probe.delayTiming:它用 PreSimulation:Once 与 Heartbeat:Once 各自测量一次 task.delay(0) 的恢复延迟,分别写入 fromPreSimulationMs 与 fromHeartbeatMs。

2. 写 Deferred 安全的代码

Deferred 下处理器在下一个恢复点运行,绝不在 :Fire() 或属性赋值内部运行。由此产生一系列具体后果:

  • 嵌套 fire 按队列顺序执行;
  • 在处理器内部连接的监听器会错过同一步内发出的 fire;
  • Destroying 或 CharacterRemoving 处理器看到的 Parent 是 nil。

对策被写成三条动作:在处理器内部读状态、用 :Once()、在 Destroy 之前把清理所需的信息取出来。

技能引用的实测结论是:仅采用 Deferred 就把某款已上线游戏的帧时间从 6–8 ms 降到 4–5 ms。这些行为在 Probe.signals 里被逐项探测,包括"处理器是否在 yield 之前跑过"、"处理器内部连接是否会漏掉同一步的 fire"、"嵌套顺序"、"Destroying 看到的 Parent"、"处理器内 Disconnect 会丢弃多少次排队调用"、":Once() 是否只跑一次"、"Destroy 之后排队调用是否仍然执行"、"三次属性赋值触发多少次 changed",以及自触发事件的递归深度。

其中自触发那一项值得单独说明,因为它推翻了一个常见误解:

	local ev5 = Instance.new("BindableEvent")
	local depth = 0
	ev5.Event:Connect(function(d)
		depth = math.max(depth, d)
		if d < 50 then
			ev5:Fire(d + 1)
		end
	end)
	local ok, err = pcall(function()
		ev5:Fire(1)
	end)

文档记载的重入上限是 10,而实测在 Deferred + BindableEvent 组合下到达 50 层仍未报错。结论不是"可以依赖更深的递归",而是不要把文档里的重入上限当成安全护栏。

3. 只在合法且廉价的位置 yield

绝对不能 yield 的位置包括:__index 等元方法、table.sort 比较函数、gsub 回调——否则抛出 attempt to yield across metamethod/C-call boundary。同样不能 yield 的位置是每帧处理器:在 Heartbeat 里写 task.wait(0.25),1 秒内会堆叠出 16 个线程。

更反直觉的一条是:pcall 不是补救手段。如果 task.wait 在 pcall 下失败,它的线程会继续留在调度器注册表里。仓库里对此有明确的危险性说明,见 Probe.yields 的注释:

Yield boundaries are probed with coroutine.yield in a private coroutine, never with task.wait or a yielding WaitForChild: a failed task.wait under pcall leaves the thread registered with the scheduler ("already 'waiting'"), and Studio 0.743 crashed shortly after such a probe.

因此探针本身只用私有协程中的 coroutine.yield 来测边界:

	out.inIndex = attempt(function()
		local lazy = setmetatable({}, {
			__index = function()
				coroutine.yield()
				return 1
			end,
		})
		return lazy.x
	end)

堆叠问题也被量化了,见 Probe.pileup:一段是在 Heartbeat 里直接 task.wait(0.25),统计峰值并发线程;另一段换成 busy 标志加 task.delay(0.25, ...) 释放标志,统计实际运行次数。实测结果是峰值 16 个线程对 4 次运行。

4. 面向两套求解器写类型

新模块以 --!strict 开头。方法定义为 function Class.name(self: Class, ...)——冒号形式在两套求解器上都会放过字段拼写错误。优先组合而非类型化元表继承,因为后者在两套求解器上都会产生误报。用 IsA 或 FindFirstChildOfClass 收窄类型,而不是 :: any。

关键约束是门禁必须同时在旧求解器与新求解器上跑,因为 strict 脚本会跟随 Workspace.UseNewLuauTypeSolver,而该属性是 NotScriptable,脚本读不到。

仓库的实现见 rbx_luau.py 的 typecheck。它刻意分两趟调用 rbx_check,每趟只带一套求解器,这样每条结果只包含自己的发现:

        old = rbx_check.check(files, sourcemap=sourcemap, timeout=timeout, solver="old")
        new = rbx_check.check(files, sourcemap=sourcemap, timeout=timeout, solver="new")

返回结构包含 ok、files、old、new、only_old、only_new;only_old / only_new 按 (file, line) 做集合差,用于定位"只在某一套求解器上出现"的差异——这正是判断代码是否依赖求解器差异的依据。

另一个容易踩的细节在 sourcemap:生成 Rojo sourcemap 时必须带 --include-non-scripts,否则 Folder 与 remote 会缺失,新求解器会在经过它们的每一条路径上报 unknown key。

--!strict 缺失也会被审计标记。见 LuauAudit.luau:

	if ctx.className == "ModuleScript" and not dir.strict then
		add("info", "module-not-strict", 1, "ModuleScript without --!strict: new modules start strict so the checker sees field and argument types")
	end

5. 每个对象拥有自己的清理

Destroy 是幂等的,并且会断开它建立的所有连接。以玩家为键的表要在 PlayerRemoving 时清空。旧角色必须销毁:在 Default 设置下,重生的角色只是被取消了父级,连接仍然保留。

"泄漏"的定义也被收紧了:泄漏是永远降不下来的内存,单纯的增长不是泄漏。

仓库里给出的标准模板见 Class.luau:

--!strict
local RunService = game:GetService("RunService")

local Spinner = {}
Spinner.__index = Spinner

type Fields = {
	part: BasePart,
	speed: number,
	_connections: { RBXScriptConnection },
	_destroyed: boolean,
}
export type Spinner = typeof(setmetatable({} :: Fields, Spinner))

function Spinner.new(part: BasePart, speed: number): Spinner
	local self = setmetatable({
		part = part,
		speed = speed,
		_connections = {},
		_destroyed = false,
	}, Spinner)
	table.insert(self._connections, RunService.PreSimulation:Connect(function(dt: number)
		self:step(dt)
	end))
	table.insert(self._connections, part.Destroying:Connect(function()
		self:Destroy()
	end))
	return self
end

function Spinner.step(self: Spinner, dt: number)
	self.part.CFrame *= CFrame.Angles(0, self.speed * dt, 0)
end

function Spinner.Destroy(self: Spinner)
	if self._destroyed then
		return
	end
	self._destroyed = true
	for _, c in self._connections do
		c:Disconnect()
	end
	table.clear(self._connections)
end

return Spinner

模板体现了四个决定:__index 指向类表而不是函数;Fields 类型加 typeof(setmetatable(...)) 导出类型;方法用点式定义显式标注 self: Spinner(调用方仍写 obj:step(dt));Destroy 用 _destroyed 标志保证幂等,并把连接全部断开后 table.clear。

清理的证明不靠 Luau Heap GUI,而靠 Leak.luau。它的核心技巧是用弱键表统计存活对象,使探针本身不持有引用:

function Leak.retained(make, release, n: number, rounds: number?)
	local weak = setmetatable({}, { __mode = "k" })
	local objects = {}
	for i = 1, n do
		local o = make(i)
		weak[o] = true
		objects[i] = o
	end
	release(objects)
	table.clear(objects)
	local mode = Leak.collect(rounds)
	local alive = 0
	for _ in weak do
		alive += 1
	end
	return { made = n, alive = alive, gc = mode }
end

Leak.collect 还处理了 Roblox 的限制:脚本只能调用 collectgarbage("count"),所以它先尝试 _G.collectgarbage,不可用时退化为分配垃圾制造压力(Leak.luau)。趋势判定用最小二乘斜率 Leak.slope,配合 Leak.sample 每 N 个周期采样 gcinfo() 与 Stats.InstanceCount。

P7 的实测结果直接排除了两类常见泄漏:模块级 registry 持有 200 个表时全部存活,清空后为 0;100 个已 Destroy 的 Part 因为一条未断开的 workspace.ChildAdded 连接捕获而全部存活,Disconnect 后为 0。角色场景也验证了修复方式:CharacterRemoving 里 task.defer(character.Destroy, character) 能让连接真正断开。

6. 并行负责计算,串行负责写入

一个独立单元一个 Actor;require 必须在并行阶段之前完成;写入必须在 task.synchronize() 之后。每个 Actor 是独立的 Luau VM,模块状态不共享。对 SharedTable 的读改写必须走 SharedTable.increment 或 update——8 个 Actor 上用普通 += 1 丢失了 79% 的更新。

Worker 模板把这个模式固化了,见 ParallelWorker.server.luau:

--!strict
local actor = script:GetActor()
if actor == nil then
	return
end
type WorkModule = { run: (jobId: number, payload: any, results: SharedTable) -> () }
local ref = actor:WaitForChild("WorkModule") :: ObjectValue
-- Dynamic require paths are "Unknown require" errors for the type checker: cast require, type the result.
local Work: WorkModule = (require :: any)(ref.Value) -- serial: before any parallel phase

actor:BindToMessageParallel("work", function(jobId: number, payload: any, results: SharedTable)
	local ok, err = pcall(function()
		Work.run(jobId, payload, results)
	end)
	if not ok then
		results["error" .. jobId] = tostring(err)
	end
	SharedTable.increment(results, "done", 1)
end)
actor:SetAttribute("Ready", true)

两个细节值得注意:script:GetActor() 为空时直接 return,这样同一份文件放在 ServerStorage 里不会执行;动态 require 路径对类型检查器是 "Unknown require",所以先用 (require :: any) 转换再给结果标注类型;完成计数用 SharedTable.increment,而不是 += 1。

驱动器见 Parallel.luau。workers 创建 N 个 Actor,各挂一个 ObjectValue 指向工作模块,克隆模板,然后轮询 Ready 属性,超时报出可诊断的错误信息(Parallel.luau)。run 通过 SendMessage("work", ...) 轮询分发,用 results.done 判断完成,超时报出"only X of Y jobs finished"(Parallel.luau)。

串行—并行—串行的标准形态在 procedures 中被写成一段完整示例(procedures.md):先 ConnectParallel,算完后 task.synchronize(),再写属性,并顺手验证同步前的写入会失败。这段代码还有一个隐含约束——phase 切换不要包在 pcall 里。

7. 原生代码与 buffer 只在测量之后启用

--!native 在带类型的数值代码上收益明显:数值循环 3.3 倍,带类型的 Vector3 循环 4.9 倍,而 Vector3 参数未标注类型时收益为 0。原生代码不能全量开启,因为它会拖慢启动并消耗全局内存预算。buffer 在持续入向流量超过约 50 KB/s 之后才划算,且必须做范围检查,因为整数写入会静默回绕。

这三条都有探针。基准用 Bench.luau:排序用例名、逐用例预热、轮内交错执行以抵消漂移、每轮之间 task.wait() 避免脚本超时,取中位数并四舍五入到三位小数:

	for _ = 1, rounds do
		for _, name in names do -- interleaved so drift hits every case alike
			local t0 = os.clock()
			cases[name]()
			table.insert(times[name], (os.clock() - t0) * 1000)
			if task then
				task.wait()
			end
		end
	end

Bench.ratio(results, base, other) 返回基准除以对比项的中位数比值,大于 1 表示后者更快。

buffer 的部分用 BufferCodec.luau。它的类型宽度表与取值范围表是显式的:

local WIDTH: { [string]: number } = {
	u8 = 1, i8 = 1, u16 = 2, i16 = 2, u32 = 4, i32 = 4, f32 = 4, f64 = 8, bool = 1, unorm8 = 1, vec3f32 = 12,
}
local RANGE: { [string]: { number } } = {
	u8 = { 0, 255 }, i8 = { -128, 127 }, u16 = { 0, 65535 }, i16 = { -32768, 32767 },
	u32 = { 0, 4294967295 }, i32 = { -2147483648, 2147483647 },
}

checkInt 同时拒绝非数字、非有限值和带小数的值,再检查范围(BufferCodec.luau)。浮点字段要求有限值,unorm8 会 clamp 到 0..1 再乘 255 取整,str8 限制 255 字节并先写长度,vec3f32 逐个校验分量。schema() 会在 schema 阶段就拒绝未知类型名,并在出现 str8 时把 size 置为 nil(变长记录无法给出定长):

	for _, pair in spec do
		local name: string, kind: string = pair[1], pair[2]
		if kind ~= "str8" and not WIDTH[kind] then
			error(`unknown type {kind} for field {name}`, 2)
		end

列表编码在头部写一个 u16 计数,并用 checkInt("count", "u16", #list) 提前拦住超长列表(BufferCodec.luau)。

8. 注入的 chunk 不是游戏本身

在 Server 上执行的 execute_luau chunk 拥有自己的模块缓存:它看到的 Counter.n 是 0,而游戏脚本看到的是 41。要读游戏状态,走 attributes 或 BindableFunction 钩子。

这条在 procedures.md 的 P5 里有完整对照实验,并且给出了游戏脚本侧的正确做法:设置模块状态、暴露一个 BindableFunction,让 chunk 通过 hook:Invoke("counter") 读值。同一份引导脚本还承担了在真实 server Script 里跑 native A/B 的职责——因为注入 chunk 的结果不能代表游戏脚本。

开工前必须确立的六项事实

技能要求在写下第一行修复之前,先把环境事实钉死。这些事实无法全部由脚本读取。

项目 如何确认 关键限制
Signal 模式 Workspace > SignalBehavior;Rojo 项目文件;rbx_luau.audit(place) 脚本读不到;Default 等同 Immediate;未设该属性的 Rojo 构建场所是 Default
Server Authority Workspace.AuthorityMode = Server 会强制 Deferred 与定步长仿真;游戏逻辑转交 scenario-roblox-gameplay
类型环境 Workspace.LuauTypeCheckMode、UseNewLuauTypeSolver、Rojo 是否提供 sourcemap 后两者 NotScriptable
代码运行位置 Server、Client,还是 Actor 之下 原生代码只对服务端脚本有帮助
基线数字 热路径的每帧毫秒、线上 KB/s、每周期堆斜率 优化前必须存在
PlayerCharacterDestroyBehavior Properties 面板 不可脚本化

未知时的默认取值被明确列出:Deferred、--!strict、双求解器都过门禁、不开 native、不用 Actors、不用 buffers。这组默认值的意义是把"未经验证的优化"和"未经验证的环境假设"都排除在起点之外。

SignalBehavior 的不可读性在代码里也有体现:LuauAudit.tree 用 pcall 包裹属性读取,读不到就记为 "unreadable";只有读到 Immediate 或 Default 时才产出 signal-behavior 提示。这解释了为什么 procedures 里记录着"在 Studio 中该规则只会在离线模式下触发"。

七步流程与门禁

技能把工作拆成七个步骤,每步都有可判定的出口条件(GATE)。这是全文最值得照抄的部分。

步骤 1:审计既有代码

目标是在上 playtest 之前找出调度器、yield、Deferred、并行、native 与泄漏方面的错误。

离线走 Lune,不需要 Studio:

rbx_luau.py audit <place.rbxl|dir> [info|warn|error]

Python 侧的封装见 rbx_luau.audit,它调用 lune run lune_luau_audit.luau <target> <min_severity>,把 stdout 解析为 JSON 并附上退出码。任何 error 级发现都会让退出码为 1,可以直接作为 CI 门禁。

在 Studio 内则对打开中的场所跑同一套规则:

-- dm: Edit
-- kit: LuauAudit
local r = LuauAudit.tree(game)
local rules: { [string]: number } = {}
for _, f in r.findings do
	local rule: string = f.rule
	rules[rule] = (rules[rule] or 0) + 1
end
return { counts = r.counts, rules = rules, total = #r.findings }

工具链自带的 Audit 覆盖遗留 API;本技能的 LuauAudit 补上它不做的检查。

GATE:0 个 error 级发现;每条 warn 要么修掉,要么用一行说明为什么可以接受。

步骤 2:修正惯用法

目标是让调度器与事件用法符合当前版本:只用 task.*;用 PreSimulation / PostSimulation / PreRender 取代 Stepped / RenderStepped;一次性监听用 :Once();把 yield 移出帧处理器(busy 标志,或一条 spawned worker 循环);让元方法永不 yield(预计算,或改成显式的可能 yield 的 get)。

GATE:审计干净;在 Deferred 下行为不变(由步骤 5 验证)。

这条门禁的两半缺一不可:静态规则清空只是必要条件,行为不变必须靠探针。

步骤 3:类型检查

目标是让错误在编辑期就被捕获,且两套求解器都通过。做法是 --!strict、Fields 类型加 typeof(setmetatable({} :: Fields, Class))、点式定义显式 self、组合优先、数组用 table.create(n, value);然后跑双趟检查:

import rbx_luau
sm = rbx_luau.sourcemap("my-rojo-project")       # rojo sourcemap, so script.Parent.X paths type-check
r = rbx_luau.typecheck(["my-rojo-project/src"], sourcemap=sm)
r["ok"], len(r["old"]["errors"]), len(r["new"]["errors"]), r["only_old"], r["only_new"]

CLI 形式为 rbx_luau.py typecheck <file|dir> <a href="https://link.gitcode.com/i/a0ca4915010d9e0a6a23d566d33df296" target="_blank">--sourcemap sourcemap.json] [--json]。要注意 _files 对不存在的路径是抛 FileNotFoundError 而不是返回零错误([rbx_luau.py),这是刻意的——luau-lsp 对缺失路径不报任何东西,静默通过是最危险的失败模式。

GATE:old 与 new 都是 0 错误。

仓库记录的门禁捕获能力(7 个 fixture 全通过)很能说明为什么必须双跑:

fixture 旧求解器 新求解器
local y = 5; y = "hello" 报错 不报错(放宽类型)
点式方法 function C.step(self: C, dt: number) 配字段拼写错误 捕获 捕获
冒号方法 function C:fire() 配字段拼写错误 漏报 漏报
组合(Knight 持有 Health) 干净 干净
类型化元表继承(Child 继承 Base) 2 个误报 9 个误报
(model :: any).Humanoid.Healthh = 5 漏报 漏报
local a: { Vector3 } = table.create(n) 干净 报错({unknown})

最后一行给出的修法是 table.create(n, Vector3.zero)。第三行与第五行则直接支撑了前文两条建议:别用冒号定义方法,别用类型化继承链。

步骤 4:所有权与清理

目标是没有任何对象比它的所有者活得更久。做法是套用类模板(Destroy 接到 Destroying)、在 PlayerRemoving 清理、销毁旧角色。然后在 Server playtest 中用 Leak.retained(make, release, n)、Leak.sample(cycle, 20) 与 Leak.slope 证明。

GATE:release 之后 alive 为 0;20 个以上周期内堆斜率为平;Destroy 之后剩余 0 条连接。

角色相关的修复写法固定在 procedures 里:player.CharacterRemoving:Connect(function(character) task.defer(character.Destroy, character) end)。实测表明 Default 设置下旧角色只是被取消父级、连接仍处于连接状态,加了这行之后连接才断开。

步骤 5:探测依赖顺序的行为

目标是拿到这个场所的事实,而不是假设。方法是在同一次 playtest 里,分别以 Server 和 Client 数据模型运行探针:

-- dm: Server
-- kit: Probe
local out = Probe.scheduler()
out.timing = Probe.delayTiming()
return out
-- dm: Server
-- kit: Probe
return Probe.signals()

GATE:结果被记录;没有任何代码依赖探针显示会被 Deferred 改变的顺序。

这条门禁的价值在于它把"顺序依赖"从代码评审的主观判断变成了可观测项。Server 与 Client 两次运行的结果要一起记录,因为两者可能不一致——procedures 中记录的是 Client 在其执行的三项检查上与 Server 一致。

步骤 6:只在有数字时优化

目标是只保留测出来的收益。做法是在 Server 数据模型里跑 Bench.run({plain=..., native=...}, 7)(交错轮次、预热、中位数);用 Parallel.workers 对比 1 个与 N 个 Actor 配同一工作模块;用 BufferCodec 对比体积与表负载。

GATE:native 比值 ≥ 1.2,并行加速比 ≥ 1.5,buffer 超过带宽门限;否则回退。

两个阈值都标注为 [added],即技能自己设定的判据,而非引擎文档给出的数字。这一点很重要:它们是可以按项目调整的工程约定,不是普适定律。

步骤 7:带证据交接

目标是让评审者不用重跑就能信任结果。做法是附上类型检查输出、审计 JSON、探针与基准结果(含构建版本、数据模型、日期);当改动可见时,通过 rbx_review 附一张 playtest 截图。

GATE:交接中的每一条结论都有数字或测试名。

关键数字一览

下表是技能给出的"测量值或声明值"清单,可作为判断自己结果是否合理的参照。注意最后一列限定了参照对象,脱离该前提引用这些数字是不成立的。

数值 实测或声明 参照
task.delay(0) 恢复 PreSimulation 起 0.07 ms,Heartbeat 起 16.42 ms Studio 0.743 Server, 60 Hz
yield 的 Heartbeat 处理器 1 秒内 16 个并发线程 每次调用 task.wait(0.25)
Deferred 帧时间收益 6–8 ms 降到 4–5 ms 某款已上线游戏(RDC 2026)
native 加速,数值循环 3.3x 普通 Luau,Server,n = 200,000
native 加速,带类型 Vector3 循环 4.9x;不带类型 0.96x 同一 kernel 不开 --!native
native 尺寸限制 每块 64K 指令、每函数 32K 块、每脚本 1M 文档;另有全局上限
并行加速 7.6x(144.5 ms → 19.0 ms) 1 对 8 Actor,32 个纯计算任务,18 核 Mac
SharedTable 普通 += 1 160,000 次更新丢失 127,107 次 SharedTable.increment 丢失 0
buffer 门限 持续入向约 50 KB/s Crusherfire
一个数字走 remote 9 字节;Color3 13 字节对打包后 5 字节 Crusherfire
SharedTable 键 字符串或 0 到 2^32 − 1 的整数 SharedTable 参考
内存预算 服务端约 6.25 GB;手机约 2 GB,其中系统占 700 MB Roblox Learn,内存泄漏
重入上限 文档写 10;自触发处理器实测到 50 未报错 Deferred, BindableEvent

质量门禁

技能把可交付标准分成可度量与可视图两类。

可度量项:

  • rbx_luau.typecheck:两套求解器均 0 错误,且带项目 sourcemap。
  • rbx_luau.audit:0 个 error;warn 全部处理完毕。
  • 工具链 Audit:无遗留调度器或废弃 API 发现。
  • 每次清理修复后 Leak.retained 的 alive 为 0,Leak.slope 平坦。
  • 场所 signal 模式的探针结果在 Server 与 Client 上都有记录。
  • 保留 native 代码或 Actor 之前,Bench 与 Parallel 的比值已记录。
  • BufferCodec 往返精确(或在 f32 精度内),且拒绝路径被测试过。

可视项(当行为可见时):通过 rbx_review 的 playtest 截图,显示物体确实在动、确实被清理,或呈现你声称的状态;性能类结论则附上手工采集的 MicroProfiler 或 Script Profiler 记录。

"拒绝路径被测试过"这一条容易被忽略但很关键。P10 的实测就覆盖了它:buffer.writeu8(b, 0, 300) 存成了 44,writeu16(70000) 存成了 4464,writeu8(3.7) 存成了 3,而 BufferCodec 对 id = 70000 的 u16 字段会拒绝编码。同一组测试还确认了 buffer 通过 BindableEvent 传递时到达的是副本(字节相同、对象不同),以及 HttpService:JSONEncode 会写成 {"m":null,"t":"buffer","base64":"aGk="}。

常见错误速查

下表把症状与修复对齐。第三列是本文补充的对应审计规则,便于把人工排查转成自动化。

错误 症状 修复 对应审计规则
wait()、spawn()、delay() 被限流、恢复偏晚 task.wait、task.spawn、task.delay 工具链 Audit
在 :Fire() 之后期待处理器已运行 Deferred 下读到过期状态 在处理器内动作,或用 task.defer —
Destroying 处理器读 Parent nil 错误 在 Destroy 前先捕获 removal-handler-reads-parent
在 Heartbeat 处理器里 task.wait 线程堆积、工作量翻倍 busy 标志,或单条 worker 循环 yield-in-frame-handler
在 __index 或排序比较函数里 yield attempt to yield across metamethod/C-call boundary 预计算;显式 getter yield-in-metamethod
strict 代码里写 function C:m() 字段拼写错误被放过 function C.m(self: C) colon-method-strict
(x :: any).Child 拼写错误通过检查 IsA、FindFirstChildOfClass 收窄 any-cast
类型化继承链 合法调用报 "does not have key" 改用组合 —
players[player] = ... 无 PlayerRemoving 服务端内存随加入人数上涨 在 PlayerRemoving 清空 player-table-no-cleanup
在 Actor 之外 ConnectParallel 报错,处理器永不执行 把脚本挂到 Actor 下 parallel-without-actor
desynchronize 之后 require 或写 Instance not safe to write in parallel 先 require;synchronize 后写 require-in-parallel、parallel-unsafe-write
在 pcall 里 task.synchronize() 某次运行导致场所崩溃(原因未隔离) phase 切换不要放进 pcall —
对未标注类型的 Vector3 代码开 --!native 没有加速 标注参数类型 native-untyped
buffer.writeu8(b, 0, 300) 实际存成 44 范围检查,或用 BufferCodec —
collectgarbage("collect") 在 Roblox 中报错 用 gcinfo() —

补充几条审计器覆盖但原表没列的规则:superseded-runservice(Stepped / RenderStepped)、env-deopt(getfenv / setfenv 会让整个脚本失去 fastcall、imports 与 native 编译)、while-true-no-yield(会以 Script timeout: exhausted allowed execution time 终止)、module-not-strict、index-function(__index 是函数比指向类表慢)、signal-behavior。

值得注意的是 parallel-without-actor 的判定条件写得很克制:脚本里出现 script:GetActor() 就不会触发,因为那说明它是一个要被克隆到 Actor 下的 worker 模板;而 LuauAudit.files 在纯文件模式下会跳过这条规则,因为磁盘上无法知道 Actor 祖先关系(LuauAudit.luau、LuauAudit.luau)。

审计器的实现边界

理解 LuauAudit 是怎么做的,才能判断它的结论可信到什么程度。它的头部注释已经把边界写清楚:它读源码文本、抹掉字符串与注释、跟踪代码块;按名字传递的处理器(Heartbeat:Connect(onStep))不会被跟踪。

抹除逻辑见 LuauAudit.strip:它逐字符处理,遇到 -- 注释按长括号语法判断并整段抹成空格、遇到 [[ 长字符串保留括号并把内部抹掉、遇到引号串处理转义;关键在于每个换行都保留,这样行号在抹除后仍然对齐。

块跟踪靠一个栈,元素记录 kind(function 或 block)、tag、起始行、是否见过 yield、以及所属函数下标。tag 由三类模式决定:帧事件名 Connect*、移除事件名 Connect* 或 Once、以及 ConnectParallel / BindToMessageParallel;__x = function、table.sort(、gsub( 则打上 metamethod 标签(LuauAudit.luau)。

"是否是 yield"由一个模式列表判定,涵盖 task.wait(、wait(、:Wait(、:WaitForChild(、Async(、coroutine.yield(、:InvokeServer(、:InvokeClient(、:Invoke(、task.desynchronize(、task.synchronize((LuauAudit.luau)。这份列表本身就是一份"哪些调用会让出线程"的实用清单。

并行安全性由一组正则表达:.Parent =、:SetAttribute(、:Destroy(、:WriteVoxels(、以及 x.Prop = 形式的属性写入;inParallel 的判定同时考虑"在 parallel 标签的函数内且尚未 synchronize"与"进入了 desynchronize 阶段"两种情况(LuauAudit.luau)。

指令解析也很讲究:directives 只扫描文件头部连续的 --!xxx 行与注释行,一旦遇到第一个非空非注释行就停止。所以 --!strict 写在中间不会被识别为模块级指令。

局限也很清楚:这是启发式的文本分析,不做控制流与别名分析;native-untyped 只看参数列表里有没有 :;@native 的下一行函数才会被检查。这些限制不影响它作为"上 playtest 之前的快速筛查",但不能替代类型检查器与运行时探针。

与其他技能的交接

技能的 Handoffs 一节划清了职责边界,避免一次改动扩散到无关领域:

  • 从 scenario-roblox-architecture 接手:模块布局、清理库选择(Trove、Janitor、Maid)、信号模块。本技能只评审其中承载的 Luau 代码。
  • 交给 scenario-roblox-networking:BufferCodec schema 与实测负载体积;remotes、限流与线格式留在那边。
  • 交给 scenario-roblox-performance:Bench 与 Parallel 结果、native 候选、泄漏斜率;帧预算与 profiling 会话留在那边。
  • 与 scenario-roblox-gameplay 双向:定步长与 Server Authority 代码;本技能提供调度器与 Deferred 规则。
  • 从 scenario-roblox-data 接手:以玩家为键的会话状态;本技能检查 PlayerRemoving 清理。
  • 交给 scenario-roblox-tooling:类型门禁与 lune_luau_audit.luau,用于 CI。

这条边界对协作很重要:类型门禁和审计脚本是可以被 CI 直接消费的产物,而性能剖析与网络协议设计有各自的专家技能。

当前 Roblox 版本注记

技能列出的这几条会随构建变化,写作时需以本仓库内容为准:

  • Deferred 是模板默认值;Default 仍映射到 Immediate;Server Authority 强制 Deferred。SignalBehavior 是 NotScriptable。
  • 新类型求解器:nonstrict 与 nocheck 于 2025-11-20 全面发布;strict 跟随 UseNewLuauTypeSolver(NotScriptable)。旧求解器保留至 2026 年。
  • wait、spawn、delay 是废弃的全局函数;Stepped 与 RenderStepped 已被取代。
  • 原生代码生成运行在服务端脚本中;debug.dumpcodesize() 只能从 Command Bar(Server 视图)调用——从 execute_luau 调用会得到 "dumpcodesize can only be called from CommandBar"。
  • vector.create 在 Roblox 中返回 Vector3;buffer 序列化为 JSON 时形如 {"m":null,"t":"buffer","base64":...}。
  • collectgarbage 在 Roblox 脚本中只接受 "count"。

最后两条在实践中经常连在一起踩:把 buffer 直接丢进 JSON 会得到 base64 包装而不是紧凑数组,把 collectgarbage("collect") 写进清理函数会直接报错。

一条最小可执行的工作流

把上面的流程压成一条命令链,适合接入日常开发或 CI:

# 1) 双求解器类型门禁(先生成 sourcemap)
rojo sourcemap . -o sourcemap.json --include-non-scripts
python3 skills/game-engines/roblox/scenario-roblox-luau/scripts/rbx_luau.py typecheck src --sourcemap sourcemap.json

# 2) 静态审计(无需 Studio,error 会让退出码为 1)
python3 skills/game-engines/roblox/scenario-roblox-luau/scripts/rbx_luau.py audit src warn

在 Studio 侧的探针执行则通过 Python 通道完成,技能文档里给出的形态是:

import sys
sys.path.insert(0, "<skills>/scenario-roblox-luau/scripts")  # also puts the lead toolkit on the path
import rbx_env, rbx_luau
from rbx_play import Playtest

with rbx_env.place_slot():
    s = rbx_env.open_place("tests/places/scenario-roblox-luau/scenario-roblox-luau.rbxl")  # keep it open
    r = rbx_luau.run(s, open("edit_audit.luau").read(), dm="Edit", kit=["LuauAudit"])
    with Playtest(s) as pt:
        r = rbx_luau.run(s, open("play_scheduler.luau").read(), dm="Server", kit=["Probe"])
        r["ok"], r["result"], r["error"]

rbx_luau.run 会把本技能的 AgentKit 模块(scripts/agentkit/luau/<Name>.luau)以及 lead 技能的模块内联到 chunk 之前,并把错误行号映射回你自己的 chunk。实现上通过 kit_source 把每个模块包进一个立即执行的函数并赋给同名局部变量,templates/Class 会被命名为 Class(rbx_luau.py)。

注意该片段里两条硬性约束:不要在脚本里关闭场所窗口,也不要退出 Studio;每个 agent 只开一个场所并在整轮运行中保持打开。

参考文件索引

最后一点需要说明的证据边界:这些实测数字来自 Studio 0.743 在 macOS(Apple Silicon)上的运行,测试用的是从未发布过的本地场所,每个 MCP playtest 只有一个客户端。Windows、手机、主机与 VR 未覆盖,Team Create 与真实 DataStore 也未覆盖。在自己的项目里引用上述任何数字之前,应先用 Bench.run、Leak.retained 与 Parallel.workers 在同一构建上重测一遍——这恰好也是这个技能最核心的主张。

登录后查看全文
skills