主题
第 0 章：从可视化编辑器到状态同步 Lua 开发
理解 SE Lua 能解决什么、客户端与服务端如何分工，以及如何开始第一条学习主线。
你会学到什么
- 世界版 / SE / 状态同步地图是什么，和原点版有什么区别。
- 为什么"用过编辑器"之后还需要学习 Lua。
- 编辑器、服务端、客户端和数据脚本分别负责什么。
- 为什么教程只能使用当前 API 文档 / Meta 已公开的能力。
- 本系列会用什么方式带你从编辑器经验过渡到脚本开发。
本章先建立概念，不要求你编写 Lua。后续出现代码时，每个 API 名称、参数、运行端和获取方式都会以当前公开 API 契约为准，并通过静态检查或真实编辑器验证。
完全没写过 Lua：先认这 7 个符号
第一轮不需要系统学习整门 Lua。先能读懂下面这些结构，就足够跟着教程修改示例：
| 写法 | 先这样理解 | 常见误区 |
|---|---|---|
local score = 0 | 创建只在当前范围使用的变量 | 漏写 local 会让状态边界变模糊 |
nil | “当前没有值” | 查找对象可能返回 nil，使用前要判空 |
{ score = 1 } | 一张 table，可装配置或消息字段 | table 不能冒充 Vector3 等引擎类型 |
function (...) ... end | 定义稍后执行的一段逻辑 | 事件回调不会在 Connect 时立即执行 |
if 条件 then ... end | 条件成立才执行 | false 和 nil 才是假值，数字 0 仍是真值 |
object.Name | 读取属性 | 属性是否存在取决于对象的具体公开类型 |
object:Destroy() | 调用对象方法 | 冒号和点号不是随意互换；按 API 示例使用 |
-- 后面是注释，不会作为逻辑执行。教程中的 local、判空和类型检查看起来会让代码稍长，但它们能把“对象还没加载”“名字写错”“类型不对”变成可读日志，而不是让新手直接面对 nil 报错。
世界版 / SE 的定位
世界版是在原有 PC 版地图编辑器（原点版）基础上开发的特化型编辑器。它不是原点版的升级或替代，而是与原点版并行存在的另一套创作工具。
在本教程中，世界版、SE 和状态同步地图指向同一套创作环境；“SE”是后文最常用的简称。
| 工具 | 更适合 |
|---|---|
| 世界版 / SE | 即时操作、大场景、更多玩家、随进随出、多人共同互动 |
| 原点版 | 更依赖真实物理机关、公平同步一致性的传统派对/跑酷/机关类玩法 |
创作思维的变化
- 世界版：更像"只有一个统一运转的世界"，所有玩家连入同一个世界。
- 原点版：更像"每位玩家各自跑着同一场游戏"。
这句话会影响你后面所有脚本设计。在世界版里，你更需要考虑：哪些状态应该由服务端维护？哪些表现只需要客户端显示？
“统一运转的世界”不等于服务器永不关闭，也不等于普通 Lua 变量会永久保存。分数、胜负等当前对局状态通常由服务端维护；需要跨对局保留的数据，要在后续章节通过已公开的存储服务设计独立的保存流程。
为什么需要 Lua
可视化编辑器适合快速搭场景和配置基础行为，但当玩法变复杂时，你会遇到这些需求：
- 命中目标后给玩家加分。
- 倒计时 60 秒后结算。
- 客户端 UI 显示分数和时间。
- 服务端保存最高分。
- 多人进入同一个世界时各自有不同状态。
这些规则很难只靠可视化配置维护清楚。Lua 的作用就是把这些逻辑组织成可读、可复用、可调试的脚本。
如何创建状态同步地图
如果你还没有创建过世界版地图，按以下步骤操作：
- 启动工程页，右上角选择【新建地图】。
- 在新建地图模板窗口中，选择【世界模式】分类下的【空白地图（世界版）】模板。
- 输入项目名称（即地图名称），点击【创建】，进入地图编辑界面。
确认你使用的是世界版模板，而不是原点版模板，后续的 Lua 脚本开发才适用。
从编辑器到 Lua 的思维转换
| 编辑器中做的事 | Lua 中对应的概念 |
|---|---|
| 在场景里放一个可碰撞方块 | World 场景树下的具体物理类型，例如 WorldUnit |
| 修改这个方块的位置 | 读取或设置该具体类型公开的 Position / CFrame 属性；不能假设所有 Unit 都有这些属性 |
| 配置“碰撞时执行动作” | 连接 WorldUnit.OnCollisionEnter 等具体类型已公开的事件 |
| 给玩家显示文字反馈 | UI 文本节点更新或 print 日志 |
| 拖一个 UI 文本 | EUI 节点 + 稳定 Name，导出数据只作辅助参考 |
| 点击运行试玩 | 脚本在 client/server 两端分别执行 |
这里最重要的变化是：编辑器里看到的“对象”到了 Lua 中并不都叫同一种类型。Unit 只提供所有单位共有的层级、名称和生命周期能力；位置、碰撞、文本等能力属于不同的具体类型。后文每次使用成员前，都会先确认对象的具体类型和公开获取链。
先记住四个职责位置
| 位置 | 主要职责 | 小白判断方法 |
|---|---|---|
| 编辑器 | 摆场景、配置初始属性、搭 UI、选择真实资源 | 不需要在运行中变化的初始内容，优先在这里完成 |
server/ | 维护权威玩法状态，校验客户端意图，结算与存储 | 会影响分数、奖励、胜负或所有玩家的结果，优先放服务端 |
client/ | 读取本地输入，更新 HUD、相机、音效等本地表现 | 只影响当前玩家看到或操作到的内容，通常放客户端 |
data/ / common/ | 保存无副作用配置，或双端共用的定义和纯逻辑 | 两端都要读取、且不应在加载时启动玩法的内容放这里 |
这张表是本教程的工程建议，不代表所有 API 都被固定在某个目录。某个 API 究竟能在哪一端调用，仍以它在当前 API 文档 / Meta 中声明的运行域为准。
公开 API 是教程红线
你可能会在旧示例、SDK 实现、日志或网络讨论中看到更多名称。本教程采用一条更稳妥的规则：
- 类型、属性、函数、事件或枚举没有出现在当前 API 文档 / Meta 的公开契约中，就视为尚未向作者开放。
- SDK 内部实现只能帮助维护者理解语义，不能成为教程教你调用某个能力的依据。
- 即使某个未公开名称在某个编辑器版本里“碰巧能跑”，教程也不会把它当作可用 API。
这样做的目的不是限制探索，而是保证你从教程复制的代码只依赖正式公开、可以持续维护的能力。
本系列的主线项目
前半部分会围绕一个小项目推进：
text
生成脚本工程 → 找到具体类型的球体和方块 → 为物理单位连接公开碰撞事件
→ 显示系统提示 → 播放特效 → 重置球体
→ 随机刷新方块 → 标记最后触碰玩家
→ 服务端维护分数和倒计时 → RemoteEvent 通知客户端
→ 客户端 UI 展示分数和倒计时 → 加入重置按钮本系列如何阅读
本系列按由浅入深组织，共 6 个 Part：
- Part 0（第 0 章）：导读，理解世界版和 Lua 的关系。
- Part 1（第 1–6 章）：核心入门，从生成工程到写出第一段玩法逻辑。
- Part 2（第 7–12 章）：常用玩法能力，玩家、通信、UI、存储、物理。
- Part 3（第 13–16 章）：3C 与表现层，角色系统、角色控制与动画、相机、音效特效。
- Part 4（第 17–19 章）：资产与项目工程化，资产加载、自定义资产、Manager 拆分。
- Part 5（第 20–22 章）：平台服务、测试与综合项目。
如果你是有 Lua 基础的初级作者，建议第一轮按顺序读到第 11 章，就能完成一个完整的"球体碰撞方块"小游戏。第 12–22 章为按需进阶内容，可按项目需要选读。
更稳的读法是分三层推进，而不是第一天就把所有高级能力塞进项目：
| 层级 | 推荐章节 | 目标 | 读完后应留下什么 |
|---|---|---|---|
| 第一层：跑通闭环 | 01–08 | 脚本工程、对象查找、事件、服务端状态、RemoteEvent | 一个能在 server 计分、client 显示结果的小玩法 |
| 第二层：补齐玩法能力 | 09–18 | UI、配置、存档、物理、角色、表现、资产 | HUD testspec、排行榜记录、资产加载成功/失败日志 |
| 第三层：工程化与发布 | 19–22 | Manager、平台服务、QA、Capstone | 可复用模块边界、平台接入设计单、运行证据和截图 |
每读一层都先追求“能运行、能解释、能复盘”，再进入下一层。这样学习压力更小，也更接近真实地图从原型到发布的节奏。
练习任务
先判断下面需求更适合继续用可视化配置，还是需要 Lua：
| 需求 | 建议 |
|---|---|
| 在场景里放一个方块 | 编辑器即可 |
| 球碰到方块后计分 | 需要 Lua |
| 每个玩家有自己的倒计时 UI | 需要 Lua |
| 改一个物体的初始颜色 | 编辑器优先 |
| 保存玩家历史最高分 | 需要 Lua |
然后为你自己的一个玩法想法补一张小表，作为后续学习的交付物：
| 项 | 填写 |
|---|---|
| 玩法名称 | 例如：推球撞方块计分 |
| 需要服务端维护的状态 | 分数、倒计时、胜负 |
| 只需要客户端显示的表现 | HUD、提示文字、音效、相机震动 |
| 可以继续用编辑器完成的部分 | 场景摆放、初始 UI、资源整理 |
| 必须用 Lua 组织的逻辑 | 碰撞计分、RemoteEvent、存档 |
这张表不用写得很长，但要能说明：为什么这个玩法适合进入 SE Lua 主线，而不是只靠可视化配置。
常见错误
错误：把世界版当成原点版升级版
世界版 / SE 和原点版是两套并行创作工具，不是“新旧版本”的关系。选择模板前先确认玩法类型：如果你要做多人同场、随进随出、服务端统一状态的玩法，本系列才是合适路线。
错误：一开始就追求全套系统
初学 SE Lua 时，不要一上来就做技能、排行榜和完整商业化链路。先按主线跑通“场景对象 → 碰撞事件 → 服务端计分 → 客户端 UI”这个闭环，再按需读进阶章节。
错误：把 Lua 当作替代编辑器的工具
Lua 不是要替代可视化编辑器。场景摆放、资源整理、UI 初始布局仍然优先在编辑器中完成；Lua 负责把这些对象组织成可复用、可调试、可验证的玩法逻辑。
本章验收标准
- [ ] 我知道世界版不是原点版的简单升级。
- [ ] 我理解"统一运转的世界"会影响脚本设计。
- [ ] 我知道 Lua 的作用是扩展复杂玩法逻辑。
- [ ] 我能区分编辑器、server、client、data/common 的基本职责。
- [ ] 我知道
Unit基类不自动拥有位置、碰撞或 UI 文本等具体类型能力。 - [ ] 我知道未在当前 API 文档 / Meta 公开的名称不能写进教程代码。
- [ ] 我知道后续主线会围绕"球体碰撞方块小游戏"展开。
- [ ] 我能为自己的玩法写出一张“编辑器 / server / client / data”分工草表。
本章产物
- 一张“编辑器 / server / client / data”分工草表。
- 一个第一轮学习目标：先跑通“场景对象 → 碰撞事件 → 服务端计分 → 客户端 UI”闭环。
- 一个按需阅读判断：第 12–22 章只在项目需要对应能力时进入，不作为第一轮负担。
- 一张三层学习台阶表：标出当前项目处在“跑通闭环 / 补齐玩法能力 / 工程化发布”的哪一层。
本章 API 对照
下一章预告
下一章我们将生成 Lua 脚本工程，了解 client/server/common 的目录结构和运行入口。