§1 引言

原版模組指在不修改 Minecraft 游戲本體的前提下，通過命令方塊、一鍵命令、數(shù)據(jù)包、資源包等方式對游戲的可玩性做出修改。之所以稱之為原版模組，乃是為了和使用 Mod Loader/API 環(huán)境基于 Java 開發(fā)的 Mod 作區(qū)分，這些 Mod Loader/API 包括 Forge，Liteloader，F(xiàn)abric 等。自 Minecraft Java 版 1.13 起的數(shù)據(jù)包概念問世之后，原版模組的制作已變得十分便捷。本文內的原版模組便是指利用數(shù)據(jù)包和可能的配套資源包對游戲的可玩性做出修改。

本文內容適用于 Minecraft Java 版 1.19 版本，但大部分內容也適合 1.13-1.18 版本，或只需要做簡單修改，請讀者自行區(qū)分。系統(tǒng)環(huán)境為 Windows 10，其它環(huán)境下有較小的差異。本文參考和吸取了大量其他玩家的意見、建議和教程等，無法一一列出，在此一并表示感謝。

本文更側重教程而非開發(fā)手冊，因此很多內容的完整格式并沒有列出，此時請讀者自行查閱相關的 wiki 鏈接。由于國內訪問?Minecraft Wiki?速度較慢，因此本文中 wiki 頁面鏈接均使用?biligame 的鏡像。由于?Minecraft 英文 Wiki?往往更新更及時且內容更準確，因此有英文閱讀能力的可直接查看英文 wiki 的相關內容。

本文中青銅色楷體表示其應當被替換為合適的字符串，綠色楷體表示JSON文件中的注釋，點擊左下角顯/隱可切換顯示或隱藏注釋。

§1.1 命令基礎

本文不會介紹命令的基礎知識，相關內容請讀者通過如下鏈接自行了解。

• 命令?此為官方 wiki 的命令頁面，其中包括了命令的基本參數(shù)介紹：坐標、目標選擇器、數(shù)據(jù)標簽 (NBT) 、原始JSON文本、命名空間ID等內容。讀者需在學習命令過程中逐步了解這些概念。

• 記分板?此為官方 wiki 的記分板頁面，其中包括了記分板的所有準則和相關命令格式，也包含了標簽 (tag) 和組 (team) 的相關內容。

• 實體格式和player.dat格式?這兩個頁面給出了所有物品和實體(含方塊實體)的 NBT。在游戲中，實體的 NBT 可通過命令?data get entity/block?來獲取，物品的 NBT 可通過手持并輸入命令?data get entity @s SelectedItem?來獲取，以避免記憶大量的 NBT。

• 新人手冊-MC命令方塊資源?該網站包含了很多基礎的教程，不過很多內容會有些過時。還包含少量進階的內容，對于初學者可能較為復雜，請以理解其邏輯為主。

• 命令進階?該網站雖名為命令進階，實際上比前一項頁面更為初等，不過更為系統(tǒng)。

若你已對 1.18 之前版本的命令較為熟悉，可在Java版版本記錄中查看各版本間差異。

§1.2 工具準備

§1.2.1 文本編輯器

原版模組涉及的文本文件，包括文本文檔(.txt)、函數(shù)文件(.mcfunction)、JSON文件(.json, .mcmeta)、頂點著色器(.vsh)和片段著色器(.fsh)，均需使用?UTF-8?編碼格式。注意不要誤選了?UTF-8 with BOM?編碼格式。文本編輯器多如瀚海，讀者可自行選擇一種。我僅列出本人常用的兩個文本編輯器。

• Visual Studio Code?下載安裝后，可以安裝插件?Chinese (Simplified) Language Pack for Visual Studio Code?以支持中文語言，以及Data-pack Helper Plus?用于數(shù)據(jù)包各項內容的語法補全和糾錯。

• 記事本為 Windows 系統(tǒng)自帶的極簡編輯器。Windows10 的記事本已經默認是?UTF-8?編碼了。點擊查看->狀態(tài)欄可以在右下角狀態(tài)欄看到，因此可以正常使用。舊版本 Windows 的記事本仍然不是，請勿使用。

編輯器右下角可以看到?LF?或?CRLF，分別表示兩種換行符，二者均可正常使用，建議使用?LF。

為便于查看文件后綴，請將文件->文件夾選項->查看->隱藏已知文件類型的擴展名去掉勾選。我們可以在編輯器中新建文本文件，或者在文件夾中右鍵->新建->文本文檔，除?txt?以外的文本文件可通過修改文件后綴得到。

§1.2.2 壓縮軟件

數(shù)據(jù)包和資源包均可以為文件夾或 zip 文件，zip 文件需要壓縮軟件來打開和制作。游戲本體和模組本體的 jar 文件也需要使用壓縮軟件來打開。常見的壓縮軟件有：

