Modding:Item queries

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

This page documents item queries, a built-in way to create one or more items dynamically, instead of specifying a single item ID.

Overview

Valid fields

These are used in various places like machine data and shop data. These can only be used if the field docs specifically mentions that it allows item queries.

Query format

An item query consists of a string containing a query name with zero or more arguments. See the list of queries below.

⚠ Item queries are partly case-sensitive. While some values are case-insensitive, this isn't consistent. Using the exact capitalization is recommended to avoid issues.

Argument format

Item queries can take space-delimited arguments. For example, RANDOM_ITEMS (F) 1376 1390 has three arguments: (F), 1376, and 1390.

If you have spaces within an argument, you can surround it with quotes to keep it together. For example, LOST_BOOK_OR_ITEM "RANDOM_ITEMS (O)" passes RANDOM_ITEMS (O) as one argument. You can escape inner quotes with backslashes if needed.

Remember that quotes and backslashes inside JSON strings need to be escaped too. For example, "ItemId": "LOST_BOOK_OR_ITEM \"RANDOM_ITEMS (O)\"" will send LOST_BOOK_OR_ITEM "RANDOM_ITEMS (O)" to the game code. Alternatively, you can use single-quotes for the JSON string instead, like "ItemId": 'LOST_BOOK_OR_ITEM "RANDOM_ITEMS (O)"'.

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">1g.

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">1g.

For example, you can sell a random wallpaper for data-sort-value="200">200g 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.