roblox-core

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

roblox-core

When to Use

适用场景

Use this skill when the task is primarily about core Roblox runtime structure and everyday gameplay scripting:

Choosing whether logic belongs on the client, server, or both.
Deciding where
```
Script
```
,
```
LocalScript
```
, and
```
ModuleScript
```
instances should live.

Organizing code across

ServerScriptService

ServerStorage

ReplicatedStorage

ReplicatedFirst

StarterPlayer

StarterGui

, and

Workspace

Using services, module reuse, attributes, and bindables inside normal gameplay code.
Working with common Studio scripting workflows like playtesting, Explorer layout,
```
WaitForChild()
```
, and Output-driven debugging.
Implementing straightforward input, camera, raycasting, collision, and
```
CFrame
```
behavior as part of ordinary experience scripting.

Do not use this skill when the task is mainly about:

Exhaustive engine API lookup or class-by-class reference browsing.
Cross-boundary remote design, advanced remote security, or server-authority architecture.
Persistence, memory stores, messaging, Open Cloud, OAuth, or external automation.

当任务主要围绕Roblox核心运行时结构和日常玩法脚本开发时，可使用本技能：

确定逻辑应当运行在客户端、服务端还是两端同时运行。
确定
```
Script
```
、
```
LocalScript
```
和
```
ModuleScript
```
实例的存放位置。

梳理

ServerScriptService

、

ServerStorage

、

ReplicatedStorage

、

ReplicatedFirst

、

StarterPlayer

、

StarterGui

和

Workspace

之间的代码组织逻辑。

在常规玩法代码中使用服务、模块复用、属性和绑定事件。
处理常见的Studio脚本工作流，比如 playtesting、资源管理器布局、
```
WaitForChild()
```
和基于输出日志的调试。
作为常规体验脚本的一部分，实现基础的输入、相机、射线检测、碰撞和
```
CFrame
```
相关行为。

以下场景不适用本技能：

需要全面查询引擎API或逐类查阅参考文档的场景。
跨边界远程调用设计、高级远程安全或服务端权威架构相关内容。
数据持久化、内存存储、消息通信、Open Cloud、OAuth或外部自动化相关内容。

Decision Rules

判定规则

Use this skill if the main question is structural: where code lives, what runs where, what replicates, or how to organize reusable Roblox logic.
Use this skill for foundational engine patterns that appear in most experiences: services, modules, attributes, bindables, basic input, workspace access, collisions, raycasts, camera, and
```
CFrame
```
.
If the task centers on
```
RemoteEvent
```
,
```
RemoteFunction
```
, trust boundaries, request validation, or multiplayer message design, hand off to
```
roblox-networking
```
.
If the task is mainly "which API/member do I call" across a large Roblox surface area, hand off to
```
roblox-api
```
.
If the task centers on saving, loading, quotas, versioning, cross-server state, or ephemeral shared state, hand off to
```
roblox-data
```
.
If the task involves Open Cloud, web APIs, credentials, OAuth, or external tooling automation, hand off to
```
roblox-cloud
```
or
```
roblox-oauth
```
.
If a request mixes core structure with out-of-scope systems, answer only the foundational Roblox portion and explicitly exclude the rest.
If unsure, prefer the narrower interpretation and omit material that would overlap networking, data, cloud, or API-reference skills.

如果核心问题是结构性问题：代码存放位置、运行端、复制逻辑，或者如何组织可复用的Roblox逻辑，使用本技能。
如果涉及绝大多数体验都会用到的基础引擎模式：服务、模块、属性、绑定事件、基础输入、工作区访问、碰撞、射线检测、相机和
```
CFrame
```
，使用本技能。
如果任务核心是
```
RemoteEvent
```
、
```
RemoteFunction
```
、信任边界、请求校验或多人消息设计，移交到
```
roblox-networking
```
技能处理。
如果任务主要是「我要调用哪个API/成员」这类覆盖大范围Roblox能力的问题，移交到
```
roblox-api
```
技能处理。
如果任务核心是数据保存、加载、配额、版本控制、跨服务状态或临时共享状态，移交到
```
roblox-data
```
技能处理。
如果任务涉及Open Cloud、Web API、凭证、OAuth或外部工具自动化，移交到
```
roblox-cloud
```
或
```
roblox-oauth
```
技能处理。
如果请求同时包含核心结构内容和超出范围的系统，仅回答基础Roblox相关部分，并明确说明其余内容不做解答。
如果不确定范围，优先采用更窄的解释，省略和网络、数据、云或API参考类技能重叠的内容。

Instructions

使用指南

Start by identifying the runtime side for each responsibility:
- Server for authoritative world state, spawning, rule enforcement, and shared simulation.
- Client for player-local input, camera, moment-to-moment presentation, and local feedback.
- Shared modules only when both sides need the same code or constants.
Place code in containers that match replication behavior:
- ```
ServerScriptService
```
  for server-only scripts and modules.
