roblox-networking

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

roblox-networking

When to Use

适用场景

Use this skill when the task is primarily about multiplayer communication, replication, or trust boundaries in a Roblox experience:

Designing or reviewing

RemoteEvent

UnreliableRemoteEvent

, and

RemoteFunction

usage.

Deciding what the client is allowed to send versus what the server must derive or verify.
Choosing safe remote payload shapes, validating arguments, and handling replication timing.
Protecting server logic from spam, malformed payloads, impossible requests, or exploit-driven abuse.
Building interactions where the client initiates an action but the server remains authoritative.
Reasoning about network ownership, client-predicted physics, or
```
Touched
```
-related exploit risk.
Applying server-authority ideas, prediction, rollback-aware structure, or input routing for competitive or authoritative gameplay.
Designing multiplayer logic that must remain correct when streaming affects what the client can currently see or access.

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

Persistent data architecture, save formats, trading storage, or DataStore and MemoryStore design.
Broad engine API lookup as the primary task.
Open Cloud, OAuth, or external web integrations.

当任务主要涉及Roblox体验中的多人通信、内容复制或信任边界时，可使用本技能：

设计或评审

RemoteEvent

、

UnreliableRemoteEvent

和

RemoteFunction

的使用。

界定客户端允许发送的内容，以及服务端必须推导或验证的内容。
选择安全的远程负载结构、验证参数、处理复制时序问题。
保护服务端逻辑免受垃圾请求、格式错误的负载、非法请求或漏洞利用攻击。
构建客户端发起操作但服务端始终保持权威的交互逻辑。
梳理网络所有权、客户端预测物理效果，或
```
Touched
```
相关的漏洞风险。
为竞技类或权威校验类游戏应用服务端权威理念、预测、支持回滚的结构，或输入路由方案。
设计在内容流影响客户端当前可见/可访问内容时仍能保证正确性的多人游戏逻辑。

当任务主要涉及以下内容时请勿使用本技能：

持久化数据架构、存储格式、交易存储，或DataStore和MemoryStore设计。
以通用引擎API查询为核心任务。
Open Cloud、OAuth或外部Web集成。

Decision Rules

决策规则

Use this skill if the main question is "how should client and server communicate safely and correctly?"
Use this skill when a feature depends on remotes, replication timing, ownership of simulated parts, or server validation.
Prefer
```
RemoteEvent
```
for one-way signals and state notifications; prefer
```
UnreliableRemoteEvent
```
only for disposable, continuously changing data; prefer
```
RemoteFunction
```
only when a synchronous reply is truly required.
Treat the server as the authority for shared game state, rewards, combat outcomes, movement permission, and any action that affects other players.
If a client can request an action, validate permission, context, type, structure, value range, and frequency on the server before mutating state or broadcasting results.
If the task is mostly about where scripts live, core services, attributes, bindables, or basic runtime structure without a strong networking/security angle, hand off to
```
roblox-core
```
.
If the task is mainly about data persistence or cross-server state, hand off to
```
roblox-data
```
.
If the task is mainly about exhaustive class/member lookup, hand off to
```
roblox-api
```
.
If a request mixes networking with out-of-scope systems, answer only the multiplayer and trust-boundary portion and explicitly exclude the rest.
When unsure, omit material that would drift into persistence, cloud auth, or broad API catalog guidance.

如果核心问题是“客户端和服务端如何安全、正确地通信？”，可使用本技能。
当功能依赖远程调用、复制时序、模拟部件所有权或服务端验证时，可使用本技能。
单向信号和状态通知优先使用
```
RemoteEvent
```
；仅对可丢弃、持续变化的数据使用
```
UnreliableRemoteEvent
```
；仅当确实需要同步响应时使用
```
RemoteFunction
```
。
服务端作为共享游戏状态、奖励、战斗结果、移动权限及所有影响其他玩家操作的权威来源。
如果客户端可以请求某个操作，在变更状态或广播结果前，服务端需要验证权限、上下文、类型、结构、取值范围和请求频率。
如果任务主要涉及脚本存放位置、核心服务、属性、绑定事件或基础运行时结构，没有明显的网络/安全相关需求，转交
```
roblox-core
```
处理。
如果任务主要涉及数据持久化或跨服务端状态，转交
```
roblox-data
```
处理。
如果任务主要涉及全面的类/成员查询，转交
```
roblox-api
```
处理。
如果请求混合了网络相关和超出范围的系统，仅回答多人游戏和信任边界相关的部分，并明确排除其余内容。
不确定时，省略涉及持久化、云认证或通用API目录指导的内容。