• 7-Zip?是一款免費的壓縮軟件。jar 文件可以通過右鍵->7-zip->打開壓縮包來打開。

• WinRAR?是一款付費的壓縮軟件。

• Windows 資源管理器是 Windows10 系統(tǒng)自帶的軟件。它可以使得 zip 文件如同文件夾般直接打開，壓縮則用選擇->右鍵->發(fā)送到->壓縮文件夾，但它的壓縮速度十分緩慢。

§1.2.3 NBT 編輯器

我們可以使用?NBTStudio?來打開 dat 文件和其它 NBT 格式文件。

§1.2.4 繪圖工具

我們可以使用?Adobe Photoshop?或其它繪圖工具來繪制紋理。Windows 自帶的畫圖由于無法生成透明背景，因此不建議使用。

§1.3 游戲文件夾

本節(jié)中我們將對游戲文件夾的結構做簡單的介紹，我們只介紹原版模組開發(fā)中涉及的內容。.minecraft?文件夾是 Minecraft 創(chuàng)建的并用于游戲運行的文件夾，它包含了游戲的所有內容。在第一次啟動啟動器時，會自動創(chuàng)建?.minecraft?文件夾。參考?.minecraft。

.minecraft?文件夾通常位于你的啟動器目錄下。如果啟動器中設置為各版本獨立，則位于?versions/版本號下。另一種方式是在游戲內點擊選項->資源包->打開壓縮包文件夾并返回上級目錄，或者點擊單人游戲->選中世界->編輯->打開世界文件夾并返回上上級目錄。

游戲本體位于?versions/版本號/版本號.jar。該文件包含了對應版本的游戲資源和數(shù)據(jù)文件，使用壓縮軟件打開后，可以看到

• 原版資源包位于?assets?文件夾內，其中?minecraft?文件夾為命名空間?minecraft?下的資源文件。

• 原版數(shù)據(jù)包位于?data?文件夾內，其中?minecraft?文件夾為命名空間?minecraft?下的數(shù)據(jù)文件。

• pack.mcmeta?為原版資源包和數(shù)據(jù)包的元信息，1.17版本起不再包含該文件。

• pack.png?為原版資源包和數(shù)據(jù)包的圖標。

資源包文件夾位于?resourcepacks，其下方子文件夾或?zip?文件即為一個資源包，具體結構見資源包。服務器下載的資源包位于?server-resource-packs/服務器，可使用壓縮軟件打開。

資源文件?部分資源文件不被包含在原版資源包內，而是位于資源文件夾下，這主要包括各種語言文本和音效文件。資源文件索引位于?assets/indexes/版本號.json，打開后通過鍵值可知相應資源的 hash 值，對應的資源位于?assets/objects/hash前2位/hash。例如打開?assets/indexes/1.17.json，找到鍵?minecraft/lang/zh_cn.json?的?hash?為?8fb4f6725d8317a37e7f823ff424e66a46b9ef75，因此簡體中文的語言文本位于文件夾?assets/objects/8f/8fb4f6725d8317a37e7f823ff424e66a46b9ef75，使用文本編輯器打開即可看到游戲內的所有名稱的中文譯名。注意該文件中的中文均被轉化成了相應的 Unicode 表達方式，參考字體。

日志位于?logs/latest.log，可由此實時查看游戲運行中的各種反饋。對于我們而言，它可以在加載資源包和數(shù)據(jù)包時告訴我們它們是否有錯誤以及錯誤信息，包括錯誤的文件名稱、位置、錯誤的行列數(shù)等，因此這對于我們調試非常重要。簡體中文下需要設置文件編碼為?gbk，否則除 ASCII 外的字符會顯示亂碼。歷史日志位于?logs/年-月-日-序號.log.gz，使用壓縮軟件打開后使用文本編輯器打開即可查看。崩潰報告位于?crash-reports/crash-年-月-日_時.分.秒-server.txt，如果是由于資源包或數(shù)據(jù)包引起的崩潰，可以在該文件中看到原因。

存儲的物品欄位于?hotbar.nbt，存儲了游戲內使用?C+數(shù)字?存儲、X+數(shù)字?取出的創(chuàng)造模式物品快捷欄。

存檔文件位于?saves/世界名稱，由于世界格式上該內容已較為詳盡且與原版模組聯(lián)系甚遠，因此我們僅提及部分內容。該文件夾包含的區(qū)塊文件、地圖文件等內容雖然也可以使用 NBT 編輯器來編輯，但較為不便，我們建議使用 MCEdit、地圖文件生成工具等專門的工具來編輯。存檔的備份文件位于?backups/年-月-日_時.分.秒_世界名稱.zip，為存檔的備份文件，解壓后復制到?saves?即可使用。

