模组:物品数据

本页面解释游戏如何存储和解析物品数据。这是一个面向模组开发者的高级指南。

特别注意：本页面暂且严格区分物品（item）与物体（object）这两个术语。 其中物体特指物品类型为Object(O)的物品，它们是物品的真子集。

简介

综述

对于星露谷物语1.6而言，游戏中的物品有一些重要的特性：

每个物品都有一个字符串ID（ItemId，物品ID）和一个全局唯一的字符串ID （QualifiedItemId，限定性物品ID）。其中，QualifiedItemId是通过向ItemId添加物品类型标识符前缀而自动生成的。
由于历史原因，原版物品的ItemId可能并不唯一。例如，河豚（物体128）和蘑菇箱^[1]（大型打造品128）有相同的物品ID，即ItemId: 128。但可以通过QualifiedItemId区分两者，前者为(O)128，后者为(BC)128。
每个物品类型在游戏中都有一个物品数据定义以告诉游戏如何处理它。C#模组可以添加或编辑定义。每个定义都有一个唯一的前缀，用在限定性物品ID中。原版的类型包括大型打造品（(BC)），靴子（(B)），农舍地板（(FL)），家具（(F)），帽子（(H)），物体（(O)），裤子（(P)），上衣（(S)），工具（(T)），墙纸（(WP)）和武器（(W)）。
自定义物品现在可以提供它们自己的物品贴图，后者在物品数据素材的一个新字段中指定（见下文）。物品的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` 每种果树可以设置自定义贴图名称和贴图索引。默认贴图为E`TileSheets/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"> 2,000金	铜锭（5）
2	data-sort-value="5000"> 5,000金	铁锭（5）
3	data-sort-value="10000"> 10,000金	金锭（5）
4	data-sort-value="25000"> 25,000金	铱锭（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]：

匹配MineMinLevel低于当前矿井层数的物品。
从上一步所得列表中，基于MineBaseLevel和当前矿井层数之差进行概率检查。其中，概率为中心落在基础层数的钟形曲线：

层数差概率

0 100%

5 92%

10 71%

15 46%

20 25%

25 4%
层数差取绝对值；例如，基础层数在当前层数之上/之下5层都会有92%的概率。（此概率依据正态分布 e^{-(当前层数 - 基础层数)² / (2 * 12²)} 计算。）
寻找层数差最小的武器，将其加入列表（若此物品在第二步中被选中，则有双倍几率掉落）。
从余下武器列表中随机选取一个掉落物。

另请参阅

模组:目录，以获取相关内容，例如作物、鱼类、礼物喜好以及配方的相关内容。

参考

↑ 指农场山洞中的蘑菇箱。
↑ 参见游戏代码中的Utility.getUncommonItemForThisMineLevel

历史

1.6：物品现在存储在Data/Objects而不是Data/ObjectInformation中，且有了全新格式。
1.6：帽子的字段4现在用于标签，而非显示名称。
1.6：所有语言都使用了显示名称(display name)字段。
1.6：为所有物品数据添加了贴图集和贴图集索引字段。
1.6：现在所有类型的物品都使用字符串ID。

[mushroom_box-1] 指农场山洞中的蘑菇箱。

[2] 参见游戏代码中的Utility.getUncommonItemForThisMineLevel

[1]

[2]