.ski 技能檔格式說明

這頁說明目前 repo 內 skill/*.ski 的欄位用途、常見設定值，以及它們對應到哪個 runtime loader。

最適合把這份文件放在 docs/current-game/：

• 這是現行 runtime schema，不是舊站鏡像內容。
• GitHub Pages 會直接發佈 docs/，之後可以從網站直接查。
• 後續若要補更多欄位、例子或 parser 注意事項，也能和 skills.md、skills.json 放在同一條 current-game 文件線上。

Source Of Truth

.ski 說明的主要依據是：

• src/load.c
  • load_skill()
  • load_damage()
• src/body.c
  • random_situs()
• src/merc.h
  • SKILL_DATA
  • DAMAGE_DATA
  • LIMIT_DATA
• data/symbol.def
  • TAR_*
  • COST_*
  • WEAPON_*
  • RATING_*
  • ATTACK_*
• data/situs.txt
  • 實際部位權重與名稱

檔案位置與載入方式

• 索引檔：skill/skill.lst
• 實際技能檔：skill/<首字母>/<name>.ski
• loader 會先讀 skill/skill.lst，再依英文名稱首字母去對應子資料夾。

例：

• gold_blade
• 實際檔案在 skill/g/gold_blade.ski

以 gold_blade.ski 為例

skill/g/gold_blade.ski 是一個典型的近戰攻擊技能，主體可分成兩層：

1. 技能主欄位
2. 多個 #Damage 區塊

技能主欄位決定這個技能「是什麼、誰能用、怎麼啟用、耗什麼資源」。 #Damage 區塊則決定「一招一式的敘述、機率、傷害、命中部位與附帶效果」。

主欄位

#Damage 區塊

每個 #Damage 都是一個可被抽到的招式片段。

常見枚舉值

Type

來自 data/symbol.def 的 TAR_*：

Costtype

Position

Weapon

Rating

Situs 是什麼

Situs 是 #Damage 內的「命中部位 mask」。

例：

Situs           ATTACK_RANDOM

這行不是裝備欄位，也不是 data/situs.txt 裡那個 Situs = 頭部/手部/... 文字欄。 它實際上是：

• 在 .ski 裡指定一個 ATTACK_* mask
• 交給 src/body.c 的 random_situs() 選出本次命中的實際部位
• 再由 data/situs.txt 中各部位的 Chance 權重決定偏向哪裡

常見 Situs 值

ATTACK_RANDOM 的實際效果

ATTACK_RANDOM 在 src/merc.h 中是 0，但 src/body.c 會把 ATTACK_RANDOM 或 0 特判成「對全部可用部位做 weighted random」。

也就是說：

• 它不是「沒有命中部位」
• 而是「交給 body system 依 data/situs.txt 權重挑一個部位」

所以 gold_blade.ski 裡一整串：

Situs           ATTACK_RANDOM

代表這些刀招都不是固定砍頭或砍手，而是用一般近戰的隨機命中部位邏輯。

Limit 怎麼看

Limit 一行格式是：

Limit           <CLASS_*> <最低等級> <熟練度上限>

例：

Limit           CLASS_FIGHTER    1  40
Limit           CLASS_GENERAL    1  90
Limit           CLASS_BRAVO      1  90

意思是：

• fighter 1 級可學，但上限 40
• general 1 級可學，上限 90
• bravo 1 級可學，上限 90

這裡的第三欄不是百分比字串，而是 loader 直接讀入的 adept 上限數值。

常見維護規則

• Name、Slot、檔名、skill/skill.lst key 必須一致且全域唯一。
• 如果新增技能，至少一起檢查：
  • skill/skill.lst
  • src/merc.h 的 SLOT_*
  • data/symbol.def
  • skill/<letter>/<name>.ski
• Valid NO、CanAsk NO、Teach NO 常用於 NPC-only 技能，但不代表可以省略其他 runtime 欄位。
• Qutoient 是 repo 既有拼字，不要擅自改成 Quotient。
• ATTACK_RANDOM 雖然值為 0，但有特殊語意，不能當成「未設定」直接刪掉。

建議後續擴充

如果你要把這頁做成長期維護入口，下一步最值得補的是：

1. 加一張「.ski 欄位 -> SKILL_DATA 成員 -> loader case」對照表。
2. 補 #Affect、#Restrict、Effect 的完整範例。
3. 再做一頁「常見欄位值字典」，把 TAR_*、WEAPON_*、RATING_*、ATTACK_* 分頁整理。

這三塊我已先拆出第二頁：

• 進階 Loader Reference

例子來源：skill/g/gold_blade.ski、src/load.c、src/body.c、src/merc.h、data/symbol.def、data/situs.txt