- ```
ServerStorage
```
  for server-only assets or modules that do not need to replicate.
- ```
ReplicatedStorage
```
  for shared modules and replicated assets.
- ```
ReplicatedFirst
```
  only for earliest client startup work.
- ```
StarterPlayerScripts
```
  ,
```
StarterCharacterScripts
```
  ,
```
StarterGui
```
  , and
```
StarterPack
```
  for client behavior copied into each player.
Prefer explicit script intent:
- Use
```
LocalScript
```
  or
```
Script
```
  with
```
RunContext = Client
```
  for client code.
- Use
```
Script
```
  with
```
RunContext = Server
```
  or normal server placement for server code.
- Use
```
ModuleScript
```
  for reusable logic and configuration.
Retrieve services once near the top of a script with
```
game:GetService()
```
and keep names aligned with service names.
Use
```
WaitForChild()
```
when accessing replicated objects from the client unless the load order is guaranteed by the container being used.
Treat
```
ModuleScript
```
return values as cached per Luau environment:
- Require once per script and reuse the returned table or function.
- Avoid circular requires.
- Keep shared modules side-agnostic unless the module is intentionally server-only or client-only.
Use attributes for lightweight per-instance state and configuration that should live on the instance itself.
Use bindables only for communication on the same side of the client-server boundary. Prefer module-owned bindables when they simplify a local event API.
For input and camera code, keep implementation client-side and adapt to the player's active input mode rather than assuming desktop-only controls.
For workspace scripting:
- Read and write object state through clear references.
- Use raycasts for intentional spatial queries.
- Use collision groups or part properties for collision behavior.
- Use
```
CFrame
```
  operations when orientation and relative transforms matter.
Keep examples and guidance at the foundational level. Do not drift into persistence, advanced networking security, or exhaustive reference lookups.

首先为每个职责确定运行端：
- 服务端负责权威世界状态、对象生成、规则执行和共享模拟。
- 客户端负责玩家本地输入、相机、实时表现和本地反馈。
- 仅当两端需要相同代码或常量时，使用共享模块。
将代码存放在匹配复制行为的容器中：
- 仅服务端可用的脚本和模块存放在
```
ServerScriptService
```
  。
- 不需要复制的仅服务端可用资源或模块存放在
```
ServerStorage
```
  。
- 共享模块和需要复制的资源存放在
```
ReplicatedStorage
```
  。
- ```
ReplicatedFirst
```
  仅用于最早的客户端启动任务。
- 会复制到每个玩家的客户端行为存放在
```
StarterPlayerScripts
```
  、
```
StarterCharacterScripts
```
  、
```
StarterGui
```
  和
```
StarterPack
```
  。
优先明确脚本的运行意图：
- 客户端代码使用
```
LocalScript
```
  或者设置了
```
RunContext = Client
```
  的
```
Script
```
  。
- 服务端代码使用设置了
```
RunContext = Server
```
  的
```
Script
```
  ，或者存放在常规服务端位置的普通
```
Script
```
  。
- 可复用逻辑和配置使用
```
ModuleScript
```
  。
在脚本顶部通过
```
game:GetService()
```
一次性获取服务，变量名和服务名称保持一致。
从客户端访问复制的对象时使用
```
WaitForChild()
```
，除非所用容器能保证加载顺序。
注意
```
ModuleScript
```
的返回值在每个Luau环境中会被缓存：
- 每个脚本中仅require一次，复用返回的表或函数。
- 避免循环引用。
- 保持共享模块的运行端无关性，除非模块明确是仅服务端或仅客户端使用。
轻量的实例级状态和配置使用属性实现，直接挂载在实例本身。
绑定事件仅用于客户端-服务端边界同一侧的通信，如果能简化本地事件API，优先使用模块所属的绑定事件。
输入和相机代码放在客户端实现，适配玩家的活跃输入模式，不要默认仅支持桌面端控制。
工作区脚本开发注意：
- 通过清晰的引用读写对象状态。
- 射线检测仅用于明确的空间查询场景。
- 碰撞行为使用碰撞组或者部件属性控制。
- 当需要处理朝向和相对变换时使用
```
CFrame
```
  操作。
示例和指导保持基础层级，不要涉及持久化、高级网络安全或全面的参考查询内容。

Using References

参考文档使用

Open
```
references/scripting-overview.md
```
for the basic Roblox scripting workflow in Studio and the standard service-module-function-event script shape.
Open
```
references/client-server-runtime.md
```
to reason about authority, replication, edit versus runtime data models, and what each side can safely assume.

Open

references/script-locations-and-script-types.md

when deciding between

Script

LocalScript

ModuleScript

, run contexts, and container placement.

