ValheimChestSort

ValheimChestSort

給箱子加一個「一鍵整理」：打開任意容器（箱子、推車等），點擊容器界面裏 「物品堆疊」按鈕左側的「整理」按鈕，

（或按快捷鍵 R），箱內物品立刻被 合併零散堆疊 並 按類別 / 名稱重新排布，去掉空格，整整齊齊。

只重新擺放箱子裏已有的物品，不移動、不丟棄、不改動任何物品的屬性或數量（總數守恆）。

功能

• 界面按鈕：在容器界面的原版「物品堆疊」按鈕左邊，自動添加一個「整理」按鈕（克隆原按鈕製作，

外觀 / 字體 / 過渡動畫與遊戲一致）。中文界面顯示「整理」，其他語言顯示「Sort」，也可在配置中自定義。

• 快捷鍵：打開容器後按 R（可配置），與按鈕功能相同。
• 合併堆疊：同種物品的零散堆疊會自動補滿（例如 3 個 50/50 的木炭合成 1 個 50 + 1 個 100）。

只合並「名稱 + 品質 + 世界等級 + 變體 + 自定義數據」完全一致的物品。

• 按類別排序：默認順序爲 材料 → 消耗品 → 彈藥 → 武器 → 盾牌 → 護甲 → 工具/雜項，同類再按名稱、

品質從高到低排列。

• 去掉空格：整理後物品從左上角開始逐行緊湊排列，不再有空檔。
• 對箱子、推車等所有使用遊戲 Container 組件的容器都有效。
• 關閉 / 不點擊時完全是原版行爲，不影響任何原版操作。

操作

| 按鍵 / 按鈕 | 作用 |

| --- | --- |

| 「整理」按鈕 | 容器界面中、原版「物品堆疊」按鈕左側，點擊即整理當前箱子 |

| R | 整理當前打開的箱子（默認快捷鍵，可在配置中修改） |

用法：走到箱子前按 E 打開 → 點擊「整理」按鈕（或按 R）→ 箱子自動整理好 → 按 Esc 關閉。

整理時若手裏正拖着物品，會提示先放下，避免誤操作。

安裝

方式一：r2modman Mod Manager（推薦）

• 已在 上架：在 mod 管理器裏搜索 ValheimChestSort 安裝即可（會自動帶入 BepInEx 依賴）。
• 本地包導入：下載本倉庫 dist/ 下的 SuperVikingDepartment-ValheimChestSort-1.0.0.zip，在 r2modman 中

Settings → Import local mod（或 Install from file）選擇該 zip。

方式二：手動安裝（直接啓動遊戲）

• 先安裝 BepInExPack for Valheim（denikson-BepInExPack_Valheim）。
• 把 ValheimChestSort.dll 放入遊戲根目錄的 BepInEx/plugins/。
• 啓動遊戲。

注意：用 r2modman 啓動遊戲時，生效的是 profile 目錄，而不是遊戲安裝根目錄下的 BepInEx。

配置

首次啓動後生成 BepInEx/config/SuperVikingDepartment.ValheimChestSort.cfg：

| 配置項 | 默認值 | 說明 |

| --- | --- | --- |

| SortKey | R | 整理快捷鍵。填 KeyCode 名稱（R、T、B、LeftAlt、Mouse3 等）。 |

| SortMode | Category | Category = 先類別後名稱；Name = 直接按名稱排。 |

| MergeStacks | true | 是否合併零散堆疊。 |

| AddButton | true | 是否在箱子界面「物品堆疊」按鈕左邊添加「整理」按鈕。 |

| ButtonLabel | （空） | 「整理」按鈕上的文字。留空 = 自動：中文界面「整理」，其他語言「Sort」。 |

| DebugLogging | false | 輸出整理細節日誌，用於排查。 |

改完需重啓遊戲。

會不會影響成就

不會。本 mod 不設置 Game.isModded、不觸碰人物的 m_usedCheats、不給物品打作弊標記，

只是重新擺放箱內已有物品並觸發原版的「物品變更」流程，不產生新物品、不改變數量。

兼容性

• 遊戲版本：Unity 6 時期的 Valheim。
• 依賴：BepInEx 5.x（HarmonyX 隨 BepInEx 自帶）。
• 不與「一鍵裝滿 / 一鍵種田」等功能衝突。
• 單一熱鍵、不佔用原版按鈕；如與其它 mod 的按鍵衝突，改 SortKey 即可。

工作原理（簡述）

• 打開容器時，遊戲會把該容器的 ZDO 所有權移交給打開的玩家（Container.RPC_RequestOpen），

因此本地對容器的改動會被 Container.Save() 寫回 ZDO 並同步給其他玩家。

• 「整理」按鈕通過 克隆原版「物品堆疊」按鈕 生成：外觀、字體、過渡動畫沿用原版，無需自帶貼圖與字體；

若按鈕所在父節點帶佈局組，按鈕靠兄弟順序自動排到原按鈕左側，否則由一個輕量組件每幀按相對位置對齊。

• 本 mod 通過反射取到當前打開的容器（InventoryGui.m_currentContainer），對其 Inventory 做：

合併堆疊 → 排序 → 按行優先重設每件物品的 m_gridPos，最後調用一次原版 Inventory.Changed()

刷新界面並觸發存盤。整個過程是原版數據結構的重排，不繞過任何遊戲邏輯。

從源碼構建

• 安裝.NET SDK（目標 netstandard2.1）與 Node.js（打包腳本用）。
• 把本倉庫克隆到 Valheim 安裝目錄下（默認假定.. 就是遊戲根目錄）。
• 遊戲根目錄需已安裝 BepInEx（BepInEx/core/BepInEx.dll、BepInEx/core/0Harmony.dll）。
• 構建並生成發佈包：./build-package.sh 你的ThunderstoreTeam名

產物：dist/你的Team名-ValheimChestSort-版本號.zip

倉庫不在遊戲目錄下時，用屬性覆蓋路徑：

dotnet build -c Release -p:ValheimDir="C:\Steam\steamapps\common\Valheim\"

上傳到

• 運行./build-package.sh SuperVikingDepartment 生成 dist/SuperVikingDepartment-ValheimChestSort-1.0.0.zip。
• 打開，登錄後選擇該 zip 上傳。

zip 內容（ 要求）：

manifest.json 包元數據

README.md 商店頁正文

CHANGELOG.md 更新日誌

icon.png 256x256 圖標

LICENSE 許可證

plugins/ValheimChestSort.dll ← 會自動路由到 BepInEx/plugins/

倉庫結構：

ChestSortPlugin.cs 插件源碼

ValheimChestSort.csproj 項目文件

manifest.json 元數據

README.md / CHANGELOG.md / LICENSE

icon.png 圖標（256x256）

build-package.sh 一鍵構建 + 打包

tools/zip.js 無依賴 ZIP 打包器（保證 zip 內爲正斜槓路徑）

tools/make-icon.js 重新生成 icon.png

已知問題 / 說明

• 修改按鍵或開關插件後需要重啓遊戲，無法熱插拔。
• 若按鍵無效，把 BepInEx/LogOutput.log 發到問題區。加載成功會有 ValheimChestSort loaded 一行。
• 整理是「就地重排」，不會把玩家背包裏的物品放進箱子；只整理當前打開的那個容器。

來源與許可

MIT License，詳見倉庫內 LICENSE。