Instructions

使用指南

Start by classifying each piece of information:
- Client input intent.
- Server-derived authoritative state.
- Replicated presentation or notification.
- Disposable telemetry or cosmetic updates.
Choose the narrowest network primitive that matches the job:
- ```
RemoteEvent
```
  for async one-way communication.
- ```
UnreliableRemoteEvent
```
  for frequent data where dropped or out-of-order updates are acceptable.
- ```
RemoteFunction
```
  only for short, bounded request-response flows where yielding is acceptable and server ownership of the decision is clear.
Keep remote contracts explicit and small:
- Prefer stable argument order and dictionaries with string keys.
- Do not rely on metatables, function values, mixed tables, non-replicated instances, or table identity surviving a network hop.
- Pass identifiers, compact values, or validated replicated instances instead of arbitrary object trees.
Design remotes around intent, not outcome:
- Client says "I pressed interact on this target" or "I attempted to fire from here toward this hit point."
- Server decides whether the action is legal and computes the result.
- Avoid remotes where the client directly declares rewards, damage, inventory changes, or unrestricted instance mutations.
Validate every client-triggered request on the server:
- Permission/context: is the player alive, in range, in the right state, and allowed to do this now?
- Type/shape: are the arguments the expected kinds, sizes, and instance classes?
- Value sanity: reject impossible numbers,
```
NaN
```
  ,
```
inf
```
  , out-of-range vectors, or unknown ids.
- Timing: apply per-player rate limits or cooldowns before expensive work or broadcast fan-out.
Treat server-to-client rebroadcasts as privileged operations:
- Never act as a blind relay from one client to other clients.
- Validate first, then broadcast only the minimal safe data needed for presentation.
Use
```
RemoteFunction
```
conservatively:
- Expect the caller to yield.
- Keep the callback fast and deterministic.
- Avoid
```
InvokeClient()
```
  for critical flows because the server can hang or fail if the client errors, disconnects, or never returns.
Reason about replication explicitly:
- A remote arriving does not guarantee a related instance or property has already replicated to the client.
- With streaming enabled, clients may not currently have distant workspace content.
- Use
```
WaitForChild()
```
  , replication-aware design, tags, or model streaming controls instead of assuming presence.
Treat network ownership as a performance tool with security cost:
- Client-owned physics can feel responsive.
- Client-owned physics can also be abused, and
```
Touched
```
  -based server logic becomes especially risky.
- Keep gameplay-critical physics server-owned unless the responsiveness tradeoff is worth the validation burden.
For authoritative or competitive gameplay:

Prefer a server-authority mindset where the server is the source of truth and the client primarily contributes input.
Use the Input Action System for inputs that affect the core authoritative simulation.
Keep simulation state separate from local rendering and effects.

When discussing examples, stay inside scope:

Focus on multiplayer communication, validation, ownership, authority, and streaming correctness.
Do not expand into persistence architecture, cloud APIs, or general-purpose API catalogs.

首先对每类信息进行分类：
- 客户端输入意图。
- 服务端推导的权威状态。
- 复制的展示内容或通知。
- 可丢弃的遥测数据或外观更新。
选择满足需求的最轻量化网络原语：
- ```
RemoteEvent
```
  用于异步单向通信。
- ```
UnreliableRemoteEvent
```
  用于可接受丢包、乱序更新的高频数据。
- 仅当可接受阻塞、服务端明确拥有决策所有权的短生命周期请求-响应流程使用
```
RemoteFunction
```
  。
保持远程契约明确且精简：
- 优先使用稳定的参数顺序和带字符串键的字典。
- 不要依赖元表、函数值、混合表、非复制实例或表标识在网络传输中保持不变。
- 传递标识符、紧凑型值或已验证的可复制实例，而非任意对象树。
围绕意图而非结果设计远程调用：
- 客户端发送“我点击了这个目标的交互按钮”或“我尝试从这里向这个命中点开火”。
- 服务端判断操作是否合法并计算结果。
- 避免使用客户端直接声明奖励、伤害、背包变更或无限制实例修改的远程调用。
服务端验证所有客户端触发的请求：
- 权限/上下文：玩家是否存活、在有效范围内、处于正确状态、当前有权限执行该操作？
- 类型/结构：参数是否为预期的类型、大小和实例类？
- 取值合理性：拒绝非法数值、
```
NaN
```
  、
```
inf
```
  、超出范围的向量或未知ID。
