背包扩展与快捷栏

# 背包扩展与快捷栏 - 用户使用指南

## 📖 简介

**背包扩展与快捷栏** 是一个为《英灵神殿》(Valheim) 游戏设计的 BepInEx 模组，它提供了以下功能：

- ✅ **背包扩展**：在原版 4 行背包基础上添加额外的行数（最多 10 行）
- ✅ **快捷栏扩展**：在原版 8 个快捷栏槽位基础上添加额外的槽位（最多 8 个）
- ✅ **智能保护**：防止缩小背包时物品丢失
- ✅ **热更新支持**：大部分配置修改后保存即可生效，无需重启游戏
- ✅ **自定义UI**：可自定义扩展快捷栏的位置、大小、透明度、布局方向

> **🚨 重要警告**：如果减少背包大小（减少额外背包行数），而减少的行中存在物品，背包会乱码错乱！在减少背包行数之前，**必须先将减少的行中的所有物品移走或清空**。

---

## 🚀 安装方法

### 前置要求

1. **BepInEx** - 必须安装 BepInEx 框架
2. **游戏版本** - 支持最新版本的《英灵神殿》

### 安装步骤

1. 下载模组文件（`.dll` 文件）
2. 将 `.dll` 文件放入游戏的 `BepInEx/plugins/` 目录
3. 启动游戏，模组会自动加载
4. 首次运行后，会在 `BepInEx/config/` 目录生成配置文件：`com.HsgtLgt.BackpackAndHotbar.cfg`

---

## ⚙️ 配置文件说明

配置文件位置：`BepInEx/config/com.HsgtLgt.BackpackAndHotbar.cfg`

配置文件使用标准的 INI 格式，可以直接用文本编辑器打开修改。配置文件分为以下几个部分：

- `[快捷栏扩展]` - 快捷栏相关配置
- `[扩展快捷栏UI]` - 扩展快捷栏UI显示相关配置
- `[日志]` - 日志输出相关配置
- `[背包扩展]` - 背包扩展相关配置

---

## 📦 [背包扩展] 配置说明

### 额外背包行数

```ini
额外背包行数 = 6
```

- **类型**：整数 (Int32)
- **默认值**：`2`
- **取值范围**：`0-10`
- **说明**：在背包底部添加额外的行数。效果：背包会从默认的 4 行扩展到 (4+此值) 行。
  - 例如：设置为 `6`，背包会从 4 行扩展到 10 行
  - 设置为 `0`，背包保持原版 4 行不变
- **⚠️ 重要提示**：
  - 背包第二行（索引 1，即原版快捷栏下方的那一行）的格子会自动映射到扩展快捷栏槽位
  - 添加太多行可能会与箱子窗口重叠（建议开启"自动调整箱子位置"）
  - **🚨 严重警告**：**如果减少背包大小（减少额外背包行数），而减少的行中存在物品，背包会乱码错乱！**
    - 在减少背包行数之前，**必须先将减少的行中的所有物品移走或清空**
    - 例如：从 6 行减少到 2 行，第 5、6 行中的物品必须先移走
    - 否则背包界面会出现乱码、物品位置错乱等问题
- **热更新**：✅ 支持（修改后保存配置即可生效，无需重启游戏）

### 自动调整箱子位置

```ini
自动调整箱子位置 = true
```

- **类型**：布尔值 (Boolean)
- **默认值**：`true`
- **可选值**：`true` 或 `false`
- **说明**：当背包扩展时，是否自动向下移动箱子位置以避免与扩展的背包重叠。
  - `true` = 开启自动调整，箱子会随着额外背包行数自动向下移动
  - `false` = 关闭自动调整，箱子保持原位置不变
- **建议**：建议保持 `true`，避免箱子与扩展背包重叠
- **热更新**：✅ 支持

---

## ⌨️ [快捷栏扩展] 配置说明

### 快捷栏槽位数量

```ini
快捷栏槽位数量 = 8
```

