Modding:Migrate to Stardew Valley 1.6
Revision as of 03:36, 10 December 2022 by Pathoschild (talk | contribs) (→Custom wild trees: update for build 22344 (SeedItemId now optional))
This page is for mod authors. Players: see Modding:Mod compatibility instead.
The following describes the upcoming Stardew Valley 1.6.0, and may change before release.
This page explains how to update your mods for compatibility with the next major game version (tentatively Stardew Valley 1.6.0), and documents some of the changes and new functionality. See also Migrate to SMAPI 4.0.
This describes an unreleased alpha version of the game. Things will change before it's released!
FAQs
What's changing?
Stardew Valley 1.6 makes fundamental changes to the game code to make it more extensible for mods.
Is this the modapocalypse?
Maybe. The update includes major changes to fundamental parts of the game, and SMAPI and Content Patcher can't feasibly rewrite every older mod for compatibility with some of the changes. This will break many existing mods until they're updated for the changes. However, per discussion between the game developers and modding community, we've agreed that this short-term pain is more than offset by the huge long-term improvements to modding.
How to update your mod
- Update your mod code and assets for the changes listed below (particularly Breaking changes for C# mods and Breaking changes for content packs).
- If SMAPI still says your mod is incompatible, check the TRACE messages in the log file for the reason why.
If the logs say "marked 'assume broken' in SMAPI's internal compatibility list", you can increase the Version in your content pack's manifest.json file to bypass it. - Test the mod in-game and make any other changes needed.
What's new architecturally?
.NET 6
- See also: .NET 6 under breaking changes.
For C# mod authors, Stardew Valley 1.6 updates from .NET 5 to .NET 6. See What's new in .NET 6 and What's new in C# 10 for more info, but some highlights include...
- improved performance;
- improved hot reload;
- new LINQ methods;
- record structs;
- and support for ARM64 on macOS.
What's new for items
Custom items
Overview
Stardew Valley 1.6 makes three major changes to how items work in the game:
- Each item now has a string ID (ItemId) and a globally unique string ID (QualifiedItemId). The QualifiedItemId is auto-generated by prefixing the ItemId with the item type identifier.
For legacy reasons, the ItemId for vanilla items may not be globally unique. For example, Pufferfish (object 128) and Mushroom Box (bigcraftable 128) both have ItemId: 128. They can be distinguished by their QualifiedItemId, which are (O)128 and (BC)128 respectively.
- Each item type now has an item data definition in the game code which tells the game how to handle it. C# mods can add or edit definitions. Each definition has a unique prefix which is used in the qualified item IDs. The vanilla types are bigcraftables ((BC)), boots ((B)), farmhouse flooring ((FL)), furniture ((F)), hats ((H)), objects ((O)), pants ((P)), shirts ((S)), tools ((T)), wallpaper ((WP)), and weapons ((W)).
- Custom items can now provide their own item texture, specified in a new field in the item data assets (see below). The item's ParentSheetIndex field is the index within that texture.
In other words, the four important fields for items are:
| name | type | description |
|---|---|---|
| ItemId | string | An item key which should be globally unique, but may not be for existing vanilla items. For example, 128 (vanilla item) or Example.ModId_Watermelon (custom item). This should only have alphanumeric, underscore, and dot characters so it's safe to use in delimited fields, file names, etc. By convention this should include your mod ID or author name, like ExampleAuthor.ModId_ItemName. |
| QualifiedItemId | string | A globally unique item key, like (O)128 for a vanilla item or (O)Example.ModId_Watermelon for a custom one. This is auto-generated from the TypeDefinitionId and ItemId fields. |
| ParentSheetIndex | int | The item's sprite index within its spritesheet. |
| TypeDefinitionId | string | The ID for the data definition which defines the item, like (O) for an object. You can use ItemRegistry.type_* constants with this field:
if (item.TypeDefinitionId == ItemRegistry.type_object)
...
|
Item references
Item references throughout the game code now use the ItemId instead of the ParentSheetIndex. Since the ItemId is identical to the index for existing vanilla items, most data assets are unaffected by this change. For example, here's from Data/NPCDispositions with one custom item:
"Universal_Like": "-2 -7 -26 -75 -80 72 395 613 634 635 636 637 638 724 459 Example.ModID_watermelon"
Unless otherwise noted, unqualified item IDs will produce objects. Some assets let you override that by specifying a QualifiedItemId value instead. For example, you can add (O)128 to the gift taste list to explicitly add for an object. Here's a partial list of data assets and their supported item ID formats:
| data asset | item ID format |
|---|---|
| Data/CraftingRecipes Data/CookingRecipes |
|
| Data/fruitTrees |
|
| Data/NPCGiftTastes | Both supported, but only (O) items can be gifted. |
Item types
These are the item types for which custom items can added/edited:
| item type | type identifier | data asset |
|---|---|---|
| big craftables | (BC) | Data/BigCraftablesInformation Each item can set a custom texture name in field 11, and sprite index in field 10. The default texture is TileSheets/Craftables. |
| boots | (B) | Data/Boots Each item can set a custom texture name in fields 9 (item) and 7 (shoe color), and sprite index in fields 8 (item) and 5 (shoe color). The default textures are Maps/springobjects (item) and Characters/Farmer/shoeColors (shoe color). |
| crops | not technically an item type | Data/Crops Each crop can set a custom texture name in field 9, and sprite index in field 2. The default texture is TileSheets/crops. |
| fish (in fish tanks) | not technically an item type | Data/AquariumFish Each fish can set a custom aquarium texture name in field 6, and sprite index in field 0. The default texture is LooseSprites/AquariumFish. |
| furniture | (F) | Data/Furniture Each item can set a custom texture name in field 9, and sprite index in field 8. The default texture is TileSheets/furniture. |
| fruit trees | not technically an item type | Data/FruitTrees Each fruit tree can set a custom texture name in field 4, and sprite index in field 0. The default texture is TileSheets/fruitTrees. |
| hats | (H) | Data/Hats Each item can set a custom texture name in field 7, and sprite index in field 6. The default texture is Characters/Farmer/hats. |
| objects | (O) | Data/ObjectInformation Each item can set a custom texture name in field 10, and sprite index in field 9. The default texture is Maps/springobjects. |
| pants & shirts | (P) and (S) | Data/ClothingInformation Each item can set a custom texture name in field 10, and sprite index in fields 3 (male) and 4 (female). If field 4 is -1, it'll use the same value as the male index. The default texture is Characters/Farmer/pants and Characters/Farmer/shirts. Shirt textures must be evenly split into two parts: the left half contains the clothing sprites, and the right half contains equivalent dye masks (if any). The texture can be any width as long as it's evenly split (e.g. three clothing sprites + three dye masks wide). sprites dye masks /-----------\ /-----------\ ┌────────────────────────────────┐ │ ┌───┐┌───┐┌───┐┌───┐┌───┐┌───┐ │ │ │ 0 ││ 1 ││ 2 ││ a ││ b ││ c │ │ │ └───┘└───┘└───┘└───┘└───┘└───┘ │ │ ┌───┐┌───┐┌───┐┌───┐┌───┐┌───┐ │ │ │ 3 ││ 4 ││ 5 ││ d ││ e ││ f │ │ │ └───┘└───┘└───┘└───┘└───┘└───┘ │ └────────────────────────────────┘ |
| tools | (T) | Data/Tools Each item can set a custom texture name in the Texture field, and sprite index in the SpriteIndex field. The vanilla tools use the TileSheets/Tools texture. |
| Wallpaper & floorpaper | (WP) and (FL) | Data/AdditionalWallpaperFlooring See format docs. |
| weapons | (W) | Data/Weapons Each item can set a custom texture name in field 16, and sprite index in field 15. The default texture is TileSheets/weapons. |
When resolving an unqualified item ID like 128, the game will get the first item type for which it exists in this order: object, big craftable, furniture, weapon, boots, hat, pants, shirt, tool, wallpaper, and floorpaper.
Define a custom item
You can define custom items for most vanilla item types using only Content Patcher or SMAPI's content API.
For example, this content pack adds a new Pufferchick item with a custom image, custom gift tastes, and a custom crop that produces it. Note that item references in other data assets like Data/Crops and Data/NPCGiftTastes use the item ID.
{
"Format": "2.0.0",
"Changes": [
// add item
{
"Action": "EditData",
"Target": "Data/ObjectInformation",
"Entries": {
"Example.ModId_Pufferchick": "Pufferchick/1200/100/Seeds -74/Pufferchick/An example object.////0/Mods\\Example.ModId\\Objects"
}
},
// add gift tastes
{
"Action": "EditData",
"Target": "Data/NPCGiftTastes",
"TextOperations": [
{
"Operation": "Append",
"Target": ["Entries", "Universal_Love"],
"Value": "Example.ModId_Pufferchick",
"Delimiter": " " // if there are already values, add a space between them and the new one
}
]
},
// add crop (Pufferchick is both seed and produce, like coffee beans)
{
"Action": "EditData",
"Target": "Data/Crops",
"Entries": {
"Example.ModId_Pufferchick": "1 1 1 1 1/spring summer fall/0/Example.ModId_Pufferchick/-1/0/false/false/false/Mods\\Example.ModId\\Crops"
}
},
// add item + crop images
{
"Action": "Load",
"Target": "Mods/Example.ModId/Crops, Mods/Example.ModId/Objects",
"FromFile": "assets/{{TargetWithoutPath}}.png" // assets/Crops.png, assets/Objects.png
},
]
}
Most item data assets work just like Data/ObjectInformation. See also specific info for custom fruit trees, custom tools, and melee weapons.
Error items
In-game items with no underlying data (e.g. because you removed the mod which adds them) would previously cause issues like invisible items, errors, and crashes. This was partly mitigated by the bundled Error Handler mod.
Stardew Valley 1.6 adds comprehensive handling for such items. They'll be shown with a 🛇 sprite in inventory UIs and in-game, the name Error Item, and a description which indicates the missing item ID for troubleshooting.
For C# mods
- Compare items
-
Since Item.QualifiedItemId is globally unique, it can be used to simplify comparing items. For example:
old code new code item.ParentSheetIndex == 128 item.QualifiedItemId == "(O)128" IsNormalObjectAtParentSheetIndex(item, 128) item.QualifiedItemId == "(O)128" !item.bigCraftable && item.ParentSheetIndex == 128 item.QualifiedItemId == "(O)128" item is Boots && item.ParentSheetIndex == 505 item.QualifiedItemId == "(B)505" You can also use ItemRegistry.QualifyItemId to convert any item ID into a qualified one (if it's valid), and ItemRegistry.HasItemId to check if an item has a qualified or unqualified item ID.
Note that flavored item don't have their own ID. For example, Blueberry Wine and Wine are both (O)348. This affects flavored jellies, juices, pickles, and wines. In those cases you should still compare their separate fields like preservedParentSheetIndex (which actually contains the preserved item's ItemId, not its ParentSheetIndex).
- Construct items
- Creating items works just like before, except that you now specify the item's ItemId (not QualifiedItemId) instead of its ParentSheetIndex. For example:
new Object("128", 1); // vanilla item new Object("Example.ModId_Watermelon", 1); // custom item
You can use a new utility method to construct items from their QualifiedItemId:
Item item = ItemRegistry.Create("(B)505"); // Rubber Boots
- Define custom item types
- You can implement IItemDataDefinition for your own item type, add it to the ItemDataDefinition.ItemTypes field, and call ItemRegistry.ResetCache to register it. This provides all the logic needed by the game to handle the item type: where to get item data, how to draw them, etc. This is extremely specialized, and multiplayer compatibility is unknown. Most mods should add custom items within the existing types instead.
- New Is* methods
- 1.6 adds some StardewValley.Object methods to handle custom items in a generic way (and to let mods patch the logic):
method effect object.IsBar() Whether the item is a copper bar, iron bar, gold bar, iridium bar, or radioactive bar. object.IsBreakableStone() Whether the item is a stone debris item which can be broken by a pickaxe. object.IsFence() Whether the item is a fence. object.IsFruitTreeSapling() Whether the item is a fruit tree sapling. This checks the Data\fruitTrees keys, so it works with custom fruit trees too. object.IsHeldOverHead() Whether the player is shown holding up the item when it's selected in their toolbar. Default true (except for furniture). object.IsIncubator() Whether the item can incubate farm animal eggs when placed in a building. object.IsTapper() Whether the item is a tapper or heavy tapper. object.IsTeaSapling() Whether the item is a tea sapling. object.IsTwig() Whethere the item is a twig debris item. object.IsWeeds() Whether the item is a weed debris item. - Work with item metadata
-
1.6 adds an ItemRegistry API for working with the new item system:
method effect ItemRegistry.Create Create an item from its item ID (qualified or unqualified). If the ID doesn't match a real item, the optional allowNull parameter indicates whether to return null or an Error Item. For example: Item item = ItemRegistry.Create("(B)505"); // Rubber Boots
You can also get a specific value type instead of Item if needed. This will throw a descriptive exception if the type isn't compatible (e.g. you try to convert furniture to boots).
Boots item = ItemRegistry.Create<Boots>("(B)505"); // Rubber Boots
ItemRegistry.IsQualifiedId Get whether the given item ID is qualified with the type prefix (like (O)128 instead of 128). ItemRegistry.QualifyItemId Get the unique qualified item ID given an unqualified or qualified one. For example: string qualifiedId = ItemRegistry.QualifyItemId("128"); // returns (O)128
ItemRegistry.GetMetadata This lets you get high-level info about an item: // get info about Rubber Boots ItemMetadata info = ItemRegistry.GetMetadata("(B)505"); // get item ID info $"The item has unqualified ID {info.LocalId}, qualified ID {info.QualifiedId}, and is defined by the {info.TypeIdentifier} item data definition."; // does the item exist in the data files? bool exists = info.Exists();
And get common parsed item data:
// get parsed info ParsedItemData data = info.GetParsedData(); $"The internal name is {data.InternalName}, translated name {data.DisplayName}, description {data.Description}, etc."; // draw an item sprite Texture2D texture = data.GetTexture(); Rectangle sourceRect = data.GetSourceRect(); spriteBatch.Draw(texture, Vector2.Zero, sourceRect, Color.White);
And create an item:
Item item = metadata.CreateItem();
And get the type definition (note that this is very specialized, and you should usually use ItemRegistry instead to benefit from its caching and optimizations):
IItemDataDefinition typeDefinition = info.GetTypeDefinition();
ItemRegistry.ResolveMetadata Equivalent to ItemRegistry.GetMetadata, except that it'll return null if the item doesn't exist. ItemRegistry.GetData Get the parsed data about an item, or null if the item doesn't exist. This is a shortcut for ItemRegistry.ResolveMetadata(id)?.GetParsedData(); see the previous method for info on the parsed data.ItemRegistry.GetDataOrErrorItem Equivalent to ItemRegistry.GetData, except that it'll return info for an Error Item if the item doesn't exist (e.g. for drawing in inventory). ItemRegistry.GetErrorItemName Get a translated Error Item label.
Custom fences
You can now add or customize fences by editing the Data/FenceData asset.
This consists of a string → model lookup, where the key matches the ID field and the value is a model with these fields:
| field | effect |
|---|---|
| ID | A key which uniquely identifies this fence. The ID should only contain alphanumeric/underscore/dot characters. For custom fences, this should be prefixed with your mod ID like Example.ModId_FenceName. |
| ItemId | The unqualified item ID for the corresponding object-type item. |
| Health | The health points for a fence when it's first placed, which affects how quickly it degrades. A fence loses 1/1440 points per in-game minute (roughly 0.04 points per hour or 0.5 points for a 12-hour day).
Repairing a fence sets its max health to 2 × (base_health + repair_health_adjustment), where base_health is this field's value and repair_health_adjustment is a random value between RepairHealthAdjustmentMinimum and RepairHealthAdjustmentMaximum. |
| Texture | The asset name for the texture (under the game's Content folder) when the fence is placed. Use \ (or \\ in JSON) to separate name segments if needed. For example, the vanilla fences use individual tilesheets like LooseSprites\Fence1 (wood fence). |
| RemovalTool | A list of tools which can be used to break the fence, matching the keys in Data\ToolData. For example, "RemovalTool": ["Axe", "Pickaxe"] will let players use the axe or pickaxe. |
| PlacementSound | The audio cue ID played when the fence is placed or repaired (e.g. axe used by Wood Fence). |
| RemovalSound | (Optional) The audio cue ID played when the fence is broken or picked up by the player. Defaults to the same sound as PlacementSound. |
| RemovalDebrisType | (Optional) The type of cosmetic debris particles to 'splash' from the tile when the fence is broken with a tool. The defined values are 0 (copper), 2 (iron), 4 (coal), 6 (gold), 8 (coins), 10 (iridium), 12 (wood), 14 (stone), 32 (big stone), and 34 (big wood). Default 14 (stone). |
| RepairHealthAdjustmentMinimum RepairHealthAdjustmentMaximum |
(Optional) A random amount added to the Health when a fence is repaired by a player. See the Health field description. Both default to 0. |
| HeldObjectDrawOffset | (Optional) When an item like a torch is placed on the fence, the pixel offset to apply to its draw position. Specified as a string in the form "<x>, <y>". Defaults to "0, -20" if omitted.
|
| LeftEndHeldObjectDrawX RightEndHeldObjectDrawX |
(Optional) The X pixel offset to apply when the fence is oriented horizontally, with only one connected fence on the right (for LeftEndHeldObjectDrawX) or left (for RightEndHeldObjectDrawX). This fully replaces the X value specified by HeldObjectDrawOffset when it's applied. Default 0. |
Custom floors (craftable) & paths
You can now add or customize craftable floors & paths by editing the Data/FloorPathData asset.
This consists of a string → model lookup, where the key matches the ID field and the value is a model with these fields:
| field | effect | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| ID | A key which uniquely identifies this floor/path. The ID should only contain alphanumeric/underscore/dot characters. For vanilla floors & paths, this matches the spritesheet index in the TerrainFeatures/Flooring spritesheet; for custom floors & paths, this should be prefixed with your mod ID like Example.ModId_FloorName. | ||||||||||
| ItemId | The unqualified item ID for the corresponding object-type item. | ||||||||||
| Texture | The asset name for the texture (under the game's Content folder) when the flooring is applied or the path is placed. Use \ (or \\ in JSON) to separate name segments if needed. For example, the vanilla tilesheet is TerrainFeatures\Flooring. | ||||||||||
| Corner | The top-left pixel position for the sprite within the Texture spritesheet, specified as a model with X and Y fields. | ||||||||||
| PlacementSound | The audio cue ID played when the item is applied/placed (e.g. axchop used by Wood Floor). | ||||||||||
| FootstepSound | The audio cue ID played when the player steps on the tile (e.g. woodyStep used by Wood Floor). | ||||||||||
| WinterTexture Corner |
(Optional) Equivalent to Texture and Corner, but applied if the current location is in winter. | ||||||||||
| RemovalSound | (Optional) The audio cue ID played when the item is unapplied or picked up. Defaults to the same sound as PlacementSound. | ||||||||||
| RemovalDebrisType | (Optional) The type of cosmetic debris particles to 'splash' from the tile when the item is unapplied or picked up. The defined values are 0 (copper), 2 (iron), 4 (coal), 6 (gold), 8 (coins), 10 (iridium), 12 (wood), 14 (stone), 32 (big stone), and 34 (big wood). Default 14 (stone). | ||||||||||
| DrawContouredShadow | (Optional) Whether the shadow under the placed/applied item follows the contour of the sprite pixels, instead of just drawing a box around the tile. Default false. | ||||||||||
| ConnectType | (Optional) When drawing the flooring across multiple tiles, how the flooring sprite for each tile is selected. Defaults to Default.
The possible values are:
| ||||||||||
| CornerSize | (Optional) The pixel size of the decorative border when the ConnectType field is set to CornerDecorated or Default. | ||||||||||
| FarmSpeedBuff | (Optional) The speed boost applied to the player, on the farm only, when they're walking on paths of this type. Negative values are ignored. Default 0.1. |
Custom machines
You can now add/edit machine logic by editing the Data/Machines asset.
This consists of a string → model lookup, where...
- The key is the qualified or unqualified item ID for the item which acts as a machine (like (BC)127 for mushroom boxes). If a machine has two entries, the unqualified ID takes priority. To avoid mod conflicts, custom machines should always use unqualified item IDs (since custom IDs should already be unique).
- The value is a model with the fields listed below.
Item processing rules
| field | effect | ||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| OutputRules | The output produced by this machine. If multiple output rules can be produced, the first available one is selected. This consists of a list of models with these fields:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
| AdditionalConsumedItems | (Optional) A list of extra items required before OutputRules will be checked. If specified, every listed item must be present in the player, hopper, or chest inventory (depending how the machine is being loaded).
This consists of a list of models with these fields:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
| ReadyTimeModifiers | (Optional) Quantity modifiers applied to the produced item's processing time. The modifier conditions can use item-only tokens, which will check the input (not output) item. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
| ReadyTimeModifierMode | (Optional) A quantity modifier mode which indicates what to do if multiple modifiers apply at the same time. Default Stack. |
Behavior tweaks
| field | effect | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| PreventTimePass | (Optional) A list of cases when the machine should be paused, so the timer on any item being produced doesn't decrement. Possible values:
| ||||||||||
| AllowLoadWhenFull | (Optional) Whether the player can drop a new item into the machine before it's done processing the last one (like the crystalarium). The previous item will be lost. Default false. | ||||||||||
| ClearContentsOvernightCondition | (Optional) A game state query which indicates whether the machine should be emptied overnight, so any current output will be lost. Defaults to always false. |
Audio & visuals
| field | effect | ||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| LoadEffects WorkingEffects |
(Optional) The cosmetic effects shown when an item is loaded into the machine (for LoadEffects), or while it's processing the item (for WorkingEffects, based on the WorkingEffectChance probability). Both default to none. These consist of a list of models with these fields:
| ||||||||||||||||||||||||||||||||||||||||||
| WorkingEffectChance | (Optional) The percentage chance to apply WorkingEffects each time the day starts or the in-game clock changes, as a value between 0 (never) and 1 (always). Default 0.33. | ||||||||||||||||||||||||||||||||||||||||||
| LightWhileWorking | (Optional) The light emitted by the machine while it's processing an item. Default none.
This consists of a list of models with these fields:
| ||||||||||||||||||||||||||||||||||||||||||
| WobbleWhileWorking | (Optional) Whether the machine sprite should bulge in & out while it's processing an item. Default false. | ||||||||||||||||||||||||||||||||||||||||||
| ShowNextIndexWhileWorking ShowNextIndexWhenReady |
(Optional) Whether to show the next sprite in the machine's spritesheet while it's processing an item (ShowNextIndexWhileWorking) or ready (ShowNextIndexWhenReady). Default false. |
Player interaction messages
These only apply when the player interacts with a chest directly, instead of using a hopper or mod like Automate.
| field | effect |
|---|---|
| InvalidItemMessage | (Optional) A tokenizable string for the message shown in a toaster notification if the player tries to input an item that isn't accepted by the machine. |
| InvalidCountMessage | (Optional) A tokenizable string for the message shown in a toaster notification if the input inventory doesn't contain this item, unless overridden by InvalidCountMessage under OutputRules.
This can use extra custom tokens:
|
Advanced logic
| field | effect | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| InteractMethod | (Optional) A C# method invoked when the player interacts with the machine when it doesn't have output ready to harvest.
This must be specified in the form /// <summary>The method signature for a custom <see cref="MachineData.InteractMethod"/> method.</summary>
/// <param name="machine">The machine instance for which to produce output.</param>
/// <param name="location">The location containing the machine.</param>
/// <param name="player">The player using the machine.</param>
/// <returns>Returns whether the interaction was handled.</returns>
public static bool InteractWithMachine(Object machine, GameLocation location, Farmer player);
| ||||||||
| HasInput HasOutput |
(Optional) Whether to force adding the machine_input or machine_output context tags respectively. This isn't needed for most machines, since they'll be set based on the OutputRules field. Default false. | ||||||||
| IsIncubator | (Optional) Whether this machine acts as an incubator when placed in a building, so players can incubate eggs in it. Default false.
This is used by the incubator and ostrich incubator. The game logic assumes there's only one such machine in each building, so this generally shouldn't be used by custom machines that can be built in a vanilla barn or coop. | ||||||||
| StatsToIncrementWhenLoaded StatsToIncrementWhenHarvested |
(Optional) The game stat counters to increment when an item is placed in the machine (StatsToIncrementWhenLoaded) or when the processed output is collected (StatsToIncrementWhenHarvested). Default none. This consists of a list of models with these fields:
It's fine to use this with custom machines, but you can only increment built-in stats so it won't be applicable for most custom machines. For example, the vanilla game increments PiecesOfTrashRecycled for the recycling machine and GeodesCracked for the geode crusher. |
Interacting with machines in C#
Stardew Valley 1.6 adds two Object fields for reference:
| field | effect |
|---|---|
| lastOutputRuleId | If this is a machine, the output rule ID for the rule being processed by the machine (if any). |
| lastInputItem | If this is a machine, the item that was dropped into the machine to start the current output (if any). |
And a few methods for processing items:
| field | effect |
|---|---|
| IsMachineWorking() | Get whether the machine is currently processing an item. |
| ShouldTimePassForMachine(location) | Get whether the machine should be updated in the given location. For example, this will return false for solar panels placed indoors, or outdoors on a cloudy day. |
| GetMachineData() | Get the underlying machine data from Data/Machines. |
| PlaceInMachine(…) | Try to place an item in the machine using the rules from Data/Machines. This returns a boolean which indicates whether the machine was successfully started. |
| OutputMachine(…) | Try to set the machine output given the input item and an optional output rule to apply. Most code should call PlaceInMachine instead. |
A lot of the generic machine logic is also handled by a new MachineDataUtility class, which lets C# mods interact with machine data more directly. For example, you can check which output a machine would produce without actually updating the machine.
Custom melee weapon data
Melee weapons are defined in Data/Weapons like before, but you can now add custom behavior by editing the Data/AdditionalWeaponProperties asset. This consists of a string → model lookup, where the key is the unqualified item ID and the value is a model with these fields:
| field | effect | ||||
|---|---|---|---|---|---|
| SpecialAttack | (Optional) The secondary attack type. This can be one of Club, Dagger, or Sword. Any other value is ignored. | ||||
| Projectiles | (Optional) The projectiles fired when the weapon is used, which continue along their path until they hit a monster and cause damage. These always cause 10 damage and use a generic glowing-yellow-ball sprite. This consists of a list of models with these fields (one projectile will fire for each entry in the list):
Note that these are magic projectiles fired when the weapon is used, these aren't slingshot-style projectiles. |
Custom movie concessions
You could already add/edit concessions sold in the movie theater, but conflicts were likely since each concession had an incrementing numeric ID which matched its position in the vanilla tilesheet.
Stardew Valley 1.6 addresses that with two changes:
- The Id field is now a string, so you can use a globally unique ID like ExampleAuthor.ModId_ItemName.
- You can now use a different texture with two new required fields:
field effect Texture The asset name for the texture containing the concession's sprite. SpriteIndex The index within the Texture for the concession sprite, where 0 is the top-left sprite.
For example, this content pack adds a new 'Pufferchick Pop' concession with a custom image:
{
"Format": "2.0.0",
"Changes": [
{
"Action": "EditData",
"Target": "Data/Concessions",
"Entries": {
"Example.ModId_PufferchickPop": {
"Id": "Example.ModId_PufferchickPop", // must specify ID again when creating a new entry
"Name": "PufferchickPop",
"DisplayName": "Pufferchick Pop",
"Description": "A cute cake pop shaped like a pufferchick.",
"Price": 25,
"Texture": "{{InternalAssetKey: assets/pufferchick-pop.png}}" // an image in your content pack
"SpriteIndex": 0
}
}
}
]
}
Custom museum donations & rewards
You can now add/edit the items which the museum accepts in donation and gives back in rewards through the new Data/MuseumRewards data asset.
Format
The data asset consists of a string → model lookup, where the key matches the ID field and the value is a model with these fields:
| field | effect | ||||||
|---|---|---|---|---|---|---|---|
| ID | A key which uniquely identifies the reward group (i.e. a set of items and the reward once they're all donated). The ID should only contain alphanumeric/underscore/dot characters. For custom entries, this should be prefixed with your mod ID like Example.ModId_GroupName. | ||||||
| TargetContextTags | The items that must be donated to complete this reward group. The player must fulfill every entry in the list to unlock the reward. This consists of a list of models with these fields:
For example, an entry with the tag forage_item and count 2 will require donating any two forage items. Special case: an entry with the exact values | ||||||
| FlagOnCompletion | (Optional if RewardItemIsSpecial is true) Whether to add the ID value to the player's received mail. This is used to track whether the player has collected the reward, and should almost always be true. If this is omitted and RewardItemIsSpecial is false, the player will be able collect the reward infinite times. Default false.
After the reward is collected, you can check this value using the HasFlag condition in Content Patcher. | ||||||
| RewardEventSeenFlag | (Optional) The ID to add to the player's event-seen list when the reward is collected. (You must still specify FlagOnCompletion or RewardItemIsSpecial either way.)
After the reward is collected, you can check this value using the HasSeenEvent condition in Content Patcher. | ||||||
| RewardItemId | (Optional) The qualified item ID for the item given to the player when they donate all required items for this group. There's no reward item if omitted. | ||||||
| RewardItemCount | (Optional) The stack size for the RewardItemId (if the item supports stacking). Default 1. | ||||||
| RewardItemIsSpecial | (Optional) Whether to mark the RewardItemId as a special permanent item, which can't be destroyed/dropped and can only be collected once. Default false. | ||||||
| RewardItemIsRecipe | (Optional) Whether to give the player a cooking/crafting recipe which produces the RewardItemId, instead of the item itself. Ignored if the item type can't be cooked/crafted (i.e. non-object-type items). Default false. |
Achievements
The A Complete Collection achievement is automatically adjusted to require any custom donations added too. This is based on the number of donated items though, so removing custom donations later may incorrectly mark the museum complete (since you may have donated enough items to meet the total required).
Custom fruit trees
Data format
You can now add custom fruit trees by editing the revamped Data/fruitTrees asset. This consists of a string → model lookup, where...
- The key is the unqualified item ID for the sapling item in Data/ObjectInformation.
- The value is a model with the fields listed below.
| field | effect | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| TreeId | The unique ID for this fruit tree. This should only contain alphanumeric, underscore, and dot characters. For custom fruit trees, this should be prefixed with your mod ID like Example.ModId_FruitTreeId. | ||||||||
| DisplayName | A tokenizable string for the tree's display name. This should return a display name without 'tree' (like Cherry for a cherry tree). This is used in UI messages like "Your <display name> tree wasn't able to grow last night". | ||||||||
| Season | The season in which the fruit tree bears fruit.
Note: an unlike the previous Data/fruitTrees format, | ||||||||
| Fruit | The fruit items to add to the tree each day while the tree is in-season. The first matching fruit (if any) is selected each day.
This consists of a list of models with these fields:
| ||||||||
| Texture | The asset name for the texture under the game's Content folder. Use \ (or \\ in JSON) to separate name segments if needed. For example, vanilla fruit trees use TileSheets\fruitTrees. | ||||||||
| TextureSpriteRow | The tree's row index in the Texture spritesheet (e.g. 0 for the first tree, 1 for the second tree, etc). |
For example, this content pack adds a custom fruit tree, including custom items for the sapling and fruit:
{
"Format": "2.0.0",
"Changes": [
// add fruit + sapling items
// note: sapling must have an edibility under 0 (usually -300) to be plantable
{
"Action": "EditData",
"Target": "Data/ObjectInformation",
"Entries": {
"Example.ModId_Pufferfruit": "Pufferfruit/1200/100/Basic -6/Pufferfruit/An example fruit item.////1/Mods\\Example.ModId\\Objects",
"Example.ModId_Puffersapling": "Puffersapling/1200/-300/Basic -74/Puffersapling/An example tree sapling.////2/Mods\\Example.ModId\\Objects"
}
},
// add fruit tree
{
"Action": "EditData",
"Target": "Data/FruitTrees",
"Entries": {
"Example.ModId_Puffersapling": {
"TreeId": "Example.ModId_Puffertree",
"DisplayName": "[DataString Data\ObjectInformation Example.ModId_Pufferfruit 4]", // field 4 (display name) for our fruit item
"Season": "spring",
"Fruit": [
{
"Id": "Example.ModId_Pufferfruit",
"ItemId": "Example.ModId_Pufferfruit"
}
],
"Texture": "Mods\\Example.ModId\\FruitTrees",
"TextureSpriteRow": 0
}
}
},
// add images
{
"Action": "Load",
"Target": "Mods/Example.ModId/FruitTrees, Mods/Example.ModId/Objects",
"FromFile": "assets/{{TargetWithoutPath}}.png" // assets/FruitTrees.png, assets/Objects.png
},
]
}
The fruit trees can then be added to the game by giving the player a sapling item in the usual ways (e.g. from a shop).
Fruit items
For C# mods, the fruitsOnTree field (number of fruit on the tree) has been replaced by fruitObjectsOnTree (list of fruit items).
Custom tools
You can now create/edit tools by editing the new Data/Tools asset. This consists of a string → model lookup, where the key is the unqualified item ID and the value is a model with these fields:
| field | purpose | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ClassName | The name of the C# class to construct within the StardewValley.Tools namespace. The class must be a subclass of StardewValley.Tool, and have a constructor with no arguments. For example, given a value of Axe, the game will create StardewValley.Tools.Axe instances.
The main values are:
| |||||||||||||||
| Name | The internal name to set for the tool item. | |||||||||||||||
| DisplayName Description |
A tokenizable string for the tool's in-game display name and description. | |||||||||||||||
| Texture | The asset name for the texture containing the tool's sprite. | |||||||||||||||
| SpriteIndex | The tool's sprite index within the Texture, where 0 is the top row. | |||||||||||||||
| UpgradeLevel | (Optional) The tool upgrade level. Default -1, which keeps the default value set by the tool class. | |||||||||||||||
| AttachmentSlots | (Optional) The number of attachment slots to enable on the tool. Note that only FishingRod tools have the code to render and use attachment slots. Default -1, which keeps the default value set by the tool class. | |||||||||||||||
| SalePrice | (Optional) The default price when the item is sold to the player in a shop. Defaults to -1, in which case you should set the price manually in shops. | |||||||||||||||
| ApplyUpgradeLevelToDisplayName | (Optional) Whether to adjust the DisplayName for the usual upgrade levels. For example, the display name for a level one Axe changes to 'Copper Axe'. Default false.
The display name format in English is:
| |||||||||||||||
| ModData | (Optional) The mod data values to set when the tool is created, accessible in C# code via the tool.modData dictionary. For example:
"ModData": {
"PowerLevel": 9000
}
| |||||||||||||||
| SetProperties | (Optional) Set the value of arbitrary properties on the tool class. For example, this would disable the tool animation and require no stamina:
"SetProperties": {
"InstantUse": true,
"IsEfficient": true
}
| |||||||||||||||
| UpgradeFrom | (Optional) The requirements to buy this tool from Clint's blacksmith tool upgrade shop. If you specify multiple entries, the first one which matches will be applied.
This consists of a list of models with these fields:
For example, these are equivalent to the Steel Axe's upgrade settings: "UpgradeFrom": [
{
"RequireToolId": "(T)CopperAxe",
"Price": 5000,
"TradeItemId": "(O)335", // Iron Bar
"TradeItemAmount": 5
}
]
If you want the tool to always be available, you can just omit the conditions. For example: "UpgradeFrom": [
{
"Price": 5000
}
]
Note that Clint needs a few days to smith the new tool. If you want to sell the tool directly, add it to a regular shop instead. | |||||||||||||||
| ConventionalUpgradeFrom | (Optional) If set, prepends an upgrade for the given tool ID to the UpgradeFrom field. This applies these rules (based on the UpgradeLevel field, not the upgrade level of the specified tool ID):
For example, Iridium Axe specifies this value: "ConventionalUpgradeFrom": "(T)GoldAxe"
|
Custom wild trees
You can now create/edit wild trees by editing the Data/WildTrees asset.
This consists of a string → model lookup, where...
- The asset key is the unique tree type identifier. The vanilla tree IDs are 1 (oak), 2 (maple), 3 (pine), 6 (palm), 7 (mushroom), and 8 (mahogany). For custom trees, this should be prefixed with your mod ID like Example.ModId_TreeType. This should only contain alphanumeric/underscore/dot characters.
- The asset value is a model with thee fields listed below.
| field | effect | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Textures | The texture to use as the tree's spritesheet in-game. If multiple textures are listed, the first matching one is used.
This consists of a list of models with these fields:
| ||||||||||||
| SeedItemId | (Optional) The qualified item ID for the seed item. If omitted, the tree can't be planted and SeedChance will be ignored. | ||||||||||||
| SeedPlantable | (Optional) Whether the seed can be planted by the player. If this is false, it can only be spawned automatically via map properties. Default true. | ||||||||||||
| GrowthChance | (Optional) The probability each day that the tree will grow to the next stage without tree fertilizer, as a value from 0 (will never grow) to 1 (will grow every day). Defaults to 0.2 (20% chance). | ||||||||||||
| FertilizedGrowthChance | (Optional) Equivalent to GrowthChance, but with tree fertilizer. Defaults to 1 (100% chance). | ||||||||||||
| SeedChance | (Optional) The probability each day that the tree will produce a seed that will drop when the tree is shaken, as a value from 0 (never) to 1 (always). Default 0.05 (5% chance). | ||||||||||||
| SeedOnChopChance | (Optional) The probability that a seed will drop when the player chops down the tree, as a value from 0 (never) to 1 (always). Default 0.75 (75% chance). | ||||||||||||
| DropWoodOnChop | (Optional) Whether to drop wood when the player chops down the tree. Default true. | ||||||||||||
| DropHardwoodOnLumberChop | (Optional) Whether to drop hardwood when the player chops down the tree, if they have the Lumberjack profession. Default true. | ||||||||||||
| IsLeafy | (Optional) Whether shaking or chopping the tree causes cosmetic leaves to drop from tree and produces a leaf rustle sound. When a leaf drops, the game will use one of the four leaf sprites in the tree's spritesheet in the slot left of the stump sprite. Default true. | ||||||||||||
| IsLeafyInWinter | (Optional) Whether IsLeafy also applies in winter. Default false. | ||||||||||||
| GrowsInWinter | (Optional) Whether the tree can grow in winter (subject to GrowthChance or FertilizedGrowthChance). Default false. | ||||||||||||
| IsStumpDuringWinter | (Optional) Whether the tree is reduced to a stump in winter and regrows in spring, like the vanilla mushroom tree. Default false. | ||||||||||||
| AllowWoodpeckers | (Optional) Whether woodpeckers can spawn on the tree. Default true. | ||||||||||||
| UseAlternateSpriteWhenNotShaken UseAlternateSpriteWhenSeedReady |
(Optional) Whether to render a different tree sprite when the player hasn't shaken it on that day (UseAlternateSpriteWhenNotShaken) or it has a seed ready (UseAlternateSpriteWhenSeedReady). If either field is true, the tree spritesheet must be double-width with the alternate textures on the right. If both are true, the same alternate sprites are used for both. Default false. | ||||||||||||
| DebrisColor | (Optional) The color of the cosmetic wood chips when chopping the tree. This can be...
Defaults to 12 (brown/woody). | ||||||||||||
| ChopItems | (Optional) The additional items to drop when the tree is chopped down. All matching items are dropped.
This consists of a list of models with these fields:
| ||||||||||||
| ShakeItems | The items produced by shaking the tree when it's fully grown. This only applies the first time the tree is shaken each day. All matching items are dropped.
This consists of a list of models with these fields:
| ||||||||||||
| TapItems | The items produced by tapping the tree. If multiple items can be produced, the first available one is selected.
This consists of a list of models with these fields:
|
Trees can then be added to the game by...
- spawning them on map tiles by adding Paths index 34 to the Paths layer, with a TreeType tile property with the tree ID;
- or giving the player a seed item in the usual ways (e.g. from a shop, mail letter, etc).
Hats on aquarium fish
Custom fish in aquariums can now wear hats, just like vanilla sea urchins. This can be enabled by specifying a new field in Data/AquariumFish:
| index | field | purpose |
|---|---|---|
| 7 | hat position | The pixel position of the hat on the sprite, specified as an object with X and Y values.
Note: currently this is only used to check if the fish can wear a hat, and has no effect on its position. |
New context tags
1.6 adds several new item context tags:
| context tag | effect |
|---|---|
| campfire_item | Marks the item as a campfire. If the item also has the torch_item context tag, when it's placed in the world and turned on...
|
| fish_legendary | Marks the fish as a legendary fish. For example: it can't be caught again, shows an alternate sprite in the fishing minigame and a 'caught legendary fish' message after catching it, can't be added to a fish pond, etc. |
| fish_legendary_family | Marks the fish as part of the legendary fish family for the fishing minigame. For example: requires magic bait, can't catch two at once, smaller bobber bar, 5× XP gain, etc. |
| geode_special | Marks the item as a geode item, and prevents it from being broken open at Clint's blacksmith shop. |
item_type_<type>
|
For an object-type item, the type value from the 'type and category' field. (Non-object items always have the exact tag item_type_ with nothing after the last underscore.) This is automatic and shouldn't be set manually. The tag is checked in a few places (e.g. the museum to check if an item is an artifact or mineral), but most of the game won't be affected. |
| museum_donatable not_museum_donatable |
Set whether the item can be donated to the museum, overriding the vanilla logic. |
| not_placeable placeable |
Sets whether the item can be placed on the ground. |
not_plantable_context_<context ID>not_plantable_location_ <location name>plantable_context_ <context ID>plantable_greenhouse plantable_location_ <location name>
|
See custom planting restrictions. |
| paddy_crop | Marks the item as a paddy crop like rice or taro. This enables paddy-related logic like needing to be planted near water. |
| sign_item | Marks the item as a sign, which lets player display items on it or place it on a fish pond to show the fish count. |
| torch_item | Marks the item as a torch, which lets the player turn it on/off to emit light.
See also campfire_item. |
Contexts which affect machine processing:
| context tag | effect |
|---|---|
| crystalarium_banned | When applied to a gem or mineral item, prevents players from placing it in a crystalarium. |
| fairy_dust_banned | When applied to a machine, prevents players from using fairy dust to speed it up. |
| is_machine | Indicates the item has machine logic. This is added automatically based on Data/Machines and is informational only (it has no effect on the game logic). |
| keg_juice keg_wine |
Allows processing the item in a keg to produce a juice or wine variant. |
| machine_input machine_output |
Whether the item is a machine which accepts items from the player (machine_input) and/or which produces items for the player to collect (machine_output). If the machine data sets the ConversionMethod field, both tags are added since there's no way to know what the method does.
These are added automatically based on Data/Machines and are informational only (they have no effect on the game logic). The is_machine tag is always added if these are. |
| preserves_jelly preserves_pickle |
Allows processing the item in a preserves jar to produce a jelly or pickled variant. |
| seedmaker_banned | When applied to a seed item, prevents players from placing it in a seed maker. |
| tapper_item | Marks the item as a tapper or heavy tapper. |
tapper_multiplier_<multiplier>
|
The multiplier applied to the tapper production speed. For example, 2 will make items take half their base time (i.e. each item will finish in base time/speed multiplier). Defaults to 1 if omitted. |
Inventory class
For C# mods, 1.6 adds a new Inventory class to manage a list of items. This is used for the Farmer.items and Chest.items fields. It implements IList<Item>, so most existing code should still work fine.
This has three main benefits:
- It has methods to simplify many common operations. For example:
method effect HasAny()Get whether the inventory contains any items (ignoring empty slots). CountItemStacks()Get the number of item stacks in the inventory (ignoring empty slots). ContainsId(id)Get whether the inventory contains any item with the given qualified or unqualified item ID. ContainsId(id, minCount)Get whether the inventory contains items with the given qualified or unqualified item ID, and their combined stack size is at least minCount. CountId(id)Get the combined stack size of all items with the given qualified or unqualified item ID. GetById(id)Get a list of items in the inventory with the given qualified or unqualified item ID. ReduceId(id, count)Remove the given number of items matching the given qualified or unqualified item ID. This reduces the stack size for matching items until a total of count have been removed, and clears any slots which reach a stack size of zero. - Many common operations have been unified, so previously player-only methods can now be used with chests too.
- It has an internal index by item ID, so operations like
items.ContainsId("(O)128")are much more efficient since they no longer iterate the list.
This replaces some previous methods:
| game class | old code | migration |
|---|---|---|
| Farmer | getItemCount(id)GetTallyOfObject(id)GetTallyOfObject(id, isBigCraftable)
|
Use items.CountId(id).
|
hasItemInInventory(id, count)hasItemInInventoryNamed(name)hasItemWithNameThatContains(name)
|
Use items.ContainsId(id, count).
| |
hasItemInList(list, id, count)
|
Use list.ContainsId(id, count).
| |
areAllItemsNull()
|
Use !items.HasAny().
| |
numberOfItemsInInventory()
|
Use items.CountItemStacks() to count all items, or Items.Count(p => p is Object) to match this method's actual behavior.
| |
consumeObject(id, count)removeItemsFromInventory(id, count)
|
Use items.ReduceId(id, count).
| |
| Object | ConsumeInventoryItem(player, id, count)
|
This was somewhat specialized and shouldn't be called by mod code, but the equivalent would be (obj.autoLoadChest?.items ?? player.items).ReduceId(id, count).
|
GetTallyOfObject(player, id)
|
This was somewhat specialized and shouldn't be called by mod code, but the equivalent would be (obj.autoLoadChest?.items ?? player.items).CountId(id).
|
ItemContextTagManager class
For C# mods, 1.6 adds a new ItemContextTagManager class which simplifies working with item context tags and reduces repeated code.
This provides a few utility methods:
| method | effect |
|---|---|
GetBaseContextTags(id)
|
Get the base context tags for an item from the Data/ObjectContextTags asset. This doesn't include dynamic context tags added by the instance, which you can get via item.GetContextTags().
|
DoesTagQueryMatch(query, tags)
|
Get whether a context tag query matches the given tags. For example, ItemContextTagManager.DoesTagQueryMatch("bone_item, !fossil_item", item.GetContextTags()) returns true if the item is a bone item but not a fossil (like the Bone Flute).
|
DoAllTagsMatch(requiredTags, actualTags)DoAnyTagsMatch(requiredTags, actualTags)
|
Get whether every (DoAllTagsMatch) or at least one (DoAnyTagsMatch</samp) required tag matches the actual item tags. This supports negated required tags like "!fossil_item" too. |
DoesTagMatch(requiredTag, actualTags)
|
Get whether a single tag matches the actual item tags. This supports negated required tags like "!fossil_item" too. |
SanitizeContextTag(tag)
|
(Specialized) Replace characters that may appear in item names so they're valid in context tags. For example, SanitizeContextTag("Sam's Boombox") returns sams_boombox.
|
Other item changes
- Added optional Condition game state query field to Data/SpecialOrders.
- Item data changes:
- The display name field now exists in English too for Data/Boots, Data/Bundles, Data/CookingRecipes, Data/CraftingRecipes, Data/Fish, and Data/Furniture.
- The randomly spawned stones, twigs, and weeds have been formalized into litter. They all now have object type Litter, category -999 (Game1.litterCategory), a relevant display name/description (like Gold Stone/Break apart to obtain gold ore instead of Stone/...), a price of 0 (not sellable), and edibility of -300 (inedible). In C# code, you can use the new item methods like item.IsWeeds() to detect them. This also adds all mine ore nodes to Data/ObjectInformation, so the game no longer creates invalid items to show their sprite. (Doing so in 1.6 will now show an Error Item sprite instead.)
- For C# mods, honey items now have their preserve field set to Honey (instead of null) and now have the honey_item context tag.
- Other item logic:
- The %item mail command has a new %mail id
<item id>[count]format which accepts a qualified or unqualified item ID. This deprecates the bigobject, furniture, object, and tools options. - The Object.performObjectDropInAction method now applies the probe argument much more consistently. This only affects method calls with probe: true.
- Added new fields & methods for C# mods:
type field/method effect Item IsRecipe
Quality
Stack
sellToStorePrice(…)Equivalent to the previous Object fields/methods, to simplify common code and avoid needing to special-case Object items. FishingRod CanUseBait()
CanUseTackle()
GetBait()
GetTackle()
HasMagicBait()
HasCuriosityLure()Simplifies working with the fishing rod's bait and tackle. FruitTree TryAddFruit() Add a fruit item to the tree based on its data. IndoorPot Water() Simplifies watering dirt in the garden pot. Object GetBoundingBox()
GetBoundingBoxAt(x, y)Get the pixel collision area for the item placed in the world. These replace the former getBoundingBox(position) method. Tool isScythe() Equivalent to the previous MeleeWeapon method, to simplify common code and avoid needing to special-case MeleeWeapon items. Tree CheckForNewTexture() Reset the tree's texture if it would change based on its data.
- The %item mail command has a new %mail id
What's new for locations & weather
Custom locations
You can now add/edit locations by editing the revamped Data/Locations asset.
The asset consists of a model with these fields:
| field | effect | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| CreateLocations | The location instances to create when the save is loaded.
This consists of a string → model lookup, where...
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| DefaultArtifactSpots | The items that can be found when digging artifact spots in any location. See ArtifactSpots under Locations for info. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| DefaultFish | The items that can be found by fishing in any location. See Fish under Locations for info. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Locations | The gameplay data for locations in the game (regardless of whether they were created using the CreateLocations field or some other way).
This consists of a string → model lookup, where...
|
Custom location contexts
Vanilla contexts
- The game previously had two hardcoded location context enums: Default (for the valley) and Island (for Ginger Island). These have been replaced with data models which define the location context settings, loaded from the Data/LocationContexts asset.
- The desert is now part of a new Desert context (instead of Default). Some of the previously hardcoded desert logic (like always sunny weather) is now just part of the context data in Data/LocationContexts.
Format
Custom contexts can be created by editing the new Data/LocationContexts asset, and setting the context name in the location's LocationContext map property.
The data asset consists of a string → model lookup, where the key matches the Name field and the value is a model with these fields:
- Required fields:
-
field effect Name The unique ID for the location context. This should only contain alphanumeric/underscore/dot characters. For custom contexts, this should be prefixed with your mod ID like Example.ModId_ContextName. - Player actions:
-
field effect DefaultValidPlantableLocations (Optional) The internal names of the locations where crops can be planted and grown by default (see also custom planting restrictions). AllowRainTotem (Optional) Whether a Rain Totem can be used to force rain in this context tomorrow. MaxPassOutCost (Optional) When the player passes out (due to exhaustion or at 2am) in this context, the maximum amount of gold lost. If omitted or set to -1, uses the same value as the Default context ( 
1,000g by default).
PassOutMail (Optional) When the player passes out (due to exhaustion or at 2am) in this context, the possible letter IDs to add to their mailbox (if they haven't received it before). If multiple letters are valid, one will be chosen randomly (unless one specifies SkipRandomSelection). This consists of a list of models with these fields:
field effect Mail The letter ID to add. The game will look for an existing letter ID in Data/mail in this order (where
<billed>is Billed if they lost gold or NotBilled otherwise, and<gender>is Female or Male):<letter id>_<billed>_<gender><letter id>_<billed><letter id>
If no match is found in Data/mail, the game will send passedOut2 instead.
If the mail ID starts with passedOut, {0} in the letter text will be replaced with the gold amount lost, and it won't appear in the collections page.
MaxPassOutCost (Optional) The maximum amount of gold lost. This is applied after the context's MaxPassOutCost (i.e. the context's value is used to calculate the random amount, then this field caps the result). Defaults to unlimited. Condition (Optional) A game state query which indicates whether this entry is active. Defaults to always true. SkipRandomSelection (Optional) If true, send this mail if the Condition matches instead of choosing a random valid mail. Default false. PassOutLocations (Optional) When the player passes out (due to exhaustion or at 2am) in this context and they started the day in a different location context, the locations where they'll wake up. (If the player started the day in the same context, they'll wake up in the last bed they slept in instead.) This consists of a list of models with these fields:
field effect Location The internal location name. Position The default tile position within the location, specified as an object with X and Y fields. If the location has any bed furniture, they'll be placed in the first bed found instead. Condition (Optional) A game state query which indicates whether this entry is active. Defaults to always applied. If no locations are specified or none match, the player will wake up in their bed at home.
ReviveLocations (Optional) If the player just got knocked out in combat, the location names where they'll wake up. This consists of a list of models with these fields:
field effect Location The internal location name. Position The tile position within the location, specified as an object with X and Y fields. Condition (Optional) A game state query which indicates whether this entry is active. Defaults to always applied. If the selected location has a standard event with the exact key PlayerKilled (with no / or preconditions in the key), that event will play when the player wakes up and the game will apply the lost items or gold logic. The game won't track this event, so it'll repeat each time the player is revived. If there's no such event, the player will wake up without an event, and no items or gold will be lost.
If no locations are specified or none match, the player will wake up at Harvey's clinic.
- Season:
-
field effect SeasonOverride (Optional) The season which is always active for locations within this context (one of spring, summer, fall, or winter). For example, setting summer will make it always summer there regardless of the calendar season. If not set, the calendar season applies. - Weather:
-
field effect WeatherConditions (Optional) The weather logic to apply for locations in this context (ignored if CopyWeatherFromLocation is set). Defaults to always sunny. If multiple are specified, the first matching weather is applied. This consists of a list of models with these fields:
field effect Weather The weather ID to set. Condition (Optional) A game state query which indicates whether to apply the weather. Defaults to always applied. CopyWeatherFromLocation (Optional) The Name (i.e. unique ID) of the location context from which to inherit weather. If a passive festival is active in any location within this context, the weather is sunny for the entire context regardless of these fields.
- Music:
-
field effect DefaultMusic (Optional) The cue ID for the music to play when the player is in the location, unless overridden by a Music map property. Despite the name, this has a higher priority than the seasonal music fields below. Ignored if omitted. DefaultMusicCondition (Optional) A game state query which returns whether the DefaultMusic field should be applied (if more specific music isn't playing). Defaults to always true. DefaultMusicDelayOneScreen (Optional) When the player warps and the music changes, whether to silence the music and play the ambience (if any) until the next warp (similar to the default valley locations). Default false. SpringMusic
SummerMusic
FallMusic
WinterMusic(Optional) A list of cue IDs to play before noon in this location unless it's raining, there's a Music map property, or the context has a DefaultMusic value. If multiple values are specified, the game will play one per day in sequence. DayAmbience
NightAmbience(Optional) The cue ID for the background ambience to play when there's no music active, depending on the time of day. Both default to none. PlayRandomAmbientSounds (Optional) Whether to play random outdoor ambience sounds depending on factors like the season and time of day (e.g. birds, crickets, and mysterious groan sounds in the rain). This is unrelated to the DayAmbience and NightAmbience fields. Default true.
Custom garbage cans
Format
You can now add or edit garbage cans on any map by editing the new Data/GarbageCans asset (see examples below).
The asset consists of a data model with these fields:
| field | effect | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| DefaultBaseChance | The probability that an item will be found when searching garbage cans, as a value between 0 (never) and 1 (always). If the probability check fails, only items that set IgnoreBaseChance can spawn. This can be overridden by the per-garbage-can BaseChance field. Default 0.2. | ||||||||||||||||||||
| BeforeAll AfterAll |
The items to prepend (BeforeAll) or append (AfterAll) to the GarbageCans → Items field for all garbage cans. These work exactly like the items in that field (e.g. subject to the garbage can's base chance). | ||||||||||||||||||||
| GarbageCans | The data for individual garbage cans. This consists of a string → model lookup with these fields:
If the garbage can being searched doesn't have its own entry under GarbageCans, the game will just use the BeforeAll and AfterAll fields. |
Example new garbage can
You can add garbage cans using only Content Patcher or SMAPI's content API. For example, this content pack adds a new garbage can entry with the ID Example.ModId_Carpenter:
{
"Format": "2.0.0",
"Changes": [
{
"Action": "EditData",
"Target": "Data/GarbageCans",
"TargetField": [ "GarbageCans" ],
"Entries": {
"Example.ModId_Carpenter": {
"Items": [
// 25% chance of pufferfish
{
"ID": "Example.ModId_Pufferfish",
"Condition": "RANDOM 0.25",
"ItemId": "(O)128"
},
// else guaranteed random House Plant item
{
"ID": "Example.ModId_RandomHousePlant",
"ItemID": "RANDOM_ITEMS (F) @has_id_in_base_range 1376 1390"
}
]
}
}
}
]
}
Then you'd place an Action: Garbage Example.ModId_Carpenter map tile property to mark a tile as a garbage can using this data.
Example change for existing garbage can
You can edit an existing garbage cans using only Content Patcher or SMAPI's content API. For example, this content pack adds pufferfish to the Saloon garbage can, and moves it above the dish of the day.
Note that this uses TargetField to 'move into' the item list for the saloon, and then treat those items as the entry list being edited. Specifying an ID which isn't in the list will add a new entry, just like when editing a regular list asset.
{
"Format": "2.0.0",
"Changes": [
{
"Action": "EditData",
"Target": "Data/GarbageCans",
"TargetField": [ "GarbageCans", "Saloon", "Items" ],
"Entries": {
// 25% chance of pufferfish
{
"ID": "Example.ModId_Pufferfish",
"Condition": "RANDOM 0.25",
"ItemId": "(O)128"
}
},
"MoveEntries": [
{ "ID": "Example.ModId_Pufferfish", "BeforeId": "Base_DishOfTheDay" }
]
}
]
}
Custom map actions
C# mods can now handle custom Action & TouchAction map properties by calling GameLocation.RegisterTileAction & RegisterTouchAction, and passing a callback which receives the location, map property arguments, player who activated it, and tile position.
For example, let's say you want a locked gate which needs a custom key item. You can add a regular TouchAction Example.ModId_UnlockGate map property (e.g. by adding it directly in the map file, or using Content Patcher's EditMap, or using the content API). Then you can just handle the logic from your C# mod:
internal class ModEntry : Mod
{
/// <inheritdoc />
public override void Entry(IModHelper helper)
{
GameLocation.RegisterTouchAction("Example.ModId_UnlockGate", this.HandleUnlockGate);
}
private void HandleUnlockGate(GameLocation location, string[] args, Farmer player, Vector2 tile)
{
const string mailFlag = "Example.ModId_GateUnlocked";
const string keyId = "Example.ModId_GateKey";
// unlock gate if locked
if (!player.mailReceived.Contains(mailFlag))
{
if (!Game1.player.hasItemInInventory(keyId, 1))
{
Game1.activeClickableMenu = new DialogueBox("This gate is locked. I wonder where the key is?");
return;
}
player.removeFirstOfThisItemFromInventory(keyId);
player.mailReceived.Add(mailFlag);
}
// apply open-gate map edit
IAssetDataForMap mapHelper = this.Helper.Content.GetPatchHelper(location.map).AsMap();
mapHelper.PatchMap(
this.Helper.Content.Load<Map>("assets/unlocked-gate.tmx"),
targetArea: new Rectangle((int)tile.X - 1, (int)tile.Y - 1, 2, 2)
);
}
}
Custom map areas
You can now add/edit areas on the game menu's map UI, or even replace the entire map for a different world region, by editing the new Data/InGameMap asset. For example, this is used to show a different farm on the map depending on the current farm type.
Concepts
The game divides the map into three concepts:
- A map is one full world area rendered in one image, like the entire image shown at right.
- A map area is a smaller section of the map which is linked to one or more in-game locations. The map area might be edited/swapped depending on the context, have its own tooltip(s), or have its own player marker positions. For example, the highlighted area on the image shown at right is swapped depending on the current farm type.
- A group name is a unique key shared between all the map areas that are rendered on the same map. For example, if there was a separate map for Ginger Island, all the map areas in the valley group would be hidden.
Format
The Data/InGameMap data asset consists of a string → model lookup, where the key matches the AreaID field and the value is a model with these fields:
| field | effect | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| AreaID | A unique identifier for the area. The ID should only contain alphanumeric/underscore/dot characters. For custom areas, this should be prefixed with your mod ID like Example.ModId_AreaName. | ||||||||
| Group | A unique group key shared between all areas drawn on the same map (see concepts). When the player is in an area for one group, all map areas with a different group key are hidden automatically. The base valley map added by the base game has the group key SDV. This should only contain alphanumeric/underscore/dot characters. For custom groups, this should be prefixed with your mod ID like Example.ModId_GroupName. | ||||||||
| Texture | The asset name for the texture to draw when the area is applied to the map.
If set to the exact string "MOD_FARM", the game will apply the texture for the current farm type, regardless of whether it's a vanilla or mod farm type. (The vanilla DestRect for the farm area is "0 43 131 61".) Note: this field is required. To add an invisible area, you can set this to a valid texture (e.g. "LooseSprites\\map") and omit SourceRect instead. | ||||||||
| SourceRect | The pixel area within the Texture to draw, formatted like "<x> <y> <width> <height>". Omit this field to make the area invisible (e.g., to add zones or tooltips without changing the map).
| ||||||||
| DestRect | The pixel area within the map which is covered by this area, formatted like "<x> <y> <width> <height>".
| ||||||||
| Zones | The in-game locations to match with the map. Each zone can provide one or more of the following:
This consists of a list models with these fields:
| ||||||||
| DisplayName | (Optional) A tokenizable string for the tooltip (shown when the mouse is over the area) and scroll (shown at the bottom of the map when the player is in the location). If omitted or empty, the tooltip/scroll isn't shown. Defaults to empty. | ||||||||
| Condition | (Optional) A game state query which checks whether the area should be applied (if the group is visible). Defaults to always applied. | ||||||||
| DisplayAsUnknown | (Optional) Whether to replace the tooltip for the area with ??? if the Condition isn't met. Default false. | ||||||||
| IncludeInGroupDetection | (Optional) Whether to use this area when the game is scanning areas to see which group the player is in. If this is false, it will be ignored even if the player is in the area. Default true. |
Example
This Content Patcher content pack adds a full world map for Ginger Island, complete with tooltips and player marker positioning. If the player unlocked the beach resort, it applies the beach resort texture on top of the base map.
{
"Format": "2.0.0",
"Changes": [
// add world map edits
{
"Action": "EditData",
"Target": "Data/IngameMap",
"Entries": {
// the base world map image with tooltips/positioning
"GingerIsland_BaseMap": {
"Group": "GingerIsland",
"AreaID": "GingerIsland_BaseMap",
"Texture": "Mods/Example.ModId/GingerIsland",
"SourceRect": "0 0 300 180",
"DestRect": "0 0 300 180",
"Zones": [
{
"ValidAreas": [ "IslandSouth" ],
"MapTileCorners": "0 0 42 45",
"MapImageCorners": "105 105 231 240",
"DisplayName": "{{i18n: map-names.island-south}}"
},
// ... list each map area here
]
},
// add beach resort if unlocked
"GingerIsland_Resort": {
"Group": "GingerIsland",
"AreaID": "GingerIsland_Resort",
"Texture": "Mods/Example.ModId/GingerIsland_Resort",
"SourceRect": "0 0 300 180",
"DestRect": "0 0 300 180",
"Condition": "PLAYER_HAS_FLAG Any Island_Resort"
}
}
},
// load textures
{
"Action": "Load",
"Target": "Mods/Example.ModId/GingerIsland",
"FromFile": "assets/ginger-island.png"
}
]
}
Custom map layers
You can now add any number of map layers by suffixing a vanilla layer name (i.e. Back, Buildings, Front, or AlwaysFront) with an offset. For example, Back-1 will be drawn before/under Back, and Back2 will be drawn after/over it. You can increment the number to add more layers.
This only affects layer rendering. Tile properties must still be set on the original layers.
Custom minecarts
You can now add/edit minecart destinations by editing the Data\Minecarts data asset, which consists of a data model with two relevant fields (listed below).
| field | effect | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| MinecartsUnlocked | A game state query which indicates whether minecarts in general are unlocked. You usually shouldn't change this value, unless you're changing the overall game progression (e.g. adding an alternative way to unlock minecart access). | ||||||||||||||
| Destinations | The destinations which the player can travel to from any minecart. This consists of a string → model lookup, where the key is a unique destination ID (only containing alphanumeric/underscore/dot characters, with custom entries prefixed with your mod ID like Example.ModId_DestinationId), and the value is a model with these fields:
|
Example
This Content Patcher content pack adds the Railroad as a minecart destination, complete with a map edit adding a decorative minecart. It is available after the Earthquake has occured and minecarts have been unlocked.
{
"Format": "2.0.0",
"Changes": [
// add minecart destination
{
"Action": "EditData",
"Target": "Data/Minecarts",
"TargetField": [ "Destinations" ],
"Entries": {
"Railroad": {
"Location": "Railroad",
"Tile": { "X": 16, "Y": 39 },
"Direction": "down",
"DisplayName": "[LocationName Railroad]"
}
},
"When": {
"HasFlag": "ccBoilerRoom",
"query: {{DaysPlayed}} >= 32": true
}
},
// add decorative minecart
{
"Action": "EditMap",
"Target": "Maps/Railroad",
"FromFile": "assets/Custom_Railroad_Minecart.tmx",
"ToArea": { "X": 15, "Y": 35, "Width": 4, "Height": 5 }
}
]
}
Custom passive festivals
You can now add or modify passive festivals by editing the Data/PassiveFestivalData asset.
(A passive festival is a festival like the Night Market. They replace a location for a period of time, the player can enter/leave them anytime, and time continues passing while at the festival.)
Data format
The Data/PassiveFestivalData asset consists of a string → model lookup, where the key is the unique festival ID, and the value is a model with these fields:
| field | effect |
|---|---|
| ID | A key which uniquely identifies this festival. For custom festivals, the ID should only contain alphanumeric/underscore/dot characters, and should ideally be prefixed with your mod ID like Example.ModId_FestivalName. |
| DisplayName | A tokenizable string for the display name shown on the calendar. |
| Season | The season when the festival becomes active. |
| StartDay EndDay |
The days of month when the festival becomes active. |
| StartTime | The time of day when the festival opens each day. |
| StartMessage | A tokenizable string for the in-game toast notification shown when the festival begins each day. |
| MapReplacements | The locations to swap for the duration of the festival. Despite the field name, this swaps locations (e.g. as added by CustomLocations using Content Patcher), and not the location's map asset.
This is specified as a string → string lookup, where the key is the original location to replace and the value is the new location. Both use the internal location name, as shown by the Debug Mode mod. For example, this swaps the Beach location with BeachNightMarket during the Night Market: "MapReplacements": {
"Beach": "BeachNightMarket"
}
|
| Condition | (Optional) A game state query which indicates whether the festival is enabled (subject to the other fields like StartDay and EndDay). Defaults to always enabled. |
| ShowOnCalendar | (Optional) Whether the festival appears on the calendar, using the same iridium-star icon as the Night Market. Default true. |
| DailySetupMethod CleanupMethod |
(Optional) A C# method which applies custom logic when the day starts (DailySetupMethod) and/or overnight after the last day of the festival (CleanupMethod).
These must be specified in the form |
NPC schedules
When a passive festival is active, NPCs will check for a schedule entry in this order:
| syntax | summary |
|---|---|
<festival ID>_<festival day>
|
Applies on the given date. The <festival day> is relative, so 1 matches the festival StartDay.Example: NightMarket_3 or marriage_NightMarket_3 |
<festival ID>
|
Applies if there's no date-specific entry. Example: NightMarket or marriage_NightMarket |
If the NPC is married to a player, they'll add a marriage_ prefix to the keys (like marriage_<festival ID>_<festival day>) and ignore any entry without the prefix.
Custom planting restrictions
You can now add context tags to a crop seed, fruit tree sapling, or wild tree seed to restrict where it can be planted. This is based on these tags:
| tag | effect |
|---|---|
| plantable_greenhouse | Can always be planted in a greenhouse (i.e., locations with IsGreenhouse), regardless of any other context tag. |
plantable_location_<location name>not_plantable_location_ <location name>
|
Must or must not be planted in one of these locations. This must be the internal location name (as shown by Debug Mode), lowercase and with any spaces replaced with underscores. |
plantable_context_<context ID>not_plantable_context_ <context ID>
|
Must or must not be planted in one of these location contexts. The context ID must be lowercase, with any spaces replaced with underscores. |
When multiple tags are specified, they're applied in this precedence order:
| precedence | rule | result |
|---|---|---|
| 1 | plantable_greenhouse matches | plantable |
| 2 | plantable_location_* matches | plantable |
| 2 | not_plantable_location_* matches or not_plantable_context_* matches |
not plantable |
| 3 | plantable_context_* or plantable_location_* specified but didn't match (not_* doesn't affect this rule) |
not plantable |
| 4 | current location listed in the context's DefaultValidPlantableLocations field | plantable |
| 5 | defaults to normal planting logic | |
For example:
| tags | effect | plantable | reason |
|---|---|---|---|
| none | Farm | ☑ plantable | default behavior |
| Greenhouse | ☑ plantable | ||
| location listed in its context's DefaultValidPlantableLocations | ☑ plantable | ||
| Bus Stop | ☐ | ||
| plantable_greenhouse, not_plantable_context_default | Farm | ☐ | matches not_plantable_context_default |
| Greenhouse | ☑ plantable | overridden by plantable_greenhouse | |
| plantable_location_islandwest | Island West | ☑ plantable | matches plantable_location_islandwest |
| Island South | ☐ | doesn't match plantable_location_islandwest | |
| Farm | ☐ | ||
| plantable_context_island | Island West | ☑ plantable | matches plantable_context_island |
| Island South | ☑ plantable | ||
| Farm | ☐ | doesn't match plantable_context_island | |
| not_plantable_context_island | Island West | ☐ | matches not_plantable_context_island |
| Island South | ☐ | ||
| Farm | ☑ plantable | default behavior | |
| plantable_location_town, plantable_location_mountain | Town | ☑ plantable | matches plantable_location_town |
| Mountain | ☑ plantable | matches plantable_location_mountain | |
| Farm | ☐ | doesn't match any plantable_location_* tags |
Custom weather
You can now change the weather algorithm by editing location context data, and (with a C# mod) implement custom weathers.
Fields like Game1.weather and Game1.weatherForTomorrow are now strings to support custom mod weather IDs. The change for vanilla weather has no effect on Content Patcher packs, since the new weather IDs match the ones Content Patcher was using before (i.e. Sun, Rain, Snow, Storm, and Wind). C# mods may also see a Festival weather, while Content Patcher packs will see Sun for it. The constants like Game1.weather_sunny have the new string values (with new constants like Game1.legacy_weather_sunny for the legacy values).
The base game will treat an invalid weather as sunny. C# mods can implement custom weather effects using normal SMAPI events like UpdateTicked, or by patching methods like Game1.ApplyWeatherForNewDay and Game1.populateDebrisWeatherArray.
New map properties
1.6 adds several new map properties.
Warps & map positions
| property | explanation |
|---|---|
DefaultWarpLocation <x> <y>(valid in any location) |
The default arrival tile, used when a player or NPC is added to the location without a target tile (e.g. using debug commands like debug warp or debug eventbyid). |
Audio
| property | explanation |
|---|---|
MusicContext <context>(valid in any location) |
The music context for this location. The recommended values are Default or SubLocation.
Setting SubLocation has two effects:
|
| MusicIgnoreInRain T² (valid in any outdoor location) |
If set, the Music property is ignored when it's raining in this location. |
| MusicIgnoreInSpring T² MusicIgnoreInSummer T² MusicIgnoreInFall T² MusicIgnoreInWinter T² (valid in any outdoor location) |
If set, the Music property is ignored in the given season. |
| MusicIgnoreInFallDebris T² (valid in any outdoor location) |
If set, the Music property is ignored in fall during windy weather. |
| MusicIsTownTheme T² (valid in any location) |
If set, uses the same behavior as Pelican Town's music: it will start playing after the day music has finished, and will continue playing while the player travels through indoor areas, but will stop when entering another outdoor area that isn't marked with the same Music and MusicIsTownTheme properties. |
Crops
| property | explanation |
|---|---|
| AllowGiantCrops T | If set with any non-blank value, giant crops can grow in this location. (To plant the crop itself, you'll need custom planting restrictions or the DefaultValidPlantableLocations context field.) |
Building construction
| property | explanation |
|---|---|
| CanBuildHere T (valid in any outdoor location) |
Whether to allow constructing buildings in this location. The game will adjust automatically to account for it (e.g. Robin will let you choose where to build). See build anywhere in what's new. |
BuildConditions <query>(valid in any outdoor location) |
If CanBuildHere is set, an optional game state query which indicates whether building is allowed currently. |
| LooserBuildRestrictions T (valid in any outdoor location) |
If set, tiles don't need to be marked Buildable T or Diggable T in their properties. Tiles can be blocked with Buildable F instead. The other restrictions still apply. |
ValidBuildRect <x> <y> <width> <height>(valid in any outdoor location) |
The tile area within the map where buildings may be placed. If omitted, buildings may be placed in any open space in the map. |
Other map property changes
- The NPCWarp and Warp properties are now fault-tolerant. They'll automatically ignore extra spaces, log an informative warning if parsing still fails, and continue with the next warp if possible.
- Removed many unused map/tile properties like Arch, Debris, Fish, and asdf.
Tile property changes
- Added new Action tile properties:
layer property explanation Buildings Action BuildingSilo If a building covers this tile, enables silo interactions on this tile subject to the building's HayCapacity field in Data/BuildingsData. Buildings Action BuildingToggleAnimalDoor If a building covers this tile, opens or closes its animal door. Buildings Action Forge Opens the Forge menu. Buildings Action ObeliskWarp <location name><x><y>[whether to dismount]Warps the player to the specified location name and position with the Obelisk animation/sound effects. Buildings Action OpenShop <shop id>[from direction][open time][close time][owner tile area]Open the shop with the given <shop id>. All arguments besides the ID are optional:[from direction]: if specified, the player must be standing in this direction relative to the shop (one of down, up, left, right, or none). Setting this to none disables the requirement. The default for most vanilla shops is down.[open time]and[close time]: the start & end times in 26-hour format when the shop is available. Interacting with the tile outside those times does nothing.[owner tile area]: if specified, the tile area which must contain one of the shop owners for the shop to be available. For a custom shop, these are defined by its ValidNPCs field. This can be specified in two forms:<x><y>for a single tile, or<x><y><width><height>for a multi-tile area.
Buildings Action PlayEvent <event id>[check preconditions][skip if seen]Immediately start an event, subject to the conditions: [check preconditions]: whether to ignore the action if the event's preconditions don't match (one of true or false). Default true.[skip if seen]: whether to ignore the action if the player has already seen the given event. Default true.
If the event is skipped, the action is silently ignored.
For example,
Action PlayEvent 60367 false falsewill replay the bus arrival event from the start of the game. - Added new TouchAction tile properties:
layer property explanation Back TouchAction PlayEvent <event id>[check preconditions][skip if seen][fallback action]Equivalent to Action PlayEvent. If the event is skipped, you can optionally specify another action to call instead after the other parameters, like TouchAction PlayEvent 60367 true true TouchAction PlayEvent 520702 false falseto play another event instead. - Dropped support for non-string map & tile properties. Properties set to bool, int, or float will be converted to string when the game loads them.
- The Treasure tile property has a new Treasure Item
<item ID>format which accepts a qualified or unqualified item ID.
Other location/map changes
- Added new fishing areas to simplify compatibility between fish & map mods (specifically for hilltop farm, wilderness farm, town, and desert).
- Added validation for map properties and tile properties. If the format is invalid, the game will now log a detailed error and skip it.
- Added a descriptive error when a required location or layer isn't found. Mods can use map.RequireLayer and Game1.RequireLocation to get a location with similar error-checking.
- Game logic which checks tile indexes is now more fault-tolerant, so it won't crash if an expected tile was edited.
- Finished migrating DecoratableLocation flooring/wallpaper areas to string IDs (started in Stardew Valley 1.5.5).
- Added methods to simplify common operations:
type method effect GameLocation HasMapPropertyWithValue Get whether a map property is defined and has a non-empty value. For example:
bool canUseCasks = Game1.currentLocation.HasMapPropertyWithValue("CanCaskHere");
GetMapPropertySplitBySpaces
GetTilePropertySplitBySpacesGet the value of a map/tile property and split it into individual words. If the map/tile property isn't defined, returns an empty array. For example:
string[] fields = Game1.currentLocation.GetMapPropertySplitBySpaces("ScreenshotRegion");
TryGetMapPropertyAs Get a map property and parse it into into a Point, Rectangle, or Vector2 value. For example:
if (this.TryGetMapPropertyAs("MailboxLocation", out Point position)) { position = new Point(68, 16); // default value }
MineShaft GetLevelName Get the location name for a generated mine or Skull Cavern level. For example:
string locationName = MineShaft.GetLevelName(10); // returns "UndergroundMine10" Game1.warpFarmer(locationName, 0, 0, false);
IsGeneratedLevel Get whether a location or location name is a generated mine or Skull Cavern level. For example:
string locationName = "UndergroundMine10"; bool isMine = MineShaft.IsGeneratedLevel(locationName, out int level); // returns true, 10
VolcanoDungeon GetLevelName
IsGeneratedLevelEquivalent to the matching MineShaft methods, but for the Volcano Dungeon.
- MineShaft.tryToAddMonster now returns whether a monster was added.
What's new for buildings
Custom buildings
You can now add custom buildings by editing the Data/Buildings asset. This consists of a string → model lookup, where...
- The key is a unique building ID. The ID should only contain alphanumeric/underscore/dot characters, and should ideally be prefixed with your mod ID like Example.ModId_BuildingName.
- The value is a model with the fields listed below.
Required fields
| field | effect |
|---|---|
| Name Description |
A tokenizable string for the display name and description (e.g. shown in the construction menu). |
| Texture | The asset name for the texture under the game's Content folder. |
Construction
| field | effect | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Builder | (Optional) The NPC from whom you can request construction. The vanilla values are Robin and Wizard, but you can specify a different name if a C# mod opens a construction menu for them. Defaults to Robin. If omitted, it won't appear in any menu. | ||||||||
| BuildCost | (Optional) The gold cost to construct the building. Defaults to 0g.
| ||||||||
| BuildMaterials | (Optional) The materials you must provide to start construction, as a list of models with these fields:
| ||||||||
| BuildDays | (Optional) The number of days needed to complete construction (e.g. 1 for a building completed the next day). If set to 0, construction finishes instantly. Defaults to 0. | ||||||||
| BuildCondition | (Optional) A game state query which indicates whether the building should be available in the construction menu. Defaults to always available. | ||||||||
| AdditionalPlacementTiles | (Optional) The extra tiles to treat as part of the building when placing it through the construction menu. For example, the farmhouse uses this to make sure the stairs are clear. This consists of a list of models with these fields:
| ||||||||
| IndoorItems | (Optional) The items to place in the building interior when it's constructed or upgraded. This consists of a list of models with these fields:
| ||||||||
| MagicalConstruction | (Optional) Whether the building is magical. This changes the carpenter menu to a mystic theme while this building's blueprint is selected, and completes the construction instantly when placed. | ||||||||
| AddMailOnBuild | (Optional) A list of letter IDs to send to all players when the building is constructed for the first time. |
Upgrades
| field | effect | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| BuildingToUpgrade | (Optional) The ID of the building for which this is an upgrade, or omit to allow constructing it as a new building. For example, the Big Coop sets this to "Coop". Any numbers of buildings can be an upgrade for the same building, in which case the player can choose one upgrade path. | ||||||||
| IndoorItemMoves | (Optional) When applied as an upgrade to an existing building, the placed items in its interior to move when transitioning to the new map. This is a list of models with these fields:
| ||||||||
| UpgradeSignTile | (Optional) The tile position relative to the top-left corner of the building where the upgrade sign will be placed when Robin is building an upgrade, in the form "<x>, <y>". Defaults to approximately "5, 1" if the building interior type is Shed, else "0, 0".
| ||||||||
| UpgradeSignHeight | (Optional) The pixel height of the upgrade sign when Robin is building an upgrade. Defaults to 0. |
Exterior behavior
| field | effect |
|---|---|
| Size | (Optional) The building's width and height when constructed, measured in tiles. Defaults to a 1 x 1 area. |
| CollisionMap | (Optional) An ASCII text block which indicates which of the building's tiles the players can walk onto, where each character can be X (blocked) or O (passable). Defaults to all tiles blocked.
For example, a stable covers a 2x4 tile area with the front two tiles passable: XXXX XOOX When the collision map is parsed, leading/trailing whitespace is trimmed (both for the entire map and for each line). In JSON, you can specify it in two forms: // single line with \n line breaks
"CollisionMap": "XXXX\nXOOX"
// multi-line with optional indentation
"CollisionMap": "
XXXX
XOOX
"
|
| HumanDoor | (Optional) The position of the door that can be clicked to warp into the building interior. This is measured in tiles relative to the top-left corner tile. Defaults to disabled. |
| AnimalDoor | (Optional) The position and size of the door that animals use to enter/exit the building, if the building interior is an animal location, specified as an object with X, Y, Width, and Height fields. This is measured in tiles relative to the top-left corner tile. Defaults to disabled. |
| AnimalDoorOpenDuration AnimalDoorCloseDuration |
(Optional) The duration of the open/close animation for the animal door, measured in milliseconds. If omitted, the door switches to the open/closed state instantly. |
| AnimalDoorOpenSound AnimalDoorCloseSound |
(Optional) The sound which is played once each time the animal door is opened/closed. Disabled by default. |
Exterior appearance
| field | effect | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| SourceRect | (Optional) The building's pixel area within the Texture, specified as an object with X, Y, Width, and Height fields. Defaults to the entire texture. | ||||||||||||||||||
| Skins | (Optional) The appearances which can be selected from Robin's menu (like stone/plank/log cabins), in addition to the default appearance based on Texture. This consists of a list of models with these fields:
| ||||||||||||||||||
| FadeWhenBehind | (Optional) Whether the building should become semi-transparent when the player is behind it. Default true. | ||||||||||||||||||
| DrawOffset | (Optional) A pixel offset applied to the building sprite's placement in the world. Default 0. | ||||||||||||||||||
| SeasonOffset | (Optional) A pixel offset to apply each season. This is applied to the SourceRect position by multiplying the offset by 0 (spring), 1 (summer), 2 (fall), or 3 (winter). Default 0, so all seasons use the same source rect. | ||||||||||||||||||
| SortTileOffset | (Optional) A Y tile offset applied when figuring out render layering. For example, a value of 2.5 will treat the building as if it was 2.5 tiles further up the screen for the purposes of layering. Default 0. | ||||||||||||||||||
| DrawLayers | (Optional) A list of textures to draw over or behind the building, with support for conditions and animations. This consists of a list of models with these fields:
| ||||||||||||||||||
| DrawShadow | (Optional) Whether to draw an automatic shadow along the bottom edge of the building's sprite. Default true. |
Interior
| field | effect |
|---|---|
| IndoorMap | (Optional) The name of the map asset under Maps to load for the building interior. For example, "Shed" will load the shed's Maps/Shed map. |
| IndoorMapType | (Optional) The full name of the C# location class which will manage the building's interior location. This must be one of the vanilla types to avoid a crash when saving. There are too many to list here, but the most useful types are likely...
Defaults to the generic StardewValley.GameLocation class. |
| NonInstancedIndoorLocation | (Optional) The name of the existing global location to treat as the building's interior, like FarmHouse and Greenhouse for their buildings.
Each location can only be used by one building. If the location is already in use (e.g. because the player has two of this building), each subsequent building will use the IndoorMap and IndoorMapType instead. For example, the first greenhouse will use the global Greenhouse location, and any subsequent greenhouse will use a separate instanced location. |
| MaxOccupants | (Optional) The maximum number of animals who can live in this building. |
| AllowAnimalPregnancy | (Optional) Whether animals can get pregnant and produce offspring in this building. Default false. |
| ValidOccupantTypes | (Optional) A list of building IDs whose animals to allow in this building too. For example, [ "Barn", "Coop" ] will allow barn and coop animals in this building. Default none.
|
Item processing
| field | effect | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| HayCapacity | (Optional) The amount of hay that can be stored in this building. If built on the farm, this works just like silos and contributes to the farm's available hay. | ||||||||||||||||||||
| ItemConversions | (Optional) The item processing rules which take input items and convert them into output items using the inventories defined by Chests. This consists of a list of models with these fields:
| ||||||||||||||||||||
| Chests | (Optional) The input/output inventories that can be accessed from a tile on the building exterior. The allowed items are defined by the separate ItemConversions field. This is a list of models with these fields:
|
Tile interactions
| field | effect | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ActionTiles | (Optional) A list of tiles which the player can click to trigger an Action map tile property. This consists of a list of models with these fields:
| ||||||||||||||
| DefaultAction | (Optional) The default tile action if the clicked tile isn't in ActionTiles. Default none. | ||||||||||||||
| TileProperties | (Optional) The map tile properties to set. This consists of a list of models with these fields:
| ||||||||||||||
| AdditionalTilePropertyRadius | (Optional) When checking whether the player clicked on a TileProperties tile, an added distance around the building at which tile locations may be placed. Default 0, so only tile properties within the normal building bounds will work. |
Advanced
| field | effect | ||||||
|---|---|---|---|---|---|---|---|
| Metadata | (Optional) A list of custom properties applied to the building, which can optionally be overridden per-skin in the Skins field. Default none.
The base game recognizes these properties:
This can also contain arbitrary custom properties, which C# mods can read using building.GetMetadata(key). | ||||||
| BuildingType | (Optional) The full name of the C# type to instantiate for the building instance. Defaults to a generic Building instance.
⚠ Caution: this is meant to support vanilla building types like StardewValley.Shed. Setting this to a non-vanilla type will cause a crash when it's written to the save file, and may cause crashes in multiplayer. If you need custom behavior, consider handling it in C# based on the building type instead of creating a custom subclass; otherwise you'll need a framework mod like SpaceCore to handle serialization and multiplayer sync. | ||||||
| ModData | (Optional) A string → string lookup of arbitrary modData values to attach to the building when it's constructed. | ||||||
| ConvertBuildingOffset | (Optional) Only used when migrating pre-1.6 buildings to 1.6, specifically to adjust for the barn's footprint being reduced by one tile in the back. |
Build anywhere
Buildings and animals are no longer hardcoded to the farm location (except cabins and the farmhouse which still are). You can allow building construction for any location using the new CanBuildHere and related map properties. The game will adjust accordingly (e.g. Robin will let you choose where to construct the building).
What's new for NPCs
Custom NPC data
Custom NPCs were already possible, but 1.6 extends that with a new Data/AdditionalNPCData data asset to customize previously hardcoded game logic and specify some data for NPCs that aren't in Data/NPCDispositions.
This consists of a string → model lookup, where the key is the internal NPC name (i.e. the same key as Data/NPCDispositions if any), and the value is a model with these fields:
- Main info:
-
field effect ID The internal NPC name. This should match the entry key. DisplayName (Optional) A tokenizable string for the NPC's display name. Defaults to the display name in Data/NPCDispositions (if any), else the internal NPC name. Size (Optional) The pixel size of the individual sprites in their overworld sprite spritesheet. Specified as a model with X and Y fields. Defaults to (16, 32). Note: sizes bigger than 16×32 may break NPC spawning and pathfinding.
UnlockConditions (Optional) A game state query which indicates whether the NPC should be added to the world, checked when loading a save and when ending each day. This only affects whether the NPC is added when missing; returning false won't remove an NPC that's already been added. Defaults to true. TextureName (Optional) The last segment of the NPC's portrait and sprite asset names. For example, set to Abigail to use Portraits/Abigail and Characters/Abigail respectively. Defaults to the internal NPC name. Breather (Optional) Whether the chest on the NPC's overworld sprite puffs in and out as they breathe. Default true. - Spawn info:
-
field effect ForceSpawn (Optional) Whether to add this NPC to the world even if they don't have an entry in Data/NPCDispositions. If true, you must specify DefaultLocation to avoid errors. Defaults to false. DefaultLocation (Optional) The internal name for the home location where this NPC spawns and returns each day. Defaults to the value specified in Data/NPCDispositions (if any), else causes an error. DefaultTile (Optional) The tile position within the home location where this NPC spawns and returns each day. Specified as a model with X and Y fields. Defaults to the tile specified in Data/NPCDispositions (if any), else (0, 0). Direction (Optional) The default direction the NPC faces when they start each day. The possible values are down, left, right, and up. Defaults to the value specified in Data/NPCDispositions (if any), else up. - Social features:
-
field effect SocializeConditions (Optional) A game state query which indicates whether to enable social features (like birthdays, gift giving, friendship, and an entry in the social tab). Defaults to true (except for monsters, horses, pets, and Junimos). Visibility (Optional) Determines how the NPC is shown on the social tab when unlocked. Possible values: value effect HiddenAlways They never appear in the social tab. Hidden Until the player meets them, they don't appear on the social tab. Default Until the player meets them, their name on the social tab is replaced with "???". Friend They always appear in the social tab (including their name). Defaults to Default.
ExcludeFromIntroductionsQuest (Optional) Whether this NPC will be ignored for the introductions quest. Default false if the NPC is in Data/NPCDispositions, else true. - Hidden gift log emote:
-
field effect HiddenProfileEmoteSound (Optional) For the hidden gift log emote, the cue ID for the sound played when clicking the sprite. Defaults to drumkit6. HiddenProfileEmoteDuration (Optional) For the hidden gift log emote, how long the animation plays measured in milliseconds. Defaults to 4000 (4 seconds). HiddenProfileEmoteStartFrame (Optional) For the hidden gift log emote, the index within the NPC's overworld sprite spritesheet at which the animation starts. If omitted for a vanilla NPC, the game plays a default animation specific to that NPC; if omitted for a custom NPC, the game just shows them walking while facing down. HiddenProfileEmoteFrameCount (Optional) For the hidden gift log emote, the number of frames in the animation. The first frame corresponds to HiddenProfileEmoteStartFrame, and each subsequent frame will use the next sprite in the spritesheet. Default 1. This has no effect if HiddenProfileEmoteStartFrame isn't set.
HiddenProfileEmoteFrameDuration (Optional) For the hidden gift log emote, how long each animation frame is shown on-screen before switching to the next one, measured in milliseconds. Default 200. This has no effect if HiddenProfileEmoteStartFrame isn't set.
Custom farm animals
You can now create and customize farm animals by editing the revamped Data/FarmAnimals asset.
This consists of a string → model lookup, where...
- The key is a unique farm animal ID. This should only contain alphanumeric/underscore/dot characters, and custom entries should be prefixed with your mod ID like Example.ModId_AnimalId.
- The value is a model with the fields listed below.
Main info
| field | effect |
|---|---|
| DisplayName | A tokenizable string for the animal type's display name. |
| House | The building ID for the main building type that houses this animal. The animal will also be placeable in buildings whose ValidOccupantTypes field contains this value. |
Animal shop
These fields affect how this farm animal type is shown in Marnie's animal shop. Animals are automatically listed if they have a valid PurchasePrice value.
| field | effect | ||||||
|---|---|---|---|---|---|---|---|
| PurchasePrice | (Optional if not purchaseable) Half the cost to purchase the animal (the actual price is double this value), or a negative value to disable purchasing this animal type. Default -1. | ||||||
| ShopTexture | (Optional if not purchaseable) The asset name for the icon texture to show in shops. Defaults to LooseSprites/Cursors or LooseSprites/Cursors2 based on the animal's position within the loaded data (but using the default isn't recommended if it's purchaseable). | ||||||
| ShopSourceRect | (Optional if not purchaseable) The pixel area within the ShopTexture to draw, specified as an object with X, Y, Width, and Height fields. This should be 32 pixels wide and 16 high. Ignored if ShopTexture isn't set. | ||||||
| RequiredBuilding | (Optional) The building that needs to be built on the farm for this animal to be available to purchase. Buildings that are upgraded from this building are valid too. Default none. | ||||||
| UnlockCondition | (Optional) A game state query which indicates whether the farm animal is available in the shop menu. Default always unlocked. | ||||||
| ShopDisplayName | (Optional) A tokenizable string for the display name shown in the shop menu. Defaults to the DisplayName field. | ||||||
| ShopDescription | (Optional) A tokenizable string for the tooltip description shown in the shop menu. Defaults to none. | ||||||
| ShopMissingBuildingDescription | (Optional) A tokenizable string which overrides ShopDescription if the RequiredBuilding isn't built. Defaults to none. | ||||||
| Genders | (Optional) The possible genders for the animal type. Currently this only affects the text shown after purchasing the animal, like "Great! I'll send little <name> to [his/her] new home right away". Default Female.
The possible values are:
| ||||||
| AlternatePurchaseTypes | (Optional) The possible variants for this farm animal (e.g. chickens can be Brown Chicken, Blue Chicken, or White Chicken). This consists of a list of models with these fields:
If multiple are listed, the first available variant is returned. Default none. |
Hatching
| field | effect | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| EggItemIds | (Optional) A list of the object IDs that can be placed in the incubator or ostrich incubator to hatch this animal. If the animal's House field doesn't match the current building, the entry will be ignored. Default none. | ||||||||||||
| IncubationTime | (Optional) How long eggs incubate before they hatch. Default 9000 minutes. | ||||||||||||
| IncubatorParentSheetOffset | (Optional) An offset applied to the incubator's sprite index when it's holding an egg. Default 1.
The vanilla values are:
| ||||||||||||
| BirthText | (Optional) A tokenizable string for the message shown when entering the building after the egg hatched. Defaults to the text "???". |
Growth
| field | effect |
|---|---|
| DaysToMature | (Optional) The number of days until a freshly purchased/born animal becomes an adult and begins producing items. Default 1. |
| CanGetPregnant | (Optional) Whether an animal can produce a child (regardless of gender). Default false. |
Produce
| field | effect | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| ProduceItemIds DeluxeProduceItemIds |
(Optional) The items produced by the animal when it's an adult. The DeluxeProduceItemIds field only applies if the Deluxe* fields match. Both default to none.
This consists of a list of models with these fields:
If multiple items can be produced, one is chosen at random (with deluxe items taking priority if applicable). | ||||||||
| DaysToProduce | (Optional) The number of days between item productions. For example, setting 1 will produce an item every other day. Default 1. | ||||||||
| ProduceOnMature | (Optional) Whether an item is produced on the day the animal becomes an adult. Default false. | ||||||||
| QualityBoostProfession | (Optional) The internal ID of a profession which increases the chance of higher-quality produce. This has the same effect as the Coopmaster and Shepherd professions, and doesn't stack with them. Defaults to the Coopmaster profession for an animal whose House value is Coop, else the Shepherd profession. | ||||||||
| ProduceSpeedProfession | (Optional) The internal ID of a profession which reduces the DaysToProduce by one. Defaults to none. | ||||||||
| ProduceSpeedBoostFriendship | (Optional) The minimum friendship points needed to reduce the DaysToProduce by one. Defaults to no reduction based on friendship. | ||||||||
| DeluxeProduceMinimumFriendship | (Optional) The minimum friendship points needed to produce the DeluxeProduceItemId. Default 200. | ||||||||
| DeluxeProduceCareDivisor DeluxeProduceLuckMultiplier |
(Optional) Quantity modifiers which change the probability of producing the DeluxeProduceItemId, based on this formula:
if happiness > 200: happiness_modifier = happiness * 1.5 else if happiness > 100: happiness_modifier = 0 else happiness_modifier = happiness - 100 ((friendship + happiness_modifier) / DeluxeProduceCareDivisor) + (daily_luck * DeluxeProduceLuckMultiplier) Specifically:
For example, given a friendship of 102 and happiness of 150, the probability with the default field values will be See Animals#Produce for more info on the calculation. | ||||||||
| HarvestType | (Optional) How produced items are collected from the animal. The valid values are:
Default DropOvernight. | ||||||||
| HarvestTool | (Optional) The tool ID with which produced items can be collected from the animal, if the HarvestType is set to HarvestWithTool. The values recognized by the vanilla tools are MilkPail and Shears. Default none. |
Audio & sprite
| field | effect | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Sound | (Optional) The audio cue ID for the sound produced by the animal (e.g. when pet). Default none. | ||||||||
| BabySound | (Optional) Overrides Sound field when the animal is a baby. Has no effect if Sound isn't specified. Default none. | ||||||||
| Texture | (Optional) The asset name for the animal's spritesheet. Defaults to Animals/<ID> (like Animals/Goat for a goat).
| ||||||||
| HarvestedTexture | (Optional) Overrides Texture if the animal doesn't currently have an item ready to collect (like the sheep's sheared sprite). Default none. | ||||||||
| BabyTexture | (Optional) Overrides Texture and HarvestedTexture when the animal is a baby. Default none. | ||||||||
| UseFlippedRightForLeft | (Optional) When the animal is facing left, whether to use a flipped version of their right-facing sprite. Default false. | ||||||||
| SpriteWidth SpriteHeight |
(Optional) The pixel height & width of the animal's sprite (before the in-game pixel zoom). Both default to 16. | ||||||||
| Skins | (Optional) A list of alternate appearances. If specified, a skin is chosen at random when the animal is purchased. This consists of a list of models with these fields:
|
Behavior
| field | effect |
|---|---|
| CanSwim | (Optional) Whether animals on the farm can swim in water once they've been pet. Default false. |
| BabiesFollowAdults | (Optional) Whether baby animals can follow nearby adults. Default false. |
| Pessimism | (Optional) An amount subtracted from the mood boost when a player pets the animal, before the Coopmaster or Shepherd profession bonus is applied. Default -1 (i.e. improves mood by one 1 point). |
| Price | (Optional) The price when the player sells the animal, before the friendship boost. Default 0. |
Other
| field | effect | ||||||
|---|---|---|---|---|---|---|---|
| ShowInSummitCredits | (Optional) Whether to show the farm animal in the credit scene on the summit after the player achieves perfection. Default false. | ||||||
| StatToIncrementOnProduce | (Optional) The game stat counters to increment when the animal produces an item. Default none. This consists of a list of models with these fields:
| ||||||
| UpDownPetHitboxTileSize LeftRightPetHitboxTileSize |
(Optional) The animal sprite's tile size in the world when the player is clicking to pet them, specified in the form <width>, <height>. The UpDownPetHitboxTileSize applies when the animal is facing up or down, and LeftRightPetHitboxTileSize applies when facing left or right. The values can be fractional (e.g. cows have a width of 1.75). Both default to a 1×1 tile.
| ||||||
| BabyUpDownPetHitboxTileSize BabyLeftRightPetHitboxTileSize |
(Optional) Overrides UpDownPetHitboxTileSize and LeftRightPetHitboxTileSize respectively before the animal is an adult. Both default to 1×1 tile. | ||||||
| MeatID | (Optional) Sets the animal's unused meat ID field when purchased. Default none. |
Custom pets
Format
You can now create and customize pets & pet breeds by editing the new Data/Pets asset.
This consists of a string → model lookup, where...
- The key is a unique identifier for the pet (not the pet breed). The vanilla IDs are Cat and Dog. For custom pets, this should be prefixed with your mod ID like Example.ModId_PetName.
- The value is a model with the fields listed below.
| field | effect | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| BarkSound | The cue ID for the pet's occasional 'bark' sound. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ContentSound | The cue ID for the sound which the pet makes when you pet it. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Behaviors | The pet's possible actions and behaviors, defined as the states in a state machine. Essentially the pet will be in one state at any given time, which also determines which state they can transition to next. For example, a cat can transition from Walk to BeginSitDown, but it can't skip instantly from Walk to SitDownLick.
This consists of a list of models with these fields:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Breeds | The cosmetic breeds which can be selected in the character customization menu when creating a save. This consists of a list of models with these fields:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| MoveSpeed | (Optional) How quickly the pet can move. Default 2. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| SleepOnBedChance SleepNearBedChance SleepOnRugChance |
(Optional) The percentage chances for the locations where the pet will sleep each night, as a decimal value between 0 (never) and 1 (always). Each value is checked in the order listed at left until a match is found. If none of them match, the pet will choose a random empty spot in the farmhouse; if none was found, it'll sleep next to its pet bowl outside. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| RepeatContentSoundAfter | (Optional) The number of milliseconds until the ContentSound is repeated once. This is used by the dog, who pants twice when pet. Defaults to -1 (disabled). |
Pet bowl
The pet bowl is now a building which can be constructed or moved. Each pet is assigned to an available pet bowl.
For C# mods, each pet now has a guid field populated with a unique ID, and each pet bowl has a petGuid field which tracks its owner (see the PetBowl::HasPet() and PetBowl::FindPet() methods).
Custom monster eradication goals
You can now add/edit Adventurer's Guild monster eradication goals by editing the new Data/MonsterSlayerQuestData data asset. This consists of a string → model lookup, where the key is a unique ID for the monster eradication goal, and the value is a model with these fields:
| field | effect |
|---|---|
| ID | A key which uniquely identifies this goal. The ID should only contain alphanumeric/underscore/dot characters, and custom goal IDs should ideally be prefixed with your mod ID like Example.ModId_GoalName. |
| DisplayName | A tokenizable string for the goal's display name, shown on the board in the Adventurer's Guild. |
| Targets | A list of monster IDs that are counted towards the Count. |
| Count | The total number of monsters (matching the Targets) which must be defeated to complete this goal. |
| RewardItemId | (Optional) The qualified item ID for the item that can be collected from Gil when this goal is completed. There's no reward item if omitted. |
| RewardItemPrice | (Optional) The price of the RewardItemId in Marlon's shop, or -1 to disable buying it from Marlon. Default -1. |
| RewardMail | (Optional) The mail flag ID to set for all players when Gil's reward menu is opened and this goal is complete. The players won't see a letter in their mailbox, even if it matches a letter ID. None is set if omitted. |
| RewardMailDialogue | (Optional) A tokenizable string for Gil's dialogue when the RewardMail is set. This has no effect if RewardMail isn't set. No extra dialogue is shown if omitted. |
Custom phone calls
Mods can now extend the telephone with custom calls (both incoming calls, and phone numbers which the player can call).
Incoming calls
You can add or customize incoming calls by editing the Data/IncomingPhoneCalls asset.
This consists of a string → model lookup, where...
- The key is a unique call ID. This should only contain alphanumeric/underscore/dot characters, and custom entries should be prefixed with your mod ID like Example.ModId_CallId.
- The value is a model with the fields listed below.
| field | effect |
|---|---|
| Dialogue | The dialogue text to show when the player answers the phone. This can use the full dialogue format (including questions and different dialogue based on the selected answer). |
| FromNpc | (Optional) The internal name of the NPC making the call. If specified, that NPC's name and portrait will be shown. |
| FromPortrait | (Optional) The asset name for the portrait spritesheet to display (like Portraits/Abigail). If FromNpc is specified too, this overrides the portrait from that NPC. If both FromNpc and FromDisplayName are null, this portrait will be shown with the display name "???". |
| FromDisplayName | (Optional) A tokenizable string for the calling NPC's display name. If FromNpc is specified too, this overrides the display name from that NPC. |
| MaxCalls | (Optional) The maximum number of times a player can receive this phone call, or <c>-1 for no limit. Default 1. |
| TriggerCondition RingCondition |
(Optional) If set, a game state query which indicates whether to trigger this phone call (TriggerCondition) or whether the phone rings when this call is received (RingCondition).
Whether a player receives this call depends on both fields: TriggerCondition is checked on the main player before sending the call to all players, then RingCondition is checked on each player to determine whether the phone rings for them. |
| IgnoreBaseChance | (Optional) Whether to ignore the 1% base chance when checking whether to trigger an incoming call. If true, the game will check if this call can be received regardless of the base chance. Default false. |
| SimpleDialogueSplitBy | (Optional, specialized) If set, marks the call as having a simple dialogue string without an NPC name and portrait, with lines split into multiple boxes by this substring. For example, "SimpleDialogueSplitBy": "#" will split Box A#Box B#Box C into three consecutive dialogue boxes.
You should omit this in most cases, and use the regular dialogue format in Dialogue to split lines if needed. This is mainly intended to support some older vanilla phone calls. |
Custom handlers in C#
C# mods can implement StardewValley.PhoneCalls.IPhoneHandler and add it to Phone.PhoneHandlers for full control over both incoming and outgoing calls:
/// <summary>The mod entry point.</summary>
internal class ModEntry : Mod
{
/// <inheritdoc />
public override void Entry(IModHelper helper)
{
Phone.PhoneHandlers.Add(new CustomPhoneHandler());
}
}
/// <summary>A custom phone handler.</summary>
internal class CustomPhoneHandler : IPhoneHandler
{
...
}
See StardewValley.PhoneCalls.DefaultPhoneHandler in the decompiled game code for an example implementation.
Custom shops
Format
You can now create and edit shops via the new Data/Shops asset. This consists of a string → model lookup, where the key is a unique ID for the shop (using a globally unique ID which includes your mod ID like ExampleMod.Id_ShopName for custom shops), and the value is a model with these fields:
| field | effect | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Items | The items to add to the shop inventory. This consists of a list of values with these fields:
| ||||||||||||||||||||||||||||||
| SalableItemTags | (Optional) A list of context tags for items which the player can sell to to this shop. Default none. | ||||||||||||||||||||||||||||||
| Owners | (Optional) The portrait and dialogue to show in the shop menu UI.
When the Action OpenShop tile property specifies This consists of a list of models with these fields:
| ||||||||||||||||||||||||||||||
| Currency | (Optional) The currency in which all items in the shop should be priced. The valid values are 0 (money), 1 (star tokens), 2 (Qi coins), and 4 (Qi gems). Default 0. For item trading, see TradeItemId for each item. | ||||||||||||||||||||||||||||||
| OpenSound | (Optional) The audio cue ID to play when the shop menu is opened. Defaults to dwop. | ||||||||||||||||||||||||||||||
| PurchaseSound | (Optional) The audio cue ID to play when an item is purchased normally. Defaults to purchaseClick. | ||||||||||||||||||||||||||||||
| purchaseRepeatSound | (Optional) The audio cue ID to play when accumulating a stack to purchase (e.g. by holding right-click on PC). Defaults to purchaseRepeat. | ||||||||||||||||||||||||||||||
| PriceModifiers | (Optional) Quantity modifiers applied to the sell price for items in this shop. See also PriceModifiers under Items. | ||||||||||||||||||||||||||||||
| PriceModifierMode | (Optional) A quantity modifier mode which indicates what to do if multiple modifiers in the PriceModifiers field apply at the same time. This only affects that specific field, it won't affect price modifiers under Items. Default Stack. | ||||||||||||||||||||||||||||||
| VisualTheme | (Optional) The visual theme to apply to the shop UI, or omit to use the default theme. The first matching theme is applied. All fields are optional and will fallback to the default theme.
This consists of a list of models with these fields:
|
Open a custom shop
You can place an Action OpenShop tile property on the map, which will open the given shop ID when the player clicks it.
In C# code, you can get the inventory for a custom shop using Utility.GetShopStock("shop id here"), open a shop menu using Utility.OpenShopMenu("shop id", …), and add temporary items to an open menu using shopMenu.AddForSale(…). The ID of the opened shop is stored in the shop menu's storeContext field.
Examples
You can add or replace entire shops. For example, this content pack adds a shop that sells ice cream in summer, and pufferfish all year:
{
"Format": "2.0.0",
"Changes": [
{
"Action": "EditData",
"Target": "Data/Shops",
"Entries": {
"Example.ModId_CustomShop": {
"Owners": [
{
"Name": "Any",
"Dialogues": [
// dialogue on sunny summer days
{
"Id": "Example.ModId_SunnySummer",
"Condition": "SEASON Summer, WEATHER Here Sun",
"Dialogue": "Ice-cream is perfect for a day like this."
},
// dialogue any other time
{
"Id": "Example.ModId_Default",
"Dialogue": "Welcome to the only place in town for pufferfish!"
}
]
}
],
"Items": [
// ice-cream in summer, default price
{
"Id": "Example.ModId_IceCream",
"Condition": "SEASON Summer",
"ItemId": "(O)233"
},
// pufferfish for 1000g, limited to one per day per player
{
"Id": "Example.ModId_PufferFish",
"ItemId": "(O)128",
"Price": 1000,
"AvailableStock": 1,
"AvailableStockLimit": "Player"
}
]
}
}
}
]
}
You can also add, replace, edit, or reorder items in a specific shop by targeting the shop's Items field. For example, this removes Trout Soup (item #219) and adds Pufferfish above bait (item #685):
{
"Format": "2.0.0",
"Changes": [
{
"Action": "EditData",
"Target": "Data/Shops",
"TargetField": [ "FishShop", "Items" ],
"Entries": {
"(O)219": null,
"Example.ModId_Pufferfish": {
"Id": "Example.ModId_Pufferfish",
"ItemId": "(O)128",
"Price": 2000
}
},
"MoveEntries": [
{ "Id": "Example.ModId_Pufferfish", "BeforeId": "(O)685" }
]
}
]
}
Vanilla shop IDs
Vanilla shops are now defined in Data/Shops too (except a few special cases like dressers and home renovations), using these shop IDs:
| shop | ID |
|---|---|
| Abandoned house shop | HatMouse |
| Adventurer's Guild | AdventureShop (regular shop) AdventureGuildRecovery (item recovery service) |
| Casino | Casino |
| Clint's blacksmith shop | Blacksmith (regular shop) ClintUpgrade (tool upgrades) |
| Desert trader | DesertTrade |
| Dwarf's shop | Dwarf |
| Harvey's clinic | Hospital |
| Ice-cream stand | IceCreamStand |
| Island trader | IslandTrade |
| Joja Mart | Joja |
| Krobus' shop | ShadowShop |
| Marnie's ranch | AnimalShop |
| Pierre's general store | SeedShop |
| Robin's carpenter shop | Carpenter |
| Stardrop Saloon | Saloon |
| Sandy's Oasis shop | Sandy |
| Traveling cart | Traveler |
| Willy's fish shop | FishShop |
Festival shops are also defined in Data/Shops now, though they can still be defined in the pre-1.6 way for backwards compatibility.
| festival shop | ID |
|---|---|
| Dance of the Moonlight Jellies | Festival_DanceOfTheMoonlightJellies_Pierre |
| Egg Festival | Festival_EggFestival_Pierre |
| Festival of Ice | Festival_FestivalOfIce_TravelingMerchant |
| Feast of the Winter Star | Festival_FeastOfTheWinterStar_Pierre |
| Flower Dance | Festival_FlowerDance_Pierre |
| Luau | Festival_Luau_Pierre |
| Night Market (decoration boat) | Festival_NightMarket_DecorationBoat |
| Night Market (magic boat) | Festival_NightMarket_MagicBoat_Day1 Festival_NightMarket_MagicBoat_Day2 Festival_NightMarket_MagicBoat_Day3 |
| Spirit's Eve | Festival_SpiritsEve_Pierre |
| Stardew Valley Fair | Festival_StardewValleyFair_StarTokens |
And two special 'shops':
| item | ID |
|---|---|
| Catalogue | Catalogue |
| Furniture Catalogue | Furniture Catalogue |
Dialogue changes
- For C# mods, Dialogue now tracks the translation key used to build it (when applicable). For example, you can detect when the player is rejected at the Flower Dance (derived from Three-Heart Dance Partner):
private void OnMenuChanged(object sender, MenuChangedEventArgs e) { bool isDanceRejection = Game1.currentLocation?.currentEvent?.FestivalName == "Flower Dance" && e.NewMenu is DialogueBox dialogueBox && dialogueBox.characterDialogue is {} dialogue && dialogue.TranslationKey == $"Characters\\Dialogue\\{dialogue.speaker?.Name}:danceRejection"; }
For C# mods that create Dialogue instances directly, there's a few ways to do it now:
// from a translation key var dialogue = new Dialogue(npc, "Strings\\StringsFromCSFiles:Utility.cs.5360"); // from custom text (with or without a translation key) var dialogue = new Dialogue(npc, null, "Some arbitrary text to show as-is"); // from a translation with tokens var dialogue = Dialogue.FromTranslation(npc, "Data\\ExtraDialogue:PurchasedItem_2_QualityLow_Willy", whatToCallPlayer, particle, i.DisplayName);
You can also easily add fallback logic using Dialogue.TryGetDialogue or npc.TryGetDialogue. For example:
Dialogue dialogue = npc.TryGetDialogue($"rejection_{itemId}_{locationName}_{x}_{y}") ?? npc.TryGetDialogue($"rejection_{itemId}_{locationName}") ?? npc.TryGetDialogue($"rejection_{itemId}") ?? new Dialogue(npc, "Strings\\StringsFromCSFiles:NPC.cs.3971");
- The 'reveal taste' dialogue command now uses the format %revealtaste:
<npc name>:<item ID>to support item IDs. (The previous %revealtaste<npc name><item index>format still works to support old content packs, but the item index can only be a number.) - Fixed NPCs only using a
{day name}{hearts}_{year}dialogue if they also have a{day name}{hearts}one. - Fixed NPCs only using the
MovieInvitationdialogue key in English.
Schedule changes
- Added an NPC.ScheduleKey field which always matches their loaded schedule.
- Removed an unintended schedule fallback to a {season}_spring_{hearts} key. It'll skip to the spring default instead.
- Schedules are now fault-tolerant:
- Fixed crash if a selected schedule can't be parsed. The NPC now logs an error and continues with the next fallback instead.
- Fixed crash if certain hardcoded schedules aren't present (like Penny's marriageJob or Pam's bus).
- For C# mods, removed the dayOfMonth parameter in NPC.getSchedule(). This was misleading since it used Game1.dayOfMonth in all but one line regardless.
What's new for everything else
Buff overhaul
1.6 rewrites buffs to work more consistently and be more extensible:
- Buff logic is unified into Game1.player.buffs, which is the single source of truth for buff data. This replaces the previous player.added* and player.appliedBuffs fields, BuffsDisplay logic, enchantment stat bonuses, and boots/ring attribute changes on (un)equip.
- This also removes limitations on buff types (e.g. buffs can add weapon bonuses and weapons can add attribute buffs) and buffable equipment (e.g. equipped tools can have buffs too).
- Buff effects are now fully recalculated when they change, to fix a range of longstanding bugs like attribute drift and double-debuffs. Just like before, the buffs are managed locally; only the buff IDs and aggregate attribute effects are synced.
For C# mods:
- Each buff now has a unique string ID. You can apply a new buff with the same ID to replace it (so you no longer need to manually find and remove previous instances of the buff).
- You can add standard buff effects to any equipment by overriding Item.AddEquipmentEffects, or add custom behaviour/buffs by overriding Item.onEquip and Item.onUnequip.
- You can add custom food or drink buffs by overriding Item.GetFoodOrDrinkBuffs().
- The Buff constructor now supports a custom icon texture, sprite index, display name, description, and millisecond duration to fully support custom buffs.
- You can change how buff attributes are displayed (or add new attributes) by extending the BuffsDisplay.displayAttributes list.
For example, here's how to add a custom buff which adds +3 speed:
Buff buff = new Buff(
buff_id: "Example.ModId/ZoomZoom",
display_name: "Zoom Zoom", // can optionally specify description text too
icon_texture: this.Helper.Content.Load<Texture2D>("assets/zoom.png"),
icon_sheet_index: 0,
duration: 30_000, // 30 seconds
buff_effects: new BuffEffects()
{
speed = { 10 } // shortcut for buff.speed.Value = 10
}
);
Game1.player.applyBuff(buff);
You can also implement your own custom effects in code by checking if the buff is active, like Game1.player.hasBuff("Example.ModId/ZoomZoom").
Custom audio
You can now add or edit music tracks or sound effects (called cues) by editing the Data/AudioCueModificationData asset. New cues are added to the game's soundbank, so they can be used anywhere normal audio can be used (e.g. the Music map property).
Format
The Data/AudioCueModificationData asset consists of a string → model lookup, where the key matches the ID, and the value is a model with the fields below.
Entries in this asset describe an override applied to the soundbank. The override is applied permanently for the current game session, even if the asset is edited to remove it. Overriding a cue will reset all values to the ones specified.
| field | effect | ||||||
|---|---|---|---|---|---|---|---|
| ID | A unique cue ID, used when playing the sound in-game. The ID should only contain alphanumeric/underscore/dot characters. For custom audio cues, this should be prefixed with your mod ID like Example.ModId_AudioName. | ||||||
| FilePaths | A list of file paths (not asset names) from which to load the audio. These can be absolute paths or relative to the game's Content folder. Each file can be .ogg or .wav. If you list multiple paths, a random one will be chosen each time it's played. | ||||||
| Category | The audio category, which determines which volume slider in the game options applies. This should be one of Default, Music, Sound, Ambient, or Footsteps (see a description of each category). Defaults to Default. | ||||||
| StreamedVorbis | Whether the audio should be streamed from disk when it's played, instead of being loaded into memory ahead of time. This is only possible for Ogg Vorbis (.ogg) files, which otherwise will be decompressed in-memory on load. Default false.
This is a tradeoff between memory usage and performance, so you should consider which value is best for each audio cue:
| ||||||
| Looped | Whether the audio cue loops continuously until stopped. Default false. | ||||||
| UseReverb | Whether to apply a reverb effect to the audio. Default false. |
Example
This content pack adds a new music cue to the game, and plays it when the player enters the bus stop:
{
"Format": "2.0.0",
"Changes": [
// add music cue
{
"Action": "EditData",
"Target": "Data/AudioCueModificationData",
"Entries": {
"Example.ModId_Music": {
"ID": "Example.ModId_Music",
"Category": "Music",
"FilePaths": [ "{{AbsoluteFilePath: assets/music.ogg}}" ],
"StreamedVorbis": true,
"Looped": true
}
}
},
// add to bus stop
{
"Action": "EditMap",
"Target": "Maps/BusStop",
"MapProperties": {
"Music": "Example.ModId_Music"
}
}
]
}
Other changes
- The game no longer crashes when playing audio which doesn't exist. It now logs an error and returns a default quiet click sound instead. (If you use
try..catchto check if an audio cue exists, you should checkGame1.soundbank.Exists(name)instead.)
Custom giant crops
You can now add/edit giant crops by editing the Data/GiantCrops data asset. This consists of a string → model lookup, where the key matches the ID and the value is a model with these fields:
| field | effect |
|---|---|
| ID | The unqualified item ID produced by the underlying crop (i.e. the 'index of harvest' field in Data/Crops). The giant crop has a chance of growing when there's a grid of fully-grown crops which produce this item ID in a grid of TileSize tiles. |
| Texture | The asset name for the texture containing the giant crop's sprite. |
| Corner | (Optional) The top-left pixel position of the sprite within the Texture, specified as a model with X and Y fields. Defaults to (0, 0). |
| TileSize | (Optional) The area in tiles occupied by the giant crop, specified as a model with X and Y fields. This affects both its sprite size (which should be 16 pixels per tile) and the grid of crops needed for it to grow. Note that giant crops are drawn with an extra tile's height. Defaults to (3, 3). |
| Chance | (Optional) The percentage chance a given grid of crops will grow into the giant crop each night, as a value between 0 (never) and 1 (always). Default 0.01. |
| HarvestedItemId | (Optional) The item ID which is harvested when you break the giant crop. Defaults to the ID. |
| MinYields | (Optional) The minimum number of the HarvestedItemId to drop when the giant crop is broken. |
| MaxYields | (Optional) The maximum number of the HarvestedItemId to drop when the giant crop is broken. Default 21. |
Custom wedding event
The wedding event can now be changed by editing the Data\Weddings data asset, which consists of a data model with two relevant fields (listed below).
| field | effect | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| EventScript | The event script which plays the wedding. The default script automatically handles marrying either an NPC or player, but mods can edit it conditionally to run a custom script (e.g. if the player is marrying their custom NPC). | ||||||||||
| Attendees | The other NPCs which should attend the wedding (unless they're the spouse). This consists of a string → model lookup, where the key is the internal NPC name, and the value is a model with these fields:
|
Game state queries
A game state query is a vanilla way to specify conditions for some content like shop data, inspired by Content Patcher's conditions. A query consists of a comma-delimited list of conditions in the form <type> [arguments], where <type> is case-sensitive. 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.
Conditions
- Date & time
-
Condition effect DAY_OF_MONTH <day>The day of month. This can be an integer between 0 and 28, or even/odd to match on any even/odd day. 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). DAYS_PLAYED <count>Whether at least <count>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 [day offset]Whether there's a festival today, with an optional [day offset](e.g. 1 for tomorrow).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 possible values (like SEASON spring summer for spring or summer). TIME <min><max>Whether the current time is between <min>and<max>inclusively, specified in 26-hour time. Each value can be set to 0 or less to ignore it (e.g. TIME 900 -1 for 9am or later).YEAR <min year>Whether the year is equal or more than the given value. For example, YEAR 2is true in year 2 and all later years. - World
-
Condition effect 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), 4 (combat), 5 (four corners), or 6 (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. 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 (one of CommunityCenter, JojaMart, or Railroad). Returns true for any other name, regardless of whether it's accessible. LOCATION_CONTEXT <location>The location context name for the given location. LOCATION_IS_MINES <location>
LOCATION_IS_SKULL_CAVE<location>Whether the given location is in the mines or Skull Cavern. 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>[object type]+Whether at least <min count>items have been donated (by any player) 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.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. 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
GoldenWalnutsThe 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
SkullCavesDifficultyThe 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 0condition to check if it should guarantee a Red Cabbage item.WORLD_STATE_ID <id>Whether any world state flag with the given <id>is set. - Player info & progress
-
Condition effect MINE_LOWEST_LEVEL_REACHED <level>Whether any player has reached at least level <level>in the mines.PLAYER_COMBAT_LEVEL <player><level>
PLAYER_FARMING_LEVEL<player><level>
PLAYER_FISHING_LEVEL<player><level>
PLAYER_FORAGING_LEVEL<player><level>
PLAYER_LUCK_LEVEL<player><level>
PLAYER_MINING_LEVEL<player><level>Whether the specified player(s) have a skill level of at least <level>, including the effects of buffs which raise them.PLAYER_CURRENT_MONEY <player><amount>Whether the specified player(s) have at least <amount>gold.PLAYER_FARMHOUSE_UPGRADE <player><level>Whether the specified player(s) have upgraded their farmhouse or cabin to at least the given level (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_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_CRAFTING_RECIPE <player><recipe name>
PLAYER_HAS_COOKING_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_FLAG <player><id>Whether the specified player(s) have the given mail flag set (with spaces allowed in the <id>).PLAYER_HAS_ITEM <player><item>[count]Whether the specified player(s) have at least one of a normal item (not bigcraftable, furniture, etc) in their inventory. The <item>can be 858 (Qi Gems), 73 (Walnuts), or the qualified or unqualified item ID.PLAYER_HAS_PROFESSION <player><profession id>Whether the specified player(s) have the given profession ID. PLAYER_HAS_READ_LETTER <player><id>Whether the specified player(s) have read a letter, where <id>is the internal mail ID (spaces allowed). For example,PLAYER_HAS_READ_LETTER Any Visited_Island.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 given <id>.PLAYER_HAS_TOWN_KEY <player>Whether the specified player(s) have the town key. PLAYER_HAS_TRASH_CAN_LEVEL <player><level>Whether the specified player(s) have the given trash can upgrade level. The specified level must match exactly (e.g. if the player has level 2, PLAYER_HAS_TRASH_CAN_LEVEL Current 1won't match). 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><amount>Whether the specified player(s) have earned at least <amount>gold.PLAYER_SHIPPED_BASIC_ITEM <player><item ID>[min count]Whether the specified player(s) have shipped the given item at least [min count]times (or once if the min isn't specified). 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_RULE_ACTIVE <player><rule id>Whether the specified player(s) have a special rule active for a special order. Some vanilla rules are... rule ID effect DROP_QI_BEANS The player can find Qi Beans for the Qi's Crop order. LEGENDARY_FAMILY The player catch the new legendary fish for the Extended Family order. MINE_HARD
SC_HARDRaises the difficulty level of the mines or Skull Cavern. SC_NO_FOOD The player can't eat food in the Skull Cavern. PLAYER_STAT <player><stat name><min value>Whether a stat counter for the specified player(s) has at least the given value. 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 relationships
-
Condition effect PLAYER_HAS_CHILDREN <player><count>Whether the specified player(s) have least <count>children.PLAYER_HAS_PET <player>Whether the specified player(s) have a pet. PLAYER_HEARTS <player><npc><heart level>Whether the specified player(s) have a friend with at least <heart level>hearts of friendship. The<npc>can be an NPC's internal name, Any (check every NPC), or AnyDateable (check every romanceable NPC).PLAYER_HAS_MET <player><npc>Whether the specified player(s) have talked to an NPC at least once. The <npc>is an NPC's internal name.PLAYER_IS_DATING <player><npc>
PLAYER_IS_ENGAGED<player><target>
PLAYER_IS_MARRIED<player><target>
PLAYER_IS_DIVORCED<player><npc>Whether the specified player(s) have this relationship status with an NPC. The player is dating after giving the NPC a bouquet, and engaged after giving a Mermaid's Pendant but before the marriage. The <npc>can be an NPC's internal name, or Any (check every romanceable NPC).PLAYER_IS_ROOMMATE <player><target>Whether the specified player(s) have a roommate. The <target>can be an NPC's internal name, Any (with any NPC), or Player (always false).PLAYER_PREFERRED_PET <player><pet>Whether the preferred pet for the specified player(s) is Cat or Dog. - Randomization
-
Condition effect RANDOM <chance>[@addDailyLuck]A random probability check which is re-rolled each time it's called. For example, RANDOM 0.4is 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 are used with queries that check an item. For vanilla content, these are only supported for custom machine conditions. For custom queries, C# mods can specify the target_item parameter when calling GameStateQuery.CheckConditions. In any other context, they'll always return false.
Condition effect ITEM_HAS_TAG <tags>Whether the item has all of the given space-delimited tags. For example, ITEM_HAS_TAG bone_item marine_itemwill only match items with both tags.ITEM_ID <item ID>Whether the item has the given qualified or unqualified item ID. ITEM_QUALITY <quality>Whether the item's quality is <quality>or higher. The possible values for<quality>are 0 (normal), 1 (silver), 2 (gold), or 4 (iridium).ITEM_STACK <count>Whether the item stack contains at least <count>items. Note that this only applies to the target item, it doesn't include other stacks in the inventory. - Immutable
-
Condition effect TRUE A condition which always matches. FALSE A condition which never matches.
Target location
Some conditions have a <location> argument. This can be one of...
| value | result | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Here | The current player's location (regardless of the target player). | ||||||||
| Target | This value depends on the context:
| ||||||||
| 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:
| ||||||||||||
| any other | The unique multiplayer ID for the player to check. |
Using queries elsewhere
C# code can use the GameStateQuery class to work with queries, like GameStateQuery.CheckConditions(query).
You can also use game state queries in event preconditions using the new G condition flag, like some_event_id/G !SEASON Spring, WEATHER Here Sun.
Extensibility
C# mods can define custom conditions by calling GameStateQuery.RegisterQueryType("condition name", (string[] fields) => ...). To avoid conflicts, prefixing custom condition names with your mod ID (like Example.ModId_SomeCondition) is strongly recommended.
Item queries
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
The supported item queries are:
| query | effect | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
ALL_ITEMS [type ID]
|
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.
| ||||||||||||||||||||
| DISH_OF_THE_DAY | The Saloon's dish of the day. | ||||||||||||||||||||
FLAVORED_ITEM <type> <flavor ID>
|
A flavored item like Apple Wine. The <type> can be one of AgedRoe, Honey, Jelly, Juice, Pickle, Roe, or Wine. The <flavor 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.
| ||||||||||||||||||||
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. | ||||||||||||||||||||
LOST_BOOK_OR_ITEM [alternate query]
|
Returns 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, | ||||||||||||||||||||
| RANDOM_ARTIFACT_FOR_DIG_SPOT | A random item which is defined in Data/ObjectInformation with the Arch (artifact) type, which lists the current location in its drops field, and whose random probability passes. This is mainly used by artifact spots. | ||||||||||||||||||||
| RANDOM_BASE_SEASON_ITEM | A random seasonal vanilla item which can be found by searching garbage cans, breaking containers in the mines, etc. | ||||||||||||||||||||
RANDOM_ITEMS <type definition ID> [options]
|
Random items from the given type definition ID, with any combination of the following criteria and options (in any order, all optional):
For example, you can sell a random wallpaper for {
"ItemId": "RANDOM_ITEMS (WP)",
"Price": 200
}
Or a random house plant: {
"ItemId": "RANDOM_ITEMS (F) @has_id_in_base_range 1376 1390"
}
Or a random custom item added by a mod by its item ID prefix: {
"ItemId": "RANDOM_ITEMS (O) @has_id_prefix AuthorName_ModName_"
}
Or 10 random objects with any category except -13 or -14: {
"ItemId": "RANDOM_ITEMS (O) @has_category @!has_category -13 -14 @count 10"
}
| ||||||||||||||||||||
SECRET_NOTE_OR_ITEM [alternate query]
|
Returns 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, | ||||||||||||||||||||
| SHOP_TOWN_KEY | The special town key item. This is only valid in shops. | ||||||||||||||||||||
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.
| ||||||||||||||||||||
Item spawn fields
Several data assets (like machines and shops) let you configure items to create. For consistency, these all share a set of common fields (internally represented by GenericSpawnItemData and ISpawnItemData):
| field | effect |
|---|---|
| ID | A unique identifier for this entry (not the item itself) within the current list. The ID should only contain alphanumeric/underscore/dot characters. For custom items, this should be prefixed with your mod ID like Example.ModId_Parsnips.
This is semi-optional — if omitted, it'll be auto-generated from the ItemId, RandomItemId, and IsRecipe fields. However multiple entries with the same ID may cause unintended behavior (e.g. shop items reducing each others' stock limits), so it's often a good idea to set a globally unique ID instead. |
| ItemId | One of:
|
| RandomItemId | (Optional) A list of item IDs to randomly choose from, using the same format as ItemId (including item queries). If set, ItemId is optional and ignored. Each entry in the list has an equal probability of being chosen. For example:
// wood, stone, or pizza
"RandomItemId": [ "(O)388", "(O)390", "(O)206" ]
|
| Condition | (Optional) A game state query which indicates whether this entry should be applied. Defaults to always true. |
| IsRecipe | (Optional) Whether to get the crafting/cooking recipe for the item, instead of the item itself. Default false. |
| Quality | (Optional) The quality of the item to find. One of 0 (normal), 1 (silver), 2 (gold), or 4 (iridium). Invalid values will snap to the closest valid one (e.g. 7 will become iridium). Default -1, which keeps the value set by the item query (usually 0). |
| MinStack | (Optional) The item's minimum and default stack size. Default -1, which keeps the value set by the item query (usually 1). |
| MaxStack | (Optional) If set to a value higher than MinStack, the stack is set to a random value between them (inclusively). Default -1. |
| ToolUpgradeLevel | (Optional) The initial upgrade level for the tool when created (like Copper vs Gold Axe, or Training Rod vs Iridium Rod). This is ignored for non-tool items. Default -1, which keeps the value set by the item query (usually 0). |
| QualityModifiers StackModifiers |
(Optional) Quantity modifiers applied to the Quality or Stack value. Default none.
The quality modifiers operate on the numeric quality values (i.e. 0 = normal, 1 = silver, 2 = gold, and 4 = iridium). For example, silver × 2 is gold. |
| QualityModifierMode StackModifierMode |
(Optional) quantity modifier modes which indicate what to do if multiple modifiers in the QualityModifiers or StackModifiers field apply at the same time. Default Stack. |
More modData fields
The modData fields are dictionaries of arbitrary string values which are synchronized in multiplayer and persisted in the save file, so mods can store custom data about the instances. The game already has the field for buildings, characters (including NPCs and players), items, locations, and terrain features.
Stardew Valley 1.6 adds a modData field for the Quest type, to support custom quest mods.
Quantity modifiers
Quantity modifiers apply dynamic changes to a numeric field in a data asset like Data/Shops or Data/Machines. For example, you can multiply a shop item's price or increase a machine output's quality. You can specify any number of modifiers for the same field.
Modifier format
These consist of a list of models with these fields:
| field | effect |
|---|---|
| Id | An ID for this modifier. This only needs to be unique within the current modifier list. For a custom entry, you should use a unique ID which includes your mod ID like ExampleMod.Id_ModifierName. |
| Modification | The type of change to apply. The possible values are Add, Subtract, Multiply, Divide, and Set. |
| Amount | (Optional if RandomAmount specified) The operand applied to the target value (e.g. the multiplier if used with Multiply). |
| RandomAmount | (Optional) A list of possible amounts to randomly choose from. If set, Amount is optional and ignored. Each entry in the list has an equal probability of being chosen, and the choice is persisted for the current day. For example:
"Amount": [ 1, 2, 3.5, 4 ]
|
| Condition | (Optional) A game state query which indicates whether this change should be applied. Defaults to always true. |
Modifier mode
Quality modifier fields are often accompanied by a mode field (like PriceModifiers and PriceModifierMode), which indicate what to do when multiple modifiers apply to the same value. Available modes:
| value | effect |
|---|---|
| Stack | Apply each modifier to the result of the previous one. For example, two modifiers which double a value will quadruple it. |
| Minimum | Apply the modifier which results in the lowest value. |
| Maximum | Apply the modifier which results in the highest value. |
Examples
For example, this will double the price of a shop item in Data/Shops:
"PriceModifiers": [
{
"Modification": "Multiply",
"Amount": 2.0
}
]
This will set the price to a random value between 100–1000, or 3–5 times the item's normal sell price, whichever is higher (like the Traveling Cart):
"PriceModifierMode": "Maximum",
"PriceModifiers": [
{
"Modification": "Set",
"RandomAmount": [ 100, 200, 300, 400, 500, 600, 700, 800, 900, 1000 ]
},
{
"Modification": "Multiply",
"RandomAmount": [ 3, 4, 5 ]
}
]
Tokenizable string format
Stardew Valley 1.6 adds support for literal strings that contain tokens (currently only supported for custom map areas and custom shops).
Literal text
Previously you often needed to load text from a string key in data assets. With this new format, you can use the literal text directly in the asset instead (including Content Patcher tokens):
// before
"Dialogue": "Strings\\StringsFromCSFiles:ShopMenu.cs.11488",
// after: literal text supported
"Dialogue": "Welcome to Pierre's!",
// after: literal text with Content Patcher tokens
"Dialogue": "Welcome to Pierre's, {{PlayerName}}! {{i18n: translatable-text}}",
Tokens
You can inject tokens using square brackets. For example, "[LocalizedText Strings\StringsFromCSFiles:ShopMenu.cs.11488] This is raw text" will show something like "Welcome to Pierre's! This is raw text". Here are the supported tokens:
| token format | output |
|---|---|
[ArticleFor <word>]
|
The grammatical article (a or an) for the given word when playing in English, else blank. For example, [ArticleFor apple] apple will output an apple.
|
[CharacterName <name>]
|
The translated display name for an NPC, given their internal name. |
[DataString <asset name> <key> <index>]
|
Parses the data asset identified by <asset name>, finds the entry matching <key>, splits the slash-delimited string, and returns the value with index <index> (starting from 0).
For example, [DataString Data\Blueprints Silo 8] matches the word "Silo" from this entry in Data\Blueprints: "Silo": "390 100 330 10 334 5/3/3/-1/-1/-2/-1/null/Silo/Allows you to cut and store grass for feed./Buildings/none/48/128/-1/null/Farm/100/false"
|
| [DayOfMonth] | The numeric day of month, like 5 on spring 5. |
[EscapedText <text>]
|
Replaces spaces in the given text with a special character that lets you pass them into other space-delimited tokens. The characters are automatically turned back into spaces when displayed. |
| [FarmerUniqueID] | The target player's unique internal multiplayer ID |
| [FarmName] | The farm name for the current save (without the injected "Farm" text). |
[GenderedText <male text> <female text>
|
Depending on the target player's gender, show either the male text or female text. If the text contains spaces, you'll need to escape them using EscapedText. |
[LocalizedText <string key>]
|
Translation text loaded from the given string key. If the translation has placeholder tokens like {0}, you can add the values after the string key. |
[LocationName <location ID>]
|
The translation display name for a location given its ID (i.e. the same ID as in Data/AdditionalLocationData). |
| [PositiveAdjective] | A random adjective from the Strings\Lexicon data asset's RandomPositiveAdjective_PlaceOrEvent entry. |
| [Season] | The current season name, like spring. |
[SpouseFarmerText <spouse is farmer text> <spouse is NPC text>
|
Show a different text depending on whether the target player's spouse is a player or NPC. If the text contains spaces, you'll need to escape them using EscapedText. |
[SpouseGenderedText <male text> <female text>]
|
Equivalent to GenderedText, but based on the gender of the player's NPC or player spouse instead. |
| [SuggestedItem] | (For shops only.) The name of a random item currently available in the shop stock. |
When passing an input argument for tokens like ArticleFor, the input can contain its own nested tokens. For example, "[ArticleFor [SuggestedItem]] [SuggestedItem]" would output something like an Apple.
If you're using Content Patcher, you can use its tokens anywhere in the string (including within square brackets); they'll be expanded before the game parses the string. For example, "{{Spouse}} would love [ArticleFor [SuggestedItem]] [SuggestedItem]!" would output something like "Alexa would love an Apple!".
Dialogue changes
- Added new dialogue commands:
command description $f <response IDs>Forget any number of space-delimited dialogue response IDs previously answered by the player. $v <event id>[check preconditions][skip if seen]Immediately start an event and end the current dialogue, subject to the conditions: [check preconditions]: whether to ignore the command if the event's preconditions don't match (one of true or false). Default true.[skip if seen]: whether to ignore the command if the player has already seen the given event. Default true.
If the event is skipped, the dialogue continues to the next line instead.
For example,
$v 60367 false falsewill replay the bus arrival event from the start of the game. - Dialogue response IDs are now strings, so mods can use a unique key like Example.ModId_ResponseName (instead of hoping no other mod uses the same number). Prefixing the mod ID is recommended to simplify troubleshooting and avoid conflicts. For best compatibility, custom IDs should only contain alphanumeric/underscore/dot characters.
- Unknown dialogue commands starting with $ are no longer parsed as a portrait number if they're not numeric.
Event changes
Major changes:
- Event IDs are now strings, so mods can use a unique key like Example.ModId_EventName (instead of hoping no other mod uses the same number). Prefixing the mod ID is recommended to simplify troubleshooting and avoid conflicts. For best compatibility, custom IDs should only contain alphanumeric/underscore/dot characters.
- Added validation for event preconditions & commands. If a format or assumption is invalid, the game now logs a detailed error and (if applicable) skips the command, instead of crashing or silently ignoring it.
- You can now invert a precondition by prefixing it with !. For example,
!O Abigailwill match if the player is not married to Abigail. - C# mods can now add custom event preconditions & commands using Event.RegisterCustomPrecondition and Event.RegisterCustomCommand respectively.
- Added new event commands:
command description addItem <item ID>[count][quality]Add an item to the player inventory (or open a grab menu if their inventory is full). The <item ID>is the qualified or unqualified item ID, and[quality]is a numeric quality value.temporaryAnimatedSprite ... Add a temporary animated sprite to the event, using these space-delimited fields: index field effect 0 texture The asset name for texture to draw. 1–4 rectangle The pixel area within the texture to draw, in the form <x><y><width><height>.5 interval The millisecond duration for each frame in the animation. 6 frames The number of frames in the animation. 7 loops The number of times to repeat the animation. 8–9 tile The tile position at which to draw the sprite, in the form <x><y>.10 flicker [TODO: document what this does] (one of true or false). 11 flip Whether to flip the sprite horizontally when it's drawn (one of true or false). 12 sort tile Y The tile Y position to use in the layer depth calculation, which affects which sprite is drawn on top if two sprites overlap. 13 alpha fade [TODO: document what this does] 14 scale A multiplier applied to the sprite size (in addition to the normal 4× pixel zoom). 15 scale change [TODO: document what this does] 16 rotation The rotation to apply to the sprite, measured in radians. 17 rotation change [TODO: document what this does] 18+ flags Any combination of these space-delimited flags: - hold_last_frame: after playing the animation once, freeze the last frame as long as the sprite is shown.
- ping_pong: [TODO: document what this does]
- motion
<x><y>: [TODO: document what this does] - acceleration
<x><y>: [TODO: document what this does] - acceleration_change
<x><y>: [TODO: document what this does]
warpFarmers [ <x><y><direction>]+<default offset><default x><default><direction>Warps connected players to the given tile coordinates and numeric directions. The <x><y><direction>triplet is repeated for each connected player (e.g. the first triplet is for the main player, second triplet is for the first farmhand, etc). The triplets are followed by an offset direction (one of up, down, left, or right), and a final triplet which defines the default values used by any other player.
Improved commands:
- Added support for arbitrary item IDs in awardFestivalPrize and itemAboveHead.
- Added removeItem argument for an optional count, like removeItem
<item ID>[count]. - Removed weddingSprite command (which was broken and unused).
- Removed ambientLight's four-argument form (which was unused and had confusing behavior).
- Removed showFrame farmer's flip option (which was broken and unused).
- Fixed some commands assuming a boolean argument is true if present, regardless of its value. This affects the changeToTemporaryMap, emote, extendSourceRect, faceDirection, globalFade, globalFadeToClear, positionOffset, and warp commands.
- Fixed some commands assuming any value except the exact case-sensitive string true is false. This affects the animate, glow, hideShadow, ignoreMovementAnimation, temporaryAnimatedSprite, temporarySprite, and viewport commands.
- Fixed some commands silently ignoring values they can't parse as the expected type. This affects the addItem, makeInvisible, and removeItem commands.
- Fixed crash when some commands are passed farmer[number] for a player who's not available, or farmer[number] when they expect farmer.
- Fixed some commands not taking into account custom farmer actors when checking farmer* actor IDs.
- Fixed makeInvisible not hiding terrain features when using the default area size.
- Fixed ignoreMovementAnimation ignoring its _ignore_ argument.
Other improvements:
- Festivals now set the event ID to a value like festival_fall16, instead of -1.
- For C# mods, the new Event.fromAssetName field indicates which data asset (if any) the event was loaded from.
- Event script errors are now logged (in addition to being shown in the chatbox like before).
New C# utility methods
Stardew Valley 1.6 adds a new ArgUtility class which handles splitting, reading, and validating string[] argument lists. The main methods are:
| ArgUtility method | effect |
|---|---|
| SplitBySpace | Split a space-separated list of arguments into an array. This automatically ignores extra spaces, so " x y " and "x y" are equivalent. For example:
string[] fields = ArgUtility.SplitBySpace("a b c");
string secondField = fields[1]; // "b"
|
| SplitBySpaceAndGet | Get the value at an index in a space-delimited string (if found), else return the default value. For example:
string thirdField = ArgUtility.SplitBySpaceAndGet("a b c", 2); // "c"
string invalidFieldA = ArgUtility.SplitBySpaceAndGet("a b c", 5); // null
string invalidFieldB = ArgUtility.SplitBySpaceAndGet("a b c", 5, defaultValue: "boop"); // "boop"
If you want to read multiple values, it's much more efficient to use SplitBySpace and read them from the array instead. |
| Get GetFloat GetInt |
Get a parsed value from an array by its index (if found and valid), else the default value.
For example, code like this: int value = fields.Length > 4 && int.TryParse(fields[4], out int parsed)
? parsed
: -1;
Can now be rewritten like this: int value = ArgUtility.GetInt(fields, 4, -1);
|
| TryGet TryGetBool TryGetFloat TryGetInt TryGetPoint TryGetRectangle TryGetVector2 |
Try to get a parsed value from an array by its index. If it's not found or can't be converted to the expected value, it sets the out string error argument so you can log an error if needed.
For example, this parses a numeric value from a space-delimited string: string[] fields = ArgUtility.SplitByString("10 35");
if (ArgUtility.TryGetInt(fields, 1, out int value, out string error))
this.Helper.Monitor.Log($"Parsed value: {value}"); // "Parsed value: 35"
else
this.Helper.Monitor.Log($"Failed parsing value: {error}", LogLevel.Warn);
|
| TryGetRemainder | Try to get all arguments starting from an index as a concatenated string. For example:
string[] fields = ArgUtility.SplitByString("A B C D E F");
if (ArgUtility.TryGetRemainder(fields, 2, out string remainder, out string error))
this.Helper.Monitor.Log($"Remainder: {remainder}"); // "Remainder: C D E F"
else
this.Helper.Monitor.Log($"Failed getting remainder: {error}", LogLevel.Warn);
|
| TryGetOptional TryGetOptionalBool TryGetOptionalFloat TryGetOptionalInt TryGetOptionalRemainder |
Equivalent to TryGet*, except that it'll return a default value if the argument is missing. For example:
string[] fields = ArgUtility.SplitByString("10");
if (ArgUtility.TryGetOptionalInt(fields, 1, out int value, out error, defaultValue: 99))
this.Helper.Monitor.Log($"Parsed value: {value}"); // "Parsed value: 99"
else
this.Helper.Monitor.Log($"Failed parsing value: {error}", LogLevel.Warn);
|
| HasIndex | Get whether an index is within the bounds of the array. For example:
string[] fields = ArgUtility.SplitByString("10 5");
bool inRange = ArgUtility.HasIndex(fields, 1); // true (index = '5')
|
1.6 also adds some new methods to the Utility class. Here are some of the most useful ones for mods:
| Utility method | effect |
|---|---|
| StringToDirection | Converts a string direction (one of down, left, right, or up) into a direction code recognized by various game methods (i.e. Game1.down, etc). If the string contains a number, the numeric value is returned (even if it's not a valid direction). If it's any other unrecognized value, the method returns -1. |
| CreateDaySaveRandom | Creates a Random instance using the most common seed (based on the save ID and total days played). |
| CreateRandom | Creates a Random by combining the given seed values, which can be any numeric type. |
| TryParseEnum | Parses a string into an enum value if possible, case-insensitively. Unlike Enum.TryParse, an invalid numeric value won't be cast:
Enum.TryParse("999999", out DayOfWeek day); // true, even though there's no matching DayOfWeek value
Utility.TryParseEnum("999999", out DayOfWeek day); // false
|
| GetDeterministicHashCode | (Specialized) Get a hash code which is always the same for a given input (unlike string.GetHashCode()), even if you restart the game or play on another computer. For example, this ensures that randomized shop items are the same across all players in multiplayer and don't change when you reload the save. |
And finally, it adds new extension methods:
| extension method | effect |
|---|---|
| random.GetChance | Perform a random probability check.
This just lets you simplify code like this: if (Game1.random.NextDouble() < 0.8)
Into a more semantic form: if (Game1.random.GetChance(0.8))
|
Static delegate builder
For C# mods, StaticDelegateBuilder is a specialized class which converts a method name into an optimized delegate which can be called by code. This is used by vanilla code to optimize methods referenced in assets like Data/Machines.
For example, given a static method like this:
public static bool DropInDeconstructor(Item machine, Item droppedInItem, Farmer who, bool probe, ref Item output, ref int minutesUntilReady) { ... }
And a delegate which matches it:
public delegate bool MachineItemConversionDelegate(Item machine, Item droppedInItem, Farmer who, bool probe, ref Item output, ref int minutesUntilReady);
You can create an optimized delegate and call it like this:
if (StaticDelegateBuilder.TryCreateDelegate("StardewValley.Object.DropInDeconstructor", out MachineItemConversionDelegate method, out string error))
return method(this, inputItem, who, probe, ref newHeldItem, ref minutesUntilMorning);
else
Game1.log.Warn($"Machine {ItemId} has invalid conversion method: {error}");
The TryCreateDelegate method will cache created delegates, so calling it again will just return the same delegate instance.
Game logging changes
The game now writes debug output through an internal Game1.log wrapper, instead of using Console.WriteLine directly. For example:
// old code
Console.WriteLine("Error playing sound: " + ex);
// new code
Game1.log.Error("Error playing sound.", ex);
This has a few benefits:
- For vanilla players, the game no longer uses time & resources writing to a console that's not visible anyway.
- For modded players, SMAPI can now...
- distinguish between the game's debug/warn/error messages (so many warnings/errors that would previously appear as hidden TRACE messages will now be shown with the correct level);
- apply its formatting rules to exceptions logged by the game too;
- redirect game output much more efficiently without console interception.
Other changes
Audio
- Added silence audio cue. This is different from none in that it suppresses both town music and ambient sounds.
- Added Game1.soundBank.Exists(cueName) method to check if an audio cue exists.
Debug commands
- Added new debug commands:
command description bsm If the player is standing right under a building, open a menu to change the building appearance. forcebuild Equivalent to build, but disables all safety checks so you can build in a location that wouldn't normally allow buildings, build on top of farm animals or placed objects, etc. gamequery / gq Syntax: gq <query>Check whether the given game state query matches in the current context. For example:
gq !SEASON Spring, WEATHER Here Sun > Result: true.
itemquery / iq Syntax: iq <query>Open a shop menu with all the items matching an item query (all items free). For example:
- debug iq ALL_ITEMS shows all items;
- debug iq ALL_ITEMS (W) shows all weapons;
- debug iq (O)128 shows a pufferfish (object 128);
- debug iq FLAVORED_ITEM Wine (O)128 shows Pufferfish Wine.
qualifiedid Print the held item's display name and qualified item ID. shop Syntax: shop <shop ID>[owner name]Open a shop defined in Data/Shops, regardless of whether one of the owners is nearby. Specifying
[owner name]will use that NPC, otherwise the command will find the closest valid NPC if possible (else open with no NPC).testwedding Immediately play the wedding event. thishouseupgrade / thishouse / thu Equivalent to houseupgrade, but can be used to upgrade another player's house by running it from inside or just south of its exterior. - Fixed ebi debug command not playing events correctly if called from the same location as the event.
Quests
- Quests now have string IDs, to simplify custom quest frameworks.
Time
- For C# mods, the Game1.realMilliSecondsPerGame and Game1.realMilliSecondsPerGameTenMinutes fields are no longer marked const, and the GameLocation.getExtraMillisecondsPerInGameMinuteForThisLocation() method has been replaced with a settable ExtraMillisecondsPerInGameMinute property. That lets you change the time rate used by the vanilla game code, but you should be careful doing this since it may cause unintended effects.
Other
- All space-delimited fields now ignore extra spaces instead of crashing. This affects map/tile properties, data assets, event commands, game state queries, etc.
- The desert no longer assumes the player arrived by bus unless their previous location was the bus stop.
- The SpriteText methods now accept arbitrary Color tints instead of a few predefined color IDs.
- Added Id fields to simplify content pack edits in fish pond, movie concession, random bundle, and tailoring recipe data.
- Added MoneyDial.ShouldShakeMainMoneyBox field to simplify custom dials.
Breaking changes for C# mods
This section only describes how this update may break existing mods. See the what's new sections above for more info, including new functionality mods can use.
See also Breaking changes for content packs, which affect C# mods too.
.NET 6
- See also: .NET 6 under what's new.
Stardew Valley 1.6 updates from .NET 5 to .NET 6. SMAPI can still load .NET 5 mods fine, but you'll get a build error when compiling them. To update a C# mod:
- Make sure you have Visual Studio Community 2022 or later. (Compiling .NET 6 with earlier versions of Visual Studio isn't officially supported.)
- In Visual Studio, click Help > Check For Updates and install the latest version.
- Fully exit Visual Studio.
- Open each mod's .csproj file in a text editor, then find this line:
<TargetFramework>net5.0</TargetFramework>
And change it to this:
<TargetFramework>net6.0</TargetFramework>
- Delete your solution's hidden .vs folder, and every project's bin and obj folders.
- Reopen the solution in Visual Studio, click Build > Rebuild Solution, and make sure it still loads into the game fine.
Item ID changes
- See also: custom items in what's new.
The main Item properties have changed. To migrate existing code:
- Don't use ParentSheetIndex to compare items. For example, item.ParentSheetIndex == 0 will match both weeds and any custom item whose sprite is the first one in its custom spritesheet. You should compare items using their new ItemId and QualifiedItemId properties instead. For example, here's how to migrate various common forms:
old code new code item.ParentSheetIndex == 848 item.QualifiedItemId == "(O)848" IsNormalObjectAtParentSheetIndex(item, 74) item.QualifiedItemId == "(O)74" !item.bigCraftable && item.ParentSheetIndex == 128 item.QualifiedItemId == "(O)128" item is Boots && item.ParentSheetIndex == 505 item.QualifiedItemId == "(B)505" - Don't assume item sprites are in the vanilla spritesheets. For example, instead of rendering Game1.objectSpriteSheet for an object, call
ItemRegistry.GetMetadata(item.QualifiedItemId).GetTexture()to get its texture. - Creating items works just like before, except that you now specify the item's ItemId (not QualifiedItemId) instead of its ParentSheetIndex. This is the same value for vanilla items. For example:
new Object("634", 1); // vanilla item new Object("Example.ModId_Watermelon", 1); // custom item
You can also use the new ItemRegistry API to construct items from their QualifiedItemId:
Item item = ItemRegistry.Create("(B)505"); // Rubber Boots
Other ID changes
Many other things in the game now have unique string IDs too (including buffs, events, and fruit trees). To migrate existing code:
- When referencing numeric IDs, you usually just need to convert them into a string (like
Game1.player.hasBuff("1590166")orGame1.player.eventsSeen.Contains("1590166")). - When creating buffs, see buff overhaul for how to create buffs now.
Building and animal changes
- See also: build anywhere in what's new.
- Since all locations now allow buildings and animals, mod code which handles BuildableGameLocation and IAnimalLocation won't detect all buildable locations. You can replace them with location.IsBuildableLocation() (or just access location.buildings directly) and location.animals.Any() instead. Mods should no longer have any reference at all to BuildableGameLocation and IAnimalLocation.
- Since buildings can be built anywhere, you can no longer assume a building is on the farm. You can check the new building.buildingLocation field instead.
- You should review direct references to the farm (like
Game1.getFarm()orGame1.getLocationFromName("Farm")) to see if it needs to be rewritten to allow location. Utility.numSilos()should no longer be used to calculate available hay, since it doesn't account for custom buildings with hay storage. UseGame1.getFarm().GetHayCapacity()instead.- The Cat and Dog classes are now unused; all pets are now Pet directly.
Player changes
- See also: buff overhaul in what's new.
- Several Game1.player / Farmer fields changed as part of the buff overhaul:
old field how to migrate appliedBuffs
appliedSpecialBuffsUse Game1.player.hasBuff(id)instead.attack
immunityUse Attack and Immunity instead. addedCombatLevel
addedFarmingLevel
addedFishingLevel
addedForagingLevel
addedLuckLevel
addedMiningLevel
attackIncreaseModifier
critChanceModifier
critPowerModifier
knockbackModifier
resilience
weaponPrecisionModifier
weaponSpeedModifierUse equivalent properties under Game1.player.buffs instead (e.g. Game1.player.buffs.CombatLevel). addedSpeed
CombatLevel
CraftingTime
FarmingLevel
FishingLevel
ForagingLevel
LuckLevel
MagneticRadius
MaxStamina
MiningLevel
StaminaThese are now readonly and can't be set directly. You can change them by adding a buff, equipment bonus, etc instead. - Buffs are now recalculated automatically, and you can reset a buff by just reapplying it. See buff overhaul for more info.
- Buff logic has been centralized into Game1.player.buffs. This replaces a number of former fields/methods like Game1.buffsDisplay.
Collision changes
The game's tile collision logic has been overhauled and merged into a simpler set of methods on GameLocation instances:
| method | effect |
|---|---|
| CanSpawnCharacterHere | Get whether NPCs can be placed on the given tile (e.g. it's within the map bounds and tile is walkable), and there's no placed object (even if walkable like flooring) and the NoFurniture tile property isn't set. |
| CanItemBePlacedHere | Get whether items can be placed on the given tile in non-floating form (e.g. it's within the map bounds and not blocked by a non-walkable item). If the item_is_passable argument is true, this ignores players/NPCs on the tile. |
| isBuildable | Get whether buildings can be placed on the given tile. |
| IsTilePassable | Get whether the tile can be walked on (ignoring collisions with in-game objects, NPCs, etc). |
| IsTileOccupiedBy | Get whether the tile contains a player, object, NPC/monster/pet/etc, terrain feature, building, etc. You can specify ignore_passables: false to ignore objects which can be walked over (like flooring), and override collision_mask to change the collision logic (e.g. collision_mask: GameLocation.CollisionMask.All & ~GameLocation.CollisionMask.Farmers to ignore players on the tile).
|
| IsTileBlockedBy | Equivalent to calling both IsTilePassable and IsTileOccupiedBy. |
| IsLocationSpecificOccupantOnTile IsLocationSpecificPlacementRestriction |
Generally shouldn't be used directly. Checks for location-specific collisions (e.g. ladders in the mines or parrot platforms on Ginger Island). |
Check for obsolete code
Perform a full rebuild of your mod (in Visual Studio, click Build > Rebuild Solution), then check the Error List pane for any warnings like "'X' is obsolete". Anything from the vanilla game code which is marked obsolete won't work anymore and is only kept for save migrations. Usually the warning will include an explanation of what you should use instead.
Breaking changes for content packs
This section only describes how this update may break existing mods. See the what's new sections above for more info, including new functionality mods can use.
Standardized data fields
1.6 standardizes the number of fields in data assets, and fixes inconsistencies between English and localized files. This is a major breaking change for content packs, and for C# mods which edit data assets.
Three examples illustrate the standardization:
- Data/CookingRecipes had four fields in English, and a fifth field in other languages for the display name. The display name field is now required in English too.
- Data/BigCraftables had an optional 9th field which indicates whether it's a lamp, and a 10th field for the display name. Even if it's empty, the 9th field is now required (note the extra / before the last field):
// before "151": "Marble Brazier/500/-300/Crafting -9/Provides a moderate amount of light./true/true/0/Marble Brazier", // 9 fields // after "151": "Marble Brazier/500/-300/Crafting -9/Provides a moderate amount of light./true/true/0//Marble Brazier" // 10 fields
- Data/ObjectInformation had several optional fields at the end. These are now required even if empty:
// before "0": "Weeds/0/-1/Basic/Weeds/A bunch of obnoxious weeds." // after "0": "Weeds/0/-1/Basic/Weeds/A bunch of obnoxious weeds.///"
Existing mods which add entries without the now-required fields may cause errors and crashes. XNB mods which change data are likely universally broken.
The exception is fields which only exist for modding, like the texture + index overrides for custom items. These can typically be omitted.
Standardized ID fields
Stardew Valley 1.6 adds an Id field to these assets. For Content Patcher content packs, these replace the previous synthetic ID:
| asset | old key | new key | migration steps |
|---|---|---|---|
| Data/ConcessionTastes Data/MovieReactions Data/RandomBundles (area) Data/RandomBundles (bundle) |
Name NPCName AreaName none |
Id | None. The Id field is set automatically to the same value (or Name for bundles), so there's no change for content packs. Omit the new field when creating a new entry. |
| Data/FishPondData Data/RandomBundles (bundle set) |
RequiredTags none |
Id | Use the new Id field to target an entry, and add it when creating a new entry. Required. |
| Data/TailoringRecipes | FirstItemTags and SecondItemTags | Id | Use the new Id field to target an entry, and add it when creating a new entry. Defaults to the CraftedItemIds (comma-delimited) or CraftedItemId value if omitted, but there's a high chance of conflicts so mods should always specify a unique ID. |
For example, let's say you have a patch like this using Content Patcher:
{
"Format": "2.0.0",
"Changes": [
{
"Action": "EditData",
"Target": "Data/TailorRecipes",
"Entries": {
"item_cloth|item_pufferchick": {
"FirstItemTags": [ "item_cloth" ],
"SecondItemTags": [ "item_pufferchick" ],
"CraftedItemId": "(S)1260"
}
}
}
]
}
When updating to Stardew Valley 1.6, replace the synthetic ID (item_cloth|item_pufferchick) with a real one:
- To edit an existing entry, unpack the asset and get its new Id value.
- To add a custom entry, use a globally unique ID prefixed with your mod ID. This should only have alphanumeric, underscore, and dot characters so it's safe to use in delimited fields, file names, etc. The recommended format is ExampleAuthor.ModId_EntryName.
For example:
{
"Format": "2.0.0",
"Changes": [
{
"Action": "EditData",
"Target": "Data/TailorRecipes",
"Entries": {
"ExampleAuthor.ModId_RainCoatFromPufferchick": {
"Id": "ExampleAuthor.ModId_RainCoatFromPufferchick", // need to specify ID again when creating it
"FirstItemTags": [ "item_cloth" ],
"SecondItemTags": [ "item_pufferchick" ],
"CraftedItemId": "(S)1260"
}
}
}
]
}
Event ID changes
- See also: string event IDs in what's new.
Events now have unique string IDs.
When creating an event:
- New events should use a globally unique ID in the form Your.ModId_EventName. Existing events should be fine as-is, but it may be worth migrating them to avoid future conflicts.
- Every non-fork event must have a precondition in its key (even if it's empty). For example, change
"Your.ModId_EventName": "..."to"Your.ModId_EventName/": "...". This is needed for the game to distinguish between events and fork scripts."Example.ModId_EventName/": "...", // event: loaded automatically by the game "SomeFork": "..." // event fork: ignored unless it's loaded through an event script
XNB impact
Here's a summary of the XNB files which changed in Stardew Valley 1.6.
This doesn't include...
- new files (since they won't impact existing mods);
- changes in non-English files;
- new fields when the vanilla entries didn't change (e.g. optional custom item fields).
Shorthand:
- 'broken' means removing new content or potentially important changes, or potentially causing significant display bugs. This is a broad category — the game may work fine without it or crash, depending how it uses that specific content.
- 'mostly unaffected' means mods will only be affected if they edit specific entries or fields.
- Blank means no expected impact for the vast majority of mods.
XNB mods are disproportionately affected since (a) they replace the entire file and (b) they're loaded through the MonoGame content pipeline which is less tolerant of format changes.
| content file | changes | XNB | Content Patcher |
|---|---|---|---|
| Buildings/houses | fixed missing pixels | ✘ will remove changes | ✓ mostly unaffected |
| Characters/Dialogue/Emily Characters/Dialogue/Lewis |
updated %revealtaste format (backwards-compatible) | ✘ will remove changes | ✓ mostly unaffected |
| Characters/Dialogue/Linus | fixed typos | ✘ will remove changes | ✓ mostly unaffected |
| Characters/Dialogue/MarriageDialogueEmily | changed spring_Maru key to spring_Emily | ✘ will remove changes | ✓ mostly unaffected |
| Characters/Dialogue/MarriageDialogueMaru Characters/Dialogue/Maru Characters/Dialogue/Robin Characters/Dialogue/Sam |
fixed typos | ✘ will remove changes | ✓ mostly unaffected |
| Data/AquariumFish | changed key type, standardized fields | ✘ broken | ✘ likely broken |
| Data/BigCraftablesInformation | changed key type, standardized fields | ✘ broken | ✘ likely broken |
| Data/Boots | changed key type, added display name | ✘ broken | ✘ likely broken |
| Data/Bundles | standardized fields, added display name | ✘ broken | ✘ likely broken |
| Data/ClothingInformation | changed key type, standardized fields | ✘ broken | ✘ likely broken |
| Data/ConcessionTastes | added new required fields (Texture and SpriteIndex), added automatic ID field | ✘ broken | ✓ mostly unaffected (unless they add new concessions) |
| Data/CookingRecipes | added display name | ✘ broken | ✘ likely broken |
| Data/CraftingRecipes | added display name, fixed typo in Cookout Kit entry | ✘ broken | ✘ likely broken |
| Data/Crops | changed key type | ✘ broken | |
| Data/Events/FishShop Data/Events/IslandSouth Data/Events/Mountain Data/Events/SebastianRoom Data/Events/Town |
fixed typo | ✘ will remove changes | ✓ mostly unaffected |
| Data/Festivals/spring13 Data/Festivals/spring24 Data/Festivals/summer11 Data/Festivals/summer28 Data/Festivals/winter8 |
migrated to new warpFarmers command | ✘ broken | ✘ likely broken |
| Data/Fish | changed key type | ✘ broken | |
| Data/FishPondData | changed ItemId field type, added required Id field | ✘ broken | ✘ broken if they add new entries |
| Data/fruitTrees | changed key type | ✘ broken | |
| Data/Furniture | changed key type, standardized fields, added display name | ✘ broken | ✘ likely broken |
| Data/hats | changed key type, standardized fields, added display name | ✘ broken | ✘ likely broken |
| Data/mail | fixed typos | ✘ will remove changes | ✓ mostly unaffected |
| Data/MovieReactions | added automatic ID field | ||
| Data/ObjectContextTags | added new entries & tags | ✘ broken | mostly unaffected (for content packs using best practices like appending values, or which only edit their own items) |
| Data/ObjectInformation | changed key type, standardized fields, added & adjusted litter items, fixed typos | ✘ broken | ✘ likely broken |
| Data/Quests | changed item fields to use item IDs (backwards-compatible) | ✘ will remove changes | ✓ mostly unaffected |
| Data/RandomBundles | optional ID field | ✘ broken | ✓ mostly unaffected (unless they add new bundlesets) |
| Data/SecretNotes | updated %revealtaste format (backwards-compatible) | ✘ will remove changes | ✓ mostly unaffected |
| Data/TailoringRecipes | changed to string item IDs (TODO: possibly backwards-compatible?), added optional ID field | ✘ broken | ✘ likely broken |
| Data/TV/TipChannel | fixed typo | ✘ will remove changes | ✓ mostly unaffected |
| Data/weapons | changed key type, added display name | ✘ broken | ✘ likely broken |
| LooseSprites/Cursors2 | new sprite in empty area | ✘ broken | |
| Maps/AbandonedJojaMart | changed map & tile properties to string | ||
| Maps/AnimalShop | added Music map property | ✘ broken | |
| Maps/Backwoods Maps/Backwoods_GraveSite Maps/Backwoods_Staircase Maps/Barn Maps/Barn2 |
changed map & tile properties to string | ||
| Maps/Barn3 | changed map & tile properties to string, added AutoFeed map property | ✘ broken | |
| Maps/BathHouse_Pool | added Music map property | ✘ broken | |
| Maps/Beach | added DefaultCrabPotArea + LegendaryFishAreaCorners + Music + MusicIgnoreInRain map properties | ✘ broken | |
| Maps/Beach-NightMarker | added DefaultCrabPotArea + DefaultFishingArea map properties | ✘ broken | |
| Maps/BoatTunnel | changed map & tile properties to string, added DefaultCrabPotArea map property | ✘ broken | |
| Maps/Cabin Maps/Cabin1 Maps/Cabin1_marriage Maps/Cabin2 Maps/Cabin2_marriage |
changed map & tile properties to string | ||
| Maps/Caldera | added Music map property | ✘ broken | |
| Maps/Club | added LocationContext map property | ✘ broken | |
| Maps/Coop Maps/Coop2 |
changed map & tile properties to string | ||
| Maps/Coop3 | changed map & tile properties to string, added AutoFeed map property | ✘ broken | |
| Maps/Desert | added LocationContext map property | ✘ broken | |
| Maps/ElliottHouse | added Music map property | ✘ broken | |
| Maps/Farm Maps/Farm_Combat |
changed map & tile properties to string, updated farmhouse area for moveable farmhouse | ✘ corrupted visuals when farmhouse is moved | |
| Maps/Farm_Fishing Maps/Farm_Foraging Maps/Farm_FourCorners |
changed map & tile properties to string, added DefaultFishingArea map property, updated farmhouse area for moveable farmhouse | ✘ broken | |
| Maps/Farm_Greenhouse_Dirt Maps/Farm_Greenhouse_Dirt_FourCorners |
changed map & tile properties to string | ||
| Maps/Farm_Island | changed map & tile properties to string, added DefaultFishingArea + DefaultCrabPotArea map properties, updated farmhouse area for moveable farmhouse | ✘ broken | |
| Maps/Farm_Mining | changed map & tile properties to string, added DefaultFishingArea map property, updated farmhouse area for moveable farmhouse | ✘ broken | |
| Maps/FarmHouse Maps/FarmHouse_Bedroom_Normal Maps/FarmHouse_Bedroom_Open Maps/FarmHouse_Cellar Maps/FarmHouse_ChildBed_0 Maps/FarmHouse_ChildBed_1 Maps/FarmHouse_CornerRoom_Add Maps/FarmHouse_CornerRoom_Remove Maps/FarmHouse_SouthernRoom_Add Maps/FarmHouse_SouthernRoom_Remove Maps/FarmHouse1 Maps/FarmHouse1_marriage Maps/FarmHouse2 Maps/FarmHouse2_marriage |
changed map & tile properties to string | ||
| Maps/Forest | added DefaultFishingArea + FishingAreaCorners + LegendaryFishAreaCorners map properties | ✘ broken | |
| Maps/Greenhouse | changed map & tile properties to string | ||
| Maps/Hospital | added Music and MusicIgnoreInRain map properties | ✘ broken | |
| Maps/Island_W | added LegendaryFishAreaCorners and FishingAreaCorners map property | ✘ broken | |
| Maps/IslandFarmHouse | changed map & tile properties to string | ||
| Maps/JojaMart | added Music and MusicContext map properties | ✘ broken | |
| Maps/LeahHouse Maps/LeoTreeHouse |
added Music map property | ✘ broken | |
| Maps/MarnieBarn Maps/Mine |
changed map & tile properties to string | ||
| Maps/Mountain | changed map & tile properties to string, added LegendaryFishAreaCorners map property | ✘ broken | |
| Maps/MovieTheater | changed map & tile properties to string. | ||
| Maps/MovieTheaterScreen | changed map & tile properties to string; changes to allow more players/NPCs at a time | ✘ broken | ✘ broken if they edit the affected tiles |
| Maps/MovieTheaterScreen_TileSheet | improved light cone; changes to allow more players/NPCs at a time. | ✘ broken visuals | ✓ mostly unaffected |
| Maps/paths | added icon for custom wild tree spawn | ||
| Maps/Saloon | added Music map property | ✘ broken | |
| Maps/SandyHouse | added LocationContext and Music map properties | ✘ broken | |
| Maps/ScienceHouse | added Music map property | ✘ broken | |
| Maps/Sewer | added LegendaryFishAreaCorners map property | ✘ broken | |
| Maps/Shed | added FloorIDs and WallIDs map properties | ✘ broken | |
| Maps/SkullCave | added LocationContext map property | ✘ broken | |
| Maps/spousePatios | changed map & tile properties to string | ||
| Maps/Sunroom | changed map & tile properties to string, added Music and MusicIgnoreInRain properties | ✘ broken | |
| Maps/Town | added LegendaryFishAreaCorners and multiple Music* map properties, changed to new garbage can IDs (backwards-compatible) | ✘ broken | |
| Maps/Mines/Volcano_SetPieces_32 | changed map & tile properties to string | ||
| Maps/Woods | added Music and MusicIgnoreInRain map properties | ✘ broken | |
| Strings/Buildings | added new entries for paint regions | ✘ broken | |
| Strings/StringsFromCSFiles Strings/StringsFromMaps |
fixed typos | ✘ will remove changes | |
| Strings/UI | added new translations | ✘ broken |
Vanilla release notes
This is a draft for the Version History section when 1.6 is released. It may be very incomplete; feel free to edit or suggest anything missing.
1.6.0
Stardew Valley 1.6.0 was released to the Steam beta branch on XX XX 20XX, and released on XX XXXX 20XX.
- New features
- The farmhouse and pet bowl can now be moved through Robin's menu.
- You can now switch existing cabins between the cabin styles through Robin's menu.
- Quality of life changes
- Marnie's animal menu now shows prices in the tooltip, in case the tooltip covers the price display.
- The museum reward menu now prevents picking up a reward that won't fit in your inventory.
- The museum reward menu now lets you exit while holding a reward. It'll be added to your inventory if possible, otherwise it'll drop at your feet.
- If an item menu exits while you're holding an item, the item is now always retrieved. (Previously only some item menus like chests would do it.)
- Various performance improvements.
- Fixes for gameplay
- The mushroom cave now provides mushrooms every second day. It was unintentionally changed to daily in Stardew Valley 1.5.
- Fixed issues with buffs:
- Fixed a range of bugs like attribute drift and double-debuff.
- Fixed food/drink buffs discarded if they have a balanced total of effects (e.g. +2 attack and -2 speed).
- Fixed negative custom buffs shown with a double-negative (e.g. "--2 speed").
- Fixed Squid Ink Ravioli buff not remaining active if another food buff is added later (although the buff icon was still shown).
- Fixed Squid Ink Ravioli not resetting the buff duration when you eat another one, unlike other food buffs.
- Fixed Squid Ink Ravioli description having an extra blank line.
- Fixed Burnt not showing the -3 Attack effect.
- Fixed buff effects formatted inconsistently in the Japanese and Korean localizations.
- Fixed gates popping off when closing them while the player overlaps the tile.
- Fixed fishing crash if a treasure chest appears while the player has a large number of stacked fishing buffs.
- Fixed issue where breaking a bee house containing honey would drop a generic "Honey" item, instead of the flavored honey it would produce when harvested.
- Fixes for visual or cosmetic issues
- The submerged fishing bobber is now recolored automatically to match the water.
- Fixed issue where a female character could choose a male shirt index during character customization, but it'd be rendered as the female variant in-game. When clothing is selected through character customization, it's now always rendered in-game with the selected variant.
- Fixed inventory & crafting menus misaligned if you resize the window while they're open.
- Fixed intro cutscene position not adjusted when the farmhouse is moved by a mod.
- Fixed cosmetic issues with the title & shipping screens for higher-resolution displays.
- Fixed calendar tooltip when a modded festival and birthday occur on the same day.
- Fixes for display text and localization
- Many NPCs have their own dialogue for accepting a movie invitation, but only in English. This now works in other languages too.
- Fixed three dialogues from Sam related to Kent that were previously never shown in-game.
- Fixed NPC name translations applied to horses/pets that share a name with that NPC.
- Fixed Professor Snail's intro event showing his name truncated (in German) or freezing (in Russian).
- Fixed unlocalized text shown for...
- the building paint menu's region names (like "Roof" or "Trim");
- NPC names in some movie theater dialogue.
- Fixed Lewis' letter for Feast of the Winter Star saying it starts at 10am instead of 9am.
- Fixed a skipped dialogue line in Maru's 14-heart event.
- Fixed various typos/errors in dialogue, events, and other display text.
- Fixed the hats added in 1.5 translating their internal name instead of setting the display name in some languages.
- Fixes for modded players
- Fixed crash if an NPC dialogue can't be parsed (it now logs the error and defaults to "..." instead).
- Fixed crash if you have a Statue of Endless Fortune, and the birthday NPC's first loved gift is a category or context tag. The statue now chooses the first valid gift taste, and falls back to a non-birthday gift if none was found.
- Fixed event setup not allowing more than 9 players.
- Fixed events not exiting correctly if they crash before the first script command.
- Fixed event errors not logged to the console.
- Fixed potential event crash if a custom NPC name contains 'farmer'.
- Other bug fixes
- Fixed various errors and crashes if an item's data is unavailable (usually due to removing a custom item mod).
- Fixed crash when applying building paint masks if the target building changed to a smaller sprite.
- Fixed crash when playing audio which doesn't exist. It now logs an error and plays a default 'quiet click' sound instead.
- Fixed hilltop farm spawning grass inside of stumps.
- Fixed being able to click the event skip button while in gamepad mode. If the player was previously viewing a letter with multiple pages, the cursor could be positioned directly above the skip button, causing the next viewed event to be skipped when the A button is pressed to progress text.
- Other changes
- Slightly reduced save file size.
- See changes for mod authors.
See also
- Modding wishlist items done in Stardew Valley 1.6 lists a few specialized changes not mentioned on this page.