- 时序：在执行消耗高的操作或广播前，应用单玩家速率限制或冷却规则。
将服务端到客户端的重广播视为特权操作：
- 永远不要作为盲中继将一个客户端的内容转发给其他客户端。
- 先验证，再仅广播展示所需的最小安全数据。
谨慎使用
```
RemoteFunction
```
：
- 调用方会进入阻塞状态。
- 保持回调逻辑快速且确定。
- 关键流程避免使用
```
InvokeClient()
```
  ，因为如果客户端报错、断开连接或永不返回，服务端会挂起或失败。
明确梳理复制逻辑：
- 收到远程调用不代表相关实例或属性已经复制到客户端。
- 开启内容流时，客户端可能没有加载远处的工作区内容。
- 使用
```
WaitForChild()
```
  、感知复制的设计、标签或模型流控制，而非假设内容一定存在。
将网络所有权视为有安全成本的性能优化工具：
- 客户端所有权的物理效果响应更快。
- 客户端所有权的物理效果也可能被滥用，基于
```
Touched
```
  的服务端逻辑风险尤其高。
- 游戏核心相关的物理效果保持服务端所有，除非响应性的收益高于验证成本。
针对权威或竞技类游戏：
- 优先采用服务端权威理念，服务端作为唯一可信来源，客户端主要提供输入。
- 影响核心权威模拟的输入使用Input Action System。
- 保持模拟状态与本地渲染和效果分离。
讨论示例时保持在范围内：
- 聚焦于多人通信、验证、所有权、权威和内容流正确性。
- 不要扩展到持久化架构、云API或通用API目录内容。

Using References

参考文档

Open
```
references/remote-events-and-callbacks.md
```
for remote selection, directionality, argument-shape limits, and safe payload design.
Open
```
references/client-server-runtime.md
```
for replication timing, latency expectations, and side ownership of gameplay responsibilities.
Open
```
references/security-and-defensive-design.md
```
for the security mindset, defensive design, and rate-limiting patterns.
Open
```
references/client-server-boundary-guidance.md
```
for concrete validation layers, secure rebroadcast patterns, and protection of client-triggered interactions.
Open
```
references/network-ownership.md
```
when physics responsiveness, client-owned parts, or
```
Touched
```
validity are part of the problem.
Open
```
references/server-authority-model-and-techniques.md
```
for authoritative simulation, prediction, rollback-aware structure, and latency-conscious design.
Open
```
references/input-action-system.md
```
when networked or authoritative gameplay depends on action-oriented, cross-platform input routing.
Open
```
references/streaming-and-replication-behavior.md
```
when correctness depends on streamed workspace content, replication focus, or models that may not be locally present.

打开
```
references/remote-events-and-callbacks.md
```
查看远程调用选择、方向性、参数结构限制和安全负载设计。
打开
```
references/client-server-runtime.md
```
查看复制时序、延迟预期和游戏职责的所属方。
打开
```
references/security-and-defensive-design.md
```
查看安全理念、防御式设计和速率限制模式。
打开
```
references/client-server-boundary-guidance.md
```
查看具体的验证层级、安全重广播模式和客户端触发交互的保护方案。
当问题涉及物理响应性、客户端所有部件或
```
Touched
```
有效性时，打开
```
references/network-ownership.md
```
。
打开
```
references/server-authority-model-and-techniques.md
```
查看权威模拟、预测、支持回滚的结构和低延迟设计。
当联网或权威游戏逻辑依赖面向动作的跨平台输入路由时，打开
```
references/input-action-system.md
```
。
当正确性依赖流式工作区内容、复制焦点或可能不存在于本地的模型时，打开
```
references/streaming-and-replication-behavior.md
```
。

Checklist

检查清单

The client-server contract is defined in terms of player intent, not client-declared outcomes.
The chosen remote primitive matches the required reliability and response behavior.
Remote payloads use stable, replication-safe shapes.
The server validates permission, context, type, structure, and values before mutating shared state.
The server applies rate limits or cooldowns to abuse-prone entry points.
Server-to-client broadcasts happen only after validation and never as blind relays.
```
RemoteFunction
```
use is justified and bounded.
Replication timing assumptions are explicit, especially when remotes reference freshly created or streamed content.
Network ownership choices are deliberate and paired with server-side validation where needed.
```
Touched
```
, proximity, click, or drag interactions are not trusted just because the engine fired them.
Authoritative gameplay uses client inputs and server-owned state rather than trusting client simulation results.
Input guidance stays focused on networked or authoritative use of the Input Action System.
No persistence architecture, Open Cloud, OAuth, or broad API catalog material is included.