- **类型**：整数 (Int32)
- **默认值**：`3`
- **取值范围**：`0-8`
- **说明**：要添加的扩展快捷栏槽位数量。效果：会在原版快捷栏(1-8)的基础上添加额外的槽位(9, 10, 11...)。这些槽位对应背包第二行的格子，将物品放入背包第二行即可在扩展快捷栏中使用。
  - 例如：设置为 `8`，会添加 8 个扩展槽位（槽位 9-16）
  - 设置为 `0`，不添加扩展槽位
- **映射关系**：
  - 扩展槽位 9 → 背包第二行第 1 列
  - 扩展槽位 10 → 背包第二行第 2 列
  - 扩展槽位 11 → 背包第二行第 3 列
  - 以此类推...
- **⚠️ 重要提示**：修改此配置后需要**重启游戏**才能生效
- **热更新**：❌ 不支持（必须重启游戏）

### 在HUD上显示快捷栏

```ini
在HUD上显示快捷栏 = true
```

- **类型**：布尔值 (Boolean)
- **默认值**：`true`
- **可选值**：`true` 或 `false`
- **说明**：是否在游戏HUD上显示扩展快捷栏UI。
  - `true` = 显示扩展快捷栏UI，会始终显示在屏幕上（即使不打开背包）
  - `false` = 隐藏扩展快捷栏UI，但快捷键功能仍然可用（可以通过快捷键使用背包第二行的物品）
- **使用场景**：
  - 如果觉得UI遮挡视线，可以设置为 `false` 隐藏UI
  - 即使隐藏UI，快捷键功能仍然完全可用
- **热更新**：✅ 支持

### 快捷栏快捷键配置

扩展快捷栏的每个槽位都可以自定义快捷键。快捷键格式为：`主键 + 修饰键`（如 `Q + LeftAlt` 表示 `Alt+Q`）。

#### 快捷栏 1 快捷键

```ini
快捷栏 1 快捷键 = Q + LeftAlt
```

- **类型**：键盘快捷键 (KeyboardShortcut)
- **默认值**：`Z + LeftAlt`（即 `Alt+Z`）
- **说明**：扩展快捷栏槽位 1（对应背包第二行第 1 列）的键盘快捷键。按下此快捷键时，会使用背包第二行第 1 列中的物品。
- **快捷键格式**：
  - 单个键：`Q`、`W`、`E` 等
  - 组合键：`Q + LeftAlt`（Alt+Q）、`Alpha1 + LeftShift`（Shift+1）等
  - 支持的修饰键：`LeftAlt`、`RightAlt`、`LeftShift`、`RightShift`、`LeftControl`、`RightControl`
- **热更新**：✅ 支持

#### 快捷栏 2-8 快捷键

```ini
快捷栏 2 快捷键 = W + LeftAlt
快捷栏 3 快捷键 = Alpha3 + LeftAlt
快捷栏 4 快捷键 = Alpha4 + LeftAlt
快捷栏 5 快捷键 = B + LeftAlt
快捷栏 6 快捷键 = N + LeftAlt
快捷栏 7 快捷键 = X
快捷栏 8 快捷键 = C
```

- **类型**：键盘快捷键 (KeyboardShortcut)
- **默认值**：
  - 快捷栏 2：`X + LeftAlt`（Alt+X）
  - 快捷栏 3：`C + LeftAlt`（Alt+C）
  - 快捷栏 4：`V + LeftAlt`（Alt+V）
  - 快捷栏 5：`B + LeftAlt`（Alt+B）
  - 快捷栏 6：`N + LeftAlt`（Alt+N）
  - 快捷栏 7：`Alpha1 + LeftAlt`（Alt+1）
  - 快捷栏 8：`Alpha2 + LeftAlt`（Alt+2）
- **说明**：扩展快捷栏槽位 2-8（对应背包第二行第 2-8 列）的键盘快捷键。
- **快捷键示例**：
  - `Q` = 单独按 Q 键
  - `Q + LeftAlt` = Alt+Q
  - `Alpha1 + LeftShift` = Shift+1
  - `F + LeftControl` = Ctrl+F
- **热更新**：✅ 支持

---

## 🎨 [扩展快捷栏UI] 配置说明

### 位置X

```ini
位置X = 800
```

