244 lines
5.5 KiB
Markdown
244 lines
5.5 KiB
Markdown
# 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 文件格式
|