Defold 团队协作与版本控制

my-game/
  game.project          ← 项目配置，必须入库
  game.projectc         ← 编译产物，不要入库
  input.gamepads        ← 手柄映射，必须入库
  main/
    main.collection     ← 启动集合
    player.go
    player.script
  assets/
    sprites.atlas
    sprites.png         ← 二进制，入库但需注意
    tileset.tilesource
  fonts/
  sounds/
  gui/
  modules/
  libraries/            ← 依赖库缓存，通常不入库
  build/                ← 构建产物，不入库
  .internal/            ← 编辑器内部状态，不入库

按资源域划分所有权，避免多人同时改同一文件：
  main/           → 客户端程序员
  gui/            → UI 美术
  assets/sprites  → 美术
  sounds/         → 音频
  modules/        → 客户端程序员

# Defold 构建产物
/build/
game.projectc

# 编辑器内部状态
.internal/
*.tmp

# 依赖缓存（由 resolve 重新下载）
/libraries/

# 系统文件
.DS_Store
Thumbs.db

# 编辑器
.vscode/
.idea/
*.swp

# 日志
*.log

[project]
dependencies#0 = https://github.com/defold/extension-camera/archive/refs/tags/2.1.0.zip
dependencies#1 = https://github.com/defold/extension-websocket/archive/refs/tags/3.0.0.zip

feat(combat): 增加暴击伤害计算
fix(player): 修复二段跳后穿墙
refactor(ui): 抽出通用的按钮组件
docs(readme): 补充构建步骤
chore(deps): 升级 camera 扩展到 2.1.0

格式：<类型>(<范围>): <描述>
类型：feat / fix / refactor / docs / chore / test / perf

git lfs install
git lfs track "*.png"
git lfs track "*.ttf"
git lfs track "*.wav"
git lfs track "*.ogg"
git add .gitattributes

# .gitattributes
*.png filter=lfs diff=lfs merge=lfs -text
*.ttf filter=lfs diff=lfs merge=lfs -text
*.wav filter=lfs diff=lfs merge=lfs -text

 {
   "name": "player",
   "type": "go",
   "position": [0, 0, 0],
-  "rotation": [0, 0, 0, 1],
+  "rotation": [0, 0, 0.707, 0.707],
   "components": [...]
 }

1. 一个资源一个负责人，避免并行修改
2. 大图拆小图，减少单文件被同时触碰的概率
3. 用图集（atlas）把多张小图合并，但图集本身又成了热点 → 权衡
4. 修改前在群里喊一声「我要改 player.png」

# 1. 看冲突文件
git status

# 2. 选择保留哪一边
git checkout --ours  assets/player.png    # 保留当前分支
git checkout --theirs assets/player.png   # 保留对方分支

# 3. 或者从共同祖先拿回原版，重新导出
git checkout --merge assets/player.png

# 4. 标记已解决
git add assets/player.png

"children": [
    "player",
    "enemy_a",     ← A 加的
    "enemy_b",     ← B 加的（本不该同时存在）
    "ui"
]

main.collection
  ├── level_1.collection      ← 关卡美术 A 负责
  ├── level_2.collection      ← 关卡美术 B 负责
  └── ui.collection           ← UI 美术负责

# 锁定一个文件，其他人无法推送修改
git lfs lock assets/sprites.png

# 查看已锁定的文件
git lfs locks

# 解锁
git lfs unlock assets/sprites.png

1. 编辑器能正常打开项目吗？
2. 所有节点引用都有效吗（无红色警告）？
3. 启动集合能正常运行吗？
4. 关键流程跑一遍（进入关卡、切换场景）？
5. 用 bob 命令行构建一次，确认无解析错误？

# .gitattributes —— 让 JSON 不做自动合并，强制产生冲突标记
*.collection merge=binary
*.go         merge=binary

main ──●──●──●──●──●──●──●──→  永远可发布
        \    /
         ●──●   feature 分支，存活不超过 2 天

git switch -c feat/double-jump
# ... 开发 ...
git fetch origin
git rebase origin/main
git push -u origin feat/double-jump
# 开 PR，CI 通过后 squash 合并

