Difference between revisions of "Modding:Item queries"

From Stardew Valley Wiki
Jump to navigation Jump to search
(copy content from Modding:Migrate to Stardew Valley 1.6 (main author Pathoschild, with a RANDOM_ITEMS example code typo fix by Lumisteria))
 
(split queries into subsections)
Line 5: Line 5:
 
This page documents '''item queries''', a built-in way to create one or more items based on a string command.
 
This page documents '''item queries''', a built-in way to create one or more items based on a string command.
  
−
==Copied from [[Modding:Migrate to Stardew Valley 1.6]]==
 
 
''Item queries'' choose one or more items dynamically, instead of specifying a single item ID. These are used in various places like [[#Custom machines|machine data]] and [[#Custom shops|shop data]].
 
''Item queries'' choose one or more items dynamically, instead of specifying a single item ID. These are used in various places like [[#Custom machines|machine data]] and [[#Custom shops|shop data]].
  
−
====Available queries====
+
==Available queries==
−
The supported item queries are:
+
===General use===
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 35: Line 34:
 
* <code>ALL_ITEMS @isRandomSale</code> will return every item in the game that's not excluded from random sale.
 
* <code>ALL_ITEMS @isRandomSale</code> will return every item in the game that's not excluded from random sale.
 
* <code>ALL_ITEMS (F) @isRandomSale</code> will return every furniture item in the game that's not excluded from random sale.
 
* <code>ALL_ITEMS (F) @isRandomSale</code> will return every furniture item in the game that's not excluded from random sale.
−
|-
 
−
| <samp>DISH_OF_THE_DAY</samp>
 
−
| The [[The Stardrop Saloon#Rotating Stock|Saloon's dish of the day]].
 
 
|-
 
|-
 
| <samp>FLAVORED_ITEM {{t|type}} {{t|ingredient ID}} {{o|ingredient flavor ID}}</samp>
 
| <samp>FLAVORED_ITEM {{t|type}} {{t|ingredient ID}} {{o|ingredient flavor ID}}</samp>
Line 43: Line 39:
  
 
For aged roe only, the {{o|ingredient flavor ID}} is the flavor of the {{t|ingredient ID}}. For example, <samp>FLAVORED_ITEM AgedRoe (O)812 128</samp> creates Aged Pufferfish Roe (812 is [[roe]] and 128 is [[pufferfish]]).
 
For aged roe only, the {{o|ingredient flavor ID}} is the flavor of the {{t|ingredient ID}}. For example, <samp>FLAVORED_ITEM AgedRoe (O)812 128</samp> creates Aged Pufferfish Roe (812 is [[roe]] and 128 is [[pufferfish]]).
−
|-
 
−
| <samp>ITEMS_SOLD_BY_PLAYER {{t|shop location}}</samp>
 
−
| Random items the player has recently sold to the {{t|shop location}}, which can be one of <samp>SeedShop</samp> (Pierre's store) or <samp>FishShop</samp> (Willy's fish shop).
 
−
|-
 
−
| <samp>LOCATION_FISH {{t|location}} {{t|bobber tile}} {{t|depth}}</samp>
 
−
| A random item that can be found by fishing in the given location. The {{t|location}} should be the internal name of the location, {{t|bobber tile}} is the position of the fishing rod's bobber in the water (in the form <samp>{{t|x}} {{t|y}}</samp>), and {{t|depth}} is the bobber's distance from the nearest shore measured in tiles (where 0 is directly adjacent to the shore).
 
−
 
−
'''Careful:''' since the target location might use <samp>LOCATION_FISH</samp> queries in its list, it's easy to cause a circular reference by mistake (e.g. location A gets fish from B, which gets fish from A). If this happens, the game will log an error and return no item.
 
−
|-
 
−
| <samp>LOST_BOOK_OR_ITEM {{o|alternate query}}</samp>
 
−
| Returns a [[Lost Books|lost book]] if the player hasn't found them all yet, else the result of the {{o|alternate query}} if specified, else nothing.
 
−
 
−
For example, <code>LOST_BOOK_OR_ITEM (O)770</code> returns [[Mixed Seeds|mixed seeds]] if the player found every book already.
 
−
|-
 
−
| <samp>RANDOM_ARTIFACT_FOR_DIG_SPOT</samp>
 
−
| A random item which is defined in <samp>Data/Objects</samp> with the <samp>Arch</samp> (artifact) type, and whose spawn rules in the <samp>Miscellaneous</samp> field match the current location and whose random probability passes. This is mainly used by [[Artifact Spot|artifact spots]].
 
−
|-
 
−
| <samp>RANDOM_BASE_SEASON_ITEM</samp>
 
−
| A random seasonal vanilla item which can be found by searching garbage cans, breaking containers in the mines, etc.
 
 
|-
 
|-
 
| <samp>RANDOM_ITEMS {{t|type definition ID}} {{o|min ID}} {{o|max ID}} {{o|flags}}</samp>
 
| <samp>RANDOM_ITEMS {{t|type definition ID}} {{o|min ID}} {{o|max ID}} {{o|flags}}</samp>
Line 115: Line 92:
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
|}
 +
 +
===Specific items===
 +
{| class="wikitable"
 +
|-
 +
! query
 +
! effect
 +
|-
 +
| <samp>DISH_OF_THE_DAY</samp>
 +
| The [[The Stardrop Saloon#Rotating Stock|Saloon's dish of the day]].
 +
|-
 +
| <samp>LOST_BOOK_OR_ITEM {{o|alternate query}}</samp>
 +
| A [[Lost Books|lost book]] if the player hasn't found them all yet, else the result of the {{o|alternate query}} if specified, else nothing.
 +
 +
For example, <code>LOST_BOOK_OR_ITEM (O)770</code> returns [[Mixed Seeds|mixed seeds]] if the player found every book already.
 +
|-
 +
| <samp>RANDOM_BASE_SEASON_ITEM</samp>
 +
| A random seasonal vanilla item which can be found by searching garbage cans, breaking containers in the mines, etc.
 
|-
 
|-
 
| <samp>SECRET_NOTE_OR_ITEM {{o|alternate query}}</samp>
 
| <samp>SECRET_NOTE_OR_ITEM {{o|alternate query}}</samp>
−
| Returns a [[Secret Notes|secret note]] (or [[Journal Scraps|journal scrap]] on the island) if the player hasn't found them all yet, else the result of the {{o|alternate query}} if specified, else nothing.
+
| A [[Secret Notes|secret note]] (or [[Journal Scraps|journal scrap]] on the island) if the player hasn't found them all yet, else the result of the {{o|alternate query}} if specified, else nothing.
  
 
For example, <code>SECRET_NOTE_OR_ITEM (O)390</code> returns [[clay]] if the player found every secret note already.
 
For example, <code>SECRET_NOTE_OR_ITEM (O)390</code> returns [[clay]] if the player found every secret note already.
Line 123: Line 118:
 
| <samp>SHOP_TOWN_KEY</samp>
 
| <samp>SHOP_TOWN_KEY</samp>
 
| The special [[Key To The Town|town key]] item. This is only valid in shops.
 
| The special [[Key To The Town|town key]] item. This is only valid in shops.
 +
|}
 +
 +
===Specialized===
 +
{| class="wikitable"
 +
|-
 +
! query
 +
! effect
 +
|-
 +
| <samp>ITEMS_SOLD_BY_PLAYER {{t|shop location}}</samp>
 +
| Random items the player has recently sold to the {{t|shop location}}, which can be one of <samp>SeedShop</samp> (Pierre's store) or <samp>FishShop</samp> (Willy's fish shop).
 +
|-
 +
| <samp>LOCATION_FISH {{t|location}} {{t|bobber tile}} {{t|depth}}</samp>
 +
| A random item that can be found by fishing in the given location. The {{t|location}} should be the internal name of the location, {{t|bobber tile}} is the position of the fishing rod's bobber in the water (in the form <samp>{{t|x}} {{t|y}}</samp>), and {{t|depth}} is the bobber's distance from the nearest shore measured in tiles (where 0 is directly adjacent to the shore).
 +
 +
'''Careful:''' since the target location might use <samp>LOCATION_FISH</samp> queries in its list, it's easy to cause a circular reference by mistake (e.g. location A gets fish from B, which gets fish from A). If this happens, the game will log an error and return no item.
 +
|-
 +
| <samp>RANDOM_ARTIFACT_FOR_DIG_SPOT</samp>
 +
| A random item which is defined in <samp>Data/Objects</samp> with the <samp>Arch</samp> (artifact) type, and whose spawn rules in the <samp>Miscellaneous</samp> field match the current location and whose random probability passes. This is mainly used by [[Artifact Spot|artifact spots]].
 
|-
 
|-
 
| <samp>TOOL_UPGRADES {{o|tool ID}}</samp>
 
| <samp>TOOL_UPGRADES {{o|tool ID}}</samp>

Revision as of 18:06, 21 January 2024

The following describes the upcoming Stardew Valley 1.6, and may change before release.

← Index

This page documents item queries, a built-in way to create one or more items based on a string command.

Item queries choose one or more items dynamically, instead of specifying a single item ID. These are used in various places like machine data and shop data.

Available queries

General use

query effect
ALL_ITEMS [type ID] [flags] Every item provided by the item data definitions. If [type ID] is set to an item type identifier (like (O) for object), only returns items from the matching item data definition.

The [flags] specify options to apply. If specified, they must be at the end of the argument list (with or without [type ID]). The flags can be any combination of:

flag effect
@isRandomSale Don't return items marked 'exclude from random sale' in Data/Furniture or Data/Objects.
@requirePrice Don't return items with a sell-to-player price below data-sort-value="1">Gold.png1g.

For example:

  • ALL_ITEMS will return every item in the game.
  • ALL_ITEMS @isRandomSale will return every item in the game that's not excluded from random sale.
  • ALL_ITEMS (F) @isRandomSale will return every furniture item in the game that's not excluded from random sale.
FLAVORED_ITEM <type> <ingredient ID> [ingredient flavor ID] A flavored item like Apple Wine. The <type> can be one of AgedRoe, Honey, Jelly, Juice, Pickle, Roe, or Wine. The <ingredient ID> is the qualified or unqualified item ID which provides the flavor (like Apple in Apple Wine). For Honey, you can set the <flavor ID> to -1 for Wild Honey.

For aged roe only, the [ingredient flavor ID] is the flavor of the <ingredient ID>. For example, FLAVORED_ITEM AgedRoe (O)812 128 creates Aged Pufferfish Roe (812 is roe and 128 is pufferfish).

RANDOM_ITEMS <type definition ID> [min ID] [max ID] [flags] All items from the given type definition ID in randomized order, optionally filtered to those with a numeric ID in the given [min ID] and [max ID] range (inclusive).

The [flags] specify options to apply. If specified, they must be at the end of the argument list (with or without [min ID] and/or [max ID]). The flags can be any combination of:

The flags can be any combination of:

flag effect
@isRandomSale Don't return items marked 'exclude from random sale' in Data/Furniture or Data/Objects.
@requirePrice Don't return items with a sell-to-player price below data-sort-value="1">Gold.png1g.

For example, you can sell a random wallpaper for data-sort-value="200">Gold.png200g in Data/Shops: 

{
    "ItemId": "RANDOM_ITEMS (WP)",
    "MaxItems": 1,
    "Price": 200
}

Or a random house plant: 

{
    "ItemId": "RANDOM_ITEMS (F) 1376 1390",
    "MaxItems": 1
}

Or a random custom item added by a mod by its item ID prefix: 

{
    "ItemId": "RANDOM_ITEMS (O)",
    "MaxItems": 1,
    "PerItemCondition": "ITEM_ID_PREFIX Target AuthorName_ModName_"
}

Or 10 random objects with any category except -13 or -14: 

{
    "ItemId": "RANDOM_ITEMS (O)",
    "MaxItems": 10,
    "PerItemCondition": "ITEM_CATEGORY, !ITEM_CATEGORY Target -13 -14"
}

Specific items

query effect
DISH_OF_THE_DAY The Saloon's dish of the day.
LOST_BOOK_OR_ITEM [alternate query] A lost book if the player hasn't found them all yet, else the result of the [alternate query] if specified, else nothing.

For example, LOST_BOOK_OR_ITEM (O)770 returns mixed seeds if the player found every book already.

RANDOM_BASE_SEASON_ITEM A random seasonal vanilla item which can be found by searching garbage cans, breaking containers in the mines, etc.
SECRET_NOTE_OR_ITEM [alternate query] A secret note (or journal scrap on the island) if the player hasn't found them all yet, else the result of the [alternate query] if specified, else nothing.

For example, SECRET_NOTE_OR_ITEM (O)390 returns clay if the player found every secret note already.

SHOP_TOWN_KEY The special town key item. This is only valid in shops.

Specialized

query effect
ITEMS_SOLD_BY_PLAYER <shop location> Random items the player has recently sold to the <shop location>, which can be one of SeedShop (Pierre's store) or FishShop (Willy's fish shop).
LOCATION_FISH <location> <bobber tile> <depth> A random item that can be found by fishing in the given location. The <location> should be the internal name of the location, <bobber tile> is the position of the fishing rod's bobber in the water (in the form <x> <y>), and <depth> is the bobber's distance from the nearest shore measured in tiles (where 0 is directly adjacent to the shore).

Careful: since the target location might use LOCATION_FISH queries in its list, it's easy to cause a circular reference by mistake (e.g. location A gets fish from B, which gets fish from A). If this happens, the game will log an error and return no item.

RANDOM_ARTIFACT_FOR_DIG_SPOT A random item which is defined in Data/Objects with the Arch (artifact) type, and whose spawn rules in the Miscellaneous field match the current location and whose random probability passes. This is mainly used by artifact spots.
TOOL_UPGRADES [tool ID] The tool upgrades listed in Data/Shops whose conditions match the player's inventory (i.e. the same rules as Clint's tool upgrade shop). If [tool ID] is specified, only upgrades which consume that tool ID are shown.
Retrieved from "https://stardewvalleywiki.com/mediawiki/index.php?title=Modding:Item_queries&oldid=152823"