模组:物品數據

出自Stardew Valley Wiki
跳至導覽 跳至搜尋

← 目錄

本頁面解釋遊戲如何存儲和解析物品數據。這是一個面向模組開發者的高級指南。

特別注意：本頁面暫且嚴格區分物品（item）與物體（object）這兩個術語。 其中物體特指物品類型為Object(O)的物品，它們是物品的真子集。

簡介

綜述

對於星露谷物語1.6而言，遊戲中的物品有一些重要的特性：

  1. 每個物品都有一個字符串ID（ItemId，物品ID）和一個全局唯一的字符串ID （QualifiedItemId，限定性物品ID）。其中，QualifiedItemId是通過向ItemId添加物品類型標識符前綴而自動生成的。

    由於歷史原因，原版物品的ItemId可能並不唯一。例如，河豚（物體128）和蘑菇箱[1]（大型打造品128）有相同的物品ID，即ItemId: 128。但可以通過QualifiedItemId區分兩者，前者為(O)128，後者為(BC)128。

  2. 每個物品類型在遊戲中都有一個物品數據定義以告訴遊戲如何處理它。C#模組可以添加或編輯定義。每個定義都有一個唯一的前綴，用在限定性物品ID中。原版的類型包括大型打造品（(BC)），靴子（(B)），農舍地板（(FL)），家具（(F)），帽子（(H)），物體（(O)），褲子（(P)），上衣（(S)），工具（(T)），牆紙（(WP)）和武器（(W)）。
  3. 自定義物品現在可以提供它們自己的物品貼圖，後者在物品數據素材的一個新欄位中指定（見下文）。物品的ParentSheetIndex欄位是相應貼圖的索引。

換而言之，物品的四個重要的欄位是：

名稱 類型 描述
ItemId string 此物品的唯一字符串ID，應當在全局唯一（為了向前兼容，原版遊戲的某些物品的ID未必唯一）。例如，128（原版物品）或 Example.ModId_Watermelon（自定義物品）。
QualifiedItemId string 全局唯一的物品鍵名，類似於原版物品的(O)128或自定義的(O)Example.ModId_Watermelon。此欄位由TypeDefinitionId和ItemId欄位自動生成。
ParentSheetIndex int 物品貼圖集中的貼圖索引。
TypeDefinitionId string 定義此物品的數據定義的ID，例如(O)代表物品（object）。可在此欄位使用 ItemRegistry.type_*常量： 
if (item.TypeDefinitionId == ItemRegistry.type_object)
   ...

物品引用

現在遊戲代碼中使用ItemId引用物品，取代了ParentSheetIndex。對於原版中已存在的物品而言，ItemId和其索引相同，因此此改動並不影響大部分的數據素材。例如，此處展示了Data/NPCGiftTastes中的一個條目，它定義了普遍受歡迎的禮物列表，包括一系列原版ID，以及一個自定義物品ID： 

"Universal_Like": "-2 -7 -26 -75 -80 72 395 613 634 635 636 637 638 724 459 Example.ModID_watermelon"

除非另有說明，否則非限定性物品ID會產出物體。某些素材允許您通過指定QualifiedItemId的值來重寫此設定。例如，您可以添加 (O)128到禮物喜好列表來強制添加一個物體。此處是數據素材及其支持的物品ID格式：

數據素材 物品ID格式
Data/CraftingRecipes
Data/CookingRecipes
  • 原料: 兩種ID均支持
  • 產品：欄位2須為非限定ID，欄位3為true（大型打造品）或 false（物體）。
Data/FruitTrees
  • 水果：兩種ID均支持
  • 樹苗：僅支持非限定ID。
Data/NPCGiftTastes 兩種ID均支持，但只有(O)類型的物品可用於送禮。

物品標識

現在遊戲代碼中使用ItemId作為物品標識，取代了ParentSheetIndex。對於原版中已存在的物品而言，ItemId和其索引相同，因此此改動並不影響大部分的數據素材。例如，此處展示了Data/NPCGiftTastes中的一個條目，它定義了普遍受歡迎的禮物列表，包括一系列原版ID，以及一個自定義物品ID： 

"Universal_Like": "-2 -7 -26 -75 -80 72 395 613 634 635 636 637 638 724 459 Example.ModID_watermelon"

除非另有說明，否則非限定性物品ID會產出物體。某些素材允許您通過指定QualifiedItemId的值來重寫此設定。例如，您可以添加 (O)128到禮物喜好列表來強制添加一個物體。此處是數據素材及其支持的物品ID格式：

數據素材 物品ID格式
Data/CraftingRecipes
Data/CookingRecipes
  • 原料: 兩種ID均支持
  • 產品：欄位2須為非限定ID，欄位3為true（大型打造品）或 false（物體）。
Data/FruitTrees
  • 水果：兩種ID均支持
  • 樹苗：僅支持非限定ID。
Data/NPCGiftTastes 兩種ID均支持，但只有(O)類型的物品可用於送禮。

物品類型

以下是自定義物品能夠添加/編輯的物品類型：

物品類型 類型標識符 數據資源
大型打造品 (BC) Data/BigCraftables
每個物品可以在Texture欄位設置一個自定義貼圖名稱，以及可以在SpriteIndex欄位設置貼圖索引。默認貼圖為TileSheets/Craftables。
靴子 (B) Data/Boots
每個物品可以在欄位9（物品）和欄位7（靴子顏色）中設置自定義貼圖名稱，以及可以在欄位8（物品）和欄位5（靴子顏色）設置貼圖索引。默認貼圖為Maps/springobjects（物品）和 Characters/Farmer/shoeColors（靴子顏色）。
作物 技術上而言並非物品類型 Data/Crops
每種作物可以設置自定義貼圖名稱和貼圖索引。默認貼圖是TileSheets/crops。
魚缸魚類 技術上而言並非物品類型 Data/AquariumFish
每種魚可以在欄位6設置自定義魚缸貼圖，以及在欄位0設置貼圖索引。默認貼圖為LooseSprites/AquariumFish。
家具 (F) Data/Furniture
每個物品都可以在欄位9設置自定義貼圖名稱，以及在欄位8設置貼圖索引。默認貼圖為TileSheets/furniture。
果樹 技術上而言並非物品類型 Data/FruitTrees
每種果樹可以設置自定義貼圖名稱和貼圖索引。默認貼圖為ETileSheets/fruitTrees。
帽子 (H) Data/Hats
每種物品可以在欄位7設置自定義貼圖名稱，以及在欄位6設置貼圖索引。默認貼圖為Characters/Farmer/hats。
物體 (O) Data/Objects
每個物品可以在Texture欄位設置自定義貼圖名稱，以及在SpriteIndex欄位設置貼圖索引。默認貼圖為 Maps/springobjects。
褲子 (P) Data/pantsData
每個物品可以在Texture欄位設置自定義貼圖名稱，以及在SpriteIndex欄位設置貼圖索引。 默認貼圖為Characters/Farmer/pants。
上衣 (S) Data/shirtData
每個物品可以在Texture欄位設置自定義貼圖名稱，以及在SpriteIndex欄位設置貼圖索引。 默認貼圖為Characters/Farmer/shirts。

上衣貼圖的寬度必須嚴格為256像素，分為兩半：左半邊為上衣貼圖，右半邊為染色這招。餘下空間如有需要可留空。 

        贴图          染色遮罩
   /-----------\  /-----------\
