创游世界脚本变量完全指南
一句话摘要
本文档全面解析创游世界脚本系统中的变量与作用域，帮你理解局部变量、自身属性、地图属性、系统属性、玩家变量表、配置表的区别与适用场景，并给出数据存储位置的选择建议。
适合谁阅读
- 遇到「变量值丢失」或「数据不知道放哪」问题的制作者
- 想深入理解变量作用域的进阶用户
- 需要设计复杂数据系统的项目开发者
你将学到什么
- 创游世界变量系统的完整分类
- 各类型变量的生命周期和存储位置
- 什么时候用局部变量，什么时候用属性
- 配置表和变量表的区别与选择
- 数据存储位置的选择原则
- 常见变量问题与解决
💡 如果你想快速查找变量问题，请查看：创游世界变量作用域速查卡
一、变量系统分类总览
创游世界的变量系统可以分为以下几个层次：
变量系统
├── 局部变量（脚本内部，临时）
├── 属性（挂载在主体上）
│ ├── 自身属性
│ ├── 当前地图属性
│ ├── 系统属性
│ └── 玩家属性
├── 玩家变量表（持久化数据）
├── 配置表（静态规则数据）
└── 其他数据类型
├── 数字
├── 真假值
├── 文本
├── 数组
├── 结构体
└── 物品类型📚 相关阅读：创游世界数据类型完全指南 - 数据类型详解
二、局部变量
2.1 什么是局部变量
局部变量是在脚本执行过程中临时创建的变量，只在当前脚本执行期间存在。
定义方式：
新建局部变量 为 初始值2.2 关键特点
| 特点 | 说明 |
|---|---|
| 生命周期 | 当前脚本执行完就消失 |
| 存储位置 | 脚本内部 |
| 类型推导 | 初始值决定变量类型 |
| 作用域 | 仅在定义它的脚本中有效 |
2.3 适用场景
适合使用局部变量的情况：
- 临时计算中间值
- 循环中的计数变量
- 一次性判断条件
- 不需要跨触发保留的值
示例：
新建局部变量 为 0
重复 10 次
设置局部变量1 为 局部变量1 + 1
结束
发送广播 "完成第" + 局部变量1 + "次"2.4 不适合的场景
不适合使用局部变量的情况：
- 需要跨脚本保留的值
- UI需要长期读取的值
- 联机需要同步的数据
- 需要持久化的玩家状态
错误示例：
// ❌ 错误：把货币存到局部变量
当点击时
新建局部变量 金币 为 100
设置局部变量金币 为 局部变量金币 - 10
// 点击结束后，金币值就消失了📚 相关阅读：广播机制深度解析 - 广播与脚本流程
三、属性系统
3.1 什么是属性
属性是挂载在某个主体（物体/地图/系统/玩家）上的变量，随主体的生命周期存在。
设置属性语句：
设置自身属性 为 值
设置当前地图属性 为 值
设置系统属性 为 值
设置玩家属性 为 值3.2 四种属性对比
| 属性类型 | 挂载主体 | 生命周期 | 存储位置 | 适用场景 |
|---|---|---|---|---|
| 自身属性 | 当前物体 | 物体存在期间 | 物体/组件 | 对象自身状态 |
| 当前地图属性 | 当前地图 | 地图存在期间 | 地图对象 | 同地图共享数据 |
| 系统属性 | 系统 | 整个游戏 | 系统层 | 全局/跨地图数据 |
| 玩家属性 | 玩家 | 玩家会话 | 玩家数据 | 玩家相关状态 |
3.3 自身属性
定义：挂载在物体/组件上的属性，记录该对象自身状态。
适用场景：
- 门是否开启
- 怪物是否已激活
- 机关是否已触发
- 角色当前状态
- 冷却剩余时间
示例：
// 检查门的状态
如果 获取自身属性 "是否开启" 等于 假
设置自身属性 "是否开启" 为 真
播放动画 "开门"
结束📚 相关阅读：自定义组件深度解析 - 自定义组件属性
3.4 当前地图属性
定义：挂载在当前地图上的属性，记录地图级共享数据。
适用场景：
- 关卡进度
- 地图内任务状态
- 当前波次
- 地图倒计时
- 地图内货币池
示例：
// 增加波次
设置当前地图属性 "当前波次" 为 获取当前地图属性 "当前波次" + 1
如果 获取当前地图属性 "当前波次" 大于 获取当前地图属性 "总波次"
发送广播 "关卡完成"
结束3.5 系统属性
定义：挂载在系统层的属性，记录全局数据。
适用场景：
- 全局设置
- 联机房间状态
- 系统级开关
- 跨地图流程控制
注意：
- 不要滥用系统属性，否则后期会出现很多逻辑都在「抢写同一层全局状态」
- 优先考虑更具体的作用域（如地图属性或玩家属性）
📚 相关阅读：系统级脚本能力解析 - 系统能力详解
3.6 玩家属性
定义：挂载在玩家对象上的属性，记录玩家相关状态。
适用场景：
- 玩家等级
- 玩家金币
- 玩家背包
- 玩家任务进度
与玩家变量表的区别：
- 玩家属性是即时读写的对象属性
- 玩家变量表更适合结构化、持久化的数据
📚 相关阅读：创游世界联机系统入门 - 联机同步
四、玩家变量表
4.1 什么是玩家变量表
玩家变量表是一种结构化的玩家数据存储方式，支持多行多字段，适合存储复杂的玩家状态。
4.2 玩家变量表特点
| 特点 | 说明 |
|---|---|
| 持久化 | 可以勾选云存储，跨会话保存 |
| 结构化 | 支持多行多字段 |
| 动态性 | 可在运行中添加/删除行 |
| 同步性 | 可用于联机数据同步 |
4.3 适用场景
适合使用玩家变量表的情况：
- 玩家背包物品
- 玩家任务列表
- 玩家成就记录
- 需要持久化的玩家进度
示例结构：
玩家变量表：背包
├── 行1：物品=血瓶, 数量=5
├── 行2：物品=金币, 数量=100
└── 行3：物品=钥匙, 数量=14.4 与配置表的区别
| 特性 | 玩家变量表 | 配置表 |
|---|---|---|
| 用途 | 动态运行数据 | 静态策划数据 |
| 变化 | 运行时可修改 | 通常只读 |
| 持久化 | 支持云存储 | 通常不持久化 |
| 修改来源 | 玩家行为 | 策划配置 |
4.5 老用户数据同步问题
问题：修改玩家变量表结构后，旧存档的玩家不会自动同步新结构。
解决思路：
- 在「玩家开始时」脚本里做同步补丁
- 检查某行、某字段是否存在
- 不存在则补加默认值
- 存在则保留原数据
示例：
当玩家开始时
如果 玩家变量表 不存在 "等级"
添加一行 "等级" 到 玩家变量表
设置玩家变量 "等级" 为 1
结束📚 相关阅读：创游世界存档与云变量设计入门 - 存档设计
五、配置表
5.1 什么是配置表
配置表用于存储结构化的静态数据，适合承载规则、参数、策划数据。
5.2 配置表特点
| 特点 | 说明 |
|---|---|
| 静态性 | 通常用于只读配置 |
| 结构化 | 支持多行多字段 |
| 运行时可改 | 可以增删行，但不建议修改原始内容 |
| 不自动持久化 | 修改不写回原始配置 |
5.3 配置表属性
| 属性 | 说明 |
|---|---|
| 总行数 | 返回配置表内的总行数 |
| 第n行 | 返回第n行数据 |
| 名为xx的行 | 按行名检索并返回对应行 |
| 是否存在某行 | 返回真假值，判断行是否存在 |
5.4 配置表指令
| 指令 | 说明 |
|---|---|
| 添加一行 | 在配置表中新增一行 |
| 从表中移除第n行 | 按行号删除指定行 |
| 从表中移除名为xx的行 | 按行名删除指定行 |
5.5 安全读取模式
重要：直接读取不存在的行会报错。
安全写法：
如果 配置表 存在某行 "物品1"
获取 配置表 名为 "物品1" 的行
// 安全读取
结束六、数据类型
6.1 数字
| 类型 | 说明 |
|---|---|
| 整数 | 如 1, 100, -5 |
| 小数 | 如 1.5, 3.14, -0.5 |
注意：
- 文本转数字失败会得到
NaN - 除数不能为0
- 小数比较建议用「是否约等于」
6.2 真假值
| 值 | 说明 |
|---|---|
| 真 | 条件成立 |
| 假 | 条件不成立 |
注意：在数组中，真可能显示为1，假可能显示为0。
6.3 文本
用于存储中英文、数字、符号等文字内容。
常用操作：
- 拼接文本
- 查找序号
- 替换
- 截取
- 判断开头/结尾
- 转换成数字
6.4 数组
数组是按顺序存储多个同类型数据的容器。
特点：
- 支持一维数组和二维数组
- 元素通过索引访问（从0开始）
- 读取越界返回空
- 写入越界系统自动补全中间空位
6.5 结构体
结构体适合把多个不同字段组合为一个整体对象。
📚 相关阅读：创游世界数据类型完全指南 - 数据类型详解
七、数据存储位置选择原则
7.1 选择流程图
这个数据需要存储吗？
↓ 是
这个数据属于谁？
├── 单个物体 → 自身属性
├── 当前地图多个物体 → 当前地图属性
├── 某个玩家 → 玩家属性 / 玩家变量表
└── 整个游戏 → 系统属性
这个数据需要持久化吗？
├── 是 → 玩家变量表（勾选云存储）
└── 否 → 属性
这个数据是静态规则吗？
├── 是 → 配置表
└── 否 → 属性 / 变量表7.2 简化记忆法
| 数据类型 | 推荐存储位置 |
|---|---|
| 临时计算 | 局部变量 |
| 某个对象自己的状态 | 自身属性 |
| 当前地图公共状态 | 当前地图属性 |
| 全局流程或跨地图状态 | 系统属性 |
| 玩家相关状态 | 玩家属性 |
| 玩家持久化数据 | 玩家变量表 |
| 静态策划规则 | 配置表 |
📚 相关阅读：脚本作用域与数据流深度研究 - 数据分层详解
7.3 一句话原则
不要为了「眼前方便」把所有东西都放同一层。
八、常见问题
Q1：为什么变量值会丢失？
原因：可能使用了局部变量存储需要持久化的数据。
解决：
- 需要长期保留的值，放到属性或玩家变量表
- 局部变量只用于临时计算
Q2：为什么切换地图后数据错乱？
原因：
- 可能把真值存在了UI层
- 可能把地图相关数据存在了系统属性而不是地图属性
解决：
- 真值放在地图层或系统层
- UI只负责显示
- 跨地图数据用系统属性或玩家变量表
📚 相关阅读：常见问题与避坑指南 - 数据问题解决
Q3：为什么配置表读取报错？
原因：直接读取了不存在的行。
解决：先判断「是否存在某行」，再读取。
Q4：数组越界了怎么办？
原因：访问了超出数组长度的索引。
解决：
- 读取越界：返回空值，需要检查索引
- 写入越界：系统自动补全，但可能不是预期行为
📚 相关阅读：创游世界数据类型速查卡 - 数组操作速查
九、实战示例
9.1 商店购买系统
当点击购买按钮时
// UI发请求，而不是直接扣钱
发送广播 "请求购买" 带参数 商品ID=1, 数量=1
结束
当收到广播 "请求购买" 时
// 地图层处理逻辑
获取玩家变量 "金币"
获取配置表 商品列表 名为 "商品1" 的行
如果 玩家金币 大于等于 商品价格
设置玩家属性 "金币" 为 玩家金币 - 商品价格
执行玩家指令 "添加物品" 参数 商品ID=1, 数量=1
发送广播 "购买成功"
否则
发送广播 "金币不足"
结束
结束
当收到广播 "购买成功" 时
// UI收到通知后刷新显示
刷新界面
结束📚 相关阅读：创游世界商店系统实战设计指南 - 商店系统完整指南
9.2 关卡波次系统
当收到广播 "怪物死亡" 时
// 检查是否所有怪物都死亡
如果 获取当前地图属性 "存活怪物数" 等于 0
设置当前地图属性 "当前波次" 为 获取当前地图属性 "当前波次" + 1
如果 当前波次 大于 总波次
发送广播 "关卡胜利"
否则
发送广播 "下一波"
结束
结束
结束📚 相关阅读：创游世界战斗系统设计入门 - 战斗系统
相关页面
关联阅读
核心研究
- 核心概念速查手册 - 核心概念速查
- 创游世界数据类型完全指南 - 数据类型详解
- 创游世界碰撞与物理系统入门 - 物理系统
- 创游世界联机系统入门 - 联机系统
脚本系统
- 脚本作用域与数据流深度研究 - 数据分层详解
- 自定义组件深度解析 - 自定义组件
- 系统级脚本能力解析 - 系统能力详解
- 创游世界UI数据同步架构 - UI同步架构
- 创游世界存档与云变量设计入门 - 存档设计
- 创游世界战斗系统设计入门 - 战斗系统
项目设计
- 创游世界商店系统实战设计指南 - 商店系统
- 创游世界地图设计基础指南 - 地图设计
教程资料
- 创游世界变量作用域速查卡 - 变量速查
- 广播机制深度解析 - 广播详解
- 创游世界数据类型速查卡 - 数据类型速查
- 常见问题与避坑指南 - 问题解决
导航入口
- 教程资料导航 - 教程资料总入口
- 创游世界知识库总导航 - 知识库总导航
- 新手阅读路线 - 学习路线导航
最后更新：2026-06-16维护者：Azek431