模组:物品查询
← 目录
|
页面仍需完善
该页面由于下列原因被标记为不完善：
|
|---|
此文档主要关于物品查询，其为动态创建一个或多个物品的内建方式，而非指定单个物品ID。
概览
可用字段
下述字段可用于诸如机器数据和商店数据的多个位置。只有在明确表明允许使用物品查询的位置，才能使用这些字段。
查询格式
物品查询是一个由查询名称及0个及以上参数组成的字符串。参见下述查询列表。
⚠ 物品查询是部分大小写敏感的。尽管某些值对大小写不敏感，但并非总是如此。推荐使用精确的大小写以规避问题。
参数格式
物品查询的参数以空格分隔。例如，RANDOM_ITEMS (F) 1376 1390有3个参数：(F)、1376 和 code>1390。
若某参数需要包含空格，则可用双引号引用之以表明这是一整个参数。例如LOST_BOOK_OR_ITEM "RANDOM_ITEMS (O)"将RANDOM_ITEMS (O) 视作一个参数。如需嵌套双引号，可以将内层双引号加上反斜杠以转义。
注意JSON字符串内部的双引号和反斜杠也需要转义。例如，"ItemId": "LOST_BOOK_OR_ITEM \"RANDOM_ITEMS (O)\""会向游戏代码传入LOST_BOOK_OR_ITEM "RANDOM_ITEMS (O)"。另一种方法是在JSON字符串使用单引号，例如"ItemId": 'LOST_BOOK_OR_ITEM "RANDOM_ITEMS (O)"'。
可用查询
一般用途
| 查询 | 效果 | ||||||
|---|---|---|---|---|---|---|---|
ALL_ITEMS [type ID] [flags]
|
返回物品数据提供的所有物品。若设置物品类型标识符[type ID]，例如(O)代表物体，则仅返回对应类别的全部物品。
而
例如：
| ||||||
FLAVORED_ITEM <type> <ingredient ID> [ingredient flavor ID]
|
带有特定风味的物品，例如苹果果酒。其中<type>为Wine、Jelly、Pickle、Juice、Roe、AgedRoe, Honey、Bait、DriedFruit、DriedMushroom 或 SmokedFish。 其中<ingredient ID>为原料的限定性或非限定性物品ID（例如苹果果酒此参数为Apple）。对于Honey，可以将<flavor ID>设为-1以获得野蜂蜜。
对于腌鱼籽，其原料ID | ||||||
RANDOM_ITEMS <type definition ID> [min ID] [max ID] [flags]
|
返回具有指定类型的物品，其次序随机。可以指定[min ID]和[max ID]以获取一定区间内的数字物品ID（包含端点值）。
例如，您可以在Data/Shops中设置售卖价格为 {
"ItemId": "RANDOM_ITEMS (WP)",
"MaxItems": 1,
"Price": 200
}
也可以售卖随机的家居植物： {
"ItemId": "RANDOM_ITEMS (F) 1376 1390",
"MaxItems": 1
}
还可以售卖模组定义的自定义物品，只需使用物品ID前缀： {
"ItemId": "RANDOM_ITEMS (O)",
"MaxItems": 1,
"PerItemCondition": "ITEM_ID_PREFIX Target AuthorName_ModName_"
}
还可以售卖10个类别不是-13或-14的随机物品： {
"ItemId": "RANDOM_ITEMS (O)",
"MaxItems": 10,
"PerItemCondition": "ITEM_CATEGORY, !ITEM_CATEGORY Target -13 -14"
}
|
1金特定物品
| 查询 | 效果 |
|---|---|
| DISH_OF_THE_DAY | 餐吧当日限定菜品。 |
LOST_BOOK_OR_ITEM [alternate query]
|
若玩家尚未集齐遗失之书，则返回一本遗失之书。否则，若指定了 [alternate query]参数，则返回此参数的物品；若未指定，不返回任何物品。
例如 |
| RANDOM_BASE_SEASON_ITEM | 返回随机的应季物品，这些物品通常可以在垃圾桶、矿井宝箱之类的地方找到。 |
SECRET_NOTE_OR_ITEM [alternate query]
|
若玩家尚未集齐秘密纸条（在姜岛则为日记残页），则返回一件相应物品。否则，若指定了[alternate query]则返回此参数的物品；若未指定，不返回任何物品。
例如 |
| SHOP_TOWN_KEY | 返回小镇钥匙。仅对商店有效。 |
特殊
| 查询 | 效果 |
|---|---|
ITEMS_SOLD_BY_PLAYER <shop location>
|
玩家最近卖给<shop location>的随机物品，此参数可以为 SeedShop（杂货店）或 FishShop（鱼店）。
|
LOCATION_FISH <location> <bobber tile> <depth>
|
可以在给定地点钓到的随机物品。其中<location>应当为地点的内部名称；<bobber tile>为浮标所在水体的位置，形如<x> <y>；<depth>为浮标距岸边的距离，单位为地块（其中0代表紧邻岸边）。
注意： 因为目标地点可能在其列表中使用LOCATION_FISH查询，因此容易造成错误的循环引用（例如地点A从地点B获取鱼，而地点B又从地点A获取鱼）。若这种情况发生，则游戏记录此错误并不返回物品。 |
| MONSTER_SLAYER_REWARDS | 返回所有已解锁的杀怪目标奖励。所有玩家从吉尔处收集的奖品都将计入在内。返回的物品列表按照MonsterSlayerQuests.xnb中的顺序排序，例如史莱姆克星戒指、野蛮人戒指、吸血戒指，以此类推。 |
MOVIE_CONCESSIONS_FOR_GUEST [NPC name]
|
返回为指定村民[NPC name]生成的电影零食列表。若缺省，则默认为当前受邀看电影的村民（若无人受邀，默认为阿比盖尔）。
|
| RANDOM_ARTIFACT_FOR_DIG_SPOT | 返回在Data/Objects中类型为Arch（古物）的随机物品，其满足如下要求：其Miscellaneous字段的生成规则符合当前地点，且其通过随机概率检查。此查询主要用于远古斑点。 |
TOOL_UPGRADES [tool ID]
|
返回Data/Shops所列出的、玩家背包中有相应升级材料的工具升级（即，类似于克林特的工具升级）。若指定了[tool ID]，则仅返回对应工具的升级。
|
物品生成字段
物品生成字段是一系列公共字段，用于在诸如机器或商店的数据素材中使用物品查询。仅适用于明确声明允许使用物品查询的数据素材。
| 字段 | 效果 | ||
|---|---|---|---|
| ID | 当前列表中此条目的唯一字符串ID（而不是物品自己的ID）。
这是半可选的，即，若缺省则从 ItemId、 RandomItemId 和 IsRecipe 字段中自动生成。然而，若不同项目具有相同ID，则可能导致意外行为（例如，商店物品ID冲突会导致买一件商品却消耗所有冲突物品的库存），因此推荐使用全局唯一的ID。 | ||
| ItemId | 下列值之一
| ||
| RandomItemId | （可选） 一个物品ID列表，将从中随机选择一项物品。该列表格式与ItemId相同（适用物品查询）。若设置此参数，则ItemId为可选参数且被忽略。该列表中每个条目都有等概率被选中。例如：
// wood, stone, or pizza
"RandomItemId": [ "(O)388", "(O)390", "(O)206" ]
| ||
| 条件 | （可选） 指示是否应当应用此条目的游戏状态查询。默认为true。
注意： 不适用于武器抛射物。 | ||
| PerItemCondition | （可选） 用于筛选其他字段返回物品的游戏状态查询。默认为true。
例如，此字段可用于筛选RANDOM_ITEMS等查询返回的物品： // random mineral
"ItemId": "RANDOM_ITEMS (O)",
"PerItemCondition": "ITEM_CATEGORY Target -12"
| ||
| MaxItems | （可选） 若此条目返回多组不同的物品，则此字段规定了返回的最大组数（但不会影响每组物品的堆叠数量；欲配置堆叠数量，参见MinStack和MaxStack字段）。默认为无穷。 | ||
| IsRecipe | （可选） 是否获取此物品对应的打造/烹饪配方，而非物品本身。默认为false。
若尚未获得相应配方，则自动解锁具有如下ID的配方：其ID等于该物品查询的ObjectInternalName字段，或等于目标物品的内部Name字段（默认为物品ID）。 | ||
| Quality | （可选） 待查找物品的品质。为 0（普通）、1（银星）、2（金星）、4（铱星）。无效数值会舍入到最近的有效数值（例如7舍入到4）。默认为-1，代表保持物品查询的值不变（通常为0）。 | ||
| MinStack | （可选） 物品的最小和默认堆叠数量。默认为-1，代表保持物品查询的值不变（通常为1）。 | ||
| MaxStack | （可选） 若设为大于MinStack的值，则堆叠数值取最小值和最大值之间的随机值（包含端点值）。默认为-1。 | ||
| ObjectInternalName | （可选） 仅用于物体。待使用的内部名称。默认为此物品在Data/Objects的名称。 | ||
| ObjectDisplayName | （可选） 仅用于物体。用于显示该物品名称的模板字符串。默认为此物品在Data/Objects的显示名称。可以包括 %DISPLAY_NAME（物品的默认显示名称）和 %PRESERVED_DISPLAY_NAME（若通过诸如机器数据中的PreserveId等方式设置了风味物品名称，则显示风味物品的名称）。
注意： 此字段中的文本会被永久存储至物品的信息，即使玩家更改语言或更换内容包也不会改变。这包括会保存当前语言的翻译文本的Content Patcher翻译（例如
| ||
| ToolUpgradeLevel | （可选） 仅用于工具。创建工具时的初始等级（例如铜/金斧头，或训练用鱼竿/铱金鱼竿）。默认为-1，即保持物品查询的值不变（通常为0）。 | ||
| QualityModifiers StackModifiers |
（可选） 应用在Quality或Stack数值上的数量修饰器。默认为none。
数量修饰器会更改品质数据（即，0 = 普通，1 = 银星，2 = 金星，4 = 铱星）。例如，银星 × 2 = 金星。 | ||
| QualityModifierMode StackModifierMode |
（可选） 指示QualityModifiers或StackModifiers字段中如果出现多个数量修饰器，这些修饰器相互作用的方式。 | ||
| ModData | （可选） 添加到待创建物品中的模组数据。默认为none。
例如： "ModData": {
"Example.ModId_FieldName": "some custom data"
}
|
关于C#模组作者
在自定义数据素材中使用物品查询
可使用ItemQueryResolver类以解析物品查询。
例如，考虑一个使用了物品生成字段的自定义数据模型，此模型用于决定添加到一开始的礼盒中的礼物：
public class InitialGiftsModel
{
public List<GenericSpawnItemData> Items = new();
}
可以使用如下方式为其生成物品：
ItemQueryContext itemQueryContext = new();
foreach (GenericSpawnItemData entry in model.Items)
{
Item item = ItemQueryResolver.TryResolveRandomItem(entry, itemQueryContext, logError: (query, message) => this.Monitor.Log($"Failed parsing item query '{query}': {message}", LogLevel.Warn));
// or TryResolve to get all items
}
亦可使用GenericSpawnItemDataWithCondition以与游戏状态查询相配合：
ItemQueryContext itemQueryContext = new();
foreach (GenericSpawnItemDataWithCondition entry in model.Items)
{
if (!GameStateQuery.CheckConditions(entry.Condition))
continue;
Item item = ItemQueryResolver.TryResolveRandomItem(entry, itemQueryContext, logError: (query, message) => this.Monitor.Log($"Failed parsing item query '{query}': {message}", LogLevel.Warn));
}
添加自定义物品查询
可以使用ItemQueryResolver.Register("Example.ModId_QueryName", handleQueryMethod)定义新的物品查询。为避免冲突，自定义查询名称应当遵从唯一字符串ID惯例。