┌────────────────────────────────┐
│ ┌───┐┌───┐┌───┐┌───┐┌───┐┌───┐ │
│ │ 0 ││ 1 ││ 2 ││ a ││ b ││ c │ │
│ └───┘└───┘└───┘└───┘└───┘└───┘ │
│ ┌───┐┌───┐┌───┐┌───┐┌───┐┌───┐ │
│ │ 3 ││ 4 ││ 5 ││ d ││ e ││ f │ │
│ └───┘└───┘└───┘└───┘└───┘└───┘ │
└────────────────────────────────┘
工具 (T) Data/Tools
每個物品可以在Texture欄位設置自定義貼圖名稱，以及在SpriteIndex欄位設置貼圖索引。原版工具使用TileSheets/Tools貼圖。
牆紙&地板 (WP) 和 (FL) Data/AdditionalWallpaperFlooring
參見 格式文檔.
武器 (W) Data/Weapons

當遊戲嘗試解析非限定性物品ID如128時，會按如下順序檢索各物品類型：物品、大型打造品、家具、武器、靴子、帽子、褲子、上衣、工具、牆紙、地板。

對於每個物品類型，Content文件夾中都有對應的兩個文件（可以 解包以編輯）：

  • 一個數據素材文件，存儲物品的文本數據（名稱、描述、價格...）；
  • 一個貼圖集文件，存儲物品在遊戲中的圖標。

每個物品都有一個ParentSheetIndex欄位，指示其在此類物品貼圖集中的位置。該索引從左到右、從上到下、從0開始計數。例如，帽子#0是Characters/Farmer/hats中的第一個貼圖。而ParentSheetIndex也常用於鑑別物品；但由於貼圖集索引並不是唯一的（例如帽子#10和物體#10難以區分），代碼需要檢查物品類型，就像item is Weapon weapon && weapon.ParentSheetIndex == 4。

獲取物品列表

安裝SMAPI後，您可以運行list_items控制台命令以瀏覽/搜索物品及其ID。

自定義物品

您可以使用Content Patcher或SMAPI的Content接口來定義原版中大部分「物體」類型的自定義物品。

例如，此內容包添加了一個自定義的河豚雞（Pufferchick）物品，包括自定義圖形、自定義禮物喜好、產出它的自定義作物。注意在其他數據素材中（例如Data/Crops或Data/NPCGiftTastes），物品引用須使用物品ID。 

{
    "Format": "2.3.0",
    "Changes": [
        // 添加物品
        {
            "Action": "EditData",
            "Target": "Data/Objects",
            "Entries": {
                "{{ModId}}_Pufferchick": {
                    "Name": "{{ModId}}_Pufferchick", // best practice to match the ID, since it's sometimes used as an alternate ID (e.g. in Data/CraftingRecipes)
                    "Displayname": "Pufferchick",
                    "Description": "An example object.",
                    "Type": "Seeds",
                    "Category": -74,
                    "Price": 1200,

                    "Texture": "Mods/{{ModId}}/Objects",
                    "SpriteIndex": 0
                }
            }
        },

        // 添加礼物喜好
        {
            "Action": "EditData",
            "Target": "Data/NPCGiftTastes",
            "TextOperations": [
                {
                    "Operation": "Append",
                    "Target": ["Entries", "Universal_Love"],
                    "Value": "{{ModId}}_Pufferchick",
                    "Delimiter": " " // 若已存在值，则添加空格
                }
            ]
        },

        // 添加作物（Pufferchick同时为种子和产物，就像咖啡豆）
        {
            "Action": "EditData",
            "Target": "Data/Crops",
            "Entries": {
                "{{ModId}}_Pufferchick": {
                    "Seasons": [ "spring", "summer", "fall" ],
                    "DaysInPhase": [ 1, 1, 1, 1, 1 ],
                    "HarvestItemId": "{{ModId}}_Pufferchick",

                    "Texture": "Mods/{{ModId}}/Crops",
                    "SpriteIndex": 0
                }
            }
        },

        // 添加物品+作物图片
        {
            "Action": "Load",
            "Target": "Mods/{{ModId}}/Crops, Mods/{{ModId}}/Objects",
            "FromFile": "assets/{{TargetWithoutPath}}.png" // assets/Crops.png, assets/Objects.png
        }
    ]
}

大多數物品數據素材的工作方式就像Data/Objects。另請參閱關於自定義果樹、自定義工具和近戰武器的詳細信息。

錯誤物品

在早於1.6的版本中，沒有數據的物品（例如當您移除了對應的模組時）會導致諸如不可見物品、錯誤、崩潰的問題。這種問題在一定程度上被捆綁的Error Handler模組減輕。

星露谷物語1.6添加了處理這類物品的完整機制。此類物品會在物品欄UI和遊戲中顯示為🛇貼圖，名稱為Error Item，並附有指示物品ID的描述，以便於問題修復。


關於C#模組

比較物品
因為Item.QualifiedItemId全局唯一，因此可用於比較物品。例如：
舊代碼 新代碼
item.ParentSheetIndex == 128 item.QualifiedItemId == "(O)128"
IsNormalObjectAtParentSheetIndex(item, 128) item.QualifiedItemId == "(O)128"
!item.bigCraftable && item.ParentSheetIndex == 128 item.QualifiedItemId == "(O)128"
item is Boots && item.ParentSheetIndex == 505 item.QualifiedItemId == "(B)505"

亦可使用ItemRegistry.QualifyItemId將任何物品ID轉換為限定性物品ID（若可行），及使用ItemRegistry.HasItemId以檢查某個物品是否擁有限定性/非限定性物品ID。

注意，有特定風味的物品沒有單獨的ID。例如，「藍莓果酒」和「果酒」的ID都是(O)348。此特性影響果醬、果汁、醃菜和果酒。在這種情形下，您仍應當比較它們有區別的欄位而不是ID，例如preservedParentSheetIndex欄位（該欄位實際上包含了它們原材料的ItemId，而不是它們的ParentSheetIndex）。

構造物品
構造物品時，請指定其ItemId（而不是QualifiedItemId）。例如： 
new Object("128", 1);                      // 原版物品
new Object("Example.ModId_Watermelon", 1); // 自定义物品

您可以使用如下實用方法來從QualifiedItemId構造物品： 

Item item = ItemRegistry.Create("(B)505"); // 橡胶靴
自定義物品類型
您可以實現IItemDataDefinition以自定義物品類型，並調用ItemRegistry.AddTypeDefinition以註冊之。這提供了遊戲所需的處理物品類型的一切邏輯：何處獲取物品數據、如何繪製物品等等。 自定義物品類型是高度專業化的，且對於多人遊戲的兼容性未知。大部分模組應當添加屬於已有類型的物品，而非新建類型。
全新Is*方法
1.6添加了一些StardewValley.Object方法，以使用通用方式處理自定義物品（並允許模組修改邏輯）：
方法 效果
object.IsBar() 物品是否為銅錠、鐵錠、金錠、銥錠其中之一。
object.IsBreakableStone() 物品是否為可以被十字鎬打破的碎石類物品。
object.IsFence() 物品是否為圍欄。
object.IsFruitTreeSapling() 物品是否為果樹樹苗。此命令會檢查Data\fruitTrees鍵，因此對自定義果樹亦有效。
object.IsHeldOverHead() 當物品在工具欄時，是否顯示玩家手持該物品。默認為true（家具除外）。
object.IsIncubator() 物品放在建築里時可否用於孵化農場動物的蛋。
object.IsTapper() 物品是否為樹液採集器或重型樹液採集器。
object.IsTeaSapling() 物品是否為茶苗。
object.IsTwig() 物品是否為樹枝（雜物）。
object.IsWeeds() 物品是否為雜草。
使用物品元數據
1.6添加了一個ItemRegistry API以便使用全新的物品系統。提供了如下方法：
方法 效果
ItemRegistry.Create 從物品ID（限定性或非限定性）創建物品。若ID無法匹配已知的物品，則可選參數allowNull規定了此時返回空值還是返回錯誤物品。例如： 
Item item = ItemRegistry.Create("(B)505"); // 橡胶靴

