🐍 蛇咬 (Snake Bite)

推箱子 × 贪吃蛇 融合解谜游戏 · Godot 4.6
Fork 教程 | 关卡格式 | TODO

---

🎮 玩法

操控一条蛇在网格地图上移动：

• 🍎 吃果子 → 蛇变长
• ✂️ 吃剪刀果子 → 获得 1 次咬断能力
• 🦷 撞自己身体 + 有剪刀 → 咬断！断肢变成可推动的箱子
• 📦 推箱子覆盖所有发光地板 → 🏁 通关

WASD / 方向键移动 | Esc 暂停 | Ctrl+Z 撤销

---

📂 项目结构

蛇咬/
├── snake.gd                 # ★ 核心：移动/咬断/推箱/撤销/通关
├── level_editor.gd          # 关卡编辑器（笔刷系统 + JSON 保存加载）
├── play_custom.gd           # 自定义关卡热加载
├── custom_level_list.gd     # 动态扫描 JSON 生成选关列表
├── level_point.gd           # 传送点（碰触触发场景跳转）
├── pause_menu.gd            # ESC 暂停菜单
├── win_screen.gd            # 胜利界面
├── global_background.gd     # 全局背景自动切换（AutoLoad）
├── project.godot            # Godot 4.6 项目配置
├── CustomLevels/            # 自定义关卡 JSON 存放处
│   ├── test one.json
│   ├── test two.json
│   └── test three.json
└── image/                   # 美术资源（头/身子/尾巴/弯折/果子/剪刀/格子）

---

🗺️ 关卡格式

每个关卡是一个 JSON 文件，放在 CustomLevels/ 目录：

{
  "width": 7,
  "height": 7,
  "objects": [
    {"type": "wall",           "x": 0, "y": 0},
    {"type": "apple",          "x": 2, "y": 1},
    {"type": "scissor_apple",  "x": 1, "y": 3},
    {"type": "glowing_floor",  "x": 3, "y": 0},
    {"type": "snake",          "x": 1, "y": 5, "length": 4},
    {"type": "river",          "x": 5, "y": 5}
  ]
}

type	含义	额外字段	必填
wall	墙壁（不可通过）	-	否
apple	果子（吃了变长）	-	否
scissor_apple	剪刀果子（获得咬断能力）	-	否
glowing_floor	发光地板（通关目标）	-	⚠️至少1个
snake	蛇初始位置	length（≥3）	⚠️必填
river	河流（箱子掉入沉没）	-	否

💡 用 Godot 编辑器打开项目 → 进入关卡编辑器可鼠标拖放设计关卡，导出为 JSON。

---

🔧 Fork & 贡献流程

1. Fork → 打开 https://github.com/HX0922/snake-bite 点右上角 Fork
2. Clone → git clone git@github.com:你的用户名/snake-bite.git
3. 关联上游 → git remote add upstream https://github.com/HX0922/snake-bite.git
4. 修改 → 改代码、加关卡
5. 提交 → git add -A && git commit -m "你做了什么" && git push origin main
6. 同步 → git fetch upstream && git merge upstream/main

---

📋 新增关卡自检清单

提交新关卡前，请逐项确认：

• JSON 格式合法（用 JSONLint 验证）
• width 和 height 与实际坐标范围一致
• 至少包含 1 个 glowing_floor（不然无法通关）
• 恰好包含 1 个 snake
• 蛇的 length ≥ 3
• 所有坐标在 0 ≤ x < width 且 0 ≤ y < height 范围内
• 关卡可通关（在编辑器里试玩验证）
• 文件名无空格、有意义的关卡名（如 蛇咬-01-入门.json）

---

🧪 本地调试

# 控制台模式运行时日志（WSL / Git Bash）
/path/to/Godot_v4.6.2-stable_win64_console.exe --path ./蛇咬 --verbose

# Godot 编辑器内调试：行号左侧点设断点 → F5 运行 → F10/F11 单步

---

🗂️ 文件对照

