mcpField
R
roblox-luau-patterns

roblox-luau-patterns

github.com/tabooharmony开发1382.2k 次安装2 周前更新
代码仓库

关于 roblox-luau-patterns

面向 Roblox Luau 开发的模式指南，涵盖模块设计、资源所有权、任务调度和失败约定，帮助开发者规划生命周期并审查代码。

主要功能

  1. 01选择函数、模块与对象结构
  2. 02明确资源所有权
  3. 03区分失败与 nil 结果
  4. 04有目的地调度任务
  5. 05审查模块约定

适用场景

  1. 01为功能选择模块结构
  2. 02清理任务与信号连接
  3. 03处理可能返回 nil 的调用
  4. 04检查调度与启动行为

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/tabooharmony/roblox-brain --skill roblox-luau-patterns

安装后在 Claude Code 中输入/roblox-luau-patterns确认已加载。

附带文件references/full.md

详细介绍

Luau 模式

何时加载

在涉及模块结构、资源所有权、调度和失败契约时加载。语义请参阅 roblox-luau-core，类型请参阅 roblox-luau-types，启动流程请参阅 roblox-architecture。

快速参考

选择结构
  • 普通函数： 无状态转换或验证的默认选择。
  • 含私有状态的模块： 由一个明确的子系统负责。不要仅为函数分组而创建管理器类。
  • 带元表的对象： 多个独立值需要共享行为和生命周期时使用。
  • 现有库抽象： 如果项目已经一致地使用某种抽象，就遵循它。不要仅为一个调用点添加 Promise、信号、清理或框架依赖。

构造函数使用 .，实例方法使用 :；可变字段应属于实例，而非类表。

明确所有权

信号连接、实例和任务都需要负责清理的所有者。拆卸时断开连接或取消任务。导出带类型的自定义信号载荷（Signal<T...>）。

先配置再设定父级，以隐藏不完整状态。只有在需要祖先关系时才提前设定父级，并说明原因。这不保证复制顺序。

保留失败语义
local ok, value = pcall(dataStore.GetAsync, dataStore, key)
if not ok then
    return nil, `read failed: {value}`
end
return value, nil -- value may legitimately be nil

不要把“调用成功并返回 nil”与“调用失败”混为一谈。只有当领域操作可以安全重复时才重试。持久化、HTTP、购买和远程调用请参阅各自领域的技能。

命名和返回契约

实践约定：将会让出执行权的函数标记为 Async，保持返回值数量一致，并优先使用具名模块导出。遵循现有项目契约；详情见 full.md。

谨慎安排调度

谨慎使用 task.defer、task.spawn、task.delay 和 task.cancel。避免使用旧式 wait() 和缺乏依据的轮询。优先采用实际的状态变更信号；否则，选择明确的调度间隔并进行测量。

审查

所有者明确，公共 API 范围精简，没有循环 require，没有意外的并发启动，成功状态与缺少数据的状态保持区分，连接和任务均得到清理，并将客户端输入交由 roblox-networking 处理。

详情：references/full.md

评论

支持 Markdown