roblox-core

roblox-core

主要来源： https://create.roblox.com/docs/en-us/scripting/services、https://create.roblox.com/docs/en-us/luau、https://create.roblox.com/docs/en-us/luau/tables、https://create.roblox.com/docs/en-us/luau/type-checking、https://create.roblox.com/docs/en-us/scripting/locations、https://create.roblox.com/docs/en-us/projects/data-model、https://create.roblox.com/docs/en-us/projects/client-server、https://create.roblox.com/docs/en-us/workspace/streaming、https://create.roblox.com/docs/en-us/scripting/multithreading、https://create.roblox.com/docs/en-us/scripting/attributes

脚本初始化

1. local Service = game:GetService("ServiceName")。只调用一次，变量名使用服务名称。
2. local Module = require(ReplicatedStorage:WaitForChild("Module"))
3. 本地辅助函数。
4. 连接事件。

服务是访问引擎功能的主要方式，可取代传统的标准库。

现代 task 库

使用现代 task API；旧版全局函数 wait()、spawn() 和 delay() 已弃用或即将弃用：

• task.wait(n?)：等待约 n 秒（默认一帧），并返回经过的时间。
• task.spawn(f, ...)：安排异步运行 f。
• task.defer(f, ...)：将 f 推迟到当前事件周期结束后运行。
• task.cancel(thread)：取消由 task.spawn/task.defer 返回的线程。

对于并行代码，task.desynchronize() 和 task.synchronize() 可在并行阶段与串行阶段之间切换当前线程。

按用途划分的服务

容器／层级服务（在 Explorer 中可见，属于 DataModel）：

• Workspace（3D 内容）
• Lighting（环境、氛围、后期效果）
• ReplicatedStorage / ReplicatedFirst（共享代码和资源）
• ServerScriptService（仅服务器端逻辑）
• StarterGui / StarterPlayer / StarterPack（克隆给玩家的模板）
• Players、Teams、SoundService 等

核心运行时和脚本服务：

• RunService：Heartbeat 在两端的物理模拟后触发；PreSimulation 在两端的物理模拟前触发；PreRender 仅限客户端，在渲染前触发。
• TweenService（参见动画技能）
• CollectionService（标签）
• ContextActionService、UserInputService、GuiService
• ContentProvider（预加载）

云端／持久化／跨服务器：

• DataStoreService、MemoryStoreService、MessagingService（参见 roblox-datastores 技能）

变现：

• MarketplaceService（游戏通行证、开发者产品；参见专门技能）
• BadgeService 等

**其他重要服务：**TeleportService、AnalyticsService、HttpService（仅支持出站请求和 JSONEncode/Decode）、PathfindingService 等。

使用 game:GetService（已知服务）或 game:FindService（可选）查找服务。避免使用 game:GetChildren() 查找服务。并非每个 DataModel 子项都是服务，而且服务可能会延迟创建。每个脚本／模块只获取一次各项服务。

Instance 创建最佳实践

在将 Instance 设为父级之前先完成配置，以避免冗余复制和额外的变更事件：

local part = Instance.new("Part")
part.Anchored = true
part.Size = Vector3.new(4, 1, 2)
part.Position = Vector3.new(0, 10, 0)
part.Parent = workspace

最后设置 Parent；不要使用 Instance.new("Part", parent) 这种双参数形式。

类型与序列化

在设计持久化值或调试序列化之前，请阅读 luau-data-types-and-serialization.md。DataStores、JSON 和 remotes 支持的类型各不相同。JSONEncode 成功执行是有用的检查，但不能证明某个值满足所有 DataStore 约束。

类型检查

类型检查采用渐进式且默认不启用。可在文件顶部添加 --!strict（仅对该文件生效），或使用 .luaurc 项目配置启用全项目类型检查。大型模块可添加类型注解（local x: number、函数签名）。类型推断可以完成大量工作。它能在编辑时发现错误，且不会产生运行时开销。

脚本位置和执行上下文

