模组:公共数据字段
← 目录
这个页面记录了公共数据字段，他们会出现在游戏文件中。
一般情况下无需通读全文；专门性较强的小节会附有指向对应字段文档的链接。
字符串格式
这些格式仅在特定支持它们的字段中使用，如果适用，字段文件将连接到该页面。
唯一字符串ID
游戏识别数据会使用唯一字符串ID。例如：Town是 Pelican Town (鹈鹕镇)的唯一ID，其它位置都不能使用这个ID。ID的使用目的很广，从内部的游戏逻辑到模组编辑
模组最佳做法：
- 使用带命名空间的ID：应向ID添加您的模组的唯一ID作为其前缀。例如，若您模组ID为
Example.PufferchickMod，而您正在添加一个“河豚鸡毛绒玩具”，则您的物品ID应类似于Example.PufferchickMod_PufferchickPlushy。在一个Content Patcher包中，您可以使用{{ModId}}_PufferchickPlushy以自动插入模组ID。
- 字符串ID仅能包含字母和数字(a–z, A–Z, 0–9)，下划线(
_)，小数点(.)。这很重要，因为字符串ID经常用于特殊字符有特殊含义的场合（类似于文件名或游戏状态查询）。
尽管游戏基本上不检查ID格式，但我们强烈推荐您使用这种精确格式以保证良好的模组兼容性、消除ID冲突以及便于（检修人员和模组代码）确认自定义内容来源于何模组。
素材名称
素材名称是每个游戏素材的唯一标识，也就是不同素材不能共用相同的名称。这往往匹配游戏Content目录下的文件, 但模组可以使用Content Patcher或C# content API来添加自定义素材。
例如，Portraits/Abigail包含阿比盖尔的头像。
素材名称不应包含Content/前缀、文件扩展名或语言代码。例如Content/Data/Achievements.de-DE.xnb文件的素材名称为Data/Achievements。
颜色
数据素材可以使用标准格式定义颜色。例如：
"DebrisColor": "White"
支持的颜色格式为：
| 格式 | 例子 | ||
|---|---|---|---|
Color属性名称。
|
ForestGreen | ||
| 十六进制颜色代码。可选的透明度介于00（透明）和FF（不透明）之间。 | #228B22 #228B22FF | ||
| 8-bit RGB颜色代码。可选的透明度介于0（透明）和255（不透明）之间。 | 34 139 34 34 139 34 255 |
C#模组可以使用Utility.StringToColor("White")等方式来解析颜色。
上下文标签
上下文标签是附于物品的任意数据标签。游戏会自动生成某些上下文标签，但其他标签可以通过物品数据手动添加。
上下文标签可以在游戏内产生不同的效果。上下文标签可以在不同的素材字段中被查询，也可使用ITEM_CONTEXT_TAG游戏状态查询来查询。上下文标签也可能仅用于提供信息，而不产生其他效果。
参见模组:物品数据#上下文标签以获取更多信息。
自定义字段
许多数据素材具有CustomFields字段。此字段会被游戏忽略，但可以被模组架构读取，从而实现特定功能。
例如，某个内容包可能通过自定义字段来添加作物：
"CustomFields": {
"Example.FrameworkMod/WetTexture": "{{InternalAssetKey: assets/crops-wet.png}}"
}
若设置了自定义字段，则可以用C#模组处理它：
CropData data = crop.GetData();
if (data != null && data.CustomFields.TryGetValue("Example.FrameworkMod/WetTexture", out string textureName))
{
// do magic
}
游戏状态查询
游戏状态查询使用特定命令语法定义了一个条件。例如，下述查询用于检查当日是否是春季或夏季：
"Condition": "SEASON Spring Summer"
欲获得更多信息，参见模组:游戏状态查询。
物品ID
每个物品都由两个字符串确定：
- 非限定性物品ID（
item.ItemId）是此物品的唯一字符串ID。原则上每个物品应当有独一无二的ID，但由于历史原因早期原版物品的ID并非独一无二。 - 限定性物品ID（
item.QualifiedItemId）在非限定性ID的基础上添加了类型前缀以防ID冲突。
例如，河豚有两个物品ID：128（非限定）和(O)128（限定）。
参阅模组:物品数据以获取更多信息。
物品查询
物品查询可使用物品ID或特定的命令语法来动态创建任何数量的物品。例如，您可以随机选取家居植物：
"ItemId": "RANDOM_ITEMS (F) 1376 1390"
参见模组:物品查询以获取更多信息。
模板字符串
“模板字符串”是包含特定标记的字符串。例如，下面的模板字符串实际上显示的是“真是美好的春日”：
"Message": "真是美好的[Season]日。"
更多信息详见模组:模板字符串。
翻译键
“翻译键”唯一指定了如何查找可翻译的文本。翻译键以<asset name>:<key>形式出现。例如，Strings\\StringsFromCSFiles:spring会在内容文件夹的Strings\StringsFromCSFiles素材中文件中查找spring键。
翻译键经常在游戏代码中（例如，通过Game1.content.LoadString）和数据素材中（例如通过LocalizedText模板字符串）被使用。
触发动作
触发动作负责在某些事发生时完成一个动作，支持多种动作 (比如发送邮件，改变好感度, 开启委托等).
例如，可以在对话同时给玩家一个物品
"Message": "Hi there! Here's a pufferfish.#%action AddItem (O)128"
参见模组:触发动作以获得更多信息。
数据结构
物品生成字段
物品生成字段是许多数据素材共用的一组用于创建物品的字段。
例如，您可以创建铱星品质的草莓果汁：
"ItemId": "FLAVORED_ITEM Juice (O)400",
"Quality": 4
参见模组:物品查询#物品生成字段以获取更多信息。
模组数据
modData字典字段存储关于实例的自定义数据。这些数据会在多人游戏中自动同步，会储存在存档文件中，且可通过C#或类似于PLAYER_MOD_DATA的游戏状态查询获取之。
当您尝试分开一组物品时，新分出来的那组物品会复制原来那组的模组数据；当把一组物品融合到另一组物品时，融合后的物品会采用后者的模组数据。除此，模组数据对于物品分开/融合逻辑并无影响（例如您可以融合具有不同模组数据的物品）。
模组数据适用于如下C#类型：Character（包括怪物、村民和玩家）、GameLocation、Item、Projectile、Quest, and TerrainFeature.
为避免模组冲突，模组数据的键名应当为唯一字符串ID：
item.modData[$"{this.ModManifest.UniqueID}/item-age"] = "30";
点
一个点（point）就代表了一个整数坐标或尺寸，单位常为像素或地块。其格式为具有X/Y位置的对象，例如：
"Position": {
"X": 0,
"Y": 0
}
数量修饰器
数量修饰器（quantity modifier）会动态地修改某些素材文件（类似于Data/Shops或Data/Machines）中的数值字段。例如，您可以将某个商店物品的价格乘以某个倍率，或增加某个机器的产品品质。您可以对同一个字段指定任意数量的修饰器。
修饰器格式
修饰器应当由包含如下字段的数据模型的列表组成：
| 字段 | 效果 |
|---|---|
| Id | 当前列表中此修饰器的唯一字符串ID。 |
| Modification | 修饰器的运算类型。可用的值为Add、Subtract、Multiply、Divide和Set。 |
| Amount | （若已指定了RandomAmount，则可选） 应用在目标数值上的操作数（例如，Multiply模式下为乘数）。 |
| RandomAmount | （可选） 一个数值列表，将从中等概率地随机取值。若设置此字段，则Amount可以忽略。 随机抽取的值在同一天内保持不变。例如：
"RandomAmount": [ 1, 2, 3.5, 4 ]
|
| Condition | （可选） 用于指示是否启用此修饰器的游戏状态查询。默认为true。 |
修饰器模式
数量修饰器常常伴有模式字段（例如PriceModifiers和PriceModifierMode），它指示多个修饰器如何同时作用于同一个值。可用的模式包括：
| 值 | 效果 |
|---|---|
| Stack | 使用后一修饰器来修饰前一修饰器的计算结果，依次计算。例如，两个“x2”修饰器会组合成一个“x4”修饰器。 |
| Minimum | 单独计算各个修饰器的结果，在这些结果中取最小值。 |
| Maximum | 单独计算各个修饰器的结果，在这些结果中取最大值。 |
例子
下面的修饰器会将Data/Shops中商店物品的售价翻倍：
"PriceModifiers": [
{
"Modification": "Multiply",
"Amount": 2.0
}
]
下面的修饰器会设置价格为100-1000之间的随机数，或原价的3-5倍，取两种计算方式的更高者（类似旅行货车）：
"PriceModifierMode": "Maximum",
"PriceModifiers": [
{
"Modification": "Set",
"RandomAmount": [ 100, 200, 300, 400, 500, 600, 700, 800, 900, 1000 ]
},
{
"Modification": "Multiply",
"RandomAmount": [ 3, 4, 5 ]
}
]
矩形
矩形（rectangle）代表一个矩形区域，单位为像素或地块。其格式为包含（左上角）X/Y位置和宽/高尺寸的对象，所有数值为整型。例如：
"Rectangle": {
"X": 0,
"Y": 0,
"Width": 16,
"Height": 32
}
Vector2
Vector2（2-向量）代表非整型的坐标或尺寸，单位为像素或地块。其格式为包含X/Y位置的对象。例如：
"Position": {
"X": 10.5,
"Y": 12.0
}