Modding:Game state queries

From Stardew Valley Wiki
Jump to navigation Jump to search

Index

This page documents game state queries, a built-in way to specify conditions in some of the game's data assets inspired by Content Patcher's conditions.

Overview

Query format

A query consists of a comma-delimited list of conditions in the form <type> [arguments]. The type can be prefixed with ! to negate it. The query is true if it's null/blank, or if every listed condition exists and is true. For example, !SEASON Spring, WEATHER Here Sun is true on sunny non-spring days.

Game state queries are partly case-sensitive. While some values are case-insensitive (e.g. both SEASON Spring and SEASON spring will work), this isn't consistent. Using the exact capitalization is recommended to avoid issues.

Argument format

Game state queries can take space-delimited arguments. For example, BUILDINGS_CONSTRUCTED Here Cabins has two arguments: Here and Cabins.

If you have spaces within an argument, you can surround it with quotes to keep it together. For example, BUILDINGS_CONSTRUCTED Here "Junimo Hut" passes Junimo Hut as one argument. You can escape inner quotes with backslashes, like ANY "BUILDINGS_CONSTRUCTED Here \"Junimo Hut\"".

Remember that quotes and backslashes inside JSON strings need to be escaped too. For example, "Condition": "BUILDINGS_CONSTRUCTED Here \"Junimo Hut\"" will send BUILDINGS_CONSTRUCTED Here "Junimo Hut" to the game code. Alternatively, you can use single-quotes for the JSON string instead, like "Condition": 'BUILDINGS_CONSTRUCTED Here "Junimo Hut"'.

Queries versus Content Patcher conditions

When making Content Patcher packs, you may be able to achieve a certain effect with either When conditions or game state queries (with different formatting in either case, but the same end result).

Which you use is mainly a performance tradeoff:

  • Content Patcher's When conditions are highly optimized and cached, so thousands of patches can check the same condition without impacting performance and the resulting changes are written once to the asset. Then there's no performance impact after the asset edit, since it's just plain unconditional data. However the asset is reloaded when patches are added/removed, which may impact performance if they change often in some cases (like reloading a map or indoor/outdoor NPC appearance).
  • A game state query has no caching, so it can significantly affect performance when it's checked often. For example, a thousand game state queries checked each update tick means sixty thousand condition evaluations per second. On the other hand, game state queries are faster in cases where the conditions are checked rarely and doing so avoids reloading textures or maps (like Appearance in Data/Characters or Music in Data/Locations).

Built-in queries

Meta

Condition effect
ANY <query>+ Get whether at least one of the listed game state queries match, where each argument is a query. For example, ANY "SEASON Winter" "SEASON Spring, DAY_OF_WEEK Friday" is true if (a) it's winter or (b) it's a spring Friday. You can list any number of queries to check.

You can nest ANY tokens inside of ANY tokens, but you're likely to get yourself into quote escaping madness if you try. Instead, approach as Sum of Products.

Here's an example.

 "ANY \"LOCATION_NAME Here BathHouse_Pool\" \"LOCATION_NAME Here BathHouse_MensLocker\" \"LOCATION_NAME Here BathHouse_WomensLocker\" \"LOCATION_NAME Here Beach, WEATHER Sun Wind, SEASON Summer\" \"IS_EVENT festival_summer5, {{HasMod|contains=spacechase0.SurfingFestival}}\""

Broken down, this means:

  • ANY of the following locations: BathHouse_Pool, BathHouse_MensLocker, BathHouse_WomensLocker.
  • The location Beach but only if it's sunny or windy, and it's summer
  • The event (in this case festival) summer5 is active, and spacechase0.SurfingFestival is installed, as the {{HasMod|contains=spacechase0.SurfingFestival}} token will either resolve to true or false, which are valid tokens.

Remember: you can token inside GSQ!

Date & time