如有需要，您亦可獲得Item以外的指定類型。若類型不匹配（例如嘗試將家具轉換為靴子），則會拋出描述性的異常。 

Boots item = ItemRegistry.Create<Boots>("(B)505"); // 橡胶靴
ItemRegistry.Exists 給定的限定性/非限定性ID是否能匹配存在的物品。例如： 
bool pufferfishExist = ItemRegistry.Exists("(O)128");
ItemRegistry.IsQualifiedId 給定的物品ID是否已添加限定性類型前綴（例如(O)128而非128）。
ItemRegistry.QualifyItemId 給定限定性/非限定性物品ID，給出唯一的限定性ID。例如： 
string qualifiedId = ItemRegistry.QualifyItemId("128"); // 返回 (O)128
ItemRegistry.GetMetadata 獲取關於物品的高級信息： 
// 获取关于橡胶靴的信息
ItemMetadata info = ItemRegistry.GetMetadata("(B)505");

// 获取物品ID信息
$"The item has unqualified ID {info.LocalId}, qualified ID {info.QualifiedId}, and is defined by the {info.TypeIdentifier} item data definition.";

// 物品是否存在于数据文件中？
bool exists = info.Exists();

獲取物品通用的、解析後的數據： 

// 获取解析后的信息
ParsedItemData data = info.GetParsedData();
$"The internal name is {data.InternalName}, translated name {data.DisplayName}, description {data.Description}, etc.";

// 绘制物品贴图
Texture2D texture = data.GetTexture();
Rectangle sourceRect = data.GetSourceRect();
spriteBatch.Draw(texture, Vector2.Zero, sourceRect, Color.White);

創建物品： 

Item item = metadata.CreateItem();

獲取類型定義（注意，此操作高度專業化。通常情況下您應當轉而使用ItemRegistry，以獲取緩存和優化上的好處）： 

IItemDataDefinition typeDefinition = info.GetTypeDefinition();
ItemRegistry.ResolveMetadata 相當於ItemRegistry.GetMetadata，除了物品不存在時會返回空值。
ItemRegistry.GetData 獲取某個物品解析後的數據，若不存在則返回null。這是ItemRegistry.ResolveMetadata(id)?.GetParsedData()的簡寫；參見前一方法以獲得關於解析後的數據的信息。
ItemRegistry.GetDataOrErrorItem 相當於ItemRegistry.GetData，除了物品不存在時會返回錯誤物品的信息（例如，在物品欄中繪製）。
ItemRegistry.GetErrorItemName 獲取翻譯後的Error Item標籤。

公共數據

品質

每個物品都有一個品質等級，該等級（依賴於物品類型）可能影響物品的售價、生命值回復等。可用的品質如下：

品質 值 常量名
普通 0 Object.lowQuality
銀星 1 Object.medQuality
金星 2 Object.highQuality
銥星 4 Object.bestQuality

類別

每個物品都有一個類別（使用負整數表示）。在代碼中，可以通過item.Category獲取物品類別，以及可以通過item.getCategoryName()獲取其翻譯後的名稱。可用的類別如下：

值 內部常量名 上下文標籤 中文翻譯 屬性
-2 Object.GemCategory category_gem 礦物 受寶石專家職業影響。
-4 Object.FishCategory category_fish 魚 受漁夫和垂釣者職業影響。
-5 Object.EggCategory category_egg 動物製品 受畜牧人職業影響。可用於彈弓。
-6 Object.MilkCategory category_milk 動物製品 受畜牧人職業影響。
-7 Object.CookingCategory category_cooking 菜品
-8 Object.CraftingCategory category_crafting 製造品 可放置
-9 Object.BigCraftableCategory category_big_craftable 可放置
-12 Object.mineralsCategory category_minerals 礦物 受寶石專家職業影響。
-14 Object.meatCategory category_meat 動物製品
-15 Object.metalResources category_metal_resources 資源
-16 Object.buildingResources category_building_resources 資源
-17 Object.sellAtPierres category_sell_at_pierres
-18 Object.sellAtPierresAndMarnies category_sell_at_pierres_and_marnies 動物製品 受畜牧人職業影響。
-19 Object.fertilizerCategory category_fertilizer 肥料 可放置、可穿行
-20 Object.junkCategory category_junk 垃圾
-21 Object.baitCategory category_bait 魚餌 可以用於釣竿。
-22 Object.tackleCategory category_tackle 魚鉤 可以用於釣竿。不可堆疊。
-23 sellAtFishShopCategory category_sell_at_fish_shop
-24 Object.furnitureCategory category_furniture 裝飾
-25 Object.ingredientsCategory category_ingredients 菜品
-26 Object.artisanGoodsCategory category_artisan_goods 工匠物品 受工匠職業影響。
-27 Object.syrupCategory category_syrup 工匠物品 受萃取者職業影響。
-28 Object.monsterLootCategory category_monster_loot 怪物戰利品
-29 Object.equipmentCategory category_equipment
-74 Object.SeedsCategory category_seeds 種子 可放置。可穿行。
-75 Object.VegetableCategory category_vegetable 蔬菜 受農耕人職業影響。可用於彈弓。
-79 Object.FruitsCategory category_fruits 水果 受農耕人職業影響（若非採集水果）。可用於彈弓。
-80 Object.flowersCategory category_flowers 花 受農耕人職業影響。
-81 Object.GreensCategory category_greens 採集品
-95 Object.hatCategory category_hat
-96 Object.ringCategory category_ring
-98 Object.weaponCategory category_weapon
-99 Object.toolCategory category_tool
控制台命令 
若安裝了Console Code模組，則可在SMAPI控制台運行如下命令以參見分好類別的物品列表： 
cs return string.Join(`\n`, Game1.objectData.Keys.Select(key => new StardewValley.Object(key, 1)).GroupBy(item => item.Category, item => item.Name).OrderByDescending(p => p.Key).Select(p => $`{p.Key}: {string.Join(`, `, p.OrderBy(name => name))}`));

上下文標籤

上下文標籤是附加在物品上的任意數據標籤。它們可以在遊戲中產生各種效果，也可能沒有任何效果而僅起到提示作用。上下文標籤對大小寫不敏感。遊戲會基於遊戲數據（例如品質）生成一些標籤，而其他標籤都定義在Data/Objects中。

下面是原版遊戲中添加或使用的上下文標籤的不完全列表。模組可以添加自定義的上下文標籤，這裡沒有列出。

自動添加到所有物品：
上下文標籤 效果
category_<category> 基於物品類別自動添加的標籤。參見物品類別列表中'上下文標籤'一列以獲取可能的取值。
fish_<metadata> 基於Data/Fish中的魚類元數據自動添加的魚類物品標籤。

對於蟹籠魚類（也就是類型為trap的魚類）：

上下文標籤 說明
fish_trap_location_<water type> 基於欄位2（'darting randomness'）。例如， fish_trap_location_ocean。

對於釣竿魚類（依舊是類型不是trap的魚類）：

