# MC Player Transfer 使用文档

## 简介

MC Player Transfer 是一个 Minecraft 基岩版角色转移工具，可以像泰拉瑞亚一样，将角色从一个世界完整转移到另一个世界。

### 支持转移的数据

- ✅ 背包全部物品
- ✅ 末影箱全部物品
- ✅ 潜影盒及其内部物品
- ✅ 装备栏（头盔、胸甲、护腿、靴子）
- ✅ 副手物品
- ✅ 经验等级
- ✅ 生命值 / 饥饿值
- ✅ 玩家坐标位置
- ✅ 游戏模式
- ✅ 物品附魔、耐久度等 NBT 数据

---

## 环境要求

- Python 3.8 或更高版本
- Windows 10/11（WSL 环境）

---

## 安装步骤

### 1. 安装 Python 依赖

打开命令行，进入项目目录，执行：

```bash
pip install -r requirements.txt
```

或手动安装：

```bash
pip install amulet-core
```

### 2. 验证安装

```bash
python main.py
```

如果显示帮助信息，说明安装成功。

---

## 使用方法

### 方法一：提取角色数据

将 `.mcworld` 文件中的角色数据提取为独立的 `.dat` 文件。

**步骤：**

1. 将你的 `.mcworld` 存档文件放入 `input/` 文件夹

2. 执行命令：
   ```bash
   python main.py extract "input/你的世界.mcworld"
   ```

3. 提取的角色数据会保存到 `output/` 文件夹，文件名格式：`世界名_时间戳.dat`

**示例：**

```bash
python main.py extract "input/World (2).mcworld"
```

输出：
```
正在解压: input/World (2).mcworld
找到数据库: /tmp/xxx/db

✓ 提取成功!
  世界名称: World (2)
  数据大小: 50617 bytes
  输出文件: output/World (2)_20251216_084843.dat
```

---

### 方法二：导入角色数据

将 `.dat` 角色文件导入到另一个 `.mcworld` 存档中。

**步骤：**

1. 准备好目标世界的 `.mcworld` 文件

2. 准备好之前提取的 `.dat` 角色文件

3. 执行命令：
   ```bash
   python main.py import "目标世界.mcworld" "output/角色数据.dat"
   ```

4. 生成的新存档文件名为 `目标世界_imported.mcworld`

**示例：**

```bash
python main.py import "我的世界.mcworld" "output/World (2)_20251216_084843.dat"
```

输出：
```
读取角色数据: 50617 bytes
正在解压: 我的世界.mcworld
✓ 角色数据已写入
正在打包: 我的世界_imported.mcworld

✓ 导入成功!
  输出文件: 我的世界_imported.mcworld
```

---

## 完整使用流程示例

### 场景：将角色从「生存世界」转移到「新世界」

```bash
# 第一步：提取生存世界的角色
python main.py extract "input/生存世界.mcworld"

# 第二步：导入到新世界
python main.py import "input/新世界.mcworld" "output/生存世界_20251216_120000.dat"

# 第三步：将生成的 新世界_imported.mcworld 导入游戏
```

---

## 如何获取 .mcworld 文件

### 方法一：从游戏导出

1. 打开 Minecraft 基岩版
2. 进入「设置」→「存储」
3. 选择要导出的世界
4. 点击「导出世界」
5. 选择保存位置，得到 `.mcworld` 文件

### 方法二：从存档文件夹打包

Windows 存档位置：
```
C:\Users\用户名\AppData\Local\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\games\com.mojang\minecraftWorlds\
```

将整个世界文件夹压缩为 `.zip`，然后改后缀为 `.mcworld`。

---

## 如何导入 .mcworld 文件到游戏

1. 双击 `.mcworld` 文件，游戏会自动导入
2. 或者将文件拖入游戏窗口
3. 或者手动解压到存档目录

---

## 项目目录结构

```
MCPlayerTransfer/
├── main.py                 # 主程序入口
├── requirements.txt        # Python 依赖
├── README.md               # 简要说明
├── src/                    # 源代码
│   ├── __init__.py
│   ├── extract_player.py   # 提取模块
│   └── import_player.py    # 导入模块
├── docs/                   # 文档
│   └── 使用文档.md
├── input/                  # 输入文件夹（放 .mcworld 文件）
└── output/                 # 输出文件夹（生成 .dat 文件）
```

---

## 常见问题

### Q: 提示找不到 leveldb 模块？

A: 执行 `pip install amulet-core`，这个包包含了所需的 leveldb 支持。

### Q: 提示找不到本地玩家数据？

A: 确保 `.mcworld` 文件是有效的基岩版存档，且曾经在单人模式下游玩过。

### Q: 导入后角色位置不对？

A: 角色数据包含坐标信息，导入后会保留原来的位置。如果新世界该位置是虚空，角色可能会掉落。建议先在新世界创建一个安全的出生点。

### Q: 可以转移多人服务器的角色吗？

A: 本工具只支持本地玩家（`~local_player`）。服务器玩家数据存储方式不同，暂不支持。

### Q: 原存档会被修改吗？

A: 不会。提取操作只读取数据，导入操作会生成新的 `_imported.mcworld` 文件，不修改原文件。

---

## 注意事项

⚠️ **重要提醒：**

1. **操作前务必备份存档**
2. **关闭游戏后再进行操作**
3. **导入会完全覆盖目标存档的本地玩家数据**
4. **建议先在测试存档上验证**

---

## 技术原理

Minecraft 基岩版使用 LevelDB 数据库存储世界数据。玩家数据存储在 key 为 `~local_player` 的条目中，格式为 NBT 二进制数据。

本工具的工作原理：
1. 解压 `.mcworld` 文件（本质是 ZIP 压缩包）
2. 打开 `db/` 目录中的 LevelDB 数据库
3. 读取或写入 `~local_player` 数据
4. 重新打包为 `.mcworld` 文件

---

## 更新日志

### v1.0.0 (2024-12-16)
- 初始版本
- 支持提取和导入本地玩家数据
- 支持 .mcworld 文件格式