Condition effect
DAY_OF_MONTH <day>+ The day of month. This can be an integer between 1 and 28, or even/odd to match on any even/odd day. You can specify multiple values to match any of them.
DAY_OF_WEEK <day>+ The day of week. This can be an integer between 0 (Sunday) and 6 (Saturday), three-letter English name (like Fri), or full English name (like Friday). You can specify multiple values to match any of them (like DAY_OF_WEEK Monday Tuesday for Monday or Tuesday).
DAYS_PLAYED <min> [max] Whether <min> to [max] (default unlimited) days have been played in the current save (including the current one). This always increments in sync with the date in the base game, but when mods change the in-game date, they may or may not update this value.
IS_FESTIVAL_DAY [location context] [day offset] Whether there's a festival today, with an optional [day offset] (e.g. 1 for tomorrow).

The [location context] (default Any) must be one of these values:

value effect
Any Check for a festival anywhere.
Here Check for a festival in the location context containing the player.
Target Check for a festival in the location context containing the target location.
any other Check for a festival in the given location context ID.
IS_PASSIVE_FESTIVAL_OPEN <id> Whether a passive festival with the given ID is active today, and the current time is within its opening hours.
IS_PASSIVE_FESTIVAL_TODAY <id> Whether a passive festival with the given ID is active today.
SEASON <season>+ The season (one of spring, summer, fall, or winter). You can specify multiple values to match any of them (like SEASON spring summer for spring or summer).
SEASON_DAY [<season> <day>]+ The season (in the same format as SEASON) and day (an integer between 1 and 28). You can specify multiple values to match any of them (like SEASON_DAY fall 15 winter 20 for fall 15 or winter 20).
TIME <min> [max] Whether the current time is between <min> and [max] (default unlimited) inclusively, specified in 26-hour time.
YEAR <min> [max] Whether the current year is between <min> and [max] (default unlimited) inclusively.

Events

Condition effect
IS_EVENT Whether the player is viewing any event or attending any active festival. This doesn't cover passive festivals like the Night Market.
IS_EVENT <event ID>+ Whether the player is viewing an event or attending an active festival whose ID matches one of the specified <event ID> values. Festivals have IDs in the form festival_<season><day> (like festival_spring13 for the Egg Festival).

World

Condition effect
BUILDINGS_CONSTRUCTED <locations> [building type] [min] [max] [count unbuilt] Whether the number of matching buildings is within a range.

For example:

  • BUILDINGS_CONSTRUCTED Here checks if any buildings were constructed in the player's current location.
  • BUILDINGS_CONSTRUCTED Target Cabin checks if there's at least one cabin in the target location.
  • BUILDINGS_CONSTRUCTED All "Junimo Hut" 3 5 checks if there's between 3 and 5 Junimo huts (inclusively) anywhere in the world.

Arguments:

  • <locations>: a target location, or All to count buildings in all locations.
  • [building type]: the building ID in Data/Buildings to count, or All to count all building types. Note that All includes default buildings like the farmhouse.
  • [min]/[max]: the minimum (default 1) and maximum (default unlimited) count to require.
  • [count unbuilt]: whether to count buildings that haven't been fully constructed yet.
