# Cartocraft 2 Specification
:::spoiler 目錄
[toc]
:::
> [!Important]
> 現在置頂不知道會不會太晚
> CTM**沒有規定**每區都要放boss喔
# Core DP & RP
:point_right: https://github.com/Cartoland/CC2-core
## 外部資料包
### [Player Motion](https://github.com/pearuhdox/Cartographer-2.0/tree/1.21/Player%20Motion%20by%20Mulv%20and%20MCC)
- Cartographer 2版，比MulverineX獨立維護版的1.4.2新。
- 注意：如果要同時發動傷害+玩家動量，傷害類型需要加入`#no_impact`標籤，以避免傷害把玩家的動量重置。
# 地圖
## 基本要求
- 遊戲版本：原版1.21.4，或相容的修復版本。
- 結構：封閉空間，內部空間至少40×40×40，外殼厚度為3，依需求使用基岩或屏障材質。
- 環境：適合1~4個玩家使用生存模式遊玩，遊戲內容至少10分鐘。
- 必須包含自訂怪物、自訂道具、基本資源。
- 文字：一般文字要能使用資源包進行翻譯。
> [!Warning]
> 地圖做著做著又踩到Mojank的大地雷了。
> [MC-162441](https://bugs.mojang.com/browse/MC-162441)：告示牌的`translate`不會在切換語言後自動更新顯示內容，且`resources.zip`比告示牌文字晚載入
> 解決方法：指令刷新告示牌的任意資料，例如平常應該不會有人用的`back_text`。
## 遊戲規則
|規則|值|
|-|-|
|難度|非和平，允許玩家修改。<br>地圖以普通難度進行平衡。|
|自然生怪|**On**<br>（特殊種類的怪物生成規則 Off）|
|日夜交替|永夜。|
|天氣交替|Off|
|怪物破壞|On|
|火焰更新|Off|
|防噴|允許玩家修改。|
|指令數量限制|10,000,000|
|指令方塊輸出|Off|
|指令回饋|地圖發布時關閉，開來除錯時不應洗版。|
- 傷害類型應該適當的選擇受難度影響（`scaling`參數）。
- 生怪規則是為了試煉生怪磚而開啟，請把自己區域的生態系改為不自然生怪。
- 懶人福音：`plains`生態系會由核心資料包幫忙改好。
- Ref: [MC-266487](https://bugs.mojang.com/browse/MC-266487) - Trial Spawners will not activate/spawn mobs if gamerule "doMobSpawning" is set to "false"
## 遊戲設定
|設定|值|
|-|-|
|強制Unicode|可開可關。|
|玩家OP權限|0|
|畫面效果|確保不開「極致！」的玩家也有正常遊戲體驗。|
## 遊戲功能
- 附魔台、鐵砧、砂輪都不禁止。
# 資料包
Rule \#1：本地圖的指令方塊只接受作為裝飾品。
## 開發環境
:::info
如果不是用VSC+Spyglass的話，可以跳過這段。
:::
- 為了讓Spyglass正確建議指令，可以把`cc2`命名空間單獨複製進自己的資料包內。
- 如果會設定`spyglass.json`的話，就盡量用那個檔案來處理。
- 提交之前要清乾淨。
- 把`mcdoc`資料夾按原本的擺放方式，放到`data`資料夾旁邊。
## 命名空間
- 十六色羊毛區：顏色的英文名稱。
- 紀念碑區：`monument`。
- 也能選擇使用自己的名字（ID等）當命名空間。
- 通用的核心功能：`cc2`。
## 目標物
- 使用十六色羊毛作為目標物，每個區域分配一種。
- 至少給3顆以防玩家犯蠢。
- 非目標物的羊毛不嚴格禁止，但應該避免和目標物混淆。
- 統一使用`cc2:objective/<color>`戰利品表提供的羊毛為基礎。
羊毛可以調整以下物品元件：
|元件|值|
|-|-|
|`custom_data`|遵守物品`custom_data`的修改規則。|
|`lore`|只能追加新的文字。|
|`attributes`|隨意發揮。|
|`damage_resistant`|隨意發揮。|
|`enchantments`|隨意發揮。|
|`item_model`|可以藏特殊彩蛋，但平常看起來應該要像原版的羊毛。|
## 道具
### Custom Data
物品的`custom_data`應該存在各自的命名空間內。
- :+1: `custom_data={gray:{wand:{}}}`
- :face_with_raised_eyebrow: `custom_data={wand:{}}`
核心資料包提供以下資料：
|測試|功能|
|-|-|
|`~{cc2:{objective:{}}}`|這個羊毛是目標物。|
|`~{cc2:{unobtainable:{}}}`|這個物品是專屬於怪物的，玩家不應該有正常手段能取得。<br>系統會自動清除玩家身上的這類物品。|
### 無副作用物品
- **不希望發生副作用時**，沒有耐久度的自訂物品都應該使用毒馬鈴薯為基底。`cc2:dummy_item`戰利品表會提供一個無副作用的物品。
- 有耐久度的物品會有工作台、鐵砧、砂輪合併物品的問題，因此應該盡可能的使用性質相近的原版物品。這項原版物品必須是預設不可堆疊的。
### 屬性值
- 慣用手武器的屬性值若使用`add_value`模式，則**應**使用`base_attack_damage`和`base_attack_speed`作為ID，以觸發遊戲顯示計算後攻擊力、攻擊速度的機制。
:::spoiler 使用自訂ID
:::
:::spoiler 使用特殊ID
:::
:::spoiler 範例
:::
- 盔甲**可以**使用和原版相同的ID：
- `armor.helmet`
- `armor.chestplate`
- `armor.leggings`
- `armor.boots`
- 除以上狀況外，所有屬性修飾都應該使用自己命名空間的ID。
### 工具等級
使用自訂材質而無法識別原材質的工具，要加上說明指出工具相當於原版的哪種材質。
- 翻譯文字參見翻譯表。
- 格式：灰色非斜體。
- 可用的材質名稱：
- `wood`
- `gold`
- `stone`
- `iron`
- `diamond`
- `netherite`
- 鑽石工具能向上升級，請謹慎使用。
:::spoiler 補充：破磚速度表
:::
### 冷卻
- `use_cooldown`的冷卻是純客戶端機制，作為道具/技能冷卻非常不可靠，請避免這樣使用。
- 右鍵偵測消耗物品後，可以用`use_cooldown`進入短暫的冷卻，避免短時間連續觸發。
## 附魔
### 名稱風格
- 專屬於指定道具的附魔才能使用白色、紅色以外的顏色。
- 泛用附魔不應該上色。
### 綁定、消失
這兩項功能應該明確引用內建的附魔以利玩家識別。
### `#tooltip_order`
- 附魔標籤`tooltip_order`應該只在核心資料包覆蓋一次。
- 若有需要，請在readme中描述排列順序。
## 物品能力敘述
### 屬性值
遊戲會自動顯示。
### 其他能力
因為這次地圖內容都可以翻譯，只要行數和顏色對了，其他用詞等細節都能在後期簡單調整。
- 原版有相近的敘述就盡量模仿。
- 在指定欄位才能發動的效果，要把裝備位置和觸發條件都寫出來。
- 例：`在非慣用手時：\n被怪物攻擊後，…`
## 實體
地圖會在和平模式下合併，請不要事先放置敵對生物。
### 特殊標記
> [!Important]
> 這段刪掉了，已經實作的同學麻煩跟著改一下。
> 意料之外的實體互動，在合併之後有抓到再一個一個修。
### 隱形輔助實體
這些實體使用特殊的UUID。
請不要移動展示實體和盔甲座。
(-1, -1)到(0, 0)的四個區塊會持續載入，請不要把標記移出這些區塊。
- 文字展示：`cc2-0-0-0-1`
- 物品展示：`cc2-0-0-0-2`
- 方塊展示：`cc2-0-0-0-3`
- 標記：`cc2-0-0-0-4`
- 盔甲座：`cc2-0-0-0-5`
### 盔甲座屬性值
在使用盔甲座的屬性後，請回復原狀（包括基礎值和修飾）。
## 方塊
請不要給玩家任何破壞基岩和屏障的手段。
## 傷害
- 為了避免令人迷惑的死亡訊息，請在有必要的時候自訂傷害類型。
- 適當的加上原版傷害標籤，例如槍械類傷害加上`#is_projectile`。
## 計分板
### 命名
一般計分項使用命名空間前綴，例如`white.timer`。
### `number`計分項 / `number` Objective
計分項`number`用於儲存乘除法所需的固定數字。數字存在對應的`#`開頭虛擬玩家中，例如`#-1`儲存數字-1、`#2000`儲存數字2000。
需要用到的數字請在自己的`#load`函數中定義。
### `cc2`計分項 / `cc2` Objective
有一些共用的參數不需要重複讀取，可以統一讀核心資料包提供的分數。
這些分數只能讀，請不要改寫。
|虛擬玩家 / Scoreholder|說明|
|-|-|
|`#difficulty`|遊戲難度，0和平\~3困難。<br>0只會在地圖合併過程中出現。|
|`#gametime`|時間。|
## 玩家相關的功能
### NBT分數
這些分數只能讀，請不要改寫。
|計分項 / Objective|倍率|對應的NBT|
|-|-|-|
|`cc2.health`|1000|`Health`|
|`cc2.absorption`|1000|`AbsorptionAmount`|
|`cc2.selected_slot`|1|`SelectedItemSlot`|
|`cc2.pos_x`|1|`Pos[0]`|
|`cc2.pos_y`|1|`Pos[1]`|
|`cc2.pos_z`|1|`Pos[2]`|
|`cc2.yaw`|1|`Rotation[0]`|
|`cc2.pitch`|1|`Rotation[1]`|
如果需要更多玩家NBT相關的分數，可以把函數掛在`#cc2.load_player_nbt_score`上，在被呼叫的時候從`cc2:player_nbt`儲存空間讀取`root.<NBT>`標籤，並轉移到`@s`的分數上。
範例：
```mcfunction
# this function is hooked on #cc2:load_player_nbt_score
execute store result score @s example.air run data get storage cc2:player_nbt root.Air
```
這個儲存空間一樣不能改寫。
### 儲存空間 / Data Storage
> [!Note]
> 這是**每個玩家各自擁有的**儲存空間管理系統（aka 玩家資料庫），普通的storage用不到這段。
- 以玩家為`@s`執行`cc2:load_player_storage`載入玩家的專屬儲存空間。
- 此玩家的資料會暫時儲存在`cc2:player_storage`。
- 每個區域應該使用`root.<area>`路徑儲存資料。
- 修改完成後，執行`cc2:save_player_storage`把資料寫入回資料庫。
範例：
Example:
```mcfunction
# as @s[type=player]
# 先載入儲存空間
function cc2:load_player_storage
# 灰區的字串foo的路徑是root.gray.foo
data modify storage cc2:player_storage root.gray.foo set value "bar"
# 修改完成後，寫回玩家資料庫
function cc2:save_player_storage
```
- 存取資料前，一定要執行載入函數以確保資料屬於目前的玩家。
- 如果沒有修改資料，可以不用執行儲存函數。
### Actionbar儲存空間
上一節的儲存空間中，可以在`root.cc2.actionbar`設定顯示在actionbar的文字。
核心系統會把所有文字合併顯示，以避免爭奪actionbar資源的問題。
- 顯示文字時：寫入到`root.cc2.actionbar[{id: <id>}].text`。
- 取消顯示時：刪除`root.cc2.actionbar[{id: <id>}]`。
- 文字總寬度必須是0。
- 寬度補償方式參見翻譯指南。
- debug小技巧：把同樣的內容連續顯示兩次，就能確認文字總寬度是不是0。
範例：
```mcfunction
# as @s[type=player]
# 先載入儲存空間
function cc2:load_player_storage
# 修改文字
data modify storage cc2:player_storage root.cc2.actionbar[{id: "gray:timer"}].text set value '["0", {"text": "0", "font": "gray:negative_width"}]'
# 修改完成後，寫回玩家資料庫
function cc2:save_player_storage
```
### 標題
請在每次顯示標題前修改標題顯示時間。
## 隊伍、標籤
和計分板的規則相同，使用命名空間前綴。
### `cc2.player`
玩家所在的隊伍。
如果需要不會攻擊玩家的召喚物，可以把召喚物也加入這個隊伍。
※ 只有生物AI受影響，隊伍內互相傷害沒有關閉。
當然，不加入隊伍變成黑暗集會風格的召喚物我也不反對。
## 全域修改
- 刪除原版進度（`recipe/*`除外）。
- 挖掘羊毛會掉落線。
- 刪除合成、染色羊毛的配方。
## 座標
- 地圖合併之後不會保留原本的絕對座標。
- 如果有依賴絕對座標的功能，請在readme中說明，地圖合併後工人會編輯指定的座標。
## 冒險模式區域
- 把偵測函數掛在`#cc2:is_in_adventure_zone`標籤上。
- 函數執行的時候會`as`和`at`在玩家上。
- 玩家應該是冒險模式時，回傳1。
- 玩家應該是生存模式時，**不執行**`return`指令。
> [!Important]
> `return fail`不等於不回傳任何東西！
> `return fail`會把別人的冒險模式區域破壞掉。
範例：
```mcfunction
# this function is hooked on #cc2:is_in_adventure_zone
execute if predicate example:is_in_the_void_biome run return 1
```
## 進度
### 圖鑑
> [!Note]
> 圖鑑不是一定要做的東西。
每種分類使用一個root，後面的項目全部連成一條直線。
範例：
```mermaid
graph LR
mob_root[怪物] --> zombie1[殭屍1號] --> zombie2[殭屍2號] --> skeleton1[骷髏1號]
item_root[道具] --> hat1[帽子1號]
```
- 圖鑑進度應全數隱藏，在適當的時機解鎖後顯示。解鎖時沒有聊天欄通知，但會顯示右上角toast。
- Root進度隨意，資料包合併後會重新整理。
## Mcdoc
> [!Note]
> 這是VSC+Spyglass開發時的輔助檔案。
> 不想要或不會用mcdoc可以跳過，這只是輔助功能。
### 一般Data storage
Dispatcher ID：`:storage`。
Dispatcher索引：data storage ID。
範例：
```
dispatch :storage[gray:example] to struct {}
```
### 玩家資料庫
Dispatcher ID：`cc2:player_storage`。
Dispatcher索引：命名空間。
範例：
```
dispatch cc2:player_storage[gray] to GrayPlayerStorage
```
### 物品Custom data
Dispatcher ID：`mcdoc:custom_data`。
參考範例：核心資料包所使用的custom data
```
dispatch mcdoc:custom_data[cc2] to struct {
[#[dispatcher_key="cc2:custom_data"] string]: cc2:custom_data[[%key]]
}
dispatch cc2:custom_data[%unknown] to any
dispatch cc2:custom_data[objective] to struct {}
dispatch cc2:custom_data[unobtainable] to struct {}
```
# 資源包
## 翻譯
- 提供`en_us`、`zh_cn`、`zh_tw`中至少一種。
- 使用各區的命名空間，以及Minecraft的命名風格（如`item.minecraft.dirt`）。
- 玩家看不到的文字（如無法取得的附魔名稱）可以不翻譯。
- 特效用文字（如`obfuscated`閃爍文字）可以不翻譯。
- 盡量避免`§`。
|類別|命名規則|
|-|-|
|翻譯命名<br>Arbitrary key name|`*<ns>.<name>*`|
|生態系|`biome.*`|
|Boss條|`bossbar.*`|
|附魔名稱|`enchantment.*`|
|實體名稱|`entity.*`|
|山羊角音色|`instrument.*`|
|物品名稱|`item.*`|
|物品敘述|`item.*.desc`<br>`item.*.desc.<#>`|
|一群物品共用的敘述|`item_desc.*`<br>`item_desc.*.<#>`|
|唱片機音樂|`jukebox_song.*`|
|聲音字幕|`subtitles.*`|
|一般訊息|`text.*`|
|工具等級|`tool_tier.cc2.<material>`|
|鍛造材質|`trim_material.*`|
|盔甲紋樣|`trim_pattern.*`|
|死亡訊息|在傷害類型定義的`message_id`使用`<ns>.<name>`格式。|
|`with`中追加的文字|`*.with.<#>`|
### 文字寬度補償
- 使用字體`cc2:space`。
- 預設分隔字串`, `的總寬度是-1。
- 字元`\ueXYZ`對應的寬度：
|值|X|Y|Z|
|-|-|-|-|
|0|通用|正寬度|1|
|1|僅Unicode|負寬度|2|
|2|-|-|4|
|3|-|-|8|
|4|-|-|16|
|5|-|-|32|
|6|-|-|64|
|7|-|-|128|
|8|-|-|256|
|9|-|-|512|
|a|-|-|1024|
|b|-|-|2048|
|f|-|-|0.5|
範例：寬度-14的字串可以用`\ue013\ue012\u1011`表示。
調整寬度補償的輔助工具：[下載世界](https://cdn.pikacnu.com/view/f2249b14-af69-43bd-806c-31b3265901ae/CC2-space-helper.zip)。（需要核心資料包）
## 聲音
- 使用原版音效時，如果字幕會讓人迷惑，請自訂聲音事件。
- 分類照著原版風格走。
- BGM務必放到`music`音軌，無論是用哪種機制播放的。
- 1.21.4生態系支援強制關閉系統BGM，請參考原版`pale_garden`。
:::spoiler 原版分類
|Sound Name|Technical Name|Description|
|-|-|-|
|Music|`music`|Controls the volume of the in-game soundtrack.|
|Jukebox/Note Blocks|`record`|Controls the volume of jukeboxes and note blocks.|
|Weather|`weather`|Contols the volume of rain and thunder.|
|Blocks|`block`|Controls the volume of block interaction and passive block sounds.<br>This includes redstone, fluids, player interaction with blocks and explosions.|
|Hostile Creatures|`hostile`|Controls the volume of all monsters and bosses.|
|Friendly Creatures|`neutral`|Controls the volume of all non-monster entities; mostly animals.|
|Players|`player`|Controls the volume of player movement, throwing/shooting projectiles and interaction with entities.|
|Ambient/Environment|`ambient`|Controls the volume of ambience and firework rockets going off.|
|Voice/Speech|`voice`|Controls the volume of the narrator.|
Some sounds choose their category based on the entity that performs the action. For example, if a vindicator steps on a block, the step sound is in the Hostile Creatures category, but if a player steps on a block, the step is in the Players category.
> [Minecraft Wiki](https://minecraft.wiki/w/Sound#Categories)
> [color=#114514]
:::
## 物品模型
### 一般情況
一般情況請全部使用`item_model`元件，搭配資源包的`items/`資料夾定義獨立的物品模型。
### 超特殊案例
以下特殊情況無法使用自訂物品模型：
1. 鑽石製品升級後，希望使用另一個自訂材質
2. 束口袋、界伏盒染色後，希望使用不同顏色的自訂染色材質
請使用custom model data中的`strings`列表提供指定字串，並在物品模型定義中使用`select`選擇對應的模型。
這樣能把撞車的可能性降到最低，相容性遠高於使用隨機的`floats`編號。
範例：
`bundle[custom_model_data={strings=["gray:shundle"]}]`
## Core Shaders
> [!Note]
> 這不屬於核心資源包。
### `rendertype_item_entity_translucent_cull`
這個shader用於物品繪製。
具有特定alpha值的物品材質會受到影響。
|Alpha|說明|
|-|-|
|250|橙羊毛區占用的物品冷卻顯示。|
|251|灰羊毛區占用的框線顯示。|
|252|灰羊毛區提供的終界傳送門特效。|
「占用」的部分請避開。
「提供」的部分可以用來呈現相同的效果。
#### Alpha 252
測試資源包請見製作群的[訊息](https://discord.com/channels/886936474723950603/1304413052938092544/1311914595564392532)。
### `rendertype_armor_cutout_no_cull`
這個shader用於盔甲繪製。
具有特定alpha值的物品材質會受到影響。
|Alpha|說明|
|-|-|
|252|灰羊毛區提供的終界傳送門特效。|
「提供」的部分可以用來呈現相同的效果。
#### Alpha 252
暫無測試資源包。
# 提交
## 檔案
1. 包含區域建築&地形的地圖檔。
2. 資料包附在地圖檔內。
3. 資源包（若有）。
4. Readme檔案，包括區域名稱、區域內容和顯示在地圖內的作者名。
- 作者名建議多給一個對英文使用者顯示的版本
## 對象
參見創聯內的[公告](https://discord.com/channels/886936474723950603/977844004005765160/1305233020361379953)。
## 時間
2025年1月31日23:59 (UTC+8)前。
# 區域作者
|區域|作者|
|-|-|
|(1) 白 / White|天天|
|(2) 橙 / Orange|末天 & 米格|
|(3) 洋紅 / Magenta|JaCkY99|
|(4) 淺藍 / Light blue|how & Icerdanny|
|(5) 黃 / Yellow|米爾希亞 & 哞欸欸|
|(6) 淺綠 / Lime|兔乃 & 夜緋羽|
|(7) 粉紅 / Pink|收音機 & Pikacnu|
|(8) 灰 / Gray|Merak & 天天|
|(9) 淺灰 / Light gray|麥喵|
|(10) 青 / Cyan|歐梅 & 連恩|
|(11) 紫 / Purple|ccJerrycc|
|(12) 藍 / Blue|GalacticAC|
|(13) 棕 / Brown|icebirdowo & Goldguest|
|(14) 綠 / Green|紙圓|
|(15) 紅 / Red|DragonL & 米格 (& Sakurapotato的素材)|
|(16) 黑 / Black|AlexCai & 亞雲|
|Bonus 1|果凍|
|Bonus 2|Merak & 天天 (& 米格的素材)|
|紀念碑 / Monument|米格|
|傳送門 / Portal|雪央|
# 重大更新
Nov. 22:
- 追加傷害類型規範。
Nov. 29:
- 增加物品繪製shaders的說明。
Dec. 8:
- 更改冒險模式區域的規格。
Dec. 28:
- 新增玩家隊伍。
- 刪除實體特殊標記規格。
Jan. 11:
- There be Player Motion
Sign in with Wallet
Connect another wallet