客户端-服务端契约基于玩家意图定义，而非客户端声明的结果。
选择的远程原语符合所需的可靠性和响应行为。
远程负载使用稳定的、复制安全的结构。
服务端在修改共享状态前验证权限、上下文、类型、结构和取值。
服务端对易被滥用的入口应用速率限制或冷却规则。
服务端到客户端的广播仅在验证后执行，永远不会作为盲中继。
```
RemoteFunction
```
的使用有合理依据且范围受限。
明确说明复制时序假设，尤其是当远程调用引用新创建或流式加载的内容时。
网络所有权选择经过慎重考虑，必要时搭配服务端验证。
不会仅因为引擎触发了
```
Touched
```
、 proximity、点击或拖拽交互就信任其合法性。
权威游戏逻辑使用客户端输入和服务端所有的状态，而非信任客户端的模拟结果。
输入指导聚焦于Input Action System的联网或权威场景使用。
不包含持久化架构、Open Cloud、OAuth或通用API目录内容。

Common Mistakes

常见错误

Letting the client tell the server who was damaged, what reward was earned, or which state change already happened.
Using
```
RemoteFunction
```
for convenience when an async
```
RemoteEvent
```
plus server-side state would be safer.
Broadcasting one client's payload to every other client without validating it first.
Passing mixed tables, metatable-backed objects, huge payloads, or sender-only instances across remotes.
Forgetting to reject
```
NaN
```
,
```
inf
```
, oversized strings, or spoofed instance references.
Assuming a remote means an associated part, attribute, or model has already replicated.
Relying on client cooldowns without server-side rate limiting.
Treating client-owned physics or
```
Touched
```
events as authoritative proof of contact.
Using unreliable channels for state that must arrive in order.
Mixing core authoritative simulation logic with local-only animation, camera, or VFX code.

允许客户端直接告知服务端谁受到了伤害、获得了什么奖励，或者已经发生了什么状态变更。
图方便使用
```
RemoteFunction
```
，而实际上异步
```
RemoteEvent
```
加服务端状态会更安全。
未经验证就将一个客户端的负载广播给所有其他客户端。
通过远程调用传递混合表、元表支撑的对象、超大负载或仅发送方可见的实例。
忘记拒绝
```
NaN
```
、
```
inf
```
、超大字符串或伪造的实例引用。
假设收到远程调用就意味着关联的部件、属性或模型已经完成复制。
仅依赖客户端冷却而没有服务端速率限制。
将客户端所有的物理效果或
```
Touched
```
事件视为接触发生的权威证明。
对要求有序到达的状态使用不可靠通道。
将核心权威模拟逻辑与本地动画、相机或VFX代码混合。

Examples

示例

Design a secure client-triggered interaction

设计安全的客户端触发交互

lua

-- Client: request an interaction attempt, not the reward itself.
InteractRemote:FireServer(targetId)

lua

-- Server: verify range, state, and target validity before applying effects.
InteractRemote.OnServerEvent:Connect(function(player, targetId)
    -- Validate player state, target existence, distance, cooldown, and permissions.
    -- Then mutate shared state on the server.
end)

lua

-- Client: request an interaction attempt, not the reward itself.
InteractRemote:FireServer(targetId)

lua

-- Server: verify range, state, and target validity before applying effects.
InteractRemote.OnServerEvent:Connect(function(player, targetId)
    -- Validate player state, target existence, distance, cooldown, and permissions.
    -- Then mutate shared state on the server.
end)

Use unreliable remotes only for disposable updates

仅对可丢弃更新使用不可靠远程调用

lua

-- Suitable for frequent cosmetic aim or camera direction updates.
AimDirectionRemote:FireServer(lookVector)

Accept dropped or out-of-order packets.
Do not use this pattern for inventory, damage, scoring, or one-time transactions.

lua

-- Suitable for frequent cosmetic aim or camera direction updates.
AimDirectionRemote:FireServer(lookVector)

可接受丢包或乱序的数据包。
不要将该模式用于背包、伤害、得分或一次性交易逻辑。

Keep authoritative simulation separate from rendering

保持权威模拟与渲染分离

lua

-- Core state changes live in shared/server-side simulation logic.
-- Local VFX and sounds react to the synchronized state afterward.

lua

-- Core state changes live in shared/server-side simulation logic.
-- Local VFX and sounds react to the synchronized state afterward.