- **类型**：浮点数 (Single)
- **默认值**：`300`
- **说明**：扩展快捷栏UI在屏幕上的X坐标位置（像素）。效果：控制扩展快捷栏的水平位置。
- **坐标系统**：
  - 屏幕左上角为原点 `(0, 0)`
  - X 值增加 = 向右移动
  - X 值减少 = 向左移动
- **建议值**：`300-500`（在原版快捷栏右侧）
- **实际示例**：设置为 `800` 时，UI 会显示在屏幕右侧
- **热更新**：✅ 支持

### 位置Y

```ini
位置Y = 900
```

- **类型**：浮点数 (Single)
- **默认值**：`50`
- **说明**：扩展快捷栏UI在屏幕上的Y坐标位置（像素）。效果：控制扩展快捷栏的垂直位置。
- **坐标系统**：
  - 屏幕左上角为原点 `(0, 0)`
  - Y 值增加 = 向下移动
  - Y 值减少 = 向上移动
- **建议值**：`50-100`（与原版快捷栏同一水平线）
- **实际示例**：设置为 `900` 时，UI 会显示在屏幕下方
- **热更新**：✅ 支持

### 宽度

```ini
宽度 = 0
```

- **类型**：浮点数 (Single)
- **默认值**：`80`
- **说明**：扩展快捷栏UI容器的宽度（像素）。效果：控制整个扩展快捷栏UI容器的水平宽度。
- **⚠️ 注意**：这是容器的大小，不是单个槽位的大小。
- **建议值**：
  - **横向布局**：宽度 = 槽位大小 × 槽位数量 + 间距
    - 例如：槽位大小 80，8 个槽位，建议宽度约 `80 × 8 + 20 = 660`
  - **纵向布局**：宽度 = 槽位大小 + 边距（约 `80 + 20 = 100`）
- **实际示例**：设置为 `0` 时，容器宽度会自动适应内容
- **热更新**：✅ 支持

### 高度

```ini
高度 = 500
```

- **类型**：浮点数 (Single)
- **默认值**：`400`
- **说明**：扩展快捷栏UI容器的高度（像素）。效果：控制整个扩展快捷栏UI容器的垂直高度。
- **⚠️ 注意**：这是容器的大小，不是单个槽位的大小。
- **建议值**：
  - **横向布局**：高度 = 槽位大小 + 边距（约 `80 + 20 = 100`）
  - **纵向布局**：高度 = 槽位大小 × 槽位数量 + 间距
    - 例如：槽位大小 80，8 个槽位，建议高度约 `80 × 8 + 20 = 660`
- **实际示例**：设置为 `500` 时，容器高度为 500 像素
- **热更新**：✅ 支持

### 槽位大小

```ini
槽位大小 = 80
```

- **类型**：浮点数 (Single)
- **默认值**：`70`
- **说明**：每个扩展快捷栏槽位的尺寸（像素）。效果：控制单个槽位的宽度和高度（正方形，长宽相同）。
- **建议值**：`70`（与原版快捷栏槽位大小一致）
- **实际示例**：设置为 `80` 时，每个槽位为 80×80 像素
- **热更新**：✅ 支持

### 背景透明度

```ini
背景透明度 = 0.649
```

- **类型**：浮点数 (Single)
- **默认值**：`0.1`
- **取值范围**：`0.0-1.0`
- **说明**：扩展快捷栏槽位背景的透明度。效果：控制每个槽位背景的可见程度。
- **透明度说明**：
  - `0.0` = 完全透明（无背景，完全看不见背景）
  - `1.0` = 完全不透明（深灰色背景，完全不透明）
  - `0.1` = 90%透明（默认值，轻微可见，几乎透明）
  - `0.649` = 约 35%透明（实际示例，背景较为明显）
- **使用建议**：
  - 想要几乎看不见背景：设置为 `0.0-0.2`
  - 想要轻微可见的背景：设置为 `0.1-0.3`
  - 想要明显的背景：设置为 `0.5-1.0`
- **热更新**：✅ 支持

### 横向布局

```ini
横向布局 = true
```