脚本	关联场景	职责
snake.gd	snake.tscn	移动、碰撞、咬断、撤销、通关
level_editor.gd	level_editor.tscn	笔刷系统、JSON 导入导出
play_custom.gd	play_custom.tscn	加载关卡 JSON 并实例化
custom_level_list.gd	custom_level_list.tscn	扫描 CustomLevels/ 生成选关
level_point.gd	level_point.tscn	碰触触发场景切换
pause_menu.gd	pause_menu.tscn	暂停/重开/返回选关
win_screen.gd	-	胜利后跳回选关
global_background.gd	global_background.tscn	AutoLoad 全局背景切换

---

✅ 已完成功能

• ✅ 贪吃蛇网格移动
• ✅ 蛇身图形自适应（直身/弯折/尾巴）
• ✅ 咬断自身变箱子
• ✅ 推箱子系统（BFS 连环推）
• ✅ 箱子沉没（河流机制）
• ✅ 发光地板通关检测
• ✅ 完整撤销系统（Z 键）
• ✅ 关卡编辑器（笔刷、JSON 保存/加载、蛇朝向选择）
• ✅ 自定义关卡热加载（存 CustomLevels/）
• ✅ 暂停菜单
• ✅ 平滑相机跟随
• ✅ 全局背景自动切换
• ✅ 蛇初始朝向自定义（JSON dir_x/dir_y）
• ✅ 通关绿框标记 + 关卡完成度存档（global.gd）
• ✅ Excel 涂色 → JSON 批量转换工具（xlsx_to_levels.py）
• ✅ 公共函数提取到 Global 单例（消除 get_custom_levels_dir 重复）

---

📝 待做事项

🐛 修复

• 清理临时文件 level_1.tscn4250219618.tmp
• .gitignore 需重新梳理（.godot/ 编辑器缓存）
• _on_snake_length_dialog_confirmed 路径硬编码 VBoxContainer，UI 结构变化会炸
• get_custom_levels_dir() 重复定义 → ✅ 已提取到 global.gd
• 撤销快捷键 Ctrl+Z 编辑器双重触发 → ✅ 蛇撤销改为纯 Z 键
• 蛇初始方向固定 RIGHT → ✅ 已支持 dir_x/dir_y

✨ 新功能

• 第 12 关蛇头未完成（晨宝 Excel 里还没画）
• 音效系统（移动 / 吃果子 / 咬断 / 通关）
• 步数计数器 + 最少步数评分
• 撤销步数限制（step_history 设上限防内存泄漏）
• 箱子外观随来源区分（蛇身变的灰色 vs 普通木箱）
• xlsx_to_levels.py: 支持在线文档直读（腾讯文档 API）
• Excel 涂色转 JSON → ✅ xlsx_to_levels.py 完成
• 关卡完成度追踪 → ✅ global.gd + 绿框
• 蛇初始朝向自定义 → ✅ PR #1

🧹 代码质量

• snake.gd 524 行偏长，可拆分为移动/碰撞模块
• 添加 GDScript 类型注解（typed arrays, return types）
• 魔法数字常量化 → ✅ 已提取 COLLISION_RADIUS / WIN_CHECK_RADIUS

---

📅 更新日志

2026-05-15

• 🏗️ 项目初始化：GitHub 仓库、gitignore、README 架构文档
• 🔀 合并 PR #1 (@pigreal)：蛇朝向、通关绿框、Global 模块、撤销改 Z
• 🐛 修复 PR #1 合并后的重复 execute_placement 调用
• 🛠️ xlsx_to_levels.py：Excel 涂色 → 11 个关卡 JSON 一键生成
• 🔍 审查 Ctrl+Z 撤销功能：发现编辑器双重触发 bug（已修复）
• 🖥️ 本地 Godot 4.6.2 调试环境配置（D:\programs\godot）

---

🌐 技术栈

• 引擎: Godot 4.6 (GL Compatibility renderer)
• 语言: GDScript
• 网格: 416px 方格
• 存储: JSON 关卡文件 + user:// 运行时缓存