roblox-core

roblox-core

适用场景

当任务主要涉及 Roblox 运行时的核心结构和日常游戏玩法脚本编写时，使用此技能：

• 选择逻辑应放在客户端、服务器端还是两者都放。
• 决定 Script、LocalScript 和 ModuleScript 实例应放在哪里。
• 在 ServerScriptService、ServerStorage、ReplicatedStorage、ReplicatedFirst、StarterPlayer、StarterGui 和 Workspace 中组织代码。
• 在常规游戏玩法代码中使用服务、复用模块、属性和 Bindable。
• 使用常见的 Studio 脚本工作流，例如游戏测试、Explorer 布局、WaitForChild() 和基于 Output 的调试。
• 在常规体验脚本中实现简单的输入、摄像机、射线检测、碰撞和 CFrame 行为。

当任务主要涉及以下内容时，不要使用此技能：

• 穷尽式引擎 API 查询或逐类浏览参考文档。
• 跨边界远程通信设计、高级远程安全或服务器权威架构。
• 持久化、内存存储、消息传递、Open Cloud、OAuth 或外部自动化。

决策规则

• 如果核心问题是结构性的：代码放在哪里、什么内容在哪运行、什么内容会复制，或如何组织可复用的 Roblox 逻辑，请使用此技能。
• 对于大多数体验中都会用到的基础引擎模式，请使用此技能：服务、模块、属性、Bindable、基本输入、工作区访问、碰撞、射线检测、摄像机和 CFrame。
• 如果任务聚焦于 RemoteEvent、RemoteFunction、信任边界、请求验证或多人游戏消息设计，请转交给 roblox-networking。
• 如果任务主要是询问在 Roblox 的大量 API 中“该调用哪个 API/成员”，请转交给 roblox-api。
• 如果任务聚焦于保存、加载、配额、版本控制、跨服务器状态或临时共享状态，请转交给 roblox-data。
• 如果任务涉及 Open Cloud、Web API、凭据、OAuth 或外部工具自动化，请转交给 roblox-cloud 或 roblox-oauth。
• 如果请求将核心结构与范围外的系统混在一起，只回答基础的 Roblox 部分，并明确排除其余部分。
• 如果不确定，优先采用较窄的解释，并省略与网络通信、数据、云服务或 API 参考技能重叠的内容。

说明

1. 首先确定每项职责由哪一端负责：
   • 服务端负责权威世界状态、生成、规则执行和共享模拟。
   • 客户端负责玩家本地输入、摄像机、即时呈现和本地反馈。
   • 仅在两端都需要相同代码或常量时使用共享模块。
2. 将代码放在与其复制行为相符的容器中：
   • ServerScriptService 用于仅在服务端运行的脚本和模块。
   • ServerStorage 用于不需要复制的服务端专用资源或模块。
   • ReplicatedStorage 用于共享模块和复制的资源。
   • ReplicatedFirst 仅用于客户端最早期的启动工作。
   • StarterPlayerScripts、StarterCharacterScripts、StarterGui 和 StarterPack 用于复制到每位玩家的客户端行为。
3. 明确脚本的用途：
   • 客户端代码使用 LocalScript，或将 Script 的 RunContext 设为 Client。
   • 服务端代码使用 RunContext 为 Server 的 Script，或将脚本放在常规服务端位置。
   • 可复用逻辑和配置使用 ModuleScript。
4. 在脚本顶部附近使用 game:GetService() 获取服务，并使名称与服务名称一致。
5. 从客户端访问复制的对象时使用 WaitForChild()，除非使用的容器能够保证加载顺序。
6. 将 ModuleScript 的返回值视为在每个 Luau 环境中都会缓存：
   • 每个脚本仅调用一次 require，并复用返回的表或函数。
   • 避免循环调用 require。
   • 除非模块明确仅供服务端或客户端使用，否则共享模块应与运行端无关。
7. 使用属性存储轻量级的实例状态和配置，使其与实例本身关联。
8. 仅使用 Bindable 在客户端-服务端边界的同一侧进行通信。若模块自带的 Bindable 能简化本地事件 API，则优先使用。
9. 输入和摄像机代码应在客户端实现，并适配玩家当前的输入模式，而不要假设玩家只使用桌面端控制方式。
10. 对于 workspace 脚本：
    • 通过清晰的引用读取和写入对象状态。
    • 使用射线投射执行有明确目的的空间查询。
    • 使用碰撞组或部件属性来控制碰撞行为。
    • 当方向和相对变换很重要时，使用 CFrame 操作。
