roblox-luau-architecture

Roblox Luau 架构

目标

让 Roblox 游戏代码保持模块化、以服务器为权威，并且易于扩展。更改架构前，使用 Roblox Studio MCP 检查现有脚本。

MCP 工作流

1. 从 list_roblox_studios、必要时的 set_active_studio 和 get_studio_state 开始。
2. 使用 script_search 或 script_grep 定位代码。
3. 编辑前，使用 script_read 阅读相关脚本。
4. 使用 multi_edit 应用编辑。
5. 使用 start_stop_play 进行游戏测试。
6. 检查 get_console_output，确认没有引入回归问题。

放置规则

• 将权威游戏逻辑放在 ServerScriptService 或服务器拥有的模块中。
• 将共享常量、类型定义、远程对象和纯共享辅助函数放在 ReplicatedStorage 中。
• 将玩家输入、摄像头、仅本地 UI 和视觉预测放在客户端脚本中。
• 尽量少用工作区脚本，并确保用途明确；优先使用管理带标签实例或已配置文件夹的服务式脚本。
• 避免在客户端和服务器之间分散重复常量。

远程边界

• 将客户端发来的每个远程载荷都视为不可信。
• 优先使用范围明确的远程对象，并为其指定明确的操作名称和类型化载荷检查。
• 对可能影响经济系统、库存、战斗或放置操作的玩家触发远程调用进行限流。
• 谨慎使用 RemoteFunctions；避免从客户端调用会长时间挂起的服务器调用。
• 绝不允许客户端决定货币、库存、所有权、伤害、任务完成状态或购买发放内容。

模块模式

以下情况使用模块：

• 具有 Init 和 Start 式生命周期的服务。
• 数据访问封装层。
• 经济计算。
• 奖励表和数值平衡常量。
• 客户端 UI 控制器。
• 确定性强且副作用少的共享实用函数。

模块应保持精简，让其他系统可以依赖它，而无需导入无关行为。

优先使用深模块

目标是构建深模块：以小巧、稳定的接口封装大量行为。浅模块的接口几乎和实现一样复杂，只有在它确实隐藏了复杂性时才值得保留。

• 接口 = 调用方必须了解的一切：函数签名，以及不变量、执行顺序、错误模式和可调用它的一方（客户端/服务器）。在 Roblox 中，远程对象的约定也是其接口的一部分。
• **删除测试：**设想删除某个模块。如果复杂性随之消失，它只是一个传递层，应将其内联。如果同样的复杂性在多个调用点重新出现，它就发挥了作用，应予以保留并加深。
• **内聚性：**将相关行为及其重要状态规则放在同一个模块中，这样修改、错误或推理所需的知识都能集中在一处，而不是分散在 LocalScript、服务器 Script 和三个常量文件中。
• 一个适配器满足某个接口只是设想中的接缝；两个才是真正的接缝。不要为单一实现增加间接层。

好的接缝应以游戏自身的术语命名（例如“硬币经济服务”“任务追踪器”），而不是泛化的名称（例如“Handler”“Manager”）。

重构输出

提出或进行架构更改时，请包含：

• 当前脚本的位置和职责。
• 建议的模块/服务边界。
• 远程约定的更改。
• 迁移步骤。
• 游戏测试和控制台检查。

后续步骤

使用 roblox-to-issues 将架构工作拆分成小任务，一次安全地落地一项，并使用 roblox-playtest-qa 验证每项更改。对于重要状态模块，使用 roblox-security-economy 审查信任边界；对于清理现有技术债，使用 roblox-code-maintenance-refactor。