创游世界项目维护与代码组织规范
一句话摘要
本文档整理创游世界项目维护的最佳实践，涵盖素材管理、脚本组织、变量命名、注释规范和版本控制，帮助你保持项目结构清晰、易于维护。
适合谁阅读
- 项目越做越乱的创作者
- 需要团队协作规范的开发者
- 想提高项目可维护性的进阶用户
你将学到什么
- 项目目录结构设计
- 素材管理规范
- 脚本组织与命名
- 注释与文档规范
- 版本控制策略
- 项目复盘方法
为什么需要项目规范
没有规范的项目会遇到：
- 找东西难：不知道某个功能在哪里
- 改东西怕：改一个地方可能影响其他地方
- 新人难上手：只有作者自己能看懂
- 版本难回退：出问题无法还原
好的项目规范 = 长期可维护的基础。
一、项目目录结构
推荐的项目结构
项目
├─ 地图
│ ├─ 菜单场景
│ │ ├─ 背景装饰
│ │ ├─ 按钮物体
│ │ └─ 菜单脚本
│ ├─ 关卡1
│ │ ├─ 地形
│ │ ├─ 敌人
│ │ ├─ 道具
│ │ └─ 关卡脚本
│ ├─ 关卡2
│ └─ ...
├─ 素材库
│ ├─ 角色
│ │ ├─ 主角
│ │ ├─ NPC
│ │ └─ 敌人
│ ├─ 道具
│ │ ├─ 消耗品
│ │ ├─ 装备
│ │ └─ 任务物品
│ ├─ 装饰
│ │ ├─ 室内
│ │ └─ 室外
│ └─ UI素材
├─ UI
│ ├─ 地图UI
│ │ ├─ 对话框
│ │ ├─ 任务面板
│ │ └─ 商店界面
│ ├─ 操作UI
│ │ ├─ 主界面
│ │ └─ 技能栏
│ └─ 物体UI
│ ├─ 血条
│ └─ 头顶名称
└─ 配置表
├─ 道具配置
├─ 怪物配置
├─ 关卡配置
└─ 技能配置地图内物体组织
地图内按功能区域组织：
├─ 玩家区域（玩家初始位置、出生点）
├─ 敌人区域（怪物出生点、巡逻路径）
├─ 机关区域（机关、谜题）
├─ 道具区域（可拾取物品、宝箱）
└─ NPC区域（商人、任务发布者）二、素材管理规范
素材命名
| 类型 | 命名格式 | 示例 |
|---|---|---|
| 角色 | [类型]_[名称] | [主角]勇者、[NPC]商人 |
| 怪物 | [级别]_[名称] | [普通]史莱姆、[精英]狼王 |
| 道具 | [类型]_[名称] | [消耗]生命药水、[装备]铁剑 |
| 装饰 | [类型]_[名称] | [室内]椅子、[室外]树 |
| 地块 | [类型]_[名称] | [草地]草1、[墙壁]石墙 |
素材分类管理
- 按功能分类：角色、道具、装饰、地块
- 按场景分类：室内、室外、地下城
- 按项目分类：通用、专属
建议：
- 通用素材放在公共区域
- 专属素材按项目/章节分类
- 定期清理无用的素材
素材使用检查
| 检查项 | 说明 |
|---|---|
| 是否有未使用的素材 | 定期清理，减小项目体积 |
| 素材是否已被正确命名 | 方便后续查找和脚本引用 |
| 素材是否有正确的组件配置 | 减少重复配置 |
三、脚本组织规范
脚本命名规范
| 对象类型 | 命名示例 | 说明 |
|---|---|---|
| 玩家脚本 | 玩家_主控制、玩家_技能 | 按功能分开 |
| 怪物脚本 | 怪物_巡逻、怪物_攻击 | 按行为分开 |
| NPC脚本 | NPC_对话、NPC_任务 | 按功能分开 |
| 机关脚本 | 机关_开关、机关_陷阱 | 按类型分开 |
| UI脚本 | UI_背包、UI_商店 | 按界面分开 |
| 地图脚本 | [地图名]_初始化、[地图名]_波次 | 地图级逻辑 |
脚本分离原则
| 原则 | 说明 | 示例 |
|---|---|---|
| 按功能分离 | 不同功能写在不同脚本 | 移动逻辑和攻击逻辑分开 |
| 按层级分离 | UI/地图/物体分层 | UI脚本只发请求，地图脚本处理逻辑 |
| 按对象分离 | 不同对象分开 | 每个敌人独立脚本 |
脚本注释规范
# 脚本说明
─────────────────────────────────
脚本名称：怪物_攻击
功能：处理怪物的攻击逻辑
作者：XXX
最后更新：2026-05-15
─────────────────────────────────
# 触发时机：当受到伤害时
# 功能：处理受伤后的反击逻辑
# 输入：伤害值、攻击者
# 输出：无（直接执行）
# TODO：待优化攻击范围检测
# BUG：与玩家无敌帧冲突（已记录）四、变量命名规范
变量命名建议
| 类型 | 命名风格 | 示例 |
|---|---|---|
| 局部变量 | 描述性中文 | 当前血量、敌人数量 |
| 自身属性 | 属性_ 前缀 | 属性_当前状态、属性_冷却时间 |
| 地图属性 | 地图_ 前缀 | 地图_波次、地图_倒计时 |
| 系统属性 | 系统_ 前缀 | 系统_难度、系统_玩家金币 |
| 玩家变量 | 存档_ 前缀 | 存档_等级、存档_背包 |
避免的命名
❌ 避免：
- a、b、c（无意义）
- temp1、temp2（临时变量未清理）
- 变量1、变量2（含义不清）
- 中文拼音混用（mubiao、diji）
✅ 推荐：
- 清晰描述：当前血量、目标坐标
- 统一语言：全中文或全英文
- 有组织：属性_xxx、地图_xxx五、广播命名规范
快速参考
| 类型 | 命名格式 | 示例 |
|---|---|---|
| 请求类 | 请求_动作_目标 | 请求_购买_道具 |
| 通知类 | 对象_动作_类型 | 敌人_死亡_通知 |
| 刷新类 | 刷新_界面_内容 | 刷新_界面_金币 |
六、组件使用规范
组件挂载原则
| 原则 | 说明 |
|---|---|
| 必要性 | 只挂需要的组件 |
| 唯一性 | 同类组件不要重复挂 |
| 配置同步 | 相同类型物体使用相同组件配置 |
常用组件配置模板
角色模板：
├─ 物理组件
│ ├─ 移动速度：5
│ └─ 碰撞盒：默认
├─ 角色组件
│ ├─ 朝向：右
│ └─ 默认动画：待机
└─ （可选）武器槽组件
怪物模板：
├─ 物理组件
├─ 生命组件
│ ├─ 最大生命：100
│ └─ 当前生命：100
├─ 伤害组件
│ └─ 伤害值：10
└─ （可选）子弹组件七、注释与文档规范
必加注释的场景
| 场景 | 注释内容 |
|---|---|
| 复杂逻辑 | 说明判断条件和处理流程 |
| 特殊处理 | 说明为什么这样做 |
| 容易出错 | 警告可能的陷阱 |
| 未完成 | TODO标记和预计方案 |
| 版本相关 | 说明哪个版本加入的逻辑 |
注释风格示例
# 复杂条件判断
# 条件：玩家金币 >= 道具价格 AND 背包有空位
# 原因：避免扣钱后背包满了无法获得道具
如果 (玩家金币 >= 道具价格) 且 (背包空位数 > 0)：
→ 执行购买逻辑
# 特殊处理：处理浮点数精度问题
# 原因：浮点数比较可能不准，所以用约等于
如果 abs(计算结果 - 预期值) <= 0.01：
→ 认为计算正确
# TODO：后续优化广播链
# 当前：3层广播嵌套，可能影响性能
# 预计：合并为2层八、版本控制策略
项目备份时机
| 时机 | 说明 |
|---|---|
| 完成重要功能后 | 可回退到稳定版本 |
| 开始风险操作前 | 改坏前先备份 |
| 定期备份 | 每周/每月固定时间 |
| 多人协作前 | 合并前备份 |
版本命名规范
格式：项目名_v版本.修订.日期
示例：RPG游戏_v1.0.20260515
版本号规则：
- 大版本：功能大更新
- 小版本：功能小更新
- 修订：修复和调整版本更新记录
# 项目更新日志
## v1.2.0 - 2026-05-15
### 新增
- 新增商店系统
- 新增背包UI
### 修改
- 优化战斗结算逻辑
- 修复敌人攻击无效BUG
### 已知问题
- 联机时金币同步有延迟（待修复）
## v1.1.0 - 2026-05-10
### 新增
- 新增第一关卡
- 新增3种怪物
...九、项目复盘方法
定期复盘检查
| 检查项 | 频率 | 负责人 |
|---|---|---|
| 项目结构是否清晰 | 每周 | 开发者 |
| 有没有冗余素材/脚本 | 每月 | 开发者 |
| 文档是否更新 | 每次大更新后 | 开发者 |
| 存档是否正常 | 每次更新后 | 开发者 |
复盘问题清单
代码层面
- 有没有重复代码可以抽象？
- 有没有太长的脚本需要拆分？
- 变量命名是否清晰？
架构层面
- UI 和逻辑是否分离？
- 广播使用是否合理？
- 数据分层是否正确？
维护层面
- 有没有 TODO 还没做？
- 有没有已知 BUG 还没修？
- 文档是否和代码一致？
十、团队协作建议
协作规范
| 规范 | 说明 |
|---|---|
| 命名统一 | 所有人使用统一的命名规范 |
| 不改他人脚本 | 如需修改，先沟通 |
| 重要变更记录 | 记录谁改了什么、为什么改 |
| 定期同步 | 定期合并和更新 |
冲突处理
当多人同时修改同一脚本时：
1. 先尝试合并
2. 如果冲突，看修改时间和内容决定保留哪个
3. 如果无法决定，联系作者确认
4. 合并后测试确保功能正常相关页面
- 创游世界广播命名规范与最佳实践 - 广播规范
- 创游世界项目结构模板 - 项目结构参考
- 创游世界新手常见卡点与避坑清单 - 常见问题
待验证问题
[待验证]创游世界是否有内置版本控制功能[待验证]多人协作时的具体限制
后续优化方向
- [ ] 补充团队协作的具体流程
- [ ] 添加项目模板下载
- [ ] 完善复盘模板