docs(zh-hans): rewrite battle system documentation

Author: Bli-AIk

doc/docs/zh-hans/part0_mise_en_place/0.1_welcome.md

@@ -1,6 +1,130 @@
 # 欢迎来到皇家厨房
 
-这里是什么地方？（关于 SoupRune）
-看看其他大厨的杰作（Showcase）
+```dialogue
+<path:/images/faces/toriel.png>
+* 欢迎，我的孩子。我看到你对制作游戏充满了热情。
+* 不用紧张，我会一步步教你的，就像烤派一样简单。
+```
 
-(TODO)
+欢迎来到 **SoupRune**——一个为创作 Deltarune / Undertale 风格游戏而生的现代化框架。
+
+如果你是第一次来到这里，可能会有些不知所措。这么多文件，这么多术语……别担心，深呼吸，让我慢慢为你讲解。
+
+## 🥣 这到底是什么？
+
+想象一下，你走进了一间厨房。
+
+在这间厨房里：
+- **炉灶**已经准备好了（Bevy 引擎）
+- **锅碗瓢盆**都摆放整齐（核心系统）
+- **基础食材**已经备好（配置模板）
+
+你需要做的，只是：
+1. 拿起菜谱（配置文件）
+2. 按照步骤添加材料（编写 RON 文件）
+3. 偶尔调整火候（修改参数）
+
+就这样，一道美味的游戏就诞生了！
+
+```dialogue
+<path:/images/faces/toriel.png>
+* 最重要的是——你不需要成为专业厨师。
+* 只要会读食谱，就能做出美味的派。
+```
+
+## 🍲 S.O.U.P 原则
+
+SoupRune 的设计理念可以用一碗热气腾腾的汤来概括：
+
+### **S - Strong (强劲内核)**
+底层使用 **Rust** 和 **Bevy 引擎**，拥有出色的性能和并行计算能力。就像一口结实的铸铁锅，能承受高温和重压。
+
+### **O - Open (自由开源)**
+采用 **LGPL-3.0** 协议。引擎代码开源，但你的游戏项目完全属于你自己。就像公共厨房——设备是大家的，但你做出的菜是你的。
+
+### **U - User-friendly (易于上手)**
+提供开箱即用的功能：对话系统、战斗框架、地图编辑器集成。就像预制的半成品——加热就能吃。
+
+### **P - Polyglot (多语言支持)**
+支持 Rust、C#、Haxe 等多种编程语言。就像准备了多种餐具——筷子、刀叉、勺子，用你最顺手的那个！
+
+## 🎮 你能做什么？
+
+使用 SoupRune，你可以创作：
+
+✅ **回合制战斗系统**（像 Undertale 那样的弹幕战斗）  
+✅ **开放世界探索**（像 Deltarune 的城镇和迷宫）  
+✅ **对话和剧情系统**（用 Mortar 脚本语言）  
+✅ **自定义 UI 界面**（战斗菜单、道具栏等）  
+✅ **动画和特效**（集成 Alight Motion 动画工具）  
+
+## 🎯 "不写代码"是真的吗？
+
+是的——**绝大部分内容**都可以通过配置文件完成！
+
+举个例子，创建一场战斗，你只需要写这样的配置文件：
+
+```ron
+// battle.ron
+(
+  player_hp: 92,
+  player_speed: 200.0,
+  battle_box_size: (150.0, 150.0),
+  chapters: [
+    // 玩家选择攻击目标
+    UIInteraction(ui_layout: "battle_menu"),
+    // 播放弹幕攻击
+    DanmakuPerformance(
+      performance: "attacks/flowey_bullets.ron",
+      position: Some((0.0, 100.0)),
+    ),
+    // 等待3秒
+    Wait(3.0),
+  ]
+)
+```
+
+看到了吗？就像填表格一样！
+
+当然，如果你想实现更复杂的逻辑（比如独特的 Boss 机制），你可以用 Rust、C# 或 Haxe 编写脚本。但对于大部分内容来说，配置文件就够了。
+
+```dialogue
+<path:/images/faces/toriel.png>
+* 别担心，孩子。我们会从最简单的开始。
+* 一步一个脚印，很快你就能烤出自己的派了。
+```
+
+## 🏗️ 引擎 vs 项目：游戏机与卡带
+
+这个比喻非常重要，让我们用任天堂 Switch 来类比：
+
+| 部分 | 比喻 | 说明 | 你需要做什么？ |
+|-----|------|------|-------------|
+| **Engine (引擎)** | Switch 主机 | 负责运行游戏的底层系统 | ❌ 不需要改动 |
+| **Core (核心库)** | 操作系统 | 提供基础功能（碰撞、渲染等） | ❌ 不需要改动 |
+| **Project (项目)** | 游戏卡带 | 你的游戏内容和剧情 | ✅ 这是你的主战场 |
+| **Assets (资源)** | 游戏数据 | 图片、音乐、配置文件 | ✅ 这是你的创意空间 |
+
+所以你要做的，就是**制作游戏卡带**——编写配置文件、准备素材、编排剧情。
+
+引擎会帮你处理所有复杂的技术问题（渲染、物理、音频等），你只需要专注于创意！
+
+## 📚 关于这份文档
+
+这份文档分为几个部分：
+
+- **Part 0: 备菜阶段**（你现在这里）— 环境配置和基础知识
+- **Part 1: 辛辣的主菜** — 战斗系统开发
+- **Part 2: 精致摆盘** — 世界场景与叙事
+- **Part 3: 灵魂甜点** — 视听效果与美化
+- **Part 4: 分子料理** — 高级脚本与底层开发
+
+```dialogue
+<path:/images/faces/toriel.png>
+* 准备好了吗，孩子？
+* 让我们开始你的烹饪之旅吧。
+```
+
+---
+
+**下一步：[挑选你的厨具 →](0.2_setup.md)**