CAN_BUILD_CABIN Whether players can build more cabins (i.e. they haven't reached the maximum number of player slots yet).
CAN_BUILD_FOR_CABINS <building ID> Whether there are fewer of the given building constructed than there are cabins.
FARM_CAVE <type>+ The current farm cave (one of Bats, Mushrooms, or None).
FARM_NAME <name> The name of the farm.
FARM_TYPE <type>+ The farm type. The <type> can be one of...
  • a numeric ID for a vanilla farm type: 1 (standard), 2 (riverland), 3 (forest), 4 (hilltop), 5 (combat), 6 (four corners), or 7 (beach);
  • a readable key for a vanilla farm type: Standard, Beach, Forest, FourCorners, Hilltop, Riverland, or Wilderness;
  • or the ID for a custom farm type.
FOUND_ALL_LOST_BOOKS Whether all the Lost Books for the museum have been found.
HAS_TARGET_LOCATION Whether the 'Target' location is explicitly set for the current context (ignoring the fallback to the current player's location).
IS_COMMUNITY_CENTER_COMPLETE Whether the community center has been repaired.
IS_CUSTOM_FARM_TYPE Whether the farm type is a custom one created by a mod. (This returns false for mods which edit/replace a vanilla farm type.)
IS_HOST Whether the current player is the main/host player.
IS_ISLAND_NORTH_BRIDGE_FIXED Whether the North Ginger Island bridge to the dig site has been repaired.
IS_JOJA_MART_COMPLETE Whether the Joja warehouse has been built.
IS_MULTIPLAYER Whether the game is currently in multiplayer mode (regardless of whether there's multiple players connected).
IS_VISITING_ISLAND <name> Whether the named NPC is visiting Ginger Island today.
LOCATION_ACCESSIBLE <name> Whether the given location is accessible. For vanilla locations, this is relevant to CommunityCenter, JojaMart, or Railroad; any other location will return true unless a mod customizes the query.
LOCATION_CONTEXT <location> <context ID>+ The location context ID for the given location.
LOCATION_HAS_CUSTOM_FIELD <location> <key> [value] Checks to see if the location has a given value in its CustomFields. If the value is omitted, checks to see if the key exists at all.
LOCATION_IS_INDOORS <location>
LOCATION_IS_OUTDOORS <location>
LOCATION_IS_MINES <location>
LOCATION_IS_SKULL_CAVE <location>
Whether the given location is indoors, outdoors, in the mines, or in the Skull Cavern.
LOCATION_NAME <location> <name>
LOCATION_UNIQUE_NAME <location> <name>
Whether the given location has the specified name or unique instanced name (you can see both names in-game using the Debug Mode mod).
LOCATION_SEASON <location> [<season>]+ Whether the given location is in one of the given seasons (which can be spring, summer, fall, or winter). This accounts for the SeasonOverride field in the location's context data.

For example, this is valid in spring or summer: LOCATION_SEASON Here spring summer.

MUSEUM_DONATIONS <min count> [max count] [object type]+ Whether all players have donated a total of <min count> to [max count] (default unlimited) inclusively to the museum. This can optionally be filtered by the object type field, like MUSEUM_DONATIONS 40 Arch Minerals to require at least 40 artifacts and minerals combined. You can omit the max count and still specify a filter.
WEATHER <location> <weather> The weather ID in the given location. The weather can be one of Festival, Rain, Snow, Storm, Sun, Wind, or a custom weather ID.
WORLD_STATE_FIELD <name> <value> Whether a property on Game1.netWorldState has the given value. If the property is numeric, this is the minimum value. Some useful values not covered by their own query:
name effect
GoldenCoconutCracked Whether the player has cracked open any Golden Coconuts (true or false).
GoldenWalnutsFound
GoldenWalnuts
The total number of Golden Walnuts found or held by any player. To check how many one player currently holds, see the PLAYER_HAS_ITEM query.
IsGoblinRemoved Whether the Henchman has been removed, so the player can access Witch's Hut (true or false).
IsSubmarineLocked Whether the Night Market submarine is currently in use by a player (true or false).
LostBooksFound The total number of Lost Books found or held by any player.
MinesDifficulty
SkullCavesDifficulty
The current Shrine of Challenge difficulty level for the mine or Skull Cavern (a numeric value, where 0 is the default level when the shrine is deactivated).
MiniShippingBinsObtained The number of times the player has obtained a Mini-Shipping Bin.
ParrotPlatformsUnlocked Whether the player has unlocked Ginger Island parrot platforms, regardless of whether they've completed them (true or false).
ServerPrivacy The multiplayer connection privacy mode (InviteOnly or FriendsOnly).
ShuffleMineChests The value of the 'mine rewards' game option (Default or Remixed).
WeatherForTomorrow The weather ID for tomorrow in the main valley area.
VisitsUntilY1Guarantee The number of times the Traveling Cart will visit before Red Cabbage is guaranteed to drop.

For example, the Traveling Cart shop uses a WORLD_STATE_FIELD VisitsUntilY1Guarantee 0 condition to check if it should guarantee a Red Cabbage item.

WORLD_STATE_FIELD <name> <min> [max] For numeric properties only, whether a property on Game1.netWorldState has a value between <min> and [max] (default unlimited). If [max] is omitted or the properties isn't numeric, the previous form is used. See the previous entry for a list of useful properties.
WORLD_STATE_ID <id>+ Whether any world state flag matching the given <id> values is set.

Player info & progress

Condition effect
MINE_LOWEST_LEVEL_REACHED <min> [max] Whether any player has reached a level between <min> and [max] (default unlimited) inclusively in the mines.
PLAYER_COMBAT_LEVEL <player> <min> [max]
PLAYER_FARMING_LEVEL <player> <min> [max]
PLAYER_FISHING_LEVEL <player> <min> [max]
PLAYER_FORAGING_LEVEL <player> <min> [max]
PLAYER_LUCK_LEVEL <player> <min> [max]
PLAYER_MINING_LEVEL <player> <min> [max]
Whether the specified player(s) have a skill level between <min> and [max] (default unlimited) inclusively, including the effects of buffs which raise them.
PLAYER_CURRENT_MONEY <player> <min> [max] Whether the specified player(s) have between <min> and [max] (default unlimited) gold inclusively.
PLAYER_FARMHOUSE_UPGRADE <player> <min> [max] Whether the specified player(s) have upgraded their farmhouse or cabin to a level between <min> and [max] (default unlimited) inclusively. See possible levels.
PLAYER_GENDER <player> <gender> Whether the specified player(s) are Male or Female.
PLAYER_HAS_ACHIEVEMENT <player> <achievement id> Whether the specified player(s) have unlocked a specific achievement ID. The valid IDs are listed in Data/Achievements, plus a few Steam achievement IDs that aren't listed.
PLAYER_HAS_ALL_ACHIEVEMENTS <player> Whether the specified player(s) have unlocked every achievement listed in Data/Achievements. This doesn't count the extra Steam achievement IDs that aren't listed in that file.
PLAYER_HAS_BUFF <player> <id> Whether the specified player(s) have a given buff ID currently applied.
PLAYER_HAS_CAUGHT_FISH <player> <id> Whether the specified player(s) have caught at least one fish with the given ID.
PLAYER_HAS_CONVERSATION_TOPIC <player> <id> Whether the specified player(s) have a conversation topic with the ID <id> active.
PLAYER_HAS_COOKING_RECIPE <player> <recipe name>
PLAYER_HAS_CRAFTING_RECIPE <player> <recipe name>
Whether the specified player(s) know the crafting/cooking recipe identified by its internal name (spaces allowed). For example, PLAYER_HAS_CRAFTING_RECIPE Current Field Snack.
PLAYER_HAS_DIALOGUE_ANSWER <player> <id> Whether the specified player(s) have chosen the given dialogue answer in a previous dialogue.
PLAYER_HAS_HEARD_SONG <player> <id> Whether the specified player(s) have heard a song track's cue name (e.g. for the jukebox track selection).
PLAYER_HAS_ITEM <player> <item> [min] [max] Whether the specified player(s) have between [min] and [max] (default unlimited) matching items in their inventory, inclusively. The <item> can be 858 or (O)858 (Qi Gems), 73 or (O)73 (Walnuts), or the qualified or unqualified item ID.
PLAYER_HAS_MAIL <player> <mail id> [type] Whether the specified player(s) have the given mail flag set.

The [type] (default Any) can be one of:

type effect
Any Mail in the mailbox, in the queue for tomorrow's mailbox, or already received.
Mailbox Mail in the mailbox.
Tomorrow Mail in the queue for tomorrow's mailbox.
Received Mail which either:
  • was in the mailbox and read by the player;
  • or has no letter in Data/mail, so it was added to the received list directly.
PLAYER_HAS_PROFESSION <player> <profession id> Whether the specified player(s) have the given profession ID.
PLAYER_HAS_RUN_TRIGGER_ACTION <player> <id> Whether the specified player(s) have applied the trigger action with the given <id>.
PLAYER_HAS_SECRET_NOTE <player> <id> Whether the specified player(s) have read a secret note, where <id> is the secret note's integer ID.
PLAYER_HAS_SEEN_EVENT <player> <id> Whether the specified player(s) have seen the event with the given <id>.
PLAYER_HAS_TOWN_KEY <player> Whether the specified player(s) have the town key.
PLAYER_HAS_TRASH_CAN_LEVEL <player> <min> [max] Whether the specified player(s) have a trash can upgrade level between <min> and [max] (default unlimited) inclusively. The <level> can be 0 (base), 1 (copper), 2 (steel), 3 (gold), or 4 (iridium).
PLAYER_LOCATION_CONTEXT <player> <location context> Whether the specified player(s) are in the given location context.
PLAYER_LOCATION_NAME <player> <location name>+
PLAYER_LOCATION_UNIQUE_NAME <player> <location name>+
Whether the specified player(s) are in the given location, using the name or unique instanced name (you can see both names in-game using the Debug Mode mod). The <location name> value doesn't recognize target location keywords like Here.
PLAYER_MOD_DATA <player> <key> <value> Whether the specified player(s) have a player.modData entry added by a mod with the given <key> and <value>.
PLAYER_MONEY_EARNED <player> <min> [max] Whether the specified player(s) have earned between <min> and [max] (default unlimited) gold inclusively.
PLAYER_KILLED_MONSTERS <player> <monster name>+ [min count] [max count] Whether the specified player(s) have killed the given monster(s) between [min count] (default 1) and [max count] (default unlimited) times inclusively. If you list multiple monsters, it'll check the combined count for all of them.

For example:

// killed 50+ slimes, skeletons, and bugs combined
PLAYER_KILLED_MONSTERS Current "Green Slime" Skeleton Bug 50
PLAYER_SHIPPED_BASIC_ITEM <player> <item ID> [min count] [max count] Whether the specified player(s) have shipped the given item between [min count] (default 1) and [max count] (default unlimited) times inclusively. This only works for the items tracked by the game for shipping stats (shown in the shipping collections menu).
PLAYER_SPECIAL_ORDER_ACTIVE <player> <order id> Whether the specified player(s) have the given special order active.
PLAYER_SPECIAL_ORDER_COMPLETE <player> <order id> Whether the specified player(s) have completed the given special order.
PLAYER_SPECIAL_ORDER_RULE_ACTIVE <player> <rule id> Whether the specified player(s) have a special rule active.
PLAYER_STAT <player> <stat name> <min value> [max value] Whether a stat counter for the specified player(s) has a value between <min value> and [max value] (default unlimited) inclusively. The available stat names are...
  • averageBedtime;
  • beachFarmSpawns;
  • beveragesMade;
  • boatRidesToIsland;
  • bouldersCracked;
  • caveCarrotsFound;
  • cheeseMade;
  • chickenEggsLayed;
  • childrenTurnedToDoves;
  • coalFound;
  • coinsFound;
  • copperFound;
  • cowMilkProduced;
  • cropsShipped;
  • daysPlayed;
  • diamondsFound;
  • dirtHoed;
  • duckEggsLayed;
  • exMemoriesWiped;
  • fishCaught;
  • geodesCracked;
  • giftsGiven;
  • goatCheeseMade;
  • goatMilkProduced;
  • goldFound;
  • goodFriends;
  • hardModeMonstersKilled;
  • individualMoneyEarned;
  • iridiumFound;
  • ironFound;
  • itemsCooked;
  • itemsCrafted;
  • itemsForaged;
  • itemsShipped;
  • monstersKilled;
  • mysticStonesCrushed;
  • notesFound;
  • otherPreciousGemsFound;
  • piecesOfTrashRecycled;
  • preservesMade;
  • prismaticShardsFound;
  • questsCompleted;
  • rabbitWoolProduced;
  • rocksCrushed;
  • seedsSown;
  • sheepWoolProduced;
  • slimesKilled;
  • starLevelCropsShipped;
  • stepsTaken;
  • sticksChopped;
  • stoneGathered;
  • stumpsChopped;
  • timesEnchanted;
  • timesFished;
  • timesUnconscious;
  • totalMoneyGifted;
  • trashCansChecked;
  • trufflesFound;
  • walnutsFound;
  • weedsEliminated.
PLAYER_VISITED_LOCATION <player> <location name>+ Whether the specified player(s) have visited one of the given location names. For example, PLAYER_VISITED_LOCATION Current IslandWest checks whether the current player has ever visited Ginger Island West.

Notes:

  • Some locations have both a common name (like Barn) and unique name (like Barn{unique ID}). This tracks the common name.
  • Generated mine and volcano dungeon levels aren't tracked.

Player relationships

Condition effect
PLAYER_FRIENDSHIP_POINTS <player> <npc> <min points> [max points] Whether the specified player(s) have a friend with friendship points between <min points> and [max points] (default unlimited) inclusively. The <npc> can be an NPC's internal name, Any (check every NPC), or AnyDateable (check every romanceable NPC).

For example, this checks if the current player has 750 or more points (i.e. 3+ hearts) with Abigail:

PLAYER_FRIENDSHIP_POINTS Current Abigail 750
PLAYER_HAS_CHILDREN <player> [min] [max] Whether the specified player(s) have a number of children between [min] (default 1) and [max] (default unlimited) inclusively.
PLAYER_HAS_PET <player> Whether the specified player(s) have a pet.
PLAYER_HEARTS <player> <npc> <min hearts> [max hearts] Whether the specified player(s) have a friend with a heart level between <min hearts> and [max hearts] (default unlimited) inclusively. The <npc> can be an NPC's internal name, Any (check every NPC), or AnyDateable (check every romanceable NPC).

For example, this checks if the current player has 3 or more hearts with Abigail:

PLAYER_HEARTS Current Abigail 3
PLAYER_HAS_MET <player> <npc>+ Whether the specified player(s) have talked to one of the given NPCs at least once. The <npc> is an NPC's internal name.
PLAYER_NPC_RELATIONSHIP <player> <npc> <type>+ Whether the specified player(s) have one of the relationship statuses with an NPC. The <npc> can be an NPC's internal name or Any (match any NPC).

<type> can be any combination of these values:

type effect
Friendly Met the NPC, but no other status applies.
Roommate The NPC has moved in with the player as a roommate.
Dating The player has given a bouquet to the NPC, but haven't yet given them a mermaid's pendant.
Engaged The player has given a mermaid's pendant to the NPC, but the marriage hasn't happened yet.
Married The NPC has moved in with the player as a spouse.
Divorced The player has dissolved their marriage with the NPC.
PLAYER_PLAYER_RELATIONSHIP <player> <other player> <type>+ Whether the specified player(s) have one of the relationship types with the other specified player(s). The <other player> can be a target player or Any (match any player).

<type> can be any combination of these values:

type effect
Friendly No other status applies.
Engaged One of the players has given a wedding ring to the other, but the marriage hasn't happened yet.
Married The players are married.
PLAYER_PREFERRED_PET <player> <pet type>+ Whether the preferred pet for the specified player(s) is one of the given types. The vanilla pet types are Cat and Dog.

Randomization

Condition effect
RANDOM <chance> [@addDailyLuck] A random probability check which is re-rolled each time it's called. For example, RANDOM 0.4 is true 40% of the time.

If the exact text @addDailyLuck is specified, the current player's daily luck is added to the probability.

SYNCED_CHOICE <interval> <key> <min> <max> <choices>+ Choose a random integer between <min> and <max> inclusively, and check whether it matches one of the <choices>. The result will be identical for all queries with the same <key> value during the given <interval> (one of tick, day, season, or year), including between players in multiplayer mode.

For example, SYNCED_CHOICE day example_key 1 5 1 2 chooses a random value between 1 and 5, and checks if it's either 1 or 2.

This is mainly useful in cases where you need to pick between a number of discrete cases. For regular probability checks, see SYNCED_RANDOM instead.

SYNCED_RANDOM <interval> <key> <chance> [@addDailyLuck] A random probability check. The result will be identical for all queries with the same <key> value during the given <interval> (one of tick, day, season, or year), including between players in multiplayer mode.

For example, SYNCED_RANDOM day cart_rare_seed 0.4 has a 40% chance to be true the first time it's called that day, and will always be the same value if called again with the same key on the same day.

If the exact text @addDailyLuck is specified, the current player's daily luck is added to the probability.

SYNCED_SUMMER_RAIN_RANDOM <base chance> <day multiplier> A specialized variant of SYNCED_DAY_RANDOM used to calculate the chance of rain in summer, which increases with the day number.

For items only

These queries apply in cases where there's an item (e.g. machine recipes, shops, etc); they'll return false if not applicable. They take a <type> argument which can be Input (the machine input item) or Target (the machine output, tree fruit, shop item, etc).

Condition effect
ITEM_CATEGORY <target> Whether the item has a non-zero category.
ITEM_CATEGORY <target> [category]+ Whether the item's category number matches one of the given values.
ITEM_CONTEXT_TAG <target> <tags> Whether the item has all of the given space-delimited tags. For example, ITEM_CONTEXT_TAG Target bone_item marine_item will only match items with both tags.
ITEM_EDIBILITY <target> [min] [max] Whether the item's edibility is between [min] (default -299) and [max] (default unlimited) inclusively. A value of -300 is inedible, so ITEM_EDIBILITY <target> without min/max values checks if the item is edible.
ITEM_ID <target> <item ID>+ Whether the item has one of the given qualified or unqualified item IDs.
ITEM_ID_PREFIX <target> <prefix> Whether the item's qualified or unqualified item ID starts with the given prefix.
ITEM_NUMERIC_ID <target> [min] [max] Whether the item has a numeric unqualified item ID which is between [min] and [max] (both defaulting to the lowest and highest possible value).
ITEM_OBJECT_TYPE <target> <type>+ Whether the item has one of the given object types.
ITEM_PRICE <target> <min> [max] Whether the item has a default purchase-from-shop price between <min> and [max] (default highest possible value). This checks the base sell price (including profit margins, but excluding custom shop data like custom prices, price modifiers, out-of-season pricing, etc).
ITEM_QUALITY <target> <min> [max] Whether the item's quality is between <min> and [max] (default unlimited) inclusively. The possible values are 0 (normal), 1 (silver), 2 (gold), or 4 (iridium).
ITEM_STACK <target> <min> [max] Whether the item stack size is between <min> and [max] (default unlimited) inclusively. Note that this only applies to the target item, it doesn't include other stacks in the inventory.
ITEM_TYPE <target> <type>+ Whether the item's type definition ID matches one of the given values. For example, ITEM_TYPE Target (BC) matches bigcraftables.
ITEM_HAS_EXPLICIT_OBJECT_CATEGORY <target> (Specialized) Whether the item has an explicit category set in Data/Objects, ignoring categories assigned dynamically in code (e.g. for rings). Items without an explicit category are often (but not always) special items like secret notes or unimplemented items.

Immutable

Condition effect
TRUE A condition which always matches.
FALSE A condition which never matches.

Common values

Target location

Some conditions have a <location> argument. This can be one of...

value result
Here The location containing the current player (regardless of the target player).
Target The location containing the in-game entity being edited (e.g. the machine for Data/Machines or fruit tree for Data/FruitTrees).

If the asset being edited isn't tied to a location, this is the location of the target player (if set), else equivalent to Here.

any other The location ID (i.e. internal name) for the location to check.

Target player

Some conditions have a <player> argument. This can be one of...

value result
Any At least one player must match the condition, regardless of whether they're online.
All Every player must match the condition, regardless of whether they're online.
Current The local player.
Host The main player.
Target This value depends on the context:
context effect
Data/LocationContexts For the PassOutLocations field only, the player whose pass-out location to get.
Data/Weddings For the Attendees field only, the attendee player (if the attendee is a player).
Data/WildTrees For the AdditionalChopDrops field only, the last player who chopped the tree.
custom queries C# mods may specify a target_farmer parameter when calling GameStateQuery.CheckConditions.
any other Equivalent to Current.
any other The unique multiplayer ID for the player to check.

For C# mod authors

Using queries elsewhere

C# code can work with queries using the GameStateQuery class, which provides utility methods like GameStateQuery.CheckConditions(query) or GameStateQuery.IsImmutablyTrue(query).

You can also use game state queries in event preconditions using the new precondition flag, like some_event_id/gameStateQuery !SEASON Spring, WEATHER Here Sun.

Extensibility

C# mods can...

  • check if a query exists using GameStateQuery.Exists("Example.ModId_ConditionName");
  • define custom queries using GameStateQuery.Register("Example.ModId_ConditionName", handleQueryMethod) (using a unique string ID for the query name);
  • and add query aliases using GameStateQuery.RegisterAlias("Example.ModId_AliasName", "Example.ModId_ConditionName") (ideally using a unique string ID for the alias).