roblox-luau-developer

Roblox Luau 开发者

用于实现、审查和重构 Roblox Luau 代码、诊断运行时问题以及同步由 Rojo 管理的代码库的工作流。假设你熟悉 Luau 和 Roblox 服务端／客户端模型；下文将介绍项目结构。

确定项目结构

首先确定项目的组织方式：

• Rojo 项目：包含 default.project.json 或 *.project.json；工具链文件和同步工作流见 references/rojo-workflow.md。
• Studio 导出：识别 .rbxlx、.rbxmx、.model.json、src/、ReplicatedStorage/、ServerScriptService/。
• TypeScript 源码：roblox-ts 项目包含 tsconfig.json、rbxtsc 和 @rbxts/* 包；其 .ts 源码是事实来源，而 out/ 是由 roblox-typescript-developer 管理的构建产物。

编辑前先阅读

• 使用 rg 搜索服务、模块、Remote 名称、Attribute 名称和 CollectionService 标签。
• 梳理 ServerScript、LocalScript 和 ModuleScript 的调用方向。
• 实例路径、Remote 名称和 UI 控件名称以项目为准。

保持服务端／客户端分层

• 权威状态和验证逻辑位于服务端。
• 客户端负责输入、显示、预测和请求。
• 必须检查 Remote 参数的类型和权限。
• DataStore 写入需要限流、重试和故障处理。

优先进行小幅修改

• 保持现有模块的返回结构、服务名称和 require 风格。
• 模块状态应保存在模块中，或通过参数传入。
• 为共享表和连接对象提供清理机制。

调试

对于运行时、复制、性能、DataStore 和 UI 不更新的问题，请遵循 references/gameplay-debugging.md 中的操作指南。如果缺陷涉及 UI 布局、焦点或屏幕生命周期，而非数据流，则交由 roblox-ui-developer 处理。

Rojo 项目

如需了解、维护和同步由 Rojo 管理的代码库，请遵循 references/rojo-workflow.md。

常见问题

• 客户端输入不可信：服务器拥有生命值、货币和库存，因此必须验证每个远程参数的类型和范围。
• LocalScript 的放置位置决定客户端代码是否会运行——可放在 StarterPlayerScripts、StarterCharacterScripts、StarterGui 或工具中。服务端 Script 应放在 ServerScriptService 或 Workspace 中。
• 使用 task.wait、task.spawn 和 task.delay；全局函数 wait、spawn 和 delay 已弃用，且调度效果更差。
• 先设置属性，再设置 Parent：设置父级会触发复制，因此实例应以最终状态复制一次。
• 对尚未复制过来的对象，客户端看到的可能是 nil：玩家刚加入后，使用 parent:WaitForChild("Name") 逐层访问。
• 保留连接对象，并在拆除时断开连接；长期存在的 :Connect 处理程序会造成泄漏，且会在实例销毁后触发。对于预期只调用一次的情况，使用 :Once。
• RemoteFunction 会阻塞调用方，因此缓慢的客户端可能拖住服务器：除非确实需要响应，否则优先使用单向 RemoteEvent。

验证

• 优先使用现有检查工具：selene、stylua、luau-lsp、lune、rojo 或项目脚本。
• 对验证结果分级：在 Studio 中执行、静态检查（lint、分析、sourcemap）、已准备但未运行，或未验证。绝不能把最后三种情况说成已通过 Studio 验证。

输出

• 修改内容：说明哪些脚本和行为发生了变化。
• 服务端／客户端边界：说明权威逻辑所在位置。
• Remote／DataStore 风险：说明新增或更改的接口。
• 验证：说明实际运行的检查，并按上述方式分级。