模组:常见的数据字段
阅读
2024-10-15更新
最新编辑:sizau
阅读：
更新日期：2024-10-15
最新编辑：sizau
← 目录
|
不完整的翻译 本文或部分尚未完全翻译成中文。
欢迎您通过编辑帮助其建设。 |
This page documents common field types which appear in the game's data files.
You normally don't need to read through this page directly; specific sections are linked from field docs on other pages.
字符串格式
这些格式仅在特定支持它们的字段中使用，如果适用，字段文件将连接到该页面。
唯一字符串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冲突以及便于（检修人员和模组代码）确认自定义内容来源于何模组。
Asset name
An asset name uniquely identifies a game asset. These usually match files in the game's Content folder, but mods can add custom assets using Content Patcher or the C# content API.
For example, Portraits/Abigail contains Abigail's portraits.
Asset names do not include the Content/ prefix, file extension, or locale code. For example, the Content/Data/Achievements.de-DE.xnb file has asset name Data/Achievements.
Color
Data assets can define colors using a standard format. For example:
"DebrisColor": "White"
The supported color formats are:
| format | example | ||
|---|---|---|---|
A Color property name.
|
ForestGreen | ||
| A hexadecimal color code. The optional alpha is a value between 00 (transparent) and FF (opaque). | #228B22 #228B22FF | ||
| An 8-bit RGB color code. The optional alpha is a value between 0 (transparent) and 255 (opaque). | 34 139 34 34 139 34 255 |
C# mods can parse a color like Utility.StringToColor("White").
Context tag
A context tag is an arbitrary data label attached to items. The game auto-generates some context tags, while others can be added through the item data.
These can produce various effects in-game, be queried in various asset fields or using the ITEM_CONTEXT_TAG game state query, or may be informational only.
See Modding:Items#Context tags for more info.
Custom fields
Many data assets have a CustomFields field. This is ignored by the game, but can be read by mod frameworks to enable custom features.
For example, a content pack can add a crop with custom fields:
"CustomFields": {
"Example.FrameworkMod/WetTexture": "{{InternalAssetKey: assets/crops-wet.png}}"
}
And then a C# mod could handle the custom field if it's set:
CropData data = crop.GetData();
if (data != null && data.CustomFields.TryGetValue("Example.FrameworkMod/WetTexture", out string textureName))
{
// do magic
}
游戏状态查询
游戏状态查询使用特定命令语法定义了一个条件。例如，下述查询用于检查当日是否是春季或夏季：
"Condition": "SEASON Spring Summer"
欲获得更多信息，参见模组:游戏状态查询。
物品ID
Every item is identified by two strings:
- An unqualified item ID (
item.ItemId) is a unique string ID for the item. This should generally be unique, but older vanilla items have non-unique numeric IDs for legacy reasons. - A qualified item ID (
item.QualifiedItemId) prefixes the unqualified ID with the type identifier to guarantee uniqueness.
For example, pufferfish has two item IDs: 128 (unqualified) and (O)128 (qualified).
See Modding:Items for more info.
Item query
An item query creates any number of items dynamically using either an item ID or a special command syntax. For example, you can select random house plants:
"ItemId": "RANDOM_ITEMS (F) 1376 1390"
See Modding:Item queries for more info.
模板字符串
“模板字符串”是包含特定标记的字符串。例如，下面的模板字符串实际上显示的是“真是美好的春日”：
"Message": "真是美好的[Season]日。"
更多信息详见模组:模板字符串。
翻译键
“翻译键”唯一指定了如何查找可翻译的文本。翻译键以<asset name>:<key>形式出现。例如，Strings\\StringsFromCSFiles:spring会在内容文件夹的Strings\StringsFromCSFiles素材中文件中查找spring键。
翻译键经常在游戏代码中（例如，通过Game1.content.LoadString）和数据素材中（例如通过LocalizedText模板字符串）被使用。
Trigger action
A trigger action performs an action when something happens, with support for a wide range of actions (like sending mail, changing friendship, starting a quest, etc).
For example, you can give the player an item from dialogue:
"Message": "Hi there! Here's a pufferfish.#%action AddItem (O)128"
See Modding:Trigger actions for more info.
Data structures
Item spawn fields
Item spawn fields are a common set of fields used to create items using item queries in many data assets.
For example, you can create an iridium-quality strawberry juice:
"ItemId": "FLAVORED_ITEM Juice (O)400",
"Quality": 4
See Modding:Item queries#Item spawn fields for more info.
Mod data
modData dictionary fields store custom data about instances. These are synchronized in multiplayer, persisted in the save file, and accessible from both C# and game state queries like PLAYER_MOD_DATA.
When you split an item stack, the new stack copies the previous one's mod data; when merged into another stack, the merged items adopt the target stack's mod data. Otherwise mod data has no effect on item split/merge logic (e.g. you can still merge items with different mod data).
In C#, these are available on these types: Character (including monsters, NPCs, and players), GameLocation, Item, Projectile, Quest, and TerrainFeature.
To avoid mod conflicts, mod data keys should be unique string IDs:
item.modData[$"{this.ModManifest.UniqueID}/item-age"] = "30";
Point
A point represents an integer coordinate or size, usually measured in pixels or tiles. This is formatted as an object with an X/Y position. For example:
"Position": {
"X": 0,
"Y": 0
}
Quantity modifiers
Quantity modifiers apply dynamic changes to a numeric field in a data asset like Data/Shops or Data/Machines. For example, you can multiply a shop item's price or increase a machine output's quality. You can specify any number of modifiers for the same field.
Modifier format
These consist of a list of models with these fields:
| field | effect |
|---|---|
| Id | The unique string ID for this modifier within the current list. |
| Modification | The type of change to apply. The possible values are Add, Subtract, Multiply, Divide, and Set. |
| Amount | (Optional if RandomAmount specified) The operand applied to the target value (e.g. the multiplier if used with Multiply). |
| RandomAmount | (Optional) A list of possible amounts to randomly choose from. If set, Amount is optional and ignored. Each entry in the list has an equal probability of being chosen, and the choice is persisted for the current day. For example:
"RandomAmount": [ 1, 2, 3.5, 4 ]
|
| Condition | (Optional) A game state query which indicates whether this change should be applied. Defaults to always true. |
Modifier mode
Quality modifier fields are often accompanied by a mode field (like PriceModifiers and PriceModifierMode), which indicate what to do when multiple modifiers apply to the same value. Available modes:
| value | effect |
|---|---|
| Stack | Apply each modifier to the result of the previous one. For example, two modifiers which double a value will quadruple it. |
| Minimum | Apply the modifier which results in the lowest value. |
| Maximum | Apply the modifier which results in the highest value. |
Examples
For example, this will double the price of a shop item in Data/Shops:
"PriceModifiers": [
{
"Modification": "Multiply",
"Amount": 2.0
}
]
This will set the price to a random value between 100–1000, or 3–5 times the item's normal sell price, whichever is higher (like the Traveling Cart):
"PriceModifierMode": "Maximum",
"PriceModifiers": [
{
"Modification": "Set",
"RandomAmount": [ 100, 200, 300, 400, 500, 600, 700, 800, 900, 1000 ]
},
{
"Modification": "Multiply",
"RandomAmount": [ 3, 4, 5 ]
}
]
Rectangle
A rectangle represents a square area, usually measured in pixels or tiles. This is formatted as an object with an X/Y position (for the top-left corner) and width/height size, where all values are integers. For example:
"Rectangle": {
"X": 0,
"Y": 0,
"Width": 16,
"Height": 32
}
Vector2
A Vector2 represents a non-integer coordinate or size, usually measured in pixels or tiles. This is formatted as an object with an X/Y position. For example:
"Position": {
"X": 10.5,
"Y": 12.0
}
沪公网安备 31011002002714 号