Modding:Migrate to Stardew Valley 1.7

←Index

This page is for mod authors. Players: see the mod compatibility list instead.

⚠ Stardew Valley 1.7 was announced, but has no planned release date.
There's no estimate for when the update will be released, so don't plan mod updates around the 1.7 release. Things will change before it's released!

This page helps mod authors prepare their mods for the upcoming Stardew Valley 1.7, and documents some of the changes and new functionality.

FAQs

SMAPI mod compatibility over time.

What's changing?

Stardew Valley 1.7 makes significant changes to many data assets to enable new game features and mod extensibility. See the sections below for more details.

Is this the modapocalypse?

Probably not. SMAPI and Content Patcher will automatically rewrite older mods for many of the changes, so they should still work as-is. Some mods may need an update.

How to update your mod

Here's a suggested 'quick start' guide to update a mod for Stardew Valley 1.7.

For C# mods:

1. Update for Stardew Valley 1.6.16 if you haven't already.
2. Rebuild the solution.
3. Fix any build errors and review any build warnings. You can search this page and previous migration guides for relevant info as needed.
4. Increment your mod version in manifest.json.
   (Some mods may be added to SMAPI's compatibility blacklist due to runtime errors. Incrementing the mod version will fix that if so.)
5. Test to make sure the mod works.
6. Skim through this page, and check any section that might be relevant to the mod.

For Content Patcher packs:

1. Update for Stardew Valley 1.6.16 if you haven't already.
2. Skim through this page, and check any section that might be relevant to the mod.

For content packs which use another framework:

See the documentation for the framework mod. Often you won't need to update the content pack if the framework mod itself was updated.

Data asset changes

Data/Boots

This has been overhauled into a data model asset, with translations moved into a new Strings/Boots asset. This also includes new fields like ContextTags and CustomFields which weren't available in the old format.

The data asset now consists of a string → model lookup, where...

• The key is the unqualified item ID.
• The value is a model with the fields listed below.

field	effect
basic info
Name	The internal item name (not shown in-game).
DisplayName Description	A tokenizable string for the item's in-game display name and description.
ContextTags	(Optional) The custom context tags to add for this item (in addition to the tags added automatically based on the other item data), specified as an array.
equipment effects
AddDefense AddImmunity	(Optional) A bonus applied to the player's defense or immunity stats when the boots are equipped. Default 0.
appearance
Texture	The asset name for the texture containing the boots sprite. Defaults to Maps/springobjects if omitted, but should always be specified for custom boots.
SpriteIndex	(Optional) The sprite's index within the Texture, where 0 is the top-left sprite. Default 0.
ColorTexture	(Optional) The asset name for the texture containing the boots color sprite. Defaults to Characters/Farmer/shoeColors if omitted.
ColorSpriteIndex	(Optional) The color sprite's index within the ColorTexture, where 0 is the top-left sprite. Default 0.
advanced
CustomFields	(Optional) The custom fields for this entry.

For example, here's how to add new boots in 1.7:

{
    "Format": "2.8.0",
    "Changes": [
        // add data
        {
            "Action": "EditData",
            "Target": "Data/Boots",
            "Entries": {
                "{{ModId}}_FancyBoots": {
                    "Name": "{{ModId}}_FancyBoots",
                    "DisplayName": "{{i18n: fancy-boots.name}}",
                    "Description": "{{i18n: fancy-boots.description}}",
                    "Texture": "Mods/{{ModId}}/Boots",
                    "SpriteIndex": 0,
                    "ColorSpriteIndex": 1
                }
            }
        },

        // add texture
        {
            "Action": "Load",
            "Target": "Mods/{{ModId}}/Boots",
            "FromFile": "assets/boots.png"
        }
    ]
}

Data/Buffs

Added one new field:

field	effect
CustomFields	(Optional) The custom fields for this entry.

Data/Events/*

See event changes below.

Data/Furniture

This has been overhauled into a data model asset. The overhaul also adds support for previously-hardcoded features like custom item descriptions (via Description), custom TVs (via the new Television furniture type and TelevisionScreen* fields), and custom fields.

The data asset now consists of a string → model lookup, where...

• The key is the unqualified item ID.
• The value is a model with the fields listed below.

field	effect
basic info
Name	The internal item name (not shown in-game).
DisplayName	A tokenizable string for the item's in-game display name.
Description	(Optional) A tokenizable string for the item's in-game description. Defaults to a generic description based on the other fields like CanPlaceIndoors and CanPlaceOutdoors.
Type	(Optional) The furniture type, which affects various furniture functionality and default values (e.g. default bounding box size). Defaults to Other. See table of valid types.
Price	(Optional) The price for this furniture when purchased from a shop. Default 0.
ContextTags	(Optional) The custom context tags to add for this item (in addition to the tags added automatically based on the other item data), specified as an array.
behavior
CanPlaceIndoors CanPlaceOutdoors	(Optional) Whether the player can place this furniture indoors and/or outdoors. Defaults to generic behavior based on the Type field (e.g. TVs can't be placed outdoors by default).
ExcludeFromRandomSale	(Optional) Whether to prevent this furniture from being shown in randomly generated shop stock or furniture catalogues. Default false.
appearance
Texture	The asset name for the texture containing the furniture sprite. Defaults to TileSheets/furniture if omitted, but should always be specified for custom furniture.
SpriteIndex	(Optional) The sprite's index within the Texture, where 0 is the top-left sprite. Default 0.
Rotations	(Optional) The number of rotations possible (1, 2, or 4). Default 1.
SpriteSize	(Optional) The sprite's size in the Texture, measured in tiles. Defaults to a generic size depending on the Type field.
BoundingBoxSize	(Optional) The collision box size when the furniture is placed in-game, measured in tiles. Defaults to a generic size depending on the Type field. The bounding box is anchored to the bottom-left corner of the SpriteSize. Width will push the right side of the box to the right, height will push the top of the box upwards.
type-specific options
BedType	(Optional) When the Type field is set to Bed, the bed type which affects who can sleep in it. Default Single. Valid values: bed type effect Single A single-sized bed with room for one player or NPC. Double A double-sized bed with room for two players or NPCs. Child A single bed for a child NPC.
TelevisionScreenOffset	(Optional) When the Type field is set to Television, the X and Y pixel offset relative to the TV's bounding box to apply when drawing the screen image onto the TV. Default none.
TelevisionScreenScale	(Optional) When the Type field is set to Television, the zoom multiplier to apply to the screen image so it fits onto the TV's screen.
advanced
CustomFields	(Optional) The custom fields for this entry.

Data/Hats

This has been overhauled into a data model asset, with translations moved into a new Strings/Hats asset. This also includes new fields like ContextTags and CustomFields which weren't available in the old format.

The data asset now consists of a string → model lookup, where...

• The key is the unqualified item ID.
• The value is a model with the fields listed below.

field	effect
basic info
Name	The internal item name (not shown in-game).
DisplayName Description	A tokenizable string for the item's in-game display name and description.
HairStyle	(Optional) What to do about the player's hair when they wear this hat. Default DrawObscuredHair. The possible values are: DrawFullHair: the hair is drawn like usual (e.g. for hats that don't hide the hair like Abigail's bow). DrawObscuredHair: the hair is partly obscured under the hat (e.g. for most hats like the cowboy hat). HideHair: the hair is fully hidden (e.g. for hats which fully cover the head like the mummy mask).
SkipHairOffset	(Optional) Whether to skip offsetting the hat to sit 'on top' of the player's current hairstyle (e.g. for masks). Default false.
Texture	The asset name for the texture containing the hat sprite. Defaults to Characters/Farmer/hats if omitted, but should always be specified for custom hats.
SpriteIndex	(Optional) The sprite's index within the Texture, where 0 is the top-left sprite. Default 0.
ContextTags	(Optional) The custom context tags to add for this item (in addition to the tags added automatically based on the other item data), specified as an array.
CustomFields	(Optional) The custom fields for this entry.

For example, here's how to add a new hat in 1.7:

{
    "Format": "2.8.0",
    "Changes": [
        // add data
        {
            "Action": "EditData",
            "Target": "Data/Hats",
            "Entries": {
                "{{ModId}}_FancyHat": {
                    "Name": "{{ModId}}_FancyHat",
                    "DisplayName": "{{i18n: fancy-hat.name}}",
                    "Description": "{{i18n: fancy-hat.description}}",
                    "HairStyle": "DrawObscuredHair",
                    "Texture": "Mods/{{ModId}}/Hats",
                    "SpriteIndex": 0
                }
            }
        },

        // add texture
        {
            "Action": "Load",
            "Target": "Mods/{{ModId}}/Hats",
            "FromFile": "assets/hats.png"
        }
    ]
}

Data/Monsters

Monster data has been completely rethought in Stardew Valley 1.7. In particular...

• For monster data in general:
  • Data/Monsters has been been overhauled into a data model asset, with translations moved into a new Strings/Monsters asset. This includes significant new features which weren't supported with the old format.
  • A new 'monster variant' concept lets multiple specific monsters share common data (e.g. Green Slime and Tiger Slime are variants of the new base Slime monster). This is particularly used for common drops.
  • A new 'monster tag' system lets monster define custom tags like slime_is_prismatic, which can be used to filter monster drops.
• For monster drops:
  • A rethought monster drop system supports the full range of vanilla features like conditions, item queries, qualified item IDs for non-object drops, and monster-specific concepts like repeating drop chance and mutually-exclusive drops.
  • All drops are now qualified item IDs. The former 'resource IDs' (formatted as negative numbers like -4) are no longer supported; items are converted into their equivalent resource debris automatically where needed.
  • Nearly all monster drops are now defined in Data/Monsters (with just a few hardcoded drops common to all monsters left).

The data asset now consists of a string → model lookup, where...

• The key is the unique string ID.
• The value is a model with the fields listed below.

field	effect
basic info
DisplayName	A tokenizable string for the monster's display name.
IsGlider	(Optional) Whether the monster is flying (e.g. so they glide over obstacles). Default false.
IsMineMonster	(Optional) Whether this monster spawns in the mines, and should be buffed after the player reaches the bottom. This sometimes applies to monsters that can appear elsewhere too (e.g. wilderness golems on the farm receive mine buffs too). Default false.
ExperiencePoints	(Optional) The combat experience points received for defeating the monster. Default 1.
stats
Health	(Optional) The initial hit points. Default 20.
Attack	(Optional) The attack power (i.e. how much damage its hits inflict on players). Default 5.
Defense	(Optional) The defense which reduces damage received by this monster. Default 0.
DodgeChance	(Optional) The percentage chance that the monster dodges an attack, as a value between 0 (never) and 1 (always). Default 0.
Speed	(Optional) The default movement speed. Default 1.
Jitteriness	(Optional) How often the monster will move in random non-player directions to try to get around objects, as a value between 0 (never) and 1 (always). Default 0.1.
DetectionDistance	(Optional) The distance at which the monster detects a player and begins moving towards them, or -1 for unlimited. Default 4.
drops
Drops	(Optional) The items which can drop when the monster is defeated. Default none. All matching entries are dropped. If the player has a burglar's ring equipped, each entry will make two attempts to drop (but fields like RepeatingChance and SkipIfDropped are independent between the two attempts). This consists of a list of models with these fields: field effect common fields See item spawn fields for the generic item fields supported for monster drops. Notes: If a drop has an item query which returns multiple item stacks, one of them will be selected at random. The Condition field can optionally contain the %RANDOM_KEY token, which is set to a unique identifier for this monster during the current tick. ForTags (Optional) The monster tags for which this drop applies. This can be a context tag-like query string like !variant_frost_bat, !variant_lava_bat (not frost bat or lava bat). Default none, meaning it applies to all monsters with this data. Chance (Optional) A probability that this item will be found, as a value between 0 (never) and 1 (always). Default 1. RepeatingChance (Optional) A compounding probability of an extra drop, as a value between 0 (never) and .95 (nearly always). Default 0. This applies after an item has been dropped based on the other fields. This chance is repeatedly checked to produce an extra drop until it fails. Each repeat drop will ignore the Chance and Condition fields, but reapply all other item spawn fields (e.g. re-selecting RandomItemId if applicable). RepeatingChanceKey (Optional) When checking the RepeatingChance field, use this to seed a predictable RNG. This can be used to synchronize separate drops. Default none. This can optionally contain the %RANDOM_KEY token, which is set to a unique identifier for this monster during the current tick. ExplodeStack (Optional) Whether to split multi-item stacks into single-item stacks. Default false. For example, let's say a monster would drop a stack of 15 wood. With this option enabled, it would instead drop 15 stacks of one wood each. SkipIfDropped (Optional) Skip the current entry if one of these drop IDs have already been dropped. Default none. This is specified as an array. For example: "SkipIfDropped": [ "ExampleDropId", "AnotherDropId" ]
variants
DefaultVariant	(Optional) When the game creates a monster of this type without specifying a variant, use the given variant instead of creating it from only the base data. Default false.
Variants	(Optional) The possible variations of this monster. Default none. Each variant is simply a set of fields which override the base data when set. For example, this creates a variant which only differs from the base monster by name and health points: "Variants": [ { "DisplayName": "{{i18n: variant-name}}", "Health": 50 } This consists of a list of models with these fields: field effect monster fields All monster fields (except DefaultVariant and Variants) can be set on the variant. All fields are optional, and default to the value set in the monster's base data. InheritDrops (Optional) Whether to inherit drops defined in the monster's base Drops field. Default true. Specifically: If true, the variant will combine the base Drops and variant Drops into one list. If false, only drops in the variant Drops field are applied.
advanced
CustomFields	(Optional) The custom fields for this entry.

For example, this Content Patcher code adds a new 'Pufferchick' monster which drops pufferfish when defeated. The monster's spritesheet is automatically loaded from Monsters/<ID>.

Note: this only adds the monster data. Currently this does nothing unless you have another mod which spawns instances of the monster in-game.

{
    "Format": "2.8.0",
    "Changes": [
        // add data
        {
            "Action": "EditData",
            "Target": "Data/Monsters",
            "Entries": {
                "{{ModId}}_Pufferchick": {
                    "DisplayName": "{{i18n: pufferchick.name}}",
                    "ExperiencePoints": 3,

                    "Health": 30,
                    "Attack": 2,
                    "Defense": 5,
                    "DodgeChance": 0.3,
                    "Speed": 2,
                    "DetectionDistance": 2,

                    "Drops": [
                        {
                            "Id": "Pufferfish",
                            "ItemId": "(O)128",
                            "Chance": 0.5,
                            "RepeatingChance": 0.1
                        }
                    ]
                }
            }
        },

        // add texture
        {
            "Action": "Load",
            "Target": "Monsters/{{ModId}}_Pufferchick",
            "FromFile": "assets/pufferchick.png"
        }
    ]
}

Data/Objects

Added one new field:

field	effect
Buffs	This field already existed, but has a field change: field effect CustomAttributes This field already existed, but has one new field: field effect CustomFields (Optional) The custom fields for this entry.

Changes for all mod authors

Switch blocks

'Switch blocks' are a new ${…}$ syntax which can be used in nearly all game text (not just dialogue). This extends the former 'gender-switch blocks' added in 1.6.0.

These are applied before most other commands or parsing, so you can safely use them in cases where characters like ^ have a different meaning (e.g. mail text).

The supported switch blocks are:

type	syntax	description
gender	${male^female} ${male^female^non-binary}	Switch between text for male, female, and non-binary players. The non-binary value is only used if a mod overrides the player's gender, since the in-game UI only allows male or female. You can also use ¦ instead of ^, in which case any ^ characters are left as-is. For example: "Mon": "Hey ${lad^lass^kiddo}$!"
randomize	${variant A ||| …}$	Defines an arbitrary number of variants from which to choose each day. After randomization, any leading or trailing whitespace is trimmed. This randomization is deterministic per day (e.g. reloading the save won't change which one is shown). For example, let's say you did this: "Rainy_Night": "I ${love ||| like ||| adore ||| somewhat enjoy ||| enjoy}$ rain.$h" That would create five variants which each have an equal probability of being selected.

Switch blocks can be arbitrary combined and nested. For example:

"Rainy_Night": "${Hello there ||| Hey ${lad^lass^kiddo}$ }$!"

Context tag changes

Added new context tags:

context tag	item types	effect
is_galaxy_weapon	weapons	Marks the tool as a galaxy weapon like the galaxy hammer or galaxy sword. This is set for vanilla scythes through Data/Weapons. This affects logic which checks for galaxy weapons (e.g. galaxy soul enchantments).

Dialogue changes

• Added a new special token in dialogue strings:

  token

  description

  |||

  This is a shortcut for the randomize switch block. Delimits an arbitrary number of dialogue variants from which to choose each day. After randomization, any leading or trailing whitespace is trimmed. This randomization is deterministic per day (e.g. reloading the save won't change which one is shown). For example, let's say you did this: "Rainy_Night": " I love rain.$h||| I like rain.$h||| I adore rain.$h||| I hate rain.$s#$b#Just kidding. I love it!$h||| I enjoy rain.$h " That would create five variants of the dialogue which each have an equal probability of being selected.

• Improved some special tokens:

  token	changes
  ||	Whitespace around the token is now ignored, so you can split text into multiple lines: "Wed8": " Isn't it expensive, coming to the desert so often like you do?#$e#You must really like to see me, huh? Hmmm... $h|| *sigh*... I do miss the beautiful flowers of Stardew Valley...$s "

• Some dialogues were merged or renamed using the new features. The previous dialogue keys are now ignored by the game.

  asset	former key	changes
  Characters/Dialogue/<NPC name>	Resort_<number> Resort_Bar_<number> Resort_Chair_<number> Resort_Dance_<number> Resort_Shore_<number> Resort_Towel_<number> Resort_Umbrella_<number> Resort_Wander_<number>	Merged into their base key (e.g. Resort_<random> into Resort) using the new ||| random-variant token.
  Characters/Dialogue/MarriageDialogue Characters/Dialogue/MarriageDialogue<NPC name> Characters/Dialogue/MarriageDialogue<NPC name>Roommates	funLeave_<NPC name> funReturn_<NPC name> jobLeave_<NPC name> jobReturn_<NPC name> patio_<NPC name> spouseRoom_<NPC name> spring_<NPC name> summer_<NPC name> fall_<NPC name> winter_<NPC name>	Moved into MarriageDialogue<NPC name> and removed the NPC suffix (like spouseRoom_<NPC name> → spouseRoom).
  	Indoor_Day_0 Indoor_Day_1 Indoor_Day_2 Indoor_Day_3 Indoor_Day_4	Merged into Indoor_Day.
  	Indoor_Night_0 Indoor_Night_1 Indoor_Night_2 Indoor_Night_3 Indoor_Night_4 Indoor_Night_<NPC name>	Merged into Indoor_Night.
  	NoBed_0 NoBed_1 NoBed_2 NoBed_3	Merged into NoBed.
  	Outdoor_0 Outdoor_1 Outdoor_2 Outdoor_3 Outdoor_4 Outdoor_<NPC name>	Merged into Outdoor.
  	Rainy_Day_0 Rainy_Day_1 Rainy_Day_2 Rainy_Day_3 Rainy_Day_4	Merged into Rainy_Day.
  	Rainy_Night_0 Rainy_Night_1 Rainy_Night_2 Rainy_Night_3 Rainy_Night_4 Rainy_Night_5 Rainy_Night_<NPC name>	Merged into Rainy_Night.

Enchantment data

Enchantments have been partly de-hardcoded into a new Data/Enchantments data asset. Mods can now easily add new enchantments, including enchantments applied through the forge using a prismatic shard or a custom item ID.

However, this logic is still hardcoded:

• Forging innate enchantments. The innate enchantments are in data, but the logic to choose which to apply is still hardcoded.
• Forging diamonds into a weapon to fill all its weapon stat slots.
• Forging three galaxy souls into galaxy weapons to transform them into infinity weapons. (The 'Galaxy Soul' enchantment is in data, but the transformation is hardcoded.)
• Several enchantments' effects when applied (though weapon buff effects are in data).

This consists of a string → model lookup, where...

• The key is the unique string ID for the enchantment.
• The value is a model with the fields listed below.

field	effect
DisplayName	A tokenizable string for the enchantment's display name, shown in tooltips. This can contain {0} for the enchantment level, if applicable.
ForgeWith	(Optional) If set, this enchantment is applied to tools by forging an item with this qualified ID into it. Default none, in which case it won't be applicable through the forge.
AppliesTo	(Optional) The tools or weapons to which this enchantment can be applied. Defaults to all tools/weapons. This is specified as an array of context tag queries. The enchantment can be applied if at least one query matches. "AppliesTo": [ "melee_weapon, !is_scythe", // any non-scythe melee weapon "hoe, upgrade_level_4" // any hoe upgraded to iridium or higher ]
IsForge	(Optional) Whether this is a weapon stat enchantment applied through the forge. Default false.
IsSecondary	(Optional) Whether this is an innate enchantment applied through the forge using a dragon tooth. Default false.
IsVisible	(Optional) Whether the enchantment should be shown in the tool/weapon's tooltip. Default true.
MaximumLevel	(Optional) The number of times this enchantment can be applied to the same tool to upgrade the enchantment level (e.g. for weapon stat enchantments). A value of 1 means there's only one enchantment level, so it can't be upgraded by applying the enchantment again. Default 1.
EquipmentEffects	(Optional) The buffs applied to the weapon when this enchantment is applied. This consists of a list of models with the fields below. You can specify any number of entries; the first one which matches the tool will be applied. field effect Id A unique string ID for this entry. MinLevel (Optional) The minimum enchantment level for which these stats apply. Default 0 (i.e. any level). other fields See the Effects field in Data/Buffs, which is equivalent to this model.
advanced
CustomFields	(Optional) The custom fields for this entry.
ClassName	(Optional, specialized) The name of the C# class to construct within the StardewValley.Enchantments namespace. The class must be a subclass of StardewValley.Enchantments.Enchantment, and have a constructor with no arguments. For example, given a value of BottomlessEnchantment, the game will create StardewValley.Enchantments.BottomlessEnchantment instances. This should usually be omitted, in which case the game will create a generic Enchantment instance which uses the data in Data/Enchantments for its ID.

Event changes

Multilingual events

All vanilla events are now multilingual, with a single copy of each event script which uses translation keys. Translations from the old per-language event files were moved into a per-language Strings/Events file.

For example:

files in 1.6.16	files in 1.7
Data/Events/Beach Data/Events/Beach.de-DE Data/Events/Beach.es-ES Data/Events/Beach.fr-FR Data/Events/Beach.hu-HU Data/Events/Beach.it-IT Data/Events/Beach.ja-JP Data/Events/Beach.ko-KR Data/Events/Beach.pt-BR Data/Events/Beach.ru-RU Data/Events/Beach.tr-TR Data/Events/Beach.zh-CN	Data/Events/Beach

Content Patcher content packs should generally be unaffected, since their edits were applied to the active version of the file automatically (which will just become the base file in all languages).

In rare cases, a mod which directly targets a specific localized asset name like Data/Events/Beach.fr-FR may no longer work or break vanilla events (depending on how it edits them). That should be a very rare case, since the APIs for both Content Patcher and SMAPI were designed to discourage doing that.

Forking deprecated

All vanilla events which used forking now use goto labels instead.

Forking still works like before for backwards compatibility, but mod events should prefer goto labels since...

• they work more consistently and intuitively with other features like skip labels;
• it's the approach that the game will be applying and developing in future versions;
• deprecated commands will be reported as an error if you use the EventValidator;
• and there's no guarantee forking will always work in future versions.

The fork-related event commands are deprecated.

Precondition slash now required for numeric event IDs

In Stardew Valley 1.6.0–16, the behavior of an event key with no / depended on whether the ID was numeric. A numeric event ID like 10040609 was treated as an event with no precondition, while a string event ID like PlayerKilled was treated as a manual script. In 1.7+, the behavior is now consistent: any event ID without a slash (like 10040609) is treated as a manual script, and any with a slash (like 10040609/) is treated as an event.

In other words:

event key format	behavior in 1.6.16	→	behavior in 1.7
<id>	event if numeric, else manual script	→	manual script
<id>/[preconditions]	event	→	event

New event commands

command	description
choose <question> [<answer> <go to label>]+	Show a dialogue box to choose from a list of responses, then optionally skip to a label based on the selected answer. Arguments: argument usage <question> The translation key or literal text to show above the choices. This can be empty ("") to omit the question line. <answer> The translation key or literal text for an answer to show. <go to label> If the player chooses this answer, jump to this label in the event (see the goto command for more info). This can be "" or _ to continue to the next command instead. For example, here's a simple choice which doesn't affect anything: choose "Do you like apples?" "I love them." _ "I hate them." _/ Or you can change the course of the event based on the choice: speak Abigail "Do you... like me?$l"/ choose "" "Yes!" happy "No." heartbroken/ label heartbroken/ speak Abigail "Oh. I understand.$s"/ faceDirection Abigail left/ pause 3000/ end/ label happy/ speak Abigail "We should explore the mines together next time!$h"/ ...
conditionSpeak <npc> [<dialogue> [condition]]+	Make an NPC say a dialogue based on arbitrary conditions. The first dialogue with a matching dialogue is spoken; if none match, the command is skipped. Arguments: argument usage <npc> The internal name of the NPC who should speak (which can be marked optional). <dialogue> The translation key or literal text for the dialogue to speak. If omitted or empty, the command is skipped when the condition is matched. [condition] One of: a game state query; or ANSWERED <response ID>+ as a shortcut for the PLAYER_HAS_DIALOGUE_ANSWER Current query; or omitted/blank to always match this dialogue if no previous one matched. For example, here Maru says a different line if the player suggested she tell the truth: conditionSpeak Maru "I accidentally dropped one of the samples... I'm so sorry.$s" "ANSWERED 38" "@ came in and slammed the door so loud I dropped this sample.$u"
goto [<target> [condition]]+	Skip forward or backward to a specific position in the event script. Each <target> can be: target description end Jump to the last end event command in the script. any other value Jump to the first label command with this name. You can list any number of label/condition pairs, and it will go to the first label with a matching condition. If a condition is omitted, it defaults to always true. If none of the conditions match, it continues to the next command normally. For example, this event script uses goto to repeat a question until a specific answer is selected: .../ label question/ choose Abigail "Hey! Did you have your eye on someone?" "Abigail" correct "Penny" wrong "Alex" wrong/ label wrong/ speak Abigail "Oh?$u"/ pause 500/ goto question/ label correct/ speak Abigail \"I thought so!$l\"/ pause 500/ end You can make goto conditional using game state queries. For example, this will go to the divorced label if you divorced Abigail, and continue to the next command if not: goto divorced "PLAYER_NPC_RELATIONSHIP Current Abigail Divorced"/
label <label>	Set a named position in the event script, which you can go to using the goto command. Note: you can't use end as a label name, since that automatically matches the end event command.

Improved existing commands

command	description
splitSpeak	You should now specify each dialogue as a separate argument (though the old syntax will still work): // in 1.6.16 splitSpeak Sam "You think so?~Yeah... kids should play and have fun while they still have the chance." // in 1.7 splitSpeak Sam "You think so?" "Yeah... kids should play and have fun while they still have the chance." This also now works with the new choose command too.

Deprecated commands

These event commands are deprecated. They still work just like before (except the ones at the bottom of the table), but if you use the EventValidator it'll report them as an error.

event command	migration
fork resetVariable switchEvent	Use the choose or goto commands instead. If you used dialogue containing the %fork token, it should be removed and replaced with equivalent event commands.
question forkX	Use the choose command instead, and replace the event fork with a label. For example, this script: // main event question fork1 "#I believe in you!#Wow, you're really arrogant."/ fork arrogant/ speak Alex "Thanks, @. I'll remember that."/ ... // 'arrogant' event emote Alex 12/ speak Alex "Hmmph... I think someone's a little jealous.$a"/ Becomes this script: choose "" "I believe in you!" believe "Wow, you're really arrogant." arrogant/ label believe/ speak Alex "Thanks, @. I'll remember that."/ ... label arrogant/ emote Alex 12/ speak Alex "Hmmph... I think someone's a little jealous.$a"/ ... Forks often duplicated the end of the script. In that case, you can have both variants just goto the common ending instead.
question null	Use choose with _ labels instead. (Setting a label argument to _ means it'll just continue to the next command instead.) For example, this command: question null "But what am I going to say to Vincent?#It's best to be honest with kids.#You did the right thing. Kids should have hope."/ Would become this command: choose "But what am I going to say to Vincent?" "It's best to be honest with kids." _ "You did the right thing. Kids should have hope." _/
quickQuestion	Use the choose command instead. The <question> and <answerX> have matching choose arguments, while the <answerX script> arguments become labels. For example, this command: quickQuestion #I'd like to help#Nah, I'll pass...(break)emote Willy 32\speak Willy "Aye... I thought you would.$h#$b#I'll leave this door unlocked for ya... you can come drop off the materials whenever you like."(break)emote Willy 28\speak Willy "Alright, suit yourself...$s#$b#If you have a change of heart, you can always come back and help out. I'll leave this door unlocked, anyhow."/ Becomes this script: choose "" "I'd like to help" accept "Nah, I'll pass..." refuse/ label accept/ emote Willy 32/ speak Willy "Aye... I thought you would.$h#$b#I'll leave this door unlocked for ya... you can come drop off the materials whenever you like."/ goto resume/ label refuse/ emote Willy 28/ speak Willy "Alright, suit yourself...$s#$b#If you have a change of heart, you can always come back and help out. I'll leave this door unlocked, anyhow."/ label resume/
cutscene bandfork elliottBookTalk question haleyDarkRoom question shaneCliffs question shaneLoan	These commands are deleted and will no longer work. They're unlikely to be used by mod events, but see their relevant events for the new equivalents if needed.

Changed event keys

Events were generally unified and de-hardcoded in 1.7. In particular...

• Several events were previously defined in the game's C# code, where they couldn't be changed by content packs. Most of these were moved into Data/Events/* with translations in Strings/Events:

  event	new asset name	new event ID
  forest raccoon finished event	Data/Events/Forest	RaccoonFinish
  forest trash bear cleanup	Data/Events/Forest	777111
  island Gourmand crop inspection	Data/Events/islandFarmCave	GourmandInspection
  summit perfection cutscene	Data/Events/Summit	SummitPerfection
  summit cheat event	Data/Events/Summit	SummitCheat

• Others were moved from non-event data into Data/Events/*:

  event	old location	new asset	new event ID
  Birdie quest intro & completed	Strings/Locations:IslandSecret_Event_BirdieIntro Strings/Locations:IslandSecret_Event_BirdieFinished Strings/Locations:alreadyGotNuts	Data/Events/IslandWest	-888999 (intro) -666777 (completed)
  field office intro & completed	Strings/Locations:IslandFieldOffice_Intro_Event Strings/Locations:FieldOfficeFinale	Data/Events/IslandFieldOffice	FieldOfficeIntro FieldOfficeDone
  Leo intro	Strings/Locations:IslandHut_Event_ParrotBoyIntro	Data/Events/IslandHut	LeoIntro
  Meowmere event	Strings/1_6_Strings:ForestPylonEvent	Data/Events/WizardHouseBasement	ForestPylon
  Mr. Qi Skull Cavern level 100	Data/ExtraDialogue:SkullCavern_100_event Data/ExtraDialogue:SkullCavern_100_event_honorable	Data/Events/SkullCave	SkullCavern100
  Professor Snail exits cave	Strings/Locations:IslandNorth_Event_SafariManAppear	Data/Events/IslandNorth	ProfSnailIntro

• Other event keys were changed or merged as part of the other event changes:

  asset	entry key	change in 1.7
  Data/Events/AbandonedJojaMart	missingBundleComplete	Event key changed to 192393 to match the event ID.
  Data/Events/Farm	992559/t 600 1130/n clothFound/o Emily/w sunny 992559/t 600 1130/n clothFound/O Emily/w sunny	Merged into a single 992559/Time 600 1130/LocalMail clothFound/Weather sunny event.
  Data/Events/QiNutRoom	10040609	Event key changed to 10040609/ per the precondition change.
  Data/Events/SamHouse	94/e 93/k 95/t 1800 1950/i 136/y 1 94/e 93/k 95/t 1800 1950/i 136/y 2	Merged into a single 95/SawEvent 93/!SawEvent 94/Time 1800 1950/HasItem 136 event.
  Data/Events/Town	611173/Hn pamHouseUpgrade/o Penny	Merged into the existing 611173/Hn pamHouseUpgrade event.

For events that didn't previously have an event ID, their new IDs will be added to the player's seen-events list automatically if needed when the save is loaded.

Other event changes

• Moved all vanilla events' on-skip behavior into their event scripts (except the pet adoption logic).

Fish pond changes

• Added new fish pond translation keys:

  asset	key	usage
  Strings/UI	PondQuery_<key>_<item ID> PondQuery_<key>_<attitude>	All PondQuery_* translation keys can now be suffixed with either the qualified item ID of the fish, or the fish's general attitude based on their fish_talk_* context tag. For example, the 'fish are OK' message for an anchovy pond will be loaded from the first key which exists in this order: PondQuery_StatusOk_(O)129, PondQuery_StatusOk_Rude, or PondQuery_StatusOk.

• Merged some fish pond translation keys:

  asset	former key	changes
  Strings/UI	PondQuery_Status<status><number (0–6)> PondQuery_StatusRequestComplete_<fish disposition><number (0–2)> PondQuery_StatusRequestPending_<fish disposition><number (0–2)>	Removed the number key suffixes using switch blocks (e.g. merged PondQuery_StatusOk<number> into PondQuery_StatusOk).

• Coral and Sea urchin now have the fish_talk_coral context tag instead of a hardcoded _Coral translation key suffixes.

Item query changes

Added one new item query:

query	effect
SEASONAL_RACCOON_SEED	Get a seasonal raccoon seed for the current season. This sets the stack size to the recommended amount based on the player's luck. When used in item spawn fields, you can set MinStack and MaxStack to override the stack size.

Item spawn field changes

• Added new item spawn fields:

  field	effect
  Enchantments	(Optional) For tools and weapons, the enchantment IDs to apply (matching their IDs in Data/Enchantments). This field applies the normal enchantment rules. Default none. This is specified as an array, and you can repeat secondary enchantments to boost their level. For example, this applies Vampiric and Attack (level 2): "Enchantments": [ "Vampiric", "Attack", "Attack" ]

  DialogueKeyValidator

  The new DialogueKeyValidator class analyses dialogue entries to detect dialogue keys which don't match one of the predefined patterns.

  This is mainly meant to implement unit tests. For example, to validate all dialogue keys in a data asset:

  string assetName = "Characters/Dialogues/Abigail";
  var dialogues = Game1.content.Load<Dictionary<string, string>>(assetName);
  
  var validator = new DialogueKeyValidator();
  foreach ((string key, string dialogue) in dialogues)
  {
      if (!validator.IsKnownFormat(assetName, key))
          Assert.Fail($"Validation failed for dialogue '{key}': key doesn't match one of the expected patterns.");
  }
  

  You can optionally extend the valid patterns by setting validator fields like MarriageDialogueKeyPatterns.

  EventValidator changes

  The EventValidator class added in 1.6.16 lets you detect issues in event scripts (mainly meant for unit tests).

  Stardew Valley 1.7 adds one token recognized by the EventArguments attribute:

  token	meaning
  goToLabel	An event label (see the goto and label event commands). This is equivalent to word, but is used by EventValidator to validate label references.

  Content manager changes

  1.7 adds a SourceCodeContentManager implementation of IContentManager. This is meant for internal unit tests, and isn't relevant for mod authors except as an example.

  Monster changes

  • The monster data has been overhauled.
  • The new monster.Tags field contains a set of metadata tags about the monster which can be checked in Data/Monsters. It's safe to add new tags to the list for existing monster types.
  • The former monster.objectsToDrop field (a list of string object IDs) has been replaced by monster.drops (an item inventory).
  • Removed monster.getExtraDropItems(). Drops should be added in Data/Monsters instead.

  Other breaking API changes

  (This section is meant as a quick reference if you have build errors; there's no need to read through it otherwise.)

  Removed or renamed types

  These classes renamed in 1.7:

  type	migration
  BaseEnchantment	Renamed to Enchantment.
  AxeEnchantment BaseWeaponEnchantment FishingRodEnchantment HoeEnchantment MilkPailEnchantment PanEnchantment PickaxeEnchantment ShearsEnchantment WateringCanEnchantment	Obsolete. Enchantments now target tools via data instead.

  Other API changes

  These class members changed in 1.7:

  type	member	migration
  BaseEnchantment (and its subclasses)	hideEnchantmentName	Replaced by EnchantmentManager.HideEnchantmentName.
  	hideSecondaryEnchantName	Replaced by EnchantmentManager.HideSecondaryEnchantName.
  	GetEnchantmentFromItem(…)	Replaced by EnchantmentManager.GetEnchantmentFromItem.
  	GetAvailableEnchantments()	Removed. To check whether any enchantments can be applied to a tool through the forge, use EnchantmentManager.CanForgeEnchant. There's no directly equivalent method in 1.7, but you can mimic the former logic if needed. static List<Enchantment> GetAvailableEnchantments() { var dataAsset = DataLoader.Enchantments(Game1.content); List<Enchantment> enchantments = []; foreach ((string id, EnchantmentData data) in dataAsset) { if (data.ForgeWith == Object.prismaticShardQID) enchantments.Add(EnchantmentManager.CreateEnchantment(dataAsset, id)); } return enchantments; }
  	GetAvailableEnchantmentsForItem(…)	Removed. To check whether any enchantments can be applied to a tool through the forge, use EnchantmentManager.CanForgeEnchant. There's no directly equivalent method in 1.7, but you can mimic the former logic if needed. static List<Enchantment> GetAvailableEnchantmentsForItem(Item? tool, Item? item) { var dataAsset = DataLoader.Enchantments(Game1.content); var contextTags = tool?.GetContextTags(); List<Enchantment> enchantments = []; foreach ((string id, EnchantmentData data) in dataAsset) { if (data.ForgeWith == Object.prismaticShardQID && (contextTags is null || EnchantmentManager.MatchesTags(contextTags, data.AppliesTo))) enchantments.Add(EnchantmentManager.CreateEnchantment(dataAsset, id)); } return enchantments; }
  	GetName()	Removed. This inconsistently returned an ID, a display name, or "Unknown Enchantment" depending on the enchantment type. Use the new Id property or the pre-existing GetDisplayName() method instead.
  	GetLevel()	Removed. Use Level instead.
  	GetType()	This was sometimes to identify enchantments (like enchantment.GetType() == expectedEnchantment.GetType()). That's no longer reliable, since 1.7 introduces data-based enchantments which may not have their own C# type. You should use the new enchantment.Id property instead.
  	ResetEnchantments()	Removed. This is no longer needed since it no longer has a cached list of enchantment instances.
  Furniture	armchair bed bench bookcase chair couch decor dresser fireplace lamp longTable other painting rug sconce table torch window	Removed. Replaced by the FurnitureType enum (e.g. Furniture.rug is now FurnitureType.Rug).
  	placementRestrictions	Removed. Replaced by CanPlaceIndoors and CanPlaceOutdoors.
  Monster	getExtraDropItems()	Removed. Drops should be added to Data/Monsters instead. Harmony patches which can't be moved into data can target Monster.RollForDrops instead.
  	objectsToDrop	Removed. Replaced by drops; see monster changes and Data/Monsters.
  Tool	GetEnchantmentLevel<T>() GetEnchantmentOfType<T>() hasEnchantmentOfType<T>()	Removed. Replaced by GetEnchantmentLevel(id), GetEnchantment(id), and HasEnchantment(id) respectively. All vanilla enchantments have a constant for the ID like EnchantmentIds.GalaxySoul.

  Name translation changes for wiki maintainers

  Some in-game item and monster names were retranslated in some languages for clarity or correctness.

  This list is mostly provided to help wiki maintainers update pages, so it doesn't include names which only changed capitalization, changed ' (straight apostrophe) to ’ (curly) in French, or aren't visible to vanilla players (like mine rocks).

  None yet.

  XNB impact

  Overview

  This section provides a summary of the XNB files which changed in Stardew Valley 1.7. This doesn't include new files (since they won't impact existing mods) or text changes in non-English files.

  XNB mods are disproportionately affected, since...

  1. they replace the entire file;
  2. they're loaded through the MonoGame content pipeline which is less tolerant of format changes;
  3. they don't benefit from the compatibility rewrites Content Patcher provides for its content packs.

  Content Patcher packs are typically unaffected (and Content Patcher will try to rewrite content packs automatically). However if a content pack replaces an entire asset instead of editing, it's more likely to be affected like an XNB mod.

  Changed assets

  Compatibility is broadly grouped into four categories:

  • "✘ broken": mods will remove new content or significant changes, or the mod's intended changes will no longer work. Effects may range from display bugs to crashes, depending how the game uses that specific content.
  • "✘ will remove changes": mods will remove minor changes in 1.7 (e.g. typo fixes).
  • "✓ mostly unaffected": mods will only be affected if they edit specific entries or fields.
  • Blank: no expected impact for the vast majority of mods.

  content asset	changes in 1.7	compatibility for pre-1.7 mods
  		XNB mods	Content Patcher packs
  Characters/Dialogue/Abigail	Merged resort dialogue keys. Removed event dialogues moved into Strings/Events. Fixed invalid dialogue keys.	✘ broken	✓ mostly unaffected
  Characters/Dialogue/Alex Characters/Dialogue/Clint	Merged resort dialogue keys. Removed event dialogues moved into Strings/Events.	✘ broken	✓ mostly unaffected
  Characters/Dialogue/Demetrius	Removed event dialogues moved into Strings/Events.
  Characters/Dialogue/Dwarf	Fixed invalid dialogue keys.	✘ broken	✓ mostly unaffected
  Characters/Dialogue/Elliott	Merged resort dialogue keys. Removed event dialogues moved into Strings/Events. Fixed invalid dialogue key.	✘ broken	✓ mostly unaffected
  Characters/Dialogue/Emily	Removed event dialogues moved into Strings/Events.
  Characters/Dialogue/Evelyn	Removed event dialogues moved into Strings/Events. Fixed invalid dialogue key.	✘ broken	✓ mostly unaffected
  Characters/Dialogue/Haley	Merged resort dialogue keys. Removed event dialogues moved into Strings/Events.	✘ broken	✓ mostly unaffected
  Characters/Dialogue/Harvey	Removed event dialogues moved into Strings/Events. Fixed invalid dialogue key.	✘ broken	✓ mostly unaffected
  Characters/Dialogue/Jodi	Fixed invalid dialogue key.	✘ broken	✓ mostly unaffected
  Characters/Dialogue/Kent	Removed event dialogues moved into Strings/Events.
  Characters/Dialogue/Leah	Merged resort dialogue keys. Removed event dialogues moved into Strings/Events.	✘ broken	✓ mostly unaffected
  Characters/Dialogue/Lewis	Removed event dialogues moved into Strings/Events. Fixed invalid dialogue key.	✘ broken	✓ mostly unaffected
  Characters/Dialogue/MarriageDialogue Characters/Dialogue/MarriageDialogue*	Merged some dialogue keys. Merged some keys from the base asset into NPC-specific assets.	✘ broken	✓ mostly unaffected
  Characters/Dialogue/Maru	Merged resort dialogue keys. Removed event dialogues moved into Strings/Events.	✘ broken	✓ mostly unaffected
  Characters/Dialogue/Pam	Removed event dialogues moved into Strings/Events.
  Characters/Dialogue/Penny	Merged resort dialogue keys. Removed event dialogues moved into Strings/Events.	✘ broken	✓ mostly unaffected
  Characters/Dialogue/Pierre Characters/Dialogue/Robin	Removed event dialogues moved into Strings/Events.
  Characters/Dialogue/Sam	Merged resort dialogue keys. Removed event dialogues moved into Strings/Events.	✘ broken	✓ mostly unaffected
  Characters/Dialogue/Sebastian	Merged resort dialogue keys. Removed event dialogues moved into Strings/Events. Fixed invalid dialogue key.	✘ broken	✓ mostly unaffected
  Characters/Dialogue/Shane	Removed event dialogues moved into Strings/Events.
  Data/Boots	Overhauled format.	✘ broken	✘ broken (until Content Patcher adds runtime migrations)
  Data/Buffs	Added new data field to data model.	✘ broken
  Data/Buildings Data/Characters	Added new item spawn field.	✘ broken
  Data/Events/* Data/Events/Festivals/*	Major changes including multilingual events, event labels, event key changes, replacing dialogue commands with event commands, etc.	✘ broken	✓ mostly unaffected
  Data/ExtraDialogues	Moved hardcoded events into Data/Events/*. Moved SummitEvent_* translations into Strings/Events (with a new name & format).	✓ mostly unaffected	✓ mostly unaffected
  Data/FishPondData Data/FruitTrees	Added new item spawn field.	✘ broken
  Data/Furniture	Overhauled format.	✘ broken	✘ broken (until Content Patcher adds runtime migrations)
  Data/GarbageCans Data/GiantCrops	Added new item spawn field.	✘ broken
  Data/Hats	Overhauled format.	✘ broken	✘ broken (until Content Patcher adds runtime migrations)
  Data/Locations	Added new item spawn field.	✘ broken
  Data/Machines	Added new item spawn field.	✘ broken
  Data/Monsters	Overhauled format.	✘ broken	✘ broken (until Content Patcher adds runtime migrations)
  Data/Movies	Added new item spawn field.	✘ broken
  Data/Objects	Added new data field to data model and new item spawn fields. Added fish_talk_coral context tag for coral and sea urchin.	✘ broken	✓ mostly unaffected
  Data/Pets Data/Shops	Added new item spawn field.	✘ broken
  Data/Weapons	Added new item spawn field. Added is_galaxy_weapon context tag for galaxy weapons.	✘ broken	✓ mostly unaffected
  Data/WildTrees	Added new item spawn field.	✘ broken
  Strings/1_6_Strings	Moved hardcoded events into Data/Events/*. Moved some translations into Strings/EnchanmentNames, Strings/Events, and Strings/Furniture.	✓ mostly unaffected	✓ mostly unaffected
  Strings/EnchantmentNames	Added translations moved from Strings/1_6_Strings. Renamed two keys (Auto-Hook → <samp.AutoHook, Bug Killer → BugKiller).	✘ broken	✓ mostly unaffected
  Strings/Events	Added translations for multilingual events. Added translations moved from NPC dialogue assets.	✘ broken
  Strings/Furniture	Added translations for catalogue descriptions (moved from Strings/1_6_Strings).	✘ broken
  Strings/Locations	Moved hardcoded events into Data/Events/*. Moved some event translations into Strings/Events.	✓ mostly unaffected	✓ mostly unaffected
  Strings/Objects	Moved catalogue descriptions into Strings/Furniture.	✓ mostly unaffected	✓ mostly unaffected
  Strings/UI	Merged some fish pond translation keys.	✘ broken	✓ mostly unaffected