main     ──●──────────────●──────────●──→  只放发布版本
            \            /            /
release      ●──●──●──●─●            /      发布准备
            /                        /
develop  ──●──●──●──●──●──●──●──●──●──→    集成分支
              \    /
feature        ●──●                        功能开发

# 新功能
git switch -c feature/inventory develop
# 发布准备
git switch -c release/1.4.0 develop
# 紧急修复
git switch -c hotfix/1.4.1 main

方案 A：美术直接提交到主干（配合资源锁）
方案 B：美术用独立的资源仓库，通过子模块引入
方案 C：美术用 Dropbox / 网盘同步，程序定期导入

main / develop 开启保护：
  - 禁止直接推送，必须走 PR
  - 至少 1 人 Approve
  - CI 必须通过（luacheck + busted + bob 构建）
  - 禁止强推

[project]
dependencies#0 = https://github.com/defold/extension-camera/archive/refs/tags/2.1.0.zip
dependencies#1 = https://github.com/defold/extension-spine/archive/refs/tags/4.2.3.zip

结构：
my-team-libs/
  ui_widgets/
    widget.gui
    widget.gui_script
  utils/
    math_utils.lua
  game.project       ← 库也要有 game.project

[project]
dependencies#2 = https://git.internal/team/my-team-libs/archive/refs/tags/1.2.0.zip

Game Object:  snake_case，语义明确
  player, enemy_grunt, ui_hud_root, spawn_point_01

组件 id:      角色_功能
  player#sprite, player#collision, player#script

脚本文件:     功能名.script
  player.script, enemy_ai.script

Lua 模块:     snake_case.lua
  math_utils.lua, inventory.lua

常量:         UPPER_SNAKE
  MAX_ENEMIES, GRAVITY, DEFAULT_HP

# 找出不符合 snake_case 的节点名
grep -rEn '"name":\s*"[A-Za-z0-9]*[A-Z]' main/ --include=*.collection --include=*.go

-- 或者写个 Lua 检查脚本，扫描调试残留
-- 常见残留：命名为 "test"、"temp"、"copy" 的节点
local BAD_PATTERNS = { "test", "temp", "copy", "debug", "aaa" }

【改了什么】简述本次改动
【为什么改】关联 issue 或需求编号
【怎么验证】1. 打开 main.collection 运行；2. 触发目标场景确认行为；3. 用 bob 构建一次
【检查清单】luacheck 通过 / busted 通过 / 场景文件无调试残留节点 / 未提交 build 与 libraries

build/           ← 完全排除
game.projectc    ← 排除
*.apk / *.ipa / *.zip  ← 排除

# game.project
[project]
version = 1.4.2

# CI 中按 tag 自动写入
VERSION="${GITHUB_REF_NAME#v}"
sed -i "s/^version = .*/version = $VERSION/" game.project

发布前：
  [ ] 所有 PR 已合并，develop 与 main 同步
  [ ] CI 全绿（luacheck + busted + 全平台构建）
  [ ] 版本号已更新并打 tag
  [ ] 变更日志已整理

发布后：
  [ ] 产物已上传到 Release
  [ ] 热更新清单已生成并验证
  [ ] 回滚方案已确认

#!/bin/bash
# ======================================
# 完整示例：项目初始化脚本 setup.sh
# 新成员克隆仓库后执行一次
# ======================================

set -euo pipefail

echo "== 1. 检查 Git LFS =="
if ! command -v git-lfs >/dev/null 2>&1; then
  echo "请先安装 Git LFS: brew install git-lfs"
  exit 1
fi
git lfs install

echo "== 2. 拉取 LFS 资源 =="
git lfs pull

echo "== 3. 检查 Java（bob 需要） =="
if ! command -v java >/dev/null 2>&1; then
  echo "请先安装 JDK 17+"
  exit 1
fi
java -version

echo "== 4. 下载 bob.jar =="
if [ ! -f bob.jar ]; then
  curl -fO https://d.defold.com/stable/bob/bob.jar
fi

echo "== 5. 解析依赖 =="
java -jar bob.jar --root . resolve

echo "== 环境就绪 =="
echo "接下来：用 Defold 编辑器打开 game.project 开始开发"