• ServerScriptService + Script（RunContext.Server）→ 仅在服务器运行，可访问 DataStores 等服务器 API。
• ReplicatedStorage → 存储共享的 ModuleScripts/资源。这里的 Script 只有在其 RunContext 设置为 Client 或 Server 时才会运行；共享逻辑应使用 ModuleScripts。
• StarterGui + LocalScript → 仅在每位玩家的客户端运行（位于克隆出的 PlayerGui 中）。
• ReplicatedFirst + LocalScript → 在客户端极早期执行（加载界面）。
• Actor + Script（RunContext.Client/Server）→ 当代码调用 task.desynchronize() 或使用 ConnectParallel() 时，可运行 Parallel Luau。Actor 必须以 DataModel 为父级，且 Script 必须设置明确的 RunContext；仅将 Script 放在 Actor 内并不会使其并行运行。只有模块本身支持并行时，才能在并行上下文中调用 require()；大多数引擎 API 和许多模块都不支持。
• Tool 有特殊的执行上下文。HopperBins 已弃用/属于旧版功能，不应在新项目中使用。

现代 Roblox 使用 BaseScript.RunContext（Legacy、Server、Client、Plugin）。Legacy 仅为向后兼容而保留，并且其行为取决于位置；新代码应优先使用明确的 Server 或 Client。RunContext 在 Studio 的 Properties 窗口中设置，运行时为只读。

始终使用 RunService:IsServer() 和 IsClient() 来判断运行时权限。IsStudio() 用于检测环境（Studio 与线上环境），而非运行上下文，因此只应将其用于测试/开发保护逻辑。

切勿将数据存储写入、经济系统或权威游戏逻辑放在客户端可以直接影响的位置。

Luau/Roblox 中的“文件”和数据

在运行中的体验中，无法直接访问文件系统（出于安全考虑）。你不能打开任意文件，也不能写入玩家可见的日志。

你可以使用：

• DataStores / MemoryStores 存储持久或临时的“保存数据”。
• ModuleScripts 编写可复用代码（require 的工作方式类似缓存的模块系统：ModuleScript 运行一次，后续调用 require 时会返回相同的值）。
• HttpService:JSONEncode/Decode + Web 调用进行外部数据交换。
• 在 Studio 中：插件拥有有限的文件 API，外部工具（Rojo、Script Sync）可以从文件系统同步代码，但体验脚本无法任意访问文件系统。

对于复杂数据，通常会将表序列化为 JSON 字符串，以便存储或传输。

其他运行时注意事项

• Attributes：使用 :SetAttribute/GetAttribute 存储轻量的实例数据；优先使用它们，而不是旧版 Value 对象。
• Random：使用 Random 类（Random.new(seed)）创建确定性或独立的随机流，而不是全局的 math.randomseed。
• StreamingEnabled：在客户端，实例可能会动态加载或卸载；应始终谨慎使用 WaitForChild/Instance.StreamingMode，并避免硬编码对远处部件的引用。
• table 实用函数：table.create(n, value)、table.find(t, value)、table.clone(t) 和 table.freeze(t)/table.isfrozen(t) 是较新的辅助函数。
• BaseScript.Enabled：启用或禁用脚本，而不删除脚本。
• ModuleScript 缓存：require 会在每个环境中执行一次 ModuleScript，并缓存返回值。
• 序列/物理类型：NumberSequence、ColorSequence 和 PhysicalProperties 是常用于粒子、光束和部件材质的 Roblox 数据类型。

架构基础

• 默认采用服务器权威的安全策略。
• 选择性复制，并考虑流式加载。
• 使用 ReplicatedStorage 存放共享模块/资源，使用 ServerScriptService 编写服务器逻辑，使用 StarterGui 作为客户端 UI 入口。
• 使用 CollectionService 标签 + Attributes 进行轻量分组和数据存储，避免创建繁重的 Instance 层级结构。
• 需要将 CPU 密集型工作移出主线程时，使用 Parallel Luau + Actors。

脚本

• scripts/ServiceHelper.lua：用于安全获取服务和在超时控制下 require 模块的小型实用工具。

参考索引

• luau-data-types-and-serialization.md：选择数据类型或诊断序列化故障。
• script-locations-contexts-and-architecture.md：确定脚本的运行位置，或调试加载和复制。
• services-catalog-and-usage.md：选择服务，或加载服务和模块。