上下文標籤 說明
fish_difficulty_<difficulty> 基於欄位1 ('chance to dart')，其中<difficulty>取easy (0–33), medium (34–66), hard (67–100), 或extremely_hard (101+)其中之一。 例如，fish_difficulty_hard.
fish_motion_<motion> 基於欄位4 ('location') 。例如fish_motion_floater。
fish_favor_weather_<weather> 基於欄位7 ('weather') 。例如fish_favor_weather_sunny。
id_<type>_<identifier> 自動添加。作為ID的另一版本。其中<type>為下列之一：B (靴子), BBL (大型打造品配方), BL (物品配方), BO (大型打造品), C (衣服), F (家具), H (帽子), O (物體), R (戒指), W (近戰武器)，否則為空。<identifier>是物品的貼圖集索引。例如河豚的值為id_o_128 (物體#128)。
item_<name> 基於物品名稱自動添加。名稱為全小寫且不含空格和單引號，其中空格使用下劃線替代。例如 《1000年後》('1000 Years From Now')具有上下文標籤item_1000_years_from_now。
向「物體」類型的物品自動添加。
上下文標籤 效果
jelly_item
juice_item
pickle_item
wine_item 		適用於小桶或罐頭瓶的產品。為被加工物品的類型。
preserve_sheet_index_<id> 適用於小桶或罐頭瓶產出的物品。為被加工物品的貼圖集索引。例如，藍莓果酒的上下文標籤為preserve_sheet_index_258，其中258是藍莓的貼圖集ID。
quality_none
quality_silver
quality_gold
quality_iridium 		基於物品品質自動添加。
quality_qi 在齊先生的菜餚特別任務期間自動添加。
Color tags:
上下文標籤 效果
color_* 顏色標籤，用在如下遊戲功能中：艾米麗的家中的染料罐、特定機器產出品著色（如果酒和醃菜）、讀書動畫等。 因為此標籤用於著色，所以每個標籤都有一個特定的RGB值，除了艾米麗的染料罐；染料罐有如下的上下文標籤組織形式：
染料罐 上下文標籤
紅色 color_red, color_salmon, color_dark_red, color_pink
橙色 color_orange, color_dark_orange, color_dark_brown, color_brown, color_copper
黃色 color_yellow, color_dark_yellow, color_gold, color_sand
綠色 color_green, color_dark_green, color_lime, color_yellow_green, color_jade, color_sea_green
藍色 color_blue, color_dark_blue, color_dark_cyan, color_light_cyan, color_cyan, color_aquamarine
紫色 color_purple, color_dark_purple, color_dark_pink, color_pale_violet_red, color_poppyseed, color_iridium
無彩色 color_black, color_gray, color_dark_gray, color_white, color_iron, color_prismatic
1.6添加的標籤
上下文標籤 效果
campfire_item 將物品標記為篝火。若物品還具有torch_item上下文標籤，則其被放置且開啟後產生如下效果：
  • 篝火的火焰會在其上繪製
  • 若為大型打造品，光線會從其中心而非頂部發出。
fish_pond_ignore 禁止玩家將此種魚類放入魚塘，即使此種魚類匹配Data/FishPondData的條目。
geode_crusher_ignored 禁止使用晶球破開器破開此物品，即使此物品在Data/Objects中有晶球欄位。
item_type_<type> 適用於物體。類型值取自「類型和類別」欄位。（非「物體」類型的物品標籤為item_type_，下劃線後沒有內容）。 此標籤自動添加，且不應手動設置。在某些地方可能檢查該標籤（例如，博物館會以此檢查物品是否為古物或礦物），但遊戲大部分不受影響。
museum_donatable
not_museum_donatable 		設置此物品可否捐給博物館，以重寫原版邏輯。
not_giftable 禁止玩家將此物品作為禮物贈送給村民。村民會完全忽略此物品（就像你拿的工具一樣）。

此標籤僅影響禮物贈予，並不影響諸如任務目標或特別請求目標的遊戲邏輯。若該村民有此物品的reject_*對話，則該對話有更高優先級。

not_placeable
placeable 		設置物品是否可以放在地上。
prevent_loss_on_death 表示此物品在玩家暈倒時不會丟失。
sign_item 標記此物品為標牌，允許玩家於其上顯示物品，或將其置於魚塘上以顯示魚數。
torch_item 標記此物品為火把，允許玩家打開/關閉它來發光。另請參閱campfire_item。
影響機器進程：
上下文標籤 效果
crystalarium_banned 應用於寶石或礦物，禁止玩家使用寶石複製機複製它。
keg_juice
keg_wine 		允許使用小桶將此物品加工為果汁或果酒。
preserves_jelly
preserves_pickle 		允許使用罐頭瓶將此物品加工為果醬或醃菜。
seedmaker_banned 用於種子物品，禁止玩家將其放入種子生產器。
tapper_item 標記此物品為樹液採集器或重型樹液採集器。
tapper_multiplier_<multiplier> 影響樹液採集器產出速率的乘數。例如，2會使得物品產出時間縮短到原先的一半（即每個物品都會在base time/speed multiplier時間內完成）。若省略，默認為1。
對遊戲邏輯無影響的提示性標籤：
上下文標籤 效果
fish_legendary
fish_legendary_family 		標記此魚為傳說魚類或傳說之魚二代。僅用於提示；傳說魚類的行為實際上被CatchLimit和IsBossFish等數據欄位決定，這些欄位存儲在Data/Locations。
geode （自動添加） 標記此物品為晶球，可以在鐵匠鋪或使用晶球破開器打開。若晶球欄位出現在Data/Objects中，則自動添加此標籤。
id_<item id> （自動添加） 限定性物品ID，像id_(o)128。可用於匹配或排除物品。ID中任何空格會被替換為下劃線，而單引號會被刪除。
is_machine （自動添加） 表示物品具有機器邏輯。根據Data/Machines自動添加。
machine_input （自動添加） 物品是否為接受玩家輸入的機器。基於Data/Machines中的如下欄位自動添加：
  • 當HasInput為true；
  • 或者當任何輸出規則有ItemPlacedInMachine觸發器。
machine_output （自動添加） 物品是否為產出玩家可收集物品的機器。基於Data/Machines中的如下欄位自動添加：
  • 當HasOutput為true;
  • 或者有任何輸出規則。

某些遊戲數據也以通用方式引用上下文標籤。例如，您可以向物品添加自定義標籤，然後在魚塘數據中引用它們。特別地，

遊戲數據 效果
魚塘 存儲在Data/FishPondData。用於匹配能夠放進魚塘的魚（參見數據文件中的RequiredTags）。
特別任務 存儲在Data/SpecialOrders。用於匹配滿足任務目標的物品（參見數據文件中的AcceptedContextTags）
裁縫 存儲在Data/TailoringRecipes。用於匹配某配方需要的物品。
禮物喜好 存儲在Data/NPCGiftTastes。用於使用上下文標籤設置角色喜歡和不喜歡的物品。

debug listtags 控制台命令 列出手持物品的所有上下文標籤

原始標籤 
此處給出從Data/ObjectContextTags提取的、上文未提及的標籤列表：alcohol_item, algae_item, ancient_item, beach_item, bomb_item, bone_item, book_item, ceramic_item, chicken_item, color_black, color_dark_gray, color_gray, color_iron, color_prismatic, color_white, cooking_item, cow_milk_item, cowboy_item, crop_year_2, dinosaur_item, doll_item, drink_item, dwarvish_item, dye_medium, dye_strong, egg_item, elvish_item, fertilizer_item, fish_bug_lair, fish_carnivorous, fish_crab_pot, fish_desert, fish_freshwater, fish_lake, fish_legendary, fish_mines, fish_night_market, fish_nonfish, fish_ocean, fish_pond, fish_river, fish_secret_pond, fish_semi_rare, fish_sewers, fish_swamp, fish_talk_demanding, fish_talk_rude, fish_talk_stiff, fish_upright, flower_item, food_bakery, food_breakfast, food_cake, food_party, food_pasta, food_salad, food_sauce, food_seafood, food_soup, food_spicy, food_sushi, food_sweet, forage_item, forage_item_beach, forage_item_cave, forage_item_desert, forage_item_mines, forage_item_secret, fossil_item, fruit_item, fruit_tree_item, furnace_item, ginger_item, goat_milk_item, golden_relic_item, honey_item, hunting_item, instrument_item, jelly_item, juice_item, large_egg_item, large_milk_item, light_source, machine_item, marine_item, mayo_item, medicine_item, milk_item, noble_item, ore_item, pickle_item, potion_item, prehistoric_item, quality_fertilizer_item, scroll_item, season_all, season_fall, season_spring, season_summer, season_winter, slime_egg_item, slime_item, statue_item, strange_doll_1, strange_doll_2, syrup_item, totem_item, toy_item, trash_item, tree_seed_item, wood_item.

ItemContextTagManager類

對於C#模組，ItemContextTagManager類簡化了上下文標籤的使用，且減少了重複代碼。

提供了一些工具方法：

方法 效果
GetBaseContextTags(id) 基於物品在Data/Objects或Data/BigCraftables中的原始數據獲取其基本上下文標籤。其中不包括基於實例類型添加的動態標籤（如品質），後者可以使用item.GetContextTags()獲取。
DoesTagQueryMatch(query, tags) 判斷上下文標籤查詢是否匹配給定標籤。例如，ItemContextTagManager.DoesTagQueryMatch("bone_item, !fossil_item", item.GetContextTags())在物品為骨頭物品但不是化石才返回true（例如骨笛）。
DoAllTagsMatch(requiredTags, actualTags)
DoAnyTagsMatch(requiredTags, actualTags) 		判斷是否每個（DoAllTagsMatch）或至少一個（DoAnyTagsMatch） 給出的標籤能匹配實際的標籤。此方法亦支持反向匹配，例如"!fossil_item"。
DoesTagMatch(requiredTag, actualTags) 判斷給出的單個標籤是否匹配實際的標籤。此方法亦支持反向匹配，例如"!fossil_item"。
SanitizeContextTag(tag) （專用） 替換物品名稱中可能出現的標點，使其可用於上下文標籤。例如，SanitizeContextTag("Sam's Boombox")返回sams_boombox。

物體

物體是放在背包或世界中的物品的默認類型。

物體數據存儲於Data/Objects（早於1.6的版本中為Data/ObjectInformation），其圖標貼圖存儲在Maps/springobjects，其代碼存儲在StardewValley.Object。

數據格式

Data/Objects中儲存的物體數據包括一個「字符串 → 數據模型」查詢，其中

  • 鍵為非限定性物品ID。
  • 值為包括如下欄位的數據模型。

基本信息

欄位 含義
Name 物品內部名稱
DisplayName
Description 		用於遊戲內顯示名稱和描述的模板字符串。
Type 物品大體上的類型，比如Arch（古物）或 Minerals（礦物）。原版類型為：Litter, Basic, Minerals, Quest, asdf, Crafting, Arch, fish, Cooking, Seeds, Ring, interactive
Category 物品類別。
Price （可選） 玩家售出該物品的價格。注意：這不是玩家從商店購買的價格。默認為0。

外觀

欄位 含義
Texture 包含此物品貼圖的素材名稱。默認為Maps/springobjects。
SpriteIndex Texture中的貼圖索引，其中0對應左上角的貼圖。

可食性

欄位 含義
Edibility （可選） 一個數值，用於決定食用該物品可以回復多少點能量（可食性 × 2.5）和生命（可食性 × 1.125）。可食性為-300的物品不可食用，而-299至-1之間的值會減少生命值和能量，取值為0的物品也可食用，但不會改變生命值/能量。默認為-300。
IsDrink （可選） 該物品是否為飲品（而非食品）。默認為false。
Buffs （可選） 玩家食用該物品可能獲得的諸效果。默認為none。

本欄位的值為包含如下欄位的一些數據模型所組成的列表：

欄位 含義
Id 列表中此項目的唯一字符串ID。
Duration （若設置了BuffId，則可選） 效果持續時長，為遊戲內的分鐘數。可以設為-2，代表效果將在當天一直持續下去。
BuffId （可選） 欲應用效果的唯一ID，此ID來自Data/Buffs。也可設為null，這樣就會忽略Data/Buffs，並將ID設置根據物品的IsDrink欄位設為food或drink。

若應用了來自Data/Buffs的效果，且指定了其他欄位，則效果數據會按如下規則混合：

欄位 效果
Duration
IconTexture
SpriteIndex
GlowColor 		若指定此欄位，則使用Data/Objects中的數據，而不是Data/Buffs中的數據。若忽略，則默認使用來自Data/Buffs的數據。
CustomAttributes 同時使用來自Data/Objects和Data/Buffs的數值。（例如，Data/Objects中的速度+1和Data/Buffs中的速度+1會導致速度+2）。
IsDebuff 使用Data/Objects中的數值。
IsDebuff （可選） 此效果是否為負面效果，若是，則戴上結實戒指會減免一半時長。默認為false。
IconTexture （可選） 欲加載的圖標所在的資源名稱。該資源必須包含一個或以上的16x16圖標。當資源包含多個圖標時，這些圖標需要排布在一個尺寸任意的網格中。若忽略，則會基於BuffId和CustomAttributes欄位繪製默認圖標。
SpriteIndex （可選） 效果圖標在IconTexture中的索引。0代表左上角。默認為0。
GlowColor （可選） 玩家獲得此效果後的輝光顏色。參見顏色格式。默認為none。
CustomAttributes 自定義效果參數（若有）。

此欄位的值為一個包含如下欄位的數據模型，它由下列中的某些欄位組成：

欄位 含義
FarmingLevel
FishingLevel
ForagingLevel
LuckLevel
MiningLevel 		（可選） 效果對技能等級的增量。負面效果此值為負。默認為0。
Attack
Defense
MagneticRadius
MaxStamina
Speed 		（可選） 效果對玩家攻擊、防禦、磁性半徑、最大體力或速度的增量。負面效果此值為負。默認為0。
CustomFields （可選） 此條目的 自定義欄位。

晶球、遠古斑點

欄位 含義
GeodeDrops
GeodeDropsDefaultItems 		（可選） 將此物品（如晶球）敲開時可能掉落的物品。只需指定二者其一，即可自動啟用該物品的晶球行為。

您可以僅指定其中一個欄位，也可同時指定兩個欄位：

  • GeodeDrops應設為可能掉落的物品。默認為none。此欄位的值為包含以下欄位的數據模型：
    欄位 含義
    公共欄位 參見物品生成欄位以獲得晶球掉落物的通用物品欄位。

    若此欄位被設為返回多個物品的物品查詢，則隨機返回一個掉落物。

    Chance （可選） 在其他欄位均匹配的條件下，掉落該物品的概率。為 0（不可能）至 1（必然）之間的小數。默認為1。
    SetFlagOnPickup （可選） 當玩家撿起該掉落物時，設置的信件標識。
    Precedence （可選） 檢查該掉落物在所有可能掉落物中的優先級。越小，優先級越高。可以為負值。具有相同優先級的掉落物會按其在列表中的順序依次檢查。默認為0。

    為了一致性，原版掉落物主要使用如下數值：

    • -1000：特殊物品，例如金色頭盔；
    • 0：正常物品。
  • GeodeDropsDefaultItems 是否從默認的晶球的掉落物中隨機選取（例如粘土、煤炭、銅礦石、銥礦石等）。默認為false。

若同時指定兩個欄位，則會以50%的概率給出自定義掉落物或默認掉落物。但若指定了自定義掉落物GeodeDrops欄位，卻沒有任何匹配的掉落物，則強制使用默認掉落物GeodeDropsDefaultItems，無論該欄位是否為true。

ArtifactSpotChances （可選） 若為古物（即Type欄位為Arch），挖掘遠古斑點獲得它的概率。

該欄位為一個「字符串 → 數據模型」查詢，其中：

  • 鍵為的地點內部名稱；
  • 值為若檢查到此物品，生成此物品的概率，為0（不可能）至 1（必然）之間的小數。

上下文標籤 & 排除規則

field purpose
ContextTags （可選） 欲為該物品添加的自定義#上下文標籤。此處「自定義」是相對於那些自動添加的上下文標籤而言的。此欄位應為一個列表，例如： 
"ContextTags": [ "color_yellow", "fish_ocean", "fish_upright", "season_summer" ]
ExcludeFromRandomSale （可選） 商店選取隨機物品售賣時，是否排除該物品。默認為false。
ExcludeFromFishingCollection
ExcludeFromShippingCollection 		（可選） 是否將此物品從「釣魚」/「售出的物品」收集品菜單中排除，也會影響完美。默認為false，此時會使用通常情況的要求（例如，古物通常情況下不會計入「售出的物品」）。

高級

欄位 含義
CustomFields （可選） 此條目的自定義欄位。

說明

  • 在早於1.6的版本中，在索引6（即「打造」欄位）中有數值的物品將在遊戲中顯示錯誤信息（例如，早於1.4版本的豆類火鍋）。在「攻擊」欄位中有數值的物品將顯示攻擊圖標和一個數字，但沒有描述。我們幾乎完全不知曉這些效果的機制。
  • 不推薦添加自定義的Arch類型物品。因為這經常導致挖掘遠古斑點卻沒有掉落物。
  • 已命名的增益效果（例如蒜油、生命藥水或增益效果#眩暈）是在遊戲代碼中實現的，不能通過食物效果欄位設置。
  • 貼圖集和遊戲數據中有一些通常不能出現在玩家背包的物品，例如，樹枝（Twig）存在於數據和貼圖集中，但無法放入背包；還有有一些僅出現在數據文件中而沒有對應貼圖的物品，比如「Lumber」（物品ID (O)30）。還有一些沒有對應物品數據的物品。數據文件中還有多個名為 Weed（雜草）和 Stone（石頭）的條目，但玩家通常只能獲得ID為390的 Stone，且不能獲得 Weed。

大型打造品

大型打造品是指可放置、兩格高（而非一格）的物品。

其數據存儲在Data/BigCraftables（早於1.6的版本中為Data/BigCraftablesInformation ）。其貼圖存儲在TileSheets/Craftables。其代碼存儲在StardewValley.Object （帶有 bigCraftable.Value = true標籤）。

數據格式

數據格式為一個「字符串 → 數據模型」查詢，其中：

  • 鍵名為非限定性物品ID。
  • 值為包含如下欄位的數據模型。

基本信息

欄位 含義
Name 內部物品名稱。
DisplayName
Description 		遊戲內顯示名稱和描述的模板字符串。
Price （可選） 玩家售出的價格。不是購入的價格。默認為0。

行為

欄位 含義
Fragility （可選） 物品如何拾起。可能的取值為 0（任意工具）、1（使用斧子/鋤頭/十字鎬可破壞，其他工具可拾起）或 2 （放置後無法移除）。默認為0。
CanBePlacedIndoors
CanBePlacedOutdoors 		（可選） 是否可以放置在室內/外。默認都為true。
IsLamp （可選） 是否為檯燈，以決定天黑時是否發光。默認為false。

外觀

欄位 含義
Texture （可選） 貼圖集的資源名稱。默認為TileSheets/Craftables。
SpriteIndex （可選） 貼圖集Texture中的貼圖索引。0代表左上角。

上下文標籤

field purpose
ContextTags （可選） 為此物品添加的自定義#上下文標籤。此處自定義是相對自動添加的上下文標籤而言的。應當為一個列表，例如： 
"ContextTags": [ "light_source", "torch_item" ]

高級

欄位 含義
CustomFields （可選） 此條目的自定義欄位。

說明

  • 數據素材中的許多物品並沒有在遊戲中實現。它們有可能完全沒有被應用於遊戲；也有可能是雖然沒有作為打造品出現，但實際上出現在了物體數據或家具數據中。

靴子

數據格式

您可以通過編輯Data/Boots編輯靴子數據。這是一個「字符串 → 字符串」字典，其中：

  • 鍵為非限定性物品ID。
  • 值為使用斜槓分隔的、包含如下欄位的字符串。
索引 欄位 效果
0 名稱 內部物品名稱（同時也是英語名稱）。
1 描述 在遊戲中顯示的、翻譯後的物品描述。
2 價格 未使用。 實際的價格是通過(防禦加成 × 100) + (免疫加成 × 100)計算的。
3 防禦加成 穿戴時的防禦加成。
4 免疫加成 穿戴時的免疫加成。
5 顏色索引 在「顏色貼圖」中，靴子的顏色索引。0代表左上角的貼圖（若有），否則默認使用Characters/Farmer/shoeColors貼圖集。
6 顯示名稱 遊戲中現實的、翻譯後的名稱（僅用於非英語素材文件）。
7 顏色貼圖 包含靴子顏色貼圖的素材名稱
8 貼圖索引 靴子在「貼圖集」中的索引，0代表左上角的貼圖。
9 貼圖集 包含靴子貼圖的貼圖集素材名稱。

在Data/Boots中的靴子數據是如下的「字符串 → 字符串」字典： 

  "511": "Dark Boots/Made from thick black leather./250/4/2/7"

自定義條目的形式如下： 

{
  "Format": "2.2.0",
  "Changes": [
    {
      "LogName": "Load boots texture",
      "Action": "Load",
      "Target": "{{ModId}}/Boots, {{ModId}}/BootsColor",
      "FromFile": "assets/{{TargetWithoutPath}}.png"
    },
    {
      "LogName": "Add boots to boots data",
      "Action": "EditData",
      "Target": "Data/Boots",
      "Entries": {
        "{{ModId}}_OPBoots": "Overpowered Boots/These boots are totally broken!/1000000/100/100/8/Overpowered Boots/{{ModId}}\\BootsColor/0/{{ModId}}\\Boots"
      }
    }
  ]
}

褲子

數據格式

您可以通過編輯Data/Pants素材以創建或編輯褲子。此素材包括一個「字符串 → 數據模型」查詢，其中：

  • 鍵為非限定性物品ID。
  • 值為包含如下欄位的數據模型。

基本褲子數據

欄位 含義
Name （可選） 物品的內部名稱。默認為Pants。
DisplayName
Description 		（可選） 用於顯示遊戲中物品名稱和描述的模板字符串。默認為通用的褲子文本（Pants 和A wearable pair of pants）。
Price （可選） 玩家在商店中購買的默認價格。默認為50。

外觀

欄位 含義
Texture 包含此褲子貼圖的貼圖集素材名稱。默認為Characters/Farmer/pants。
SpriteIndex 貼圖集Texture中的貼圖索引，0代表左上角。
DefaultColor （可選） 玩家沒有染色時，褲子的顏色（若有）。參見顏色格式。默認為255 235 203 （對應於布料的顏色）。
CanBeDyed （可選） 是否可以染色。默認為false。
IsPrismatic （可選） 是否為五彩褲子，即不斷地變化顏色。若設置，將覆蓋DefaultColor和CanBeDyed欄位。默認為false。

其他

欄位 含義
CanChooseDuringCharacterCustomization （可選） 是否可以在自定義玩家角色頁面上選擇此褲子（即創建角色時的界面）。默認為false。
CustomFields 此條目的自定義數據欄位。

上衣

數據格式

您可以通過編輯新版的Data/Shirts素材以創建或編輯上衣。此素材為一個「字符串 → 數據模型」查詢，其中：

  • 鍵為非限定性物品ID。
  • 值為包含如下欄位的數據模型。

基本上衣數據

欄位 含義
Name （可選） 物品的內部名稱。默認為Shirt。
DisplayName
Description 		（可選） 用於遊戲內名稱和描述的模板字符串。默認為通用上衣文本（Shirt和A wearable shirt）。
Price （可選） 玩家購買的價格。默認為50。

外觀

欄位 含義
Texture 包含此上衣貼圖的貼圖集素材名稱。默認為Characters/Farmer/shirts。
SpriteIndex 貼圖集Texture中的貼圖索引，0代表左上角。
DefaultColor （可選） 玩家沒有染色時，上衣的顏色（若有）。參見顏色格式。默認為none。
CanBeDyed （可選） 玩家是否可染色該上衣。默認為false。
IsPrismatic （可選） 是否為五彩上衣，即不斷地變化顏色。若設置，將覆蓋DefaultColor和CanBeDyed欄位。默認為false。
HasSleeves （可選） 是否繪製上衣袖子。默認為true。

其他

欄位 含義
CanChooseDuringCharacterCustomization （可選） 是否可以在自定義玩家角色頁面上選擇此上衣（即創建角色時的界面）。默認為false。
CustomFields 此條目的自定義數據欄位。

家具

家具是可放置的裝飾性物品，包括玩家可以坐著的椅子。

其數據存儲在Data/Furniture，貼圖存儲在TileSheets/furniture，翻譯存儲在Strings/Furniture，代碼存儲在StardewValley.Objects.Furniture。

數據格式

Data/Furniture中的數據為一個「整數 → 字符串」字典，其條目如下： 

  "18": "Country Chair/chair/-1/-1/4/750"

對於數據素材中的每個條目，其鍵為該物品的ParentSheetIndex，值為斜槓分隔的字符串，包含如下欄位：

索引 欄位 效果
0 名稱 物品內部名稱（同時也是英語名稱）。
1 類型 家具類型。可能的取值為：
value
chair
bench
couch
armchair
dresser
long table
painting
lamp
decor
other
bookcase
table
rug
window
fireplace
bed
bed double
bed child
torch
sconce
randomized_plant
fishtank
2 地塊表 家具在地塊表中所占尺寸。單位為地塊。可以形如<寬度> <高度>（例如1 2）。亦可設為-1，代表使用此類型家具的默認尺寸。
3 碰撞箱尺寸 家具的碰撞箱尺寸，單位為地塊。碰撞箱的錨點位於家具左下角，也就是會向上和向右眼神。可以形如<寬度> <高度>（例如1 2）。 亦可設為-1，代表使用此類型家具的默認尺寸。
4 旋轉 允許的旋轉類型（1，2 或 4）。
5 價格 從商店購入的價格。
6 位置限制 家具可放置的位置。
值 含義
-1 默認（使用對應家具類型的默認值）
0 只可室內
1 只可室外
2 室內外均可
7 顯示名稱 翻譯後的家具名稱。可用模板字符串。
8 貼圖集索引 貼圖集索引
9 貼圖集 （可選） 貼圖集的素材名稱。默認為TileSheets/furniture。
10 禁止隨機出售 （可選） 是否禁止該家具出現在隨機商店庫存和家具目錄中。默認為false。
11 上下文標籤 （可選） 空格分隔的上下文標籤列表。默認為none。

帽子

帽子是可以被放進物品欄帽子槽位的物品。

其數據存儲在Data/Hats，貼圖存儲在Characters/Farmer/hats，代碼存儲在StardewValley.Objects.Hat。

數據格式

Data/Hats中存儲的帽子數據為一個「整數 → 字符串」的字典。其條目如下： 

  "5": "Official Cap/Looks like it belonged to a postman or policeman. Either way, it's still very soft and smells okay./false/true"

原版遊戲中，帽子的物品ID就是其ParentSheetIndex。

數據素材中的每一項，其鍵名都是帽子的物品ID，其值為斜槓分隔的、包含如下欄位的字符串：


索引 欄位 效果
0 名稱 內部物品名稱
1 描述 翻譯後的描述
2 是否展示髮型 有三種可能取值：顯示玩家的髮型（true）、更改髮型以適應帽子（false）或 完全隱藏頭髮（hide）。
3 忽略髮型偏移 是否忽略帽子位置根據髮型的偏移（true或false之一）。例如，眼罩此欄位為true，因為眼罩的位置不受髮型的影響；但蝴蝶結此欄位為false，因為需要根據髮型調整其位置。
4 標籤 一個空格分隔的「標籤」列表。注意，這不是上下文標籤，而是用於提供雜項信息的標籤。目前，只有Prismatic一種標籤，代表帽子是五彩的，即顏色會循環變化。
5 顯示名稱 翻譯後的名稱。
6 貼圖索引 此帽子在貼圖集中的索引
7 貼圖集名稱 此帽子所在貼圖集的素材名稱。若為空，則使用默認貼圖集Characters/Farmer/hats。

帽子的類別被硬編碼為-95。（HatDataDefinition.cs::GetData）

工具

工具是可以被玩家揮舞或使用以造成特定效果（挖土、砍樹等）的物品。

其數據存儲在Data/Tools，其貼圖存儲在TileSheets/Tools，其代碼存儲在 StardewValley.Tool，以及不同的子類例如StardewValley.Tools.Axe。

數據格式

可以通過編輯Data/Tools數據文件以創建/編輯工具。此文件為一個「字符串 → 模型」查詢，其中：

  • 鍵為非限定性物品ID。
  • 值為包含如下欄位的數據模型。

基本工具數據

欄位 含義
ClassName 在StardewValley.Tools命名空間下，要創建的C#類的名稱。此類必須為StardewValley.Tool的子類，且必須有無參數的構造函數。例如，將此欄位的值設為Axe，遊戲會自動創建一個StardewValley.Tools.Axe實例。

主要的取值為：

  • 主要工具（Axe、FishingRod、Hoe、MeleeWeapon、MilkPail、Pan, Pickaxe、Shears、Wand 和 WateringCan）；
  • 特殊的GenericTool類型，應用來自Data/Tools的數據，且僅有通用邏輯，因此C#模組可以接入其自定義邏輯；
  • 從遊戲中移除的兩種工具（Lantern和Raft）可能無法正常運行。
Name 工具物品的內部名稱。
DisplayName
Description 		用於顯示遊戲內名稱和描述的模板字符串。
AttachmentSlots （可選） 工具的附件槽位數量。注意只有FishingRod工具擁有渲染和使用附件槽位的代碼。默認為-1，也就是保持工具物品類所設置的默認值。
SalePrice （可選） 商店中玩家購入此物品的默認售價。默認為-1，此時需要在商店中手動設置售價。
CustomFields 此條目的自定義欄位。

外觀

注意，如果希望在世界中正確繪製工具（即，在玩家使用它時）需要自定義代碼。

欄位 意圖
Texture 貼圖集的素材名稱。
SpriteIndex 工具在貼圖集Texture中的貼圖索引。0代表最上一行。
MenuSpriteIndex （可選） Texture中的物品圖標索引。默認為SpriteIndex。

升級

欄位 含義
UpgradeLevel （可選） 工具的升級等級。默認為-1，即保持與工具類所設的默認值相同。
ApplyUpgradeLevelToDisplayName （可選） 是否根據等級調整DisplayName。例如，1級的斧頭為「銅斧頭」。默認為false。

英語下的顯示名稱為：

升級等級 顯示名稱格式
1 Copper <display name>
2 Steel <display name>
3 Gold <display name>
4 Iridium <display name>
ConventionalUpgradeFrom （可選） 若設置，則 If set, prepends an upgrade for the given tool ID to the UpgradeFrom field. This applies these rules (based on the UpgradeLevel field, not the upgrade level of the specified tool ID):
升級等級 售價 所需物品
1 data-sort-value="2000">Gold.png2,000金 Copper Bar.png 銅錠（5）
2 data-sort-value="5000">Gold.png5,000金 Iron Bar.png 鐵錠（5）
3 data-sort-value="10000">Gold.png10,000金 Gold Bar.png 金錠（5）
4 data-sort-value="25000">Gold.png25,000金 Iridium Bar.png 銥錠（5）

例如，銥斧頭指定了如下值： 

"ConventionalUpgradeFrom": "(T)GoldAxe"
UpgradeFrom （可選） 從克林特的鐵匠鋪升級工具所需要求。若指定多個條目，則使用第一個匹配的條目。

此欄位為包含如下欄位的數據模型所組成的列表。

欄位 含義
Price （可選） 購買升級的價格。默認為0。
RequireToolId （可選） 為限定性或非限定性物品ID。若設置，則背包中必須有指定工具才能升級。購買升級後原工具將被摧毀。
TradeItemId （可選） 為限定性或非限定性物品ID。若設置，則必須給鐵匠指定物品才能升級（例如原版中許多工具需要金屬錠）。
TradeItemAmount （可選） 所需的TradeItemId數量。默認為1。
Condition （可選） 指示是否可以升級的遊戲狀態查詢。默認為總是可以。

例如，下列代碼相當於鋼斧頭的升級設置： 

"UpgradeFrom": [
    {
        "RequireToolId": "(T)CopperAxe",
        "Price": 5000,
        "TradeItemId": "(O)335", // Iron Bar
        "TradeItemAmount": 5
    }
]

若希望工具總可用，則可忽略這些條件。例如： 

"UpgradeFrom": [
    {
        "Price": 5000
    }
]

注意克林特需要幾天時間來升級工具。若希望直接賣掉工具，則將其添加到常規商店。

遊戲邏輯

欄位 含義
CanBeLostOnDeath 玩家暈倒後是否丟失此物品。默認為false。

擴展性

欄位 含義
ModData （可選） 工具被創建時所用的模組數據值，可通過tool.modData字典獲取。例如： 
"ModData": {
    "PowerLevel": 9000
}
SetProperties （可選） 設置工具C#類的任意屬性。例如，下面示例會禁用工具動畫，且禁止工具消耗體力： 
"SetProperties": {
    "InstantUse": true,
    "IsEfficient": true
}

武器

武器是玩家用來殺傷怪物的工具。

其數據存儲在Data/Weapons，其貼圖存儲在TileSheets/weapons，其代碼存儲在StardewValley.Tools.MeleeWeapon和StardewValley.Tools.Slingshot。

數據格式

Data/Weapons中的數據為一個「字符串 → 數據模型」查詢，其中：

  • 鍵為武器的非限定性物品ID。
  • 值為包含如下欄位的模型。

基本武器信息

欄位 效果
Name 內部名稱
DisplayName
Description 		用於顯示翻譯後名稱和描述的模板字符串。
Type 武器類型。可能取值為：0（刀）、1（匕首）、2（棒或錘）或 3（劍）。

外觀

欄位 效果
Texture 該武器所在的貼圖集的素材名稱。
SpriteIndex 物品在貼圖集Texture中的索引。0代表左上角。

統計

欄位 效果
MinDamage
MaxDamage 		使用此武器對怪物的最小和最大傷害。
Knockback （可選） 目標被武器擊中時後退多遠。為相對於生鏽的劍之類的基礎武器的乘數（例1.5代表生鏽的劍的150%）。默認為1。
Speed （可選） 玩家可以多快地揮舞此武器。每點相當於40毫秒，0點相當於0毫秒。這會和玩家的武器速度疊加。默認為0。
Precision （可選） 減少miss的概率。默認為0。
Defense （可選） 減少玩家受到的傷害。默認為0。
AreaOfEffect （可選） 略增大效果區域。默認為0。
CritChance （可選） 暴擊機率，為 0（從不）至 1（每次）之間的小數。其中，0.02為默認值。
CritMultiplier （可選） 暴擊所造成的傷害是普通攻擊的多少倍。可以為小數。默認為3。

遊戲邏輯

欄位 效果
CanBeLostOnDeath 玩家暈倒後此工具是否丟失。默認為true。
MineBaseLevel
MineMinLevel 		（可選） 影響礦井寶箱掉落此武器的基礎層數和最小層數。默認為-1，代表不可自動掉落。

高級

欄位 效果
Projectiles （可選） 使用該武器時發射的拋射物，它會按直線運動，直到擊中怪物、造成傷害。會分別發射列表中列出的所有拋射物。

此欄位為包含如下欄位的數據模型所組成的列表（列表中每項都會生成一個拋射物）：

欄位 效果
Id 拋射物的唯一字符串ID。
Damage （可選） 拋射物擊中怪物造成的傷害。默認為10。
Explodes （可選） 拋射物撞到東西時是否爆炸。默認為false。
Bounces （可選） 拋射物在自毀前最多可以在牆壁上反彈多少次。默認為0。
MaxDistance （可選） 拋射物能到達的最大距離，單位為地塊。默認為4。
Velocity （可選） 拋射物運動的速度。默認為10。
RotationVelocity （可選） 旋轉速度。默認為32。
TailLength （可選） 拋射物尾跡長度。默認為1。
FireSound
BounceSound
CollisionSound 		（可選） 發射拋射物、拋射物反彈或撞到東西的音效。三者均默認為none。
MinAngleOffset
MaxAngleOffset 		（可選） 每次發射該拋射物時，相對發射方向的隨機偏移。二者均默認為0，此時會以玩家面向方向的90°角方位發射。
SpriteIndex （可選） TileSheets/Projectiles素材文件中的貼圖集索引。默認為11（閃光的黃色球體貼圖）。
Item （可選） 發射的物品。若設置，則重寫SpriteIndex。

此欄位為包含如下欄位的數據模型所組成的列表：

欄位 效果
公共欄位 參見模組:物品查詢#物品生成欄位以獲取關於彈藥物品支持的一般物品欄位。

若設置為返回多個物品的物品查詢，則會隨機選擇其中一個。

注意這些實際上是武器發射的魔法拋射物，不能像彈弓一樣直接瞄準。

CustomFields 此條目的自定義欄位。

武器的類別被硬編碼為-98（Object.weaponCategory）。

彈弓說明

  • 基礎彈弓在武器數據中的ParentSheetIndex為32，每升一級，索引+1（最多不超過34，儘管原版中只能獲取32和33）。
  • 彈弓傷害是動態計算的，與武器數據無關。

礦井寶箱掉落

當玩家打碎礦井中的寶箱時，有一定概率掉落物品。如下所示為選取掉落物的機制[2]：

  1. 匹配MineMinLevel低於當前礦井層數的物品。
  2. 從上一步所得列表中，基於MineBaseLevel和當前礦井層數之差進行概率檢查。其中，概率為中心落在基礎層數的鐘形曲線：
    層數差 概率
    0 100%
    5 92%
    10 71%
    15 46%
    20 25%
    25 4%
    層數差取絕對值；例如，基礎層數在當前層數之上/之下5層都會有92%的概率。（此概率依據正態分布 e-(当前层数 - 基础层数)2 / (2 * 122) 計算。）
  3. 尋找層數差最小的武器，將其加入列表（若此物品在第二步中被選中，則有雙倍機率掉落）。
  4. 從餘下武器列表中隨機選取一個掉落物。

另請參閱

參考

  1. ↑ 指農場山洞中的蘑菇箱。
  2. ↑ 參見遊戲代碼中的Utility.getUncommonItemForThisMineLevel

歷史

  • 1.6：物品現在存儲在Data/Objects而不是Data/ObjectInformation中，且有了全新格式。
  • 1.6：帽子的欄位4現在用於標籤，而非顯示名稱。
  • 1.6：所有語言都使用了顯示名稱(display name)欄位。
  • 1.6：為所有物品數據添加了貼圖集和貼圖集索引欄位。
  • 1.6：現在所有類型的物品都使用字符串ID。
取自「https://zh.stardewvalleywiki.com/mediawiki/index.php?title=模组:物品数据&oldid=49741」