- **类型**：布尔值 (Boolean)
- **默认值**：`false`
- **可选值**：`true` 或 `false`
- **说明**：扩展快捷栏槽位的排列方向。效果：控制槽位的排列方式。
- **布局说明**：
  - `true` = **横向排列**（槽位从左到右水平排列）
    - 适合放在原版快捷栏下方或右侧
    - 例如：8 个槽位会排成一行：`[1] [2] [3] [4] [5] [6] [7] [8]`
  - `false` = **纵向排列**（槽位从上到下垂直排列）
    - 适合放在原版快捷栏右侧
    - 例如：8 个槽位会排成一列：
      ```
      [1]
      [2]
      [3]
      [4]
      [5]
      [6]
      [7]
      [8]
      ```
- **实际示例**：设置为 `true` 时，槽位横向排列
- **热更新**：✅ 支持

---

## 📝 [日志] 配置说明

### 启用日志输出

```ini
启用日志输出 = false
```

- **类型**：布尔值 (Boolean)
- **默认值**：`true`
- **可选值**：`true` 或 `false`
- **说明**：是否输出本 Mod 的日志消息。关闭后将不再输出 Info/Warning/Error/Debug。
- **使用场景**：
  - `true` = 开启日志输出，可以在日志文件中查看模组运行信息
  - `false` = 关闭日志输出，减少日志文件大小（实际示例中已关闭）
- **日志文件位置**：`BepInEx/LogOutput.log`
- **建议**：正常使用时可以关闭，排查问题时开启
- **热更新**：✅ 支持

### 启用调试日志

```ini
启用调试日志 = false
```

- **类型**：布尔值 (Boolean)
- **默认值**：`false`
- **可选值**：`true` 或 `false`
- **说明**：是否输出本 Mod 的调试日志（Debug）。建议平时关闭，仅在排查问题时开启。
- **使用场景**：
  - `true` = 开启调试日志，会输出详细的调试信息（可能很冗长）
  - `false` = 关闭调试日志（默认值，实际示例中已关闭）
- **建议**：仅在排查问题时开启，平时保持关闭
- **热更新**：✅ 支持

---

## 🎮 使用方法

### 背包扩展使用

1. **设置额外行数**：
   - 打开配置文件 `com.HsgtLgt.BackpackAndHotbar.cfg`
   - 找到 `[背包扩展]` 部分
   - 修改 `额外背包行数 = 6`（根据你的需求设置 0-10）
   - **🚨 重要警告**：如果要**减少**背包行数，必须先清空减少的行中的所有物品，否则背包会乱码错乱！
   - 保存配置文件
   - 游戏会自动应用更改（热更新，无需重启）

2. **使用扩展背包**：
   - 打开背包界面（按 `Tab` 键）
   - 你会看到背包底部增加了额外的行数
   - 可以直接在这些扩展行中放置物品
   - **注意**：背包第二行（索引 1）的格子会自动映射到扩展快捷栏槽位

3. **自动调整箱子位置**：
   - 如果开启 `自动调整箱子位置 = true`，箱子会自动向下移动，避免与扩展背包重叠
   - 如果关闭，可能需要手动调整箱子位置

### 快捷栏扩展使用

1. **设置槽位数量**（需要重启游戏）：
   - 打开配置文件
   - 找到 `[快捷栏扩展]` 部分
   - 修改 `快捷栏槽位数量 = 8`（根据你的需求设置 0-8）
   - **⚠️ 重要**：修改此配置后需要**重启游戏**才能生效

2. **使用扩展快捷栏**：
   - 打开背包界面
   - 将物品放入背包**第二行**（索引 1，即原版快捷栏下方的那一行）
   - 第二行的第 1 列对应扩展槽位 9，第 2 列对应扩展槽位 10，以此类推
   - 按下对应的快捷键即可使用物品
   - **映射关系**：
     - 背包第二行第 1 列 → 扩展槽位 9 → 快捷键（如 `Alt+Q`）
     - 背包第二行第 2 列 → 扩展槽位 10 → 快捷键（如 `Alt+W`）
     - 背包第二行第 3 列 → 扩展槽位 11 → 快捷键（如 `Alt+3`）
     - 以此类推...

