Orange - Mapshot 插件詳解
作者： Hudell (www.hudell.com)
版本： 1.7
授權： 免費供商業及非商業用途使用
一、插件概述
Orange - Mapshot 插件主要功能是在玩家於 RPG Maker MV 的地圖畫面中按下指定按鍵時，自動截取整個地圖的圖片（Mapshot），並將截圖儲存到預設或自訂的資料夾中。此功能方便開發者保存遊戲地圖畫面，作為測試、記錄或製作宣傳素材之用。
二、主要功能
- 地圖截圖觸發：玩家按下設定的按鍵（預設 keyCode 為 44，通常為 Print Screen 鍵）時，自動截取目前地圖畫面。
- 多種圖層模式：
- 0（所有）： 將所有圖層合併成一張圖片。
- 1（upper and lower）： 分別生成下層與上層圖片。
- 2（分離所有事物）： 分別生成地面、第二層、陰影以及事件等多張圖片。
- 自訂圖片格式與品質：可選擇輸出的圖片格式（png、jpeg、webp）並設定 JPEG 或 WebP 格式的圖片品質（0～100）。
- 使用地圖名稱作為檔名：可選擇啟用，生成的截圖檔名將以地圖名稱命名；否則，則以預設編號（例如 Map001）作為檔名。
- 可選擇性繪製陰影與事件：透過參數控制是否在截圖中包含自動生成的陰影效果與地圖上事件的圖像。
三、插件參數詳解
| 參數名稱 | 說明 | 預設值 |
|---|---|---|
| 使用地圖名稱 | 若設為 true，檔案名稱將以地圖名稱命名；否則以預設編號命名。 | true |
| 圖層類型 | 決定截圖模式：0 = 合併所有圖層，1 = 分離上層與下層，2 = 分離所有項目。 | 0 |
| 繪製自動陰影 | 是否在截圖中包含自動生成的陰影效果。 | true |
| 繪製事件 | 是否將地圖中的事件（非玩家角色）也繪製到截圖中。 | true |
| 鍵盤碼 | 觸發截圖所使用的鍵盤代碼（例如 44 表示 Print Screen 鍵）。 | 44 |
| 圖片類型 | 輸出圖片格式，可選 png、jpeg 或 webp。 | png |
| 圖片品質 | 適用於 jpeg 或 webp 格式，表示圖片品質（0～100）。 | 70 |
| 圖片路徑 | 截圖儲存的資料夾路徑。 | ./Mapshots |
四、內部運作機制
1. 參數讀取與初始化
插件根據描述字串 <OrangeMapshot> 自動讀取設定參數，並將其儲存在 $.Parameters 與 $.Param 物件中。依據圖片格式參數，插件也定義了輔助函數來設定 MIME 類型、檔案副檔名、圖片品質以及 Base64 處理所需的正則表達式。
2. 地圖截圖生成流程
- 取得檔名：透過
$.baseFileName()函數，依據「使用地圖名稱」參數決定檔名格式（地圖名稱或預設編號）。 - 截圖生成：
- 若圖層類型為 0，調用
Tilemap._paintEverything方法，生成合併所有圖層的 Bitmap。 - 若圖層類型為 1，分別生成下層與上層圖片。
- 若圖層類型為 2，分別生成地面、第二層、陰影與各類事件圖片。
- 若圖層類型為 0，調用
- Tilemap 擴充與重載：插件重新定義並擴充了 Tilemap 中的多個方法（如
_drawAutotile、_drawNormalTile、_drawTableEdge等），以正確截取所有地圖細節。
3. 儲存截圖
檔案儲存：函數 $.saveMapshot() 檢查是否運行於 NW.js 環境，利用 Node.js 的 fs 模組建立目標資料夾，並將 Bitmap 物件轉換為 Base64 格式，再以 fs.writeFile 方法寫入檔案。
多檔儲存：根據圖層類型不同，會產生一個或多個檔案，並依照檔名規則標註各層（如 Lower、Upper、Shadows、Events 等）。
儲存完成後，若使用 Windows 平台且未曾自動開啟資料夾，插件會自動打開儲存目錄；否則，會在遊戲內提示截圖儲存位置。
4. 按鍵觸發
插件監聽全域 keyup 事件，當使用者按下設定的鍵盤碼（預設 44）時，若當前場景為地圖場景（Scene_Map），則自動觸發截圖儲存流程。
五、使用方法
- 插件安裝：
- 將
OrangeMapshot.js放入 RPG Maker MV 專案的js/plugins/資料夾中。 - 在 RPG Maker MV 的插件管理器中新增並啟用此插件。
- 將
- 參數設定：
- 根據需求修改各項參數，例如：是否使用地圖名稱、選擇圖層類型、是否繪製陰影與事件、設定按鍵代碼、圖片格式、品質與儲存路徑。
- 運行遊戲並截圖：
- 進入地圖場景後，按下設定的截圖按鍵（例如 Print Screen），插件會自動截取地圖畫面並儲存至指定資料夾。
- 截圖完成後，系統會提示儲存位置，或直接打開儲存資料夾（Windows 平台下）。
六、技術詳解
1. 內部結構
- 參數處理模組：利用描述標記
<OrangeMapshot>讀取並儲存設定參數，供後續函數調用。 - 圖片生成與格式處理：根據使用者設定定義輔助函數，決定 MIME 類型、檔案副檔名、圖片品質及 Base64 處理。
- 地圖資料整合：利用 Tilemap 的方法取得地圖所有圖塊、事件與陰影資料，並分層繪製至 Bitmap 物件中。
- 檔案系統操作：使用 NW.js 提供的 Node.js 模組（fs、path、child_process）進行檔案目錄創建、檔案寫入及自動開啟儲存目錄。
2. 擴充與重載
為了正確截取地圖所有細節，插件重新定義了部分 Tilemap 的繪圖方法（包括自動圖塊、一般圖塊與特殊邊緣處理），以確保截圖結果與遊戲畫面一致。
七、版本資訊與授權
版本： 1.7
作者： Hudell
授權： 免費供商業及非商業用途使用
參考網址： www.hudell.com
總結來說，Orange - Mapshot 插件是一個功能強大且彈性十足的地圖截圖工具，無論是用於遊戲測試、地圖美術存檔或宣傳素材製作，都能提供非常實用的功能。透過簡單的按鍵觸發與細緻的參數設定，使用者可以輕鬆獲得多層次、多格式的地圖截圖。