• 進度位于?advancements/玩家UUID.json，記錄了玩家已完成的進度和進度判據(jù)的完成時間。對于需要完成多個判據(jù)才能達成的進度，該文件中記錄了已完成的那些判據(jù)的完成時間。

• 區(qū)塊、實體、實體興趣點、襲擊等信息分維度存儲，主世界、下界、末地、自定義維度的相應文件分別位于根文件夾、DIM-1、DIM1、dimensions/命名空間/路徑下。

• 世界信息文件?level.dat?中?WorldGenSettings?包含了世界生成時的所有維度的生成信息，玩家可以在創(chuàng)建新的世界->更多世界的選項->導入設置使用JSON文件導入，格式見自定義世界。之后還會加入數(shù)據(jù)包中的自定義維度。

• 數(shù)據(jù)包文件夾位于?datapacks，其下方子文件夾或?zip?文件即為一個數(shù)據(jù)包，具體結構見數(shù)據(jù)包。

• 結構位于?generated/命名空間/structures/文件.nbt，其記錄了游戲內使用結構方塊保存的結構，將其移動至數(shù)據(jù)包內方可使用。

§1.4 JSON文件

參考JSON。數(shù)據(jù)包的進度、戰(zhàn)利品表、戰(zhàn)利品表謂詞、物品修飾器、配方、標簽、維度、維度類型、自定義世界生成，資源包的語言文件、模型、音效、字體、credits.json?等文件均為JSON文件。.mcmeta?文件也是JSON文件，因此格式也是相同的。

JSON文件中用于分割的空格、制表符(Tab)、回車和換行符都是可去的，它們僅用于提高可讀性。編寫時，使用空格或制表符縮進，以便于查看括號匹配和層次。JSON文件通常包含用于封裝文件數(shù)據(jù)的一對大括號{}，即它是一個JSON對象，但戰(zhàn)利品表謂詞和物品修飾器文件的根數(shù)據(jù)類型還可以為JSON數(shù)組。它包含類似?"abc": "def"?這樣的?"鍵": 值?對，一般使用單引號也可以。同一個文件中如果允許有相同的鍵，則后者會覆蓋前者。

JSON數(shù)據(jù)類型有下述幾種。Wiki 上有關頁面使用了 NBT 的數(shù)據(jù)類型標注，但其實并不適用于JSON文件，我們應當將其視為相應內容的可取值范圍。

布爾型，值為?true?和?false。

{ "is_on_fire": false, "is_baby": true, "noise_caves_enabled": false }

數(shù)值，值為任何數(shù)字。2?和?2.0?沒有差異。

{ "count": 2.0, "chance": 0.025, "salt": 14357619 }

字符串，值使用雙引號/單引號圈住，可以使用顏色代碼如?§6、換行符?\n。

{ "condition": "minecraft:random_chance", "tag": "minecraft:wools", "layer0": "cpp:crop/bauhinia_seeds" }

數(shù)組，值使用中括號圈住。

{ "scale": [ 0.901, 0.901, 0.901 ], "items": [ "minecraft:zombie_head", "minecraft:skeleton_skull", "minecraft:wither_skeleton_skull", "minecraft:creeper_head" ], "requirements": [ [ "wing_of_sky", "heart_of_crystal", "nova_of_fire" ] ], "terms":[ { "condition": "minecraft:location_check", "predicate": { "biome": "minecraft:snowy_taiga" } }, { "condition": "minecraft:location_check", "predicate": { "biome": "minecraft:snowy_taiga_mountains" } } ] }

對象，使用大括號圈住。整個JSON文件內容本身就是一個JSON對象。

{ "count": { "type": "minecraft:uniform", "min": 1.0, "max": 2.0 }, "modifiers": [ { "name": "legs_armor", "attribute": "generic.armor", "operation": "addition", "amount": 4, "slot": "legs" } ] }

JSON中沒有注釋的語法，但可以使用不被使用的鍵來表示注釋。通常使用?"_comment", "_comment1", "_comment2"?這種鍵。

{ "pools": [ { "rolls": 1, "entries": [ { "_comment": "咸味粽子", "type": "minecraft:item", "name": "minecraft:cooked_cod", "functions": [ { "function": "minecraft:set_nbt", "tag": "{display:{Name:'{\"italic\":false,\"translate\":\"item.cpp.zongzi_with_salt\"}',Lore:['{\"italic\":false,\"translate\":\"item.cpp.zongzi_with_salt\"}']},id:'cpp:zongzi_with_salt',CustomModelData:12970027}" } ] } ] } ] }

我們常常在JSON中用整數(shù)來表示RGB格式顏色，對應值為:?65536×R+256×G+B。