roblox

roblox

引擎 API 参考（类和属性始终以此为准）： https://create.roblox.com/docs/reference/engine

面向 Agent 的完整文档索引：

• https://create.roblox.com/docs/llms.txt（从这里开始，然后转到引擎或 Open Cloud 子索引）
• 引擎专用：https://create.roblox.com/docs/reference/engine/llms.txt

本技能中心概述了整体情况，并引导你前往专门的 SKILL.md 入口。每项专门技能都维护自己的详细 references/ 索引，方便 Agent 仅加载所需内容。

专门技能

选择与任务匹配的技能。每项专门技能都链接到自己的详细参考资料。

• roblox-core：选择服务、类型、序列化方式和脚本位置
• roblox-networking：设计远程通信，验证客户端请求并控制复制
• roblox-datastores：保存玩家数据、处理并发写入并恢复版本
• roblox-user-interfaces：构建自适应 GUI、处理输入并添加 UI 效果
• roblox-animation：制作角色动画、配置 IK、补间属性并安排标记事件的时间
• roblox-vfx：制作粒子、翻页动画、光束、拖尾和高亮效果
• roblox-audio：构建音频图、混合效果并迁移旧版 Sound 代码
• roblox-gamepasses：处理通行证、商品、订阅、转让和购买政策
• roblox-open-cloud：通过 REST API 或受支持的 HttpService 调用自动化管理 Roblox 资源
• roblox-teleport：在不同场景间移动玩家、协调匹配并传递数据
• roblox-rojo：设置文件系统项目、与 Studio 同步、构建并导出场景
• roblox-mcp：将 Agent 连接到 Studio、检查实例、编辑脚本并进行试玩测试
• roblox-physics：构建机械结构、选择约束并分配物理所有权
• roblox-npcs：为 NPC 导航、处理被阻挡的路径，并构建巡逻或追逐行为
• roblox-testing：复现 Bug、编写测试并分析性能

共同约束

1. 优先保证服务器权威。 在服务器上验证或模拟。客户端负责输入、预测和外观效果。
2. 所有云端交互都可能失败。 对 DataStore、Marketplace、Http 等调用使用 pcall 包装。针对暂时性错误和永久性错误分别制定处理方案。
3. 预加载资源。 使用 ContentProvider:PreloadAsync 预加载动画、图像、声音和模型。
4. 使用现代 API。 使用 Animator + LoadAnimation、task.* 调度器、TweenService、IKControl、CollectionService 标签、Attributes 等。避免使用已弃用的 BodyMovers、wait/spawn/delay、Humanoid:LoadAnimation 等。
5. 遵守限制。 DataStore 预算会随并发用户数量增加，但仍有上限。粒子和透明 UI 会消耗大量填充率。尽早分析性能。
6. 采用便于维护的结构。 将权威逻辑放在 ServerScriptService，共享模块放在 ReplicatedStorage，客户端 UI 根节点放在 StarterGui，并确保模块边界清晰、命名一致。
7. 测试难点。 仅在测试场景中启用 Studio 的 API 访问权限。测试多种设备类别。将特效和 UI 的图形质量调低。测试并发情况（多个服务器同时访问相同的键）。

现代 API 说明

• 延迟事件： 设置 Workspace.SignalBehavior = Enum.SignalBehavior.Deferred（或使用对应的项目设置），让事件进入队列并批量触发，避免重入问题。
• 聊天： 使用 TextChatService 实现现代聊天；旧版 Chat 服务仍然存在，但属于较旧的 API。
• MemoryStore： 使用 MemoryStoreService 存储跨服务器、短期或高吞吐量数据，不要使用常规 DataStores。
• Parallel Luau： 使用 Actor 实例和 task.synchronize() / task.desynchronize() 处理计算密集型工作，并谨慎遵守共享状态规则。
• buffer 类型： 使用 buffer Luau 类型处理紧凑的二进制数据、序列化以及位/字节操作。
• UI 安全区域： 使用 ScreenGui.ScreenInsets 和相关属性，以适配设备刘海和安全区域。
• ConfigService： 使用集中的配置系统（通常是自定义的 ConfigService 模块或 Configuration 实例）管理实时配置和功能标志。

工作流

1. 加载负责该任务的专家技能。对于广泛的架构工作，还要阅读 architecture-principles.md。
2. 根据你处理的功能或故障，查看该专家技能链接的参考资料。对于存在交互的系统，阅读 cross-skill-integration.md。
3. 根据项目调整脚本示例，并检查其成熟度标签。在专用测试体验中验证更改。
4. 交接前，说明哪些检查已通过、哪些需要 Roblox 集成，以及尚未解决的 API 或策略问题。对于不确定的行为，请对照上述官方来源进行核实。

参考索引

• architecture-principles.md：选择跨系统的权限边界、数据流或项目结构。
• cross-skill-integration.md：将购买与持久化相结合，或将动画与效果和 UI 相结合。