Open
```
references/services.md
```
for the core
```
game:GetService()
```
pattern and which container or gameplay services matter most in foundational code.
Open
```
references/modulescripts-and-reuse-patterns.md
```
for module caching, shared code placement, configuration modules, and encapsulation patterns.
Open
```
references/attributes.md
```
for per-instance state, replication-order cautions, and change-detection patterns.
Open
```
references/bindable-events.md
```
for same-side script communication, async events, sync callbacks, and argument-shape cautions.
Open
```
references/input-overview.md
```
for client-side input handling and adapting to preferred input type across devices.

Open

references/workspace-basics-camera-raycasting-collisions-and-cframes.md

for the most common world-facing runtime patterns.

查阅
```
references/scripting-overview.md
```
了解Studio中基础Roblox脚本工作流，以及标准的服务-模块-函数-事件脚本结构。
查阅
```
references/client-server-runtime.md
```
了解权威、复制、编辑与运行时数据模型，以及各端可以安全依赖的内容。

查阅

references/script-locations-and-script-types.md

了解

Script

、

LocalScript

、

ModuleScript

、运行上下文和容器存放位置的选择规则。

查阅
```
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

了解最常见的面向世界的运行时模式。

Checklist

检查清单

Each responsibility is assigned to the correct runtime side.
Script and module placement matches replication and visibility needs.
Shared code is in
```
ModuleScript
```
form instead of duplicated across scripts.
Client code uses
```
WaitForChild()
```
where replication order is uncertain.
Services are retrieved once and reused.
Attributes are used for lightweight instance state, not arbitrary module data.
Bindables are only used on one side of the client-server boundary.
Input and camera code stays client-side.
Raycasts, collisions, and
```
CFrame
```
operations are used intentionally for spatial logic.
No advanced remote-security design is included.
No persistence, Open Cloud, OAuth, or external API automation guidance is included.
No exhaustive API catalog material is included.

每个职责都分配到了正确的运行端。
脚本和模块的存放位置匹配复制和可见性需求。
共享代码以
```
ModuleScript
```
形式存在，没有在多个脚本中重复实现。
复制顺序不确定时，客户端代码使用了
```
WaitForChild()
```
。
服务仅被获取一次并复用。
轻量的实例状态使用属性实现，没有存放任意模块数据。
绑定事件仅在客户端-服务端边界的同一侧使用。
输入和相机代码放在客户端。
射线检测、碰撞和
```
CFrame
```
操作仅用于明确的空间逻辑。
没有包含高级远程安全设计内容。
没有包含持久化、Open Cloud、OAuth或外部API自动化相关指导。
没有包含全面的API目录内容。

Common Mistakes

常见错误

Putting server-only logic in
```
ReplicatedStorage
```
or other replicated containers.
Expecting a plain
```
Script
```
to run everywhere without considering location or
```
RunContext
```
.
Using
```
LocalScript
```
where a shared
```
ModuleScript
```
should hold reusable logic.
Assuming replicated objects already exist on the client and skipping
```
WaitForChild()
```
.
Treating bindables as cross-network communication tools.
Mutating a module return value without realizing the cached reference is reused within that environment.
Using attributes for large structured data that belongs in a module or system object.
Driving camera or input code from the server.
Using
```
Touched
```
for non-physical overlap logic that should be a raycast or explicit spatial query.
Moving parts with raw position logic when relative transforms or facing direction require
```
CFrame
```
.

将仅服务端逻辑存放在
```
ReplicatedStorage
```
或其他可复制容器中。
认为普通
```
Script
```
可以在任意位置运行，忽略了存放位置或
```
RunContext
```
的影响。
应该用共享
```
ModuleScript
```
存放可复用逻辑的场景，错误使用了
```
LocalScript
```
。
认为复制的对象已经在客户端存在，省略了
```
WaitForChild()
```
调用。
将绑定事件当作跨网络通信工具使用。
修改模块返回值时，没有意识到缓存的引用会在当前环境中被复用。
用属性存放本该放在模块或系统对象中的大型结构化数据。
从服务端驱动相机或输入代码。
本该用射线检测或明确空间查询实现的非物理重叠逻辑，错误使用了
```
Touched
```
事件。
当相对变换或朝向需要使用
```
CFrame
```
时，错误使用原始位置逻辑移动部件。

Examples

示例

Choose placement by responsibility

按职责选择存放位置

lua

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

lua

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

lua

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

return Constants

lua

-- ServerScriptService/SpawnController
-- 在服务端生成并管理共享世界状态。

lua

-- StarterPlayer/StarterPlayerScripts/InputController
-- 在客户端读取玩家输入并驱动本地表现。

lua

-- ReplicatedStorage/Shared/Constants
-- 两端共用的共享模块。
local Constants = {
    MaxHealth = 100,
    RoundLength = 120,
}

return Constants

Use the standard script shape

使用标准脚本结构

lua

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)

lua

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)

Keep client-only camera code local

仅客户端的相机代码放在本地

lua

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)

lua

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)

Use attributes and bindables for local structure

本地结构使用属性和绑定事件

lua

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"))

lua

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"))