此頁面用於了解什麼是rawtext,具體寫法應該放在教學中
目前的基岩版原始JSON文字格式介於介紹和教學之間的模糊地帶,需要重新整理。
原始JSON文字(Raw JSON Text)是Minecraft用於給玩家發送並顯示富文字的格式。原始JSON文字使用JSON編寫。
Java版
原始JSON文字由聊天組件組成。根組件可包含有子組件,而子組件也可以有自己的子組件。組件可以包含格式和互動事件,這些也會應用到他們的子組件上。
聊天組件可以使用除「null」外的所有JSON資料類型。數值和布林值將會視為字串處理,而字串和陣列用於簡寫較長的對象結構,見下文所述。
- 含有純文字的字串。與只有標籤 text的對象效果相同。例如,
"A"和{"text": "A"}等價。 - 布林值將會轉換為字串直接顯示。與只有標籤 text的對象效果相同。例如,
true、"true"和{"text": "true"}等價。 - 數值將會轉換為字串直接顯示。與只有標籤 text的對象效果相同。例如,
1.9E10、"1.9E10"和{"text": "1.9E10"}等價。 - 含有多個聊天組件的列表。與含有 extra陣列的聊天組件效果相同。[注 1]例如,
["A", "B", "C"]和{"text": "A", "extra": ["B", "C"]}等價。 - 一個聊天組件對象。所有非內容標籤都是可選的。
- 內容
- 一個對象需要包含內容標籤才能生效。不同的內容類型及它們對應的標籤將於下方說明。可以含有多個內容標籤,但最終只有一個會生效。[注 2]
- 子對象
- extra:含有在此組件之後顯示的附加聊天組件的列表。
- 子聊天組件。除非額外指定,子組件將繼承父組件的所有格式和互動事件。
- 格式
- color:繪製文字時使用的顏色。有效值有:
black、dark_blue、dark_green、dark_aqua、dark_red、dark_purple、gold、gray、dark_gray、blue、green、aqua、red、light_purple、yellow、white、reset(取消父對象使用的顏色效果)。
設定為"#<hex>"可以使用以6位十六進制顏色格式定義的顏色。 - font:繪製文字時使用的字體的資源路徑。使用的字體在
assets/<namespace>/font裡定義,預設為minecraft:default。 - bold:是否將文字繪製為粗體。
- italic:是否將文字繪製為斜體。原本為斜體的自訂物品名稱可以透過將此值設定為「false」來取消斜體。
- underlined:是否為文字加入下劃線。
- strikethrough:是否為文字加入刪除線。
- obfuscated:是否將文字混淆處理。
- 互動事件
- insertion:玩家按住⇧ Shift並點擊文字時,填入聊天框的的文字。其不會覆蓋聊天框內原有的文字。僅在聊天頁面中生效。
- clickEvent:允許在玩家點擊文字時產生事件。若無附加說明,其僅在聊天頁面和完成的書中生效。
- action:點擊後發生的事件。有效值有:
- 「open_url」:在預設瀏覽器中將 value作為URL地址打開。
- 「open_file」:打開計算機上位於 value的檔案。其用於遊戲自動生成的資訊中(如截圖後顯示的資訊),且出於安全原因禁止玩家使用。
- 「run_command」:可用於告示牌上,但僅支持在父組件中使用;透過使用告示牌觸發。在聊天頁面和完成的書中觸發則會以玩家的身份輸入 value並發送。其可以用於執行指令,但需要玩家擁有相應的權限;指令必須擁有「/」前綴,否則將會視為聊天資訊發送。在告示牌中,指令將由伺服器在告示牌所在的位置執行,並將使用告示牌的玩家視為執行者。因為指令由伺服器執行,告示牌指令的權限等級與指令方塊相同,玩家的權限等級會被忽略;且其不受聊天框長度的限制,可以省略「/」前綴。
- 「suggest_command」:打開聊天頁面並輸入 value。若聊天框已有內容,其將會被覆蓋。在完成的書中無效。[1]
- 「change_page」:僅在完成的書中生效。若指定頁面存在,將完成的書翻至第 value頁。
- 「copy_to_clipboard」:將 value複製到剪貼板中。
- value:指定的URL、檔案路徑、資訊、指令或頁碼。
- action:點擊後發生的事件。有效值有:
- hoverEvent:允許在玩家將滑鼠放在文字上時顯示提示文字。
- action:提示文字的類型。有效值有:
- 「show_text」:顯示一個聊天組件。
- 「show_item」:顯示一個物品的工具提示。與在物品欄中懸浮在物品上時出現的工具提示相同。
- 「show_entity」:顯示實體的名稱、類型和UUID。用於 selector中。
- contents:此標籤的格式取決於 action的值。
- 「show_text」:一個聊天組件。可以使用字串、陣列或對象。
- 「show_item」:要顯示的物品。
- id:物品的命名空間物品ID。若無效則視為
minecraft:air。 - count:可選。物品的數量。
- tag:可選。物品的資料標籤。參見player.dat格式#物品結構。
- id:物品的命名空間物品ID。若無效則視為
- 「show_entity」:要顯示的實體。
- name:可選,若未指定則隱藏本參數。將顯示為實體名稱的聊天組件。
- type:指定實體的類型。應為一個命名空間實體ID。若無效則視為
minecraft:pig。 - id:指定實體的UUID。應為一個有效的由連字元連接的十六進制UUID。
value:此標籤的格式取決於 action的值。已棄用,請使用 contents代替。- 「show_text」:一個聊天組件。可以使用字串、陣列或對象。
- 「show_item」:一個物品的資料標籤。參見player.dat格式#物品結構。
- 「show_entity」:一個資料標籤。其不包含所有的實體資料,僅儲存實體的名稱、類型和UUID。
- name:可選,若未指定則隱藏本參數。指定該實體的名稱並顯示。包含將被解析聊天組件的JSON文字。若字串無法被解析為聊天組件,整個提示文字會顯示為「無效的實體!」。
- type:可選,若未指定則隱藏本參數。指定該實體的類型。包含將視為實體類型的純文字,可以為任何文字。
- id:可選,若未指定則顯示為空行。指定該實體的UUID。包含將視為UUID的純文字,可以為任何文字。
- action:提示文字的類型。有效值有:
由於 extra標籤的存在,以上格式可遞歸嵌套成非常複雜與多樣的文字。然而,原始JSON文字不必弄得如此複雜:幾乎所有的標籤都是可選的。
基岩版
基岩版有著相較於Java版更精簡的原始JSON文字格式,它以文字顯示為主。在字體樣式上以格式化代碼替代了Java版中color等多個組件,並拋棄了所有輔助標籤。
在基岩版中,原始JSON文字可以作用於/tellraw的內容、/titleraw的標題、NPC的名字、書和羽毛筆的文字(題目和作者除外)以及告示牌的文字。但selector組件和score組件無法在後三者中生效。
- 根組件。
- rawtext:含有所有聊天組件對象的列表。
- 聊天組件對象。
- text:在文字中直接出現的聊天組件。
\n用於換行(回車)。如果聊天組件對象中有 translate,則 text的內容會被 translate覆蓋。 - selector:可以在指令中輸出實體的名稱,如"@a" "@p" 會被轉換。(如
/[[指令/'"`uniq--nowiki-00000003-qinu`"'|'"`uniq--nowiki-00000003-qinu`"']]會向全體玩家打印執行者玩家的名字) - translate:使用玩家所選擇的語言顯示的翻譯識別符。此識別符與在assets檔案或紋理包的lang檔案中所發現的識別符相同。
- with:配合 translate使用的聊天字串參數的列表。
- 此字串是與目前語言中使用的參數按順序所對應的文字(例如,列表中的第一個元素對應於 translate中的
%%1)。
- 此字串是與目前語言中使用的參數按順序所對應的文字(例如,列表中的第一個元素對應於 translate中的
- with:with組件的另一種寫法,含有一個 rawtext組件。
- rawtext:列表中應該為聊天組件對象,此聊天組件對象是與目前語言中使用的參數按順序所對應的文字。
- ...
- rawtext:列表中應該為聊天組件對象,此聊天組件對象是與目前語言中使用的參數按順序所對應的文字。
- score:顯示所選目標在所選計分項的目前分數。 如果所選目標或所選計分項不存在,或者所選目標在所選計分項上沒有分數,則不顯示任何內容。
- name:選定要顯示分數的目標。可以是@p之類的目標選擇器或虛擬玩家名。如果為
*,則會顯示閱讀者自己的分數(例如,/[[指令/'"`uniq--nowiki-00000004-qinu`"'|'"`uniq--nowiki-00000004-qinu`"']]會向每個線上玩家顯示他們自己在「obj」計分項的分數)。 - objective:選定要顯示分數的目標所在計分項的名稱。
- name:選定要顯示分數的目標。可以是@p之類的目標選擇器或虛擬玩家名。如果為
- text:在文字中直接出現的聊天組件。
- 聊天組件對象。
- rawtext:含有所有聊天組件對象的列表。
內容類型
聊天組件可以顯示多種類型的內容。這些標籤應直接包含於聊天組件對象中。
純文字
- 聊天組件。
- text:一段文字。
- 聊天組件。
已翻譯文字
- 以目前語言顯示一段已翻譯的文字。使用的語言取決於用戶端選擇的語言,所以不同用戶端在收到同一伺服器的同一識別碼後,用戶端會使用各自的語言顯示文字。若在用戶端內未找到對應的譯文,則會檢查
en_us.json中對應的譯文。若依舊未找到,則直接輸出翻譯識別碼本身。
- 譯文可以包含應用於未知文字的變數。變數通常會以
%s(顯示列表中的下一個參數)或%1$s(顯示列表中的第1個參數;可以將1替換為其他數字,對應列表中的第N個參數)的形式出現。[注 3]顯示已翻譯文字時,這些變數將由提供的聊天組件列表填充。如果未給某變數提供參數,該變數將不會顯示。[注 4]這些變數直接在語言檔案中定義,與聊天組件無關。
- 聊天組件。
- translate:一個翻譯識別碼。
- with:可選,含有用於替換譯文內變數的聊天組件的列表。不存在 translate時忽略。
- 一個聊天組件。如果某變數無法取得聊天組件,該變數將不會顯示。
- with
[僅基岩版]:可選,with組件的另一種寫法,含有一個 rawtext組件對象。 - rawtext:含有用於替換譯文內變數的聊天組件對象的列表。
- 聊天組件。
計分項分數
- 顯示實體在計分板中某個計分項的分數。
需要解析組件。 此標籤會解析為值為計分項分數的 text標籤。
實體名稱
- 顯示由目標選擇器、玩家名稱或
*找到的實體的名稱。若為*,則會顯示讀者自己的名稱。
- 若選擇器發現了一個實體,則會顯示這個實體的名稱。若發現了多個實體,則會顯示所有被選中的實體的名稱,用分隔符(預設為灰色的半形逗號)分隔。若沒有發現實體,則不會顯示任何文字。
- 在Java版中,滑鼠懸浮在名稱上時會顯示包含名稱、類型和UUID的工具提示。點擊一個玩家的名稱會出現私信該玩家的指令建議;按住⇧ Shift點擊玩家名稱會將其名稱填入聊天框中;按住⇧ Shift點擊非玩家實體的名稱會將其UUID填入聊天框中。
需要解析組件。 - 如果選擇器發現了一個實體:
- 在Java版中,解析後的組件也會擁有 insertion標籤、類型為
show_entity的 hoverEvent標籤和類型為suggest_command的 clickEvent標籤(若此實體是一名玩家)以實現上文所述的功能。如果這些標籤已經存在於原組件上,對應標籤的值將使用原組件上的值。
- 如果選擇器發現了多個實體,此組件會解析為無內容的 text標籤,並帶有含有代表單個實體的對象的 extra標籤,各對象之間使用 separator標籤的值(若未指定則為預設值)分隔。
[僅Java版] - 如果選擇器沒有發現實體,此組件會解析為無內容的 text標籤。
- 聊天組件。
- selector:一個目標選擇器、玩家名稱或
*。 - separator
[僅Java版]:可選,用作分隔符的聊天組件。預設為 {"color": "gray", "text": ", "}。在組件顯示多個實體時,使用此標籤指定的聊天組件分隔各個實體的名稱。
- selector:一個目標選擇器、玩家名稱或
- 聊天組件。
按鍵綁定
- 顯示可設定鍵位的動作目前綁定的鍵位的名稱。其取決於用戶端的綁定配置,所以不同用戶端在收到同一伺服器的同一識別碼後,用戶端會使用各自的配置顯示鍵位名稱。
- 例如,若使用預設配置,
{"keybind": "key.inventory"}將顯示為「e」。
- 聊天組件。
- keybind:一個鍵位識別碼。
- 聊天組件。
NBT標籤值
- 如果NBT標籤的值為字串,則顯示它的內容;其他值則將顯示為SNBT。如果 interpret為真,遊戲會嘗試將取得的值解析為原始JSON文字組件並顯示。因為JSON和SNBT之間並不相通,這種解析通常只在值為字串時成功。如果 interpret為真且解析失敗,則不會顯示任何文字。如果發現多個值(通常由選擇了多個對象或路徑會選擇多個值造成),則會顯示所有值,用分隔符(預設為半形逗號)分隔。
需要解析組件。 - 如果 interpret為假,此標籤會解析為值為NBT標籤的值的 text標籤。
- 如果選擇了多個值且未提供 separator標籤,它仍然會解析為單個 text標籤,各個值之間使用半形逗號分隔。
- 如果選擇了多個值且提供了 separator標籤,每個值會解析為單獨的 text標籤,第一個值之後的值均會放入第一個值的 extra標籤,各對象之間使用 separator標籤的值分隔。
- 如果 interpret為真,組件會解析為對應的文字組件。對於同時存在於被解析的組件和原組件上的非內容標籤,標籤將使用原組件的值。
- 如果選擇了多個值,每個值會解析為對應的文字組件,第一個值之後的值均會放入第一個值的 extra標籤,各對象之間使用 separator標籤的值(若未指定則為預設值)分隔。這意味著第一個值的格式標籤會應用於之後的值裡。
- 如果 interpret為假,此標籤會解析為值為NBT標籤的值的 text標籤。
- 聊天組件。
- nbt:一段NBT路徑,用於指定NBT資料標籤。需要同時存在 block、 entity或 storage。可以含有多個相應標籤,但只會有一個生效。[注 6]
- interpret:可選,預設為「false」。若指定為「true」,則會將取得的每個值視為聊天組件並解析。不存在 nbt時忽略。
- separator:可選,用作分隔符的聊天組件。預設為
{"text": ", "}。在組件顯示多個值時,使用此標籤指定的聊天組件分隔各個值。 - block:一個座標,指定要取得資料標籤的方塊實體。座標可以是絕對座標、相對座標或局部座標。不存在 nbt時忽略。
- entity:一個目標選擇器,指定要取得資料標籤的實體。不存在 nbt時忽略。
- storage:一個命名空間ID,指定要取得資料標籤的指令儲存。不存在 nbt時忽略。
- 聊天組件。
解析組件
組件內的部分標籤( score、 selector和 nbt
此外,解析會固定取得的值。因此,這些組件的內容不再變化,不會因環境的變化而調整相應值。
歷史
| Java版 | |||||
|---|---|---|---|---|---|
| 1.7.2 | 13w37a | 加入了/tellraw,原始JSON文字用於支持該指令。 | |||
| 1.8 | 14w02a | 加入了文字組件insertion。 | |||
| 14w07a | 加入了文字組件score。 | ||||
| 14w20a | 加入了/title,其使用原始JSON文字。
| ||||
加入了文字組件selector。 | |||||
| 14w25a | 現在支持在告示牌和完成的書內使用。 | ||||
| 1.12 | 17w16a | 加入了文字組件keybind。 | |||
| 1.13 | 18w01a | 現在支持在自訂名稱內使用。 | |||
| 18w05a | 加入了/bossbar,參數<name>使用原始JSON文字。 | ||||
| 1.14 | 18w43a | 加入了文字組件nbt、block和entity。
| |||
| 現在支持在物品描述標籤內使用。 | |||||
| 18w44a | 加入了文字組件interpret。 | ||||
| 1.15 | 19w39a | 加入了文字組件storage。 | |||
| 19w41a | 為clickEvent加入了copy_to_clipboard。 | ||||
| 1.16 | 20w17a | 加入了文字組件font。
| |||
為hoverEvent加入了contents。value不再使用,但仍受支持。 | |||||
文字組件color現在可以使用十六進制顏色碼來自訂顏色。 | |||||
| 1.17 | 21w15a | 加入了文字組件separator。 | |||
| 基岩版 | |||||
| 1.9.0 | 1.9.0.0 | 加入了/tellraw,原始JSON文字用於支持該指令。 | |||
| 1.16.100 | 1.16.100.55 | 加入了文字組件score和selector。 | |||
參見
注釋
- ↑ 請注意,之後的組件將視為第一個組件的子組件,因此第一個組件的格式和互動事件將應用於之後的組件。例如,
[{"text": "A", "color": "red"}, "B", "C"]將會輸出都被繪製為紅色的文字。 - ↑ 按照 text、 translate、 score、 selector、 keybind、 nbt的順序檢查。若提供了多個內容標籤,則會使用此列表中最靠前的標籤。
- ↑ 在Java版中,選擇「下一個」參數時忽略已索引變數。所以若譯文「Hello %s, %2$s, and %s.」被賦予參數「John」和「Becky」,它將顯示為「Hello John, Becky, and Becky.」
- ↑ 在基岩版中,如果完全沒定義with組件,則會將變數視為一般文字。
- ↑ 顯示讀者自己的分數僅在發送的資訊不會被不同玩家同時閱讀時生效。顯示在聊天資訊、
/title或被獨自閱讀的完成的書[僅Java版]上時會生效,但在告示牌、講台上的完成的書等地方將無法生效。 - ↑ 按 block、 entity、 storage的順序檢查。若提供了多個標籤,則會使用此列表中最靠前的標籤。
參考
| 版本 | |||||||
|---|---|---|---|---|---|---|---|
| 開發週期 |
| ||||||
| 技術 |
| ||||||
| 多人遊戲 | |||||||
| 遊戲訂製 | |||||||
| 版本 |
| ||||||
|---|---|---|---|---|---|---|---|
| 開發 |
| ||||||
| 技術性 | |||||||
| 多人遊戲 | |||||||
| 特色功能 | |||||||