11. 示例和指南应停留在基础层面。不要扩展到持久化、高级网络安全或全面的参考查询。

使用参考资料

• 打开 references/scripting-overview.md，了解 Studio 中 Roblox 脚本的基本工作流，以及标准的服务、模块、函数和事件脚本结构。
• 打开 references/client-server-runtime.md，了解权威性、复制、编辑时与运行时的数据模型，以及每一端可以安全假设的内容。
• 在需要选择 Script、LocalScript、ModuleScript、运行上下文和容器位置时，打开 references/script-locations-and-script-types.md。
• 打开 references/services.md，了解核心 game:GetService() 模式，以及基础代码中最重要的容器或游戏服务。
• 打开 references/modulescripts-and-reuse-patterns.md，了解模块缓存、共享代码位置、配置模块和封装模式。
• 打开 references/attributes.md，了解实例级状态、复制顺序注意事项和变更检测模式。
• 打开 references/bindable-events.md，了解同侧脚本通信、异步事件、同步回调和参数形式注意事项。
• 打开 references/input-overview.md，了解客户端输入处理，以及如何在不同设备上适配首选输入类型。
• 打开 references/workspace-basics-camera-raycasting-collisions-and-cframes.md，了解最常见的面向世界的运行时模式。

检查清单

• 每项职责都分配给了正确的运行时端。
• 脚本和模块的放置符合复制和可见性需求。
• 共享代码使用 ModuleScript，而不是在多个脚本中重复编写。
• 复制顺序不确定时，客户端代码会使用 WaitForChild()。
• 服务只获取一次，并重复使用。
• 属性用于轻量级实例状态，而不是任意模块数据。
• Bindable 仅用于客户端-服务器边界的同一侧。
• 输入和摄像机代码保留在客户端。
• 有意使用射线检测、碰撞和 CFrame 操作处理空间逻辑。
• 不包含高级远程安全设计。
• 不包含持久化、Open Cloud、OAuth 或外部 API 自动化指导。
• 不包含详尽的 API 目录内容。

常见错误

• 将仅限服务器的逻辑放在 ReplicatedStorage 或其他可复制容器中。
• 未考虑位置或 RunContext，就认为普通 Script 可以在任何地方运行。
• 在应该由共享 ModuleScript 保存可复用逻辑时使用 LocalScript。
• 假设客户端上的复制对象已经存在，因而跳过 WaitForChild()。
• 将 Bindable 视为跨网络通信工具。
• 修改模块的返回值，却没有意识到同一运行环境会重复使用缓存引用。
• 将属性用于本应放在模块或系统对象中的大型结构化数据。
• 在服务器上驱动摄像机或输入代码。
• 对本应使用射线检测或显式空间查询的非物理重叠逻辑使用 Touched。
• 当相对变换或朝向需要 CFrame 时，仍使用原始位置逻辑移动部件。

示例

根据职责选择放置位置

-- ServerScriptService/SpawnController
-- Spawns and manages shared world state on the server.

-- StarterPlayer/StarterPlayerScripts/InputController
-- Reads player input and drives local presentation on the client.

-- ReplicatedStorage/Shared/Constants
-- Shared module used by both sides.
local Constants = {
    MaxHealth = 100,
    RoundLength = 120,
}

return Constants

使用标准脚本结构

local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local RoundConfig = require(ReplicatedStorage:WaitForChild("RoundConfig"))

local function onPlayerAdded(player)
    print(player.Name, "joined; round length:", RoundConfig.RoundLength)
end

Players.PlayerAdded:Connect(onPlayerAdded)

将仅限客户端的摄像机代码保留在本地

local Workspace = game:GetService("Workspace")

local camera = Workspace.CurrentCamera
camera.CameraType = Enum.CameraType.Scriptable
camera.CFrame = CFrame.lookAt(Vector3.new(0, 10, 20), Vector3.new(0, 5, 0))
camera.Focus = CFrame.new(0, 5, 0)

使用属性和 Bindable 构建本地结构

local part = script.Parent
part:SetAttribute("Active", true)

local changed = Instance.new("BindableEvent")
changed.Event:Connect(function(state)
    print("State changed:", state)
end)

changed:Fire(part:GetAttribute("Active"))