# DECKY-BOTW-SAVE-PLUGIN

**Repository Path**: netsesame/decky_botw_save_plugin

## Basic Information

- **Project Name**: DECKY-BOTW-SAVE-PLUGIN
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-23
- **Last Updated**: 2026-06-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BOTW Save Editor - Decky Loader Plugin

为 Steam Deck 设计的《塞尔达传说：旷野之息》存档编辑器。在游戏模式下直接修改存档，无需退出游戏。

## ✨ 功能特性

### 🎮 控制器友好设计
- 大按钮设计，适配触控板和手柄操作
- 预设值快速选择，无需键盘输入
- 一键操作：全满状态、收集全部克洛格等
- 手柄按键映射：肩键切换 Tab，方向键导航

### 📦 核心功能
- **基础数值修改**：卢比、普拉古、血量、体力
- **物品管理**：武器、弓箭、盾牌、服装、素材、食物
- **马匹编辑**：类型、名称、马鞍、缰绳
- **收集进度**：克洛格种子、击败敌人计数
- **地图探索**：解锁全部地图、添加地图标记

### 💾 备份管理
- 自动备份：保存修改前自动创建备份
- 手动备份：随时创建存档备份
- 一键恢复：从备份列表快速恢复
- 备份清理：自动保留最近 10 个备份

## 📋 支持的存档来源

- **Ryujinx** (Switch 模拟器)
- **Sudachi** (Ryujinx 分支)
- **Yuzu** (Switch 模拟器)
- **Eden** (Switch 模拟器)
- **Cemu** (Wii U 模拟器)
- 自定义路径（通过配置文件）

## 🚀 安装

### 通过 Decky Plugin Store（推荐）
1. 打开 Steam Deck 游戏模式
2. 进入 Decky Loader 插件商店
3. 搜索 "BOTW Save Editor"
4. 点击安装

### 手动安装
1. 克隆此仓库：
   ```bash
   git clone https://github.com/your-repo/decky-botw-editor.git
   ```

2. 构建插件：
   ```bash
   cd decky-botw-editor
   npm install
   npm run build
   ```

3. 复制到 Decky 插件目录，或安装 `build/decky-botw-editor.zip`：
   ```bash
   cp -r build/decky-botw-editor ~/homebrew/plugins/
   ```

4. 重启 Decky 或 Steam Deck

## 🔧 使用说明

### 基本操作
1. 从 Steam 游戏库启动插件
2. 插件会自动检测最新存档
3. 使用 Tab 栏切换不同编辑区域
4. 修改数值后点击 "💾 保存修改"
5. 原存档会自动备份

### 按键操作
| 按键 | 功能 |
|------|------|
| `LB` / `RB` | 切换 Tab |
| `LT` / `RT` | 翻页 |
| `A` | 确认/编辑 |
| `B` | 取消/返回 |
| `X` | 备份管理 |
| `Y` | 保存修改 |
| `方向键` | 列表导航 |

### 一键操作
- ⭐ **全满状态**：卢比、普拉古、血量、体力全满
- 🌰 **收集全部克洛格**：设置为 900 个
- 🗺️ **解锁全部地图**：显示所有地图区域
- 🏆 **100%完成度**：综合完成度设置

## 📁 文件结构

```
decky-botw-editor/
├── main.py                 # Decky 插件入口
├── plugin.json             # 插件元数据
├── package.json            # 前端依赖
├── LICENSE                 # 许可证
├── tsconfig.json           # TypeScript 配置
├── rollup.config.js        # 构建配置
├── lib/                    # Python 后端
│   ├── backup.py           # 备份管理器
│   └── paths.py            # 路径检测
├── src/                    # React 前端
│   ├── index.tsx           # 主入口
│   └── styles/
│       └── deck-ui.css     # 样式文件
└── build/                  # 构建输出
    ├── decky-botw-editor/  # Decky 插件目录
    │   ├── plugin.json
    │   ├── package.json
    │   ├── main.py
    │   ├── lib/
    │   └── dist/           # Decky 前端 bundle
    │       ├── index.js
    │       ├── styles.css
    │       └── editor/     # 原版编辑器静态资源
    └── decky-botw-editor.zip
```

## 🔬 技术实现

### 存档解析
基于哈希表定位数据，而非固定偏移：
- 每个数据项有 32 位哈希标识
- 支持多个游戏版本（v1.0 - v1.8）
- 自动检测 Wii U/Switch 格式（大小端序）

### 备份策略
- 每次保存前自动备份
- 备份存储：`~/homebrew/data/decky-botw-editor/backups/`
- 备份命名：`backup_YYYYMMDD_HHMMSS_game_data.sav`

## ⚙️ 配置

### 自定义存档路径
创建配置文件，路径指向游戏 Title ID 目录的上一级。插件会按来源自动补全 BOTW Title ID，并读取固定槽位 `0` 到 `5` 下的 `game_data.sav`。
```bash
mkdir -p ~/homebrew/settings/decky-botw-editor
cat > ~/homebrew/settings/decky-botw-editor/settings.json <<'JSON'
{
  "sources": {
    "eden": "/path/to/eden/nand/user/save/0000000000000000/profile-id"
  }
}
JSON
```
如果某个来源未配置，可在插件面板中选择该模拟器并点击“扫描当前来源”。目前预设扫描目录：
- Eden: `/home/deck/.local/share/eden`
- Cemu: `/home/deck/.local/share/Cemu`

### 备份设置
备份目录默认位于 `~/homebrew/data/decky-botw-editor/backups/`。

## 🐛 故障排除

### 未找到存档
- 确认游戏已运行并创建存档
- 检查模拟器存档路径是否正确
- 手动添加路径到配置文件

### 保存失败
- 检查存档文件权限
- 查看 `~/homebrew/logs/decky-botw-editor/` 中的日志
- 尝试从备份恢复

### 插件未加载
- 确认 Decky Loader 已安装
- 检查 `~/homebrew/plugins/` 目录
- 重启 Steam Deck

## 📝 开发

### 环境要求
- Node.js 18+
- Python 3.10+
- Decky Loader 开发环境

### 开发模式
```bash
# 前端热重载
npm run watch

# 浏览器 mock 预览（不需要 Decky 环境）
npm run mock:serve

# 后端调试
python -m debugpy --listen 5678 main.py
```

打开 `http://localhost:4173/mock.html` 可使用 mock 存档数据测试侧边栏、全屏编辑器、保存、备份和恢复流程。mock 数据只存在于浏览器会话内，不会读写真实存档。

### 构建发布
```bash
npm run build
# 输出到 build/decky-botw-editor/ 并生成 build/decky-botw-editor.zip
```

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License

## ⚠️ 免责声明

使用本工具修改存档有一定风险，可能导致存档损坏。请定期备份您的存档。使用本工具即表示您自行承担风险。

## 🔗 相关链接

- [Decky Loader](https://decky.xyz/)
- [BOTW Save Editor (Web 版)](https://github.com/marcrobledo/savegame-editors)
- [Steam Deck 文档](https://www.steamdeck.com/)