doc/docs/zh-hans/part0_mise_en_place/0.2_setup.md

@@ -1,6 +1,205 @@
 # 挑选你的厨具
 
-只需三步，点火开灶（快速安装指南）
-*特别收录：如果锅炸了怎么办？（常见安装报错）*
+```dialogue
+<path:/images/faces/toriel.png>
+* 好的，孩子。在开始烹饪之前...
+* 我们需要确保厨房里有所有必要的工具。
+* 别担心，我会帮你检查每一件的。
+```
 
-(TODO)
+在真正开始制作游戏之前，我们需要准备好开发环境。这就像准备厨具——工欲善其事，必先利其器。
+
+## 🔧 你需要什么？
+
+### 必备工具清单
+
+| 工具 | 作用 | 必需？ |
+|-----|------|--------|
+| **Rust** | 编译和运行引擎 | ✅ 必须 |
+| **Git** | 版本控制和克隆仓库 | ✅ 必须 |
+| **系统依赖库** | 图形和音频支持 | ✅ 必须 |
+| **代码编辑器** | 编写配置文件 | 🟡 推荐 |
+
+```dialogue
+<path:/images/faces/toriel.png>
+* 让我们一件一件来准备吧。
+```
+
+## 📦 Step 1: 安装 Rust
+
+Rust 是 SoupRune 的核心语言。不用担心，你不需要学习 Rust 编程——它只是用来编译和运行引擎的。
+
+### Windows
+
+1. 访问 [https://rustup.rs/](https://rustup.rs/)
+2. 下载并运行 `rustup-init.exe`
+3. 按照提示完成安装（默认选项即可）
+4. 重启终端
+
+**检查安装：**
+```bash
+rustc --version
+cargo --version
+```
+
+如果看到版本号，说明安装成功了！
+
+```dialogue
+<path:/images/faces/toriel.png>
+* 很好！第一步完成了。
+```
+
+### Linux (Ubuntu/Debian)
+
+首先安装系统依赖：
+```bash
+sudo apt-get update
+sudo apt-get install -y \
+  g++ \
+  pkg-config \
+  libx11-dev \
+  libasound2-dev \
+  libudev-dev \
+  libwayland-dev \
+  libxkbcommon-dev
+```
+
+然后安装 Rust：
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+source $HOME/.cargo/env
+```
+
+**检查安装：**
+```bash
+rustc --version
+cargo --version
+```
+
+### macOS
+
+1. 打开终端
+2. 运行以下命令：
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+3. 按照提示完成安装
+4. 运行 `source $HOME/.cargo/env`
+
+**检查安装：**
+```bash
+rustc --version
+cargo --version
+```
+
+## 🌐 Step 2: 安装 Git
+
+Git 用于克隆 SoupRune 仓库和管理你的项目版本。
+
+### Windows
+访问 [https://git-scm.com/downloads](https://git-scm.com/downloads) 下载安装包。
+
+### Linux
+```bash
+sudo apt-get install git
+```
+
+### macOS
+```bash
+brew install git
+# 或者使用 Xcode Command Line Tools
+xcode-select --install
+```
+
+**检查安装：**
+```bash
+git --version
+```
+
+## 💻 Step 3: 选择代码编辑器（推荐）
+
+虽然用记事本也能编辑配置文件，但一个好的编辑器能让你事半功倍。
+
+推荐的编辑器：
+
+### 新手友好型
+- **[Visual Studio Code](https://code.visualstudio.com/)** — 功能强大，有丰富的插件
+  - 推荐插件：`Even Better TOML`（用于编辑 RON 文件）
+  - 推荐插件：`Rust Analyzer`（如果你打算写 Rust 脚本）
+
+### 专业开发者
+- **[RustRover](https://www.jetbrains.com/rust/)** — JetBrains 出品的 Rust IDE
+- **[Neovim](https://neovim.io/)** — 如果你喜欢终端编辑器
+
+```dialogue
+<path:/images/faces/toriel.png>
+* 选择你最熟悉的工具就好。
+* 就像有人喜欢木勺，有人喜欢铁勺一样。
+```
+
+## 🍳 准备完成检查清单
+
+在继续之前，请确认以下几点：
+
+- [ ] Rust 已安装（`rustc --version` 能显示版本号）
+- [ ] Cargo 已安装（`cargo --version` 能显示版本号）
+- [ ] Git 已安装（`git --version` 能显示版本号）
+- [ ] （Linux）系统依赖库已安装
+- [ ] 代码编辑器已安装（推荐）
+
+如果全部打勾，那你就准备好了！
+
+## ⚠️ 常见问题
+
+### "command not found: cargo"
+
+这通常意味着 Rust 的路径没有被添加到环境变量中。
+
+**解决方法：**
+```bash
+# Linux/macOS
+source $HOME/.cargo/env
+
+# Windows (PowerShell)
+$env:PATH += ";$env:USERPROFILE\.cargo\bin"
+```
+
+然后重启终端。
+
+### Linux 编译时报错 "could not find system library"
+
+确保安装了所有开发库：
+```bash
+sudo apt-get install -y \
+  g++ \
+  pkg-config \
+  libx11-dev \
+  libasound2-dev \
+  libudev-dev \
+  libwayland-dev \
+  libxkbcommon-dev
+```
+
+### Windows 上编译很慢
+
+这是正常的！Rust 第一次编译会需要一些时间（10-30分钟）。后续的编译会快很多。
+
+可以考虑：
+- 使用 `--release` 模式编译（更慢但运行快）
+- 升级到 SSD 硬盘
+- 增加虚拟内存
+
+```dialogue
+<path:/images/faces/toriel.png>
+* 如果遇到其他问题，不要慌张...
+* 可以到我们的 Discord 社区寻求帮助。
+* 那里有很多热心的大厨会帮助你的。
+```
+
+## 🎉 恭喜！
+
+你已经准备好了所有的厨具！现在让我们真正点燃炉火吧。
+
+---
+
+**下一步：[第一次点火 →](0.3_quick_start.md)**