维护提醒

BWIKI 全站将于 9 月 3 日(全天)进行维护,期间无法编辑任何页面或发布新的评论。

全站通知:

模组:公共数据字段

来自星露谷物语维基
跳到导航 跳到搜索

目录

这个页面记录了公共数据字段,他们会出现在游戏文件中。

一般情况下无需通读全文;专门性较强的小节会附有指向对应字段文档的链接。

字符串格式

这些格式仅在特定支持它们的字段中使用,如果适用,字段文件将连接到该页面。

唯一字符串ID

游戏识别数据会使用唯一字符串ID。例如:TownPelican 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 PatcherC# 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

每个物品都由两个字符串确定:

  • 非限定性物品IDitem.ItemId)是此物品的唯一字符串ID。原则上每个物品应当有独一无二的ID,但由于历史原因早期原版物品的ID并非独一无二。
  • 限定性物品IDitem.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(包括怪物、村民和玩家)、GameLocationItemProjectileQuest, and TerrainFeature.

为避免模组冲突,模组数据的键名应当为唯一字符串ID

item.modData[$"{this.ModManifest.UniqueID}/item-age"] = "30";

一个(point)就代表了一个整数坐标或尺寸,单位常为像素或地块。其格式为具有X/Y位置的对象,例如:

"Position": {
    "X": 0,
    "Y": 0
}

数量修饰器

数量修饰器(quantity modifier)会动态地修改某些素材文件(类似于Data/ShopsData/Machines)中的数值字段。例如,您可以将某个商店物品的价格乘以某个倍率,或增加某个机器的产品品质。您可以对同一个字段指定任意数量的修饰器。

修饰器格式

修饰器应当由包含如下字段的数据模型的列表组成:

字段 效果
Id 当前列表中此修饰器的唯一字符串ID
Modification 修饰器的运算类型。可用的值为AddSubtractMultiplyDivideSet
Amount (若已指定了RandomAmount,则可选) 应用在目标数值上的操作数(例如,Multiply模式下为乘数)。
RandomAmount (可选) 一个数值列表,将从中等概率地随机取值。若设置此字段,则Amount可以忽略。 随机抽取的值在同一天内保持不变。例如:
"RandomAmount": [ 1, 2, 3.5, 4 ]
Condition (可选) 用于指示是否启用此修饰器的游戏状态查询。默认为true。

修饰器模式

数量修饰器常常伴有模式字段(例如PriceModifiersPriceModifierMode),它指示多个修饰器如何同时作用于同一个值。可用的模式包括:

效果
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
}