roblox-code-maintenance-refactor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Roblox Code Maintenance Refactor

Roblox 代码维护与重构

Goal

目标

Improve code health without changing player-facing behavior accidentally.

在不意外改变玩家可见行为的前提下改善代码健康状况。

Refactor Rules

重构规则

Read before editing.
Keep changes scoped.
Preserve remote contracts unless intentionally migrating.
Avoid mixing behavior changes with cleanup.
Playtest after meaningful refactors.
Check console output.

编辑前先阅读代码。
保持改动范围明确。
除非有意进行迁移，否则应保留 remote 契约。
避免将行为变更与代码清理混在一起。
完成有意义的重构后进行游戏测试。
检查控制台输出。

Targets

重构目标

Duplicated constants and reward formulas.
Large scripts with mixed responsibilities.
Client/server boundary confusion.
Dead remotes, stale UI paths, unused modules.
Repeated event connection patterns.
Unclear names around valuable state.
Magic numbers that should be balance tables.

重复的常量和奖励公式。
职责混杂的大型脚本。
客户端与服务端边界不清。
无效的 remote、过时的 UI 路径和未使用的模块。
重复的事件连接模式。
关键状态附近的命名不清晰。
应改为平衡数值表的魔法数字。

Finding Deepening Opportunities

寻找深化模块的机会

Beyond obvious cleanup, hunt for shallow modules to deepen — where the interface is nearly as complex as the implementation, so callers carry complexity that should be hidden.

Where does understanding one concept require bouncing between many tiny scripts?
Where were pure helpers extracted only for tidiness, but the real bugs live in how they're called (no locality)?
Where do client and server share a responsibility that leaks across the remote boundary?

Apply the deletion test to anything you suspect is shallow: if deleting it just moves complexity around, inline it; if deleting it would scatter the same complexity across many call sites, keep it and give it a small, stable interface named from the game's vocabulary. Present each opportunity as: files involved · the friction today · the proposed change · the benefit (locality + testability). Don't propose new indirection for a single implementation. See

roblox-luau-architecture

for the deep-module model.

除了明显的清理工作，还要寻找可以深化的浅模块——这类模块的接口与实现几乎同样复杂，导致本应被隐藏的复杂度转移给了调用方。

理解一个概念时，是否需要在许多微小脚本之间来回跳转？
是否只是为了代码整洁而提取了纯辅助函数，但真正的缺陷其实存在于它们的调用方式中（缺乏局部性）？
客户端与服务端之间是否存在共同承担的责任，并跨越 remote 边界产生泄漏？

对任何疑似浅模块的内容应用删除测试：如果删除它只是让复杂度四处转移，就将其内联；如果删除它会让相同的复杂度散布到许多调用点，就应保留它，并为其提供一个小型、稳定的接口，使用游戏自身的术语命名。每个机会都应按以下形式呈现：涉及的文件 · 当前存在的摩擦 · 建议的改动 · 收益（局部性 + 可测试性）。不要为单一实现引入新的间接层。有关深模块模型，请参阅

roblox-luau-architecture

。

MCP Workflow

MCP 工作流

Use
```
script_grep
```
to find duplication, old names, or call sites.
Read all affected scripts with
```
script_read
```
.
Make small edits with
```
multi_edit
```
.
Use
```
start_stop_play
```
to verify the relevant loop.
Check
```
get_console_output
```
.

使用
```
script_grep
```
查找重复代码、旧命名或调用点。
使用
```
script_read
```
阅读所有受影响的脚本。
使用
```
multi_edit
```
进行小范围编辑。
使用
```
start_stop_play
```
验证相关循环。
使用
```
get_console_output
```
检查控制台输出。

Output

输出

Return:

Refactor goal.
Behavior preserved.
Scripts changed.
Verification performed.
Follow-up debt items.

重构目标。
保持不变的行为。
已修改的脚本。
已执行的验证。
后续技术债事项。

下一步

Verify no behavior changed with

roblox-playtest-qa

. For larger structural changes, design them in

roblox-luau-architecture

and slice them with

roblox-to-issues

so they land one safe step at a time.

使用

roblox-playtest-qa

验证行为未发生变化。对于较大的结构性改动，应先在

roblox-luau-architecture

中进行设计，再使用

roblox-to-issues

拆分为多个安全的步骤逐步实施。