3. **自定义快捷键**：
   - 打开配置文件
   - 找到 `快捷栏 1 快捷键`、`快捷栏 2 快捷键` 等配置项
   - 修改为你喜欢的快捷键组合
   - 快捷键格式：`主键 + 修饰键`（如 `Q + LeftAlt` 表示 `Alt+Q`）
   - 保存配置文件即可生效（热更新）

4. **显示/隐藏UI**：
   - 设置 `在HUD上显示快捷栏 = true` 显示UI
   - 设置 `在HUD上显示快捷栏 = false` 隐藏UI
   - 即使隐藏UI，快捷键功能仍然完全可用

### 自定义扩展快捷栏UI

1. **调整位置**：
   - 修改 `位置X` 和 `位置Y` 配置项
   - 坐标系统：屏幕左上角为原点 `(0, 0)`
   - X 值增加向右移动，Y 值增加向下移动
   - 建议先设置为默认值，然后在游戏中观察位置，再逐步调整

2. **调整大小**：
   - 修改 `宽度`、`高度` 和 `槽位大小` 配置项
   - 根据你的槽位数量和布局方向来调整
   - 横向布局时，宽度需要更大；纵向布局时，高度需要更大

3. **调整透明度**：
   - 修改 `背景透明度` 配置项（0.0-1.0）
   - 值越小越透明，值越大越不透明
   - `0.0` = 完全透明，`1.0` = 完全不透明

4. **切换布局方向**：
   - 修改 `横向布局` 配置项
   - `true` = 横向排列（从左到右），`false` = 纵向排列（从上到下）

---

## ⚠️ 重要注意事项

### 背包扩展

1. **物品映射关系**：
   - 背包第二行（索引 1）的格子会自动映射到扩展快捷栏槽位
   - 第二行第 1 列 → 扩展槽位 9
   - 第二行第 2 列 → 扩展槽位 10
   - 以此类推
   - **因此，第二行主要用于扩展快捷栏，建议不要在这里存放普通物品**

2. **缩小背包保护**：
   - **🚨 严重警告**：**如果减少背包大小（减少额外背包行数），而减少的行中存在物品，背包会乱码错乱！**
   - 在减少背包行数之前，**必须先将减少的行中的所有物品移走或清空**
   - 例如：从 6 行减少到 2 行，第 5、6 行中的物品必须先移走
   - 否则背包界面会出现乱码、物品位置错乱等问题
   - 当缩小背包行数时，如果扩展行中有物品，模组会尝试自动迁移物品
   - 如果保留区域空间不足，模组会阻止缩小并恢复到原值
   - **强烈建议在缩小前先清空扩展行，避免出现乱码错乱问题**

3. **箱子位置**：
   - 建议开启 `自动调整箱子位置 = true`，避免箱子与扩展背包重叠
   - 如果关闭此选项，可能需要手动调整箱子位置

### 快捷栏扩展

1. **槽位映射**：
   - 扩展槽位 9-16 对应背包第二行的第 1-8 列
   - **只有放入背包第二行的物品才能通过扩展快捷栏使用**

2. **快捷键冲突**：
   - 默认快捷键使用 `Alt` 组合键，通常不会与游戏内快捷键冲突
   - 如果遇到冲突，可以在配置文件中修改快捷键
   - 快捷键格式：`主键 + 修饰键`（如 `Q + LeftAlt`）

3. **重启要求**：
   - **修改 `快捷栏槽位数量` 后需要重启游戏才能生效**
   - 其他配置项支持热更新，修改后保存即可生效

### 兼容性

1. **其他模组**：
   - 本模组使用 Harmony 补丁，可能与修改背包或快捷栏的其他模组冲突
   - 如果遇到问题，请检查是否有其他模组也在修改相同功能

2. **存档兼容性**：
   - 本模组完全兼容原版存档
   - 如果卸载模组，扩展行的物品可能会丢失（建议卸载前先清空扩展行）

---

## 🐛 常见问题

### Q1: 修改配置后没有生效？

**A:** 
- 检查是否保存了配置文件
- 大部分配置支持热更新，保存后即可生效
- **`快捷栏槽位数量` 需要重启游戏才能生效**
- 如果仍然无效，尝试重启游戏

### Q2: 扩展快捷栏UI不显示？

**A:**
- 检查 `在HUD上显示快捷栏` 配置是否为 `true`
- 检查 `快捷栏槽位数量` 是否大于 0
- 检查UI位置是否在屏幕可见范围内（`位置X` 和 `位置Y`）
- 尝试调整 `位置X` 和 `位置Y` 配置项

### Q3: 快捷键不工作？

**A:**
- 检查快捷键配置是否正确（格式：`主键 + 修饰键`）
- **确保物品已放入背包第二行（索引 1）**
- 检查快捷键是否与其他模组或游戏内快捷键冲突
- 尝试重新设置快捷键

### Q4: 缩小背包时出现乱码错乱或物品丢失？

**A:**
- **🚨 严重警告**：如果减少背包大小（减少额外背包行数），而减少的行中存在物品，背包会乱码错乱！
- **解决方法**：在减少背包行数之前，**必须先将减少的行中的所有物品移走或清空**
- 例如：从 6 行减少到 2 行，第 5、6 行中的物品必须先移走
- 模组有自动保护机制，会尝试迁移物品
- 如果保留区域空间不足，模组会阻止缩小
- **强烈建议在缩小前先清空扩展行，避免出现乱码错乱问题**

### Q5: 箱子与背包重叠？

**A:**
- 开启 `自动调整箱子位置 = true` 配置项
- 或者减少 `额外背包行数`
- 或者手动调整箱子位置

### Q6: 如何查看日志？

**A:**
- 日志文件位置：`BepInEx/LogOutput.log`
- 确保 `启用日志输出` 配置为 `true`
- 如果需要详细调试信息，可以开启 `启用调试日志`

### Q7: 快捷键格式怎么写？

**A:**
- 单个键：`Q`、`W`、`E`、`Alpha1`（数字1）、`Alpha2`（数字2）等
- 组合键：`Q + LeftAlt`（Alt+Q）、`Alpha1 + LeftShift`（Shift+1）等
- 支持的修饰键：`LeftAlt`、`RightAlt`、`LeftShift`、`RightShift`、`LeftControl`、`RightControl`
- 示例：
  - `Q + LeftAlt` = Alt+Q
  - `Alpha1 + LeftShift` = Shift+1
  - `F + LeftControl` = Ctrl+F

---

## 📚 技术信息

- **模组名称**：背包扩展与快捷栏
- **模组ID**：`com.HsgtLgt.BackpackAndHotbar`
- **版本**：`1.0.0`
- **框架**：BepInEx + Harmony
- **游戏**：英灵神殿 (Valheim)

---

## 📞 获取帮助

如果遇到问题或需要帮助，可以：

1. 查看日志文件：`BepInEx/LogOutput.log`（需要开启 `启用日志输出`）
2. 检查配置文件是否正确
3. 尝试禁用其他模组，排查冲突
4. 查看项目文档或联系模组作者

---

## 📝 配置示例

以下是一个完整的配置示例，展示了所有配置项的设置：

```ini
[快捷栏扩展]
快捷栏槽位数量 = 8
在HUD上显示快捷栏 = true
快捷栏 1 快捷键 = Q + LeftAlt
快捷栏 2 快捷键 = W + LeftAlt
快捷栏 3 快捷键 = Alpha3 + LeftAlt
快捷栏 4 快捷键 = Alpha4 + LeftAlt
快捷栏 5 快捷键 = B + LeftAlt
快捷栏 6 快捷键 = N + LeftAlt
快捷栏 7 快捷键 = X
快捷栏 8 快捷键 = C

[扩展快捷栏UI]
位置X = 800
位置Y = 900
宽度 = 0
高度 = 500
槽位大小 = 80
背景透明度 = 0.649
横向布局 = true

[日志]
启用日志输出 = false
启用调试日志 = false

[背包扩展]
额外背包行数 = 6
自动调整箱子位置 = true
```

---

**祝您游戏愉快！** 🎮