translators
8,446
edits
Changes
→Contents: update for 1.6.4 (added SpecificBaitBuff + SpecificBaitMultiplier + CanUseTrainingRod)
</pre>
</pre>
==Data format (Stardew Valley 1.5.6 and earlier)==
==Data format==
Data/Locations controls many things about locations.
You can add or edit locations by editing the <samp>Data/Locations</samp> asset.
This consists of a string → model lookup, where...
* The key is the [[Modding:Common data field types#Unique string ID|unique string ID]] of the location (i.e. "internal name"), which will also be used as the location's <samp>Name</samp> (not <samp>DisplayName</samp>) field. (The farm will use <samp>Farm_{{t|type key}}</samp> for a vanilla farm type, or <samp>Farm_{{t|type ID}}</samp> for a custom farm type, or <samp>Farm_Standard</samp> if no type-specific entry was found.)
* The value is a model with the fields listed below.
===Basic info===
{| class="wikitable"
{| class="wikitable"
|-
|-
! field
! field
|-
|-
| <samp>DisplayName</samp>
| <samp>DisplayName</samp>
| ''(Optional but strongly recommended)'' A [[#Tokenizable string format|tokenizable string]] for the translated location name. This is used anytime the location name is shown in-game for base game logic or mods.
| ''(Optional but strongly recommended)'' A [[Modding:Tokenizable strings|tokenizable string]] for the translated location name. This is used anytime the location name is shown in-game for base game logic or mods.
|-
|-
| <samp>DefaultArrivalTile</samp>
| <samp>DefaultArrivalTile</samp>
| ''(Optional but strongly recommended)'' The default tile position where the player should be placed when they arrive in the location, if arriving from a warp that didn't specify a tile position. Default none, which usually places the player at (0, 0).
| ''(Optional but strongly recommended)'' The default tile position where the player should be placed when they arrive in the location, if arriving from a warp that didn't specify a tile position. Default none, which usually places the player at (0, 0).
|-
|-
| <samp>CreateOnLoad</samp>
| <samp>CreateOnLoad</samp>
| ''(Optional)'' The full name of the C# location class to create. 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 <samp>StardewValley.GameLocation</samp> (default value) and <samp>StardewValley.Locations.DecoratableLocation</samp>.
| ''(Optional)'' The full name of the C# location class to create. 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 <samp>StardewValley.GameLocation</samp> (default value) and <samp>StardewValley.Locations.DecoratableLocation</samp>.
|}
|}
|-
| <samp>CanPlantHere</samp>
| ''(Optional)'' Whether crops and trees can be planted and grown here by default, unless overridden by their plantable rules. Defaults to true for farms and false for other locations.
|-
| <samp>ExcludeFromNpcPathfinding</samp>
| ''(Optional)'' Whether NPCs should ignore this location when pathfinding between locations. Default false.
|}
|}
===Contents===
{| class="wikitable" style="margin-left: 2em;"
{| class="wikitable"
|-
|-
! field
! field
|-
|-
| ''common fields''
| ''common fields''
| See [[#Item spawn fields|item spawn fields]] for the generic item fields supported by artifact spot drops.
| See [[Modding:Item queries#Item spawn fields|item spawn fields]] for the generic item fields supported by artifact spot drops.
If set to an [[#Item queries|item query]] which returns multiple items, one of them will be selected at random.
If set to an [[Modding:Item queries|item query]] which returns multiple items, one of them will be selected at random.
|-
|-
| <samp>Chance</samp>
| <samp>Chance</samp>
|-
|-
| ''common fields''
| ''common fields''
| See [[#Item spawn fields|item spawn fields]] for the generic item fields supported by forage items.
| See [[Modding:Item queries#Item spawn fields|item spawn fields]] for the generic item fields supported by forage items.
This must return an <samp>Object</samp> item (or subclass of <samp>Object</samp>). If set to an [[#Item queries|item query]] which returns multiple items, one of them will be selected at random.
This must return an <samp>Object</samp> item (or subclass of <samp>Object</samp>). If set to an [[Modding:Item queries|item query]] which returns multiple items, one of them will be selected at random.
|-
|-
| <samp>Chance</samp>
| <samp>Chance</samp>
| <samp>CuriosityLureBuff</samp>
| <samp>CuriosityLureBuff</samp>
| ''(Optional)'' The value to add to the spawn chance when the player has the [[Curiosity Lure]] equipped, if set to 0 or higher. This affects both the <samp>Chance</samp> field and the <samp>Data\Fish</samp> chance, if applicable. Default -1, which keeps the default behavior (i.e. no effect on the <samp>Chance</samp> field and a scaled boost to the <samp>Data\Fish</samp> chance).
| ''(Optional)'' The value to add to the spawn chance when the player has the [[Curiosity Lure]] equipped, if set to 0 or higher. This affects both the <samp>Chance</samp> field and the <samp>Data\Fish</samp> chance, if applicable. Default -1, which keeps the default behavior (i.e. no effect on the <samp>Chance</samp> field and a scaled boost to the <samp>Data\Fish</samp> chance).
|-
| <samp>SpecificBaitBuff</samp>
| ''(Optional)'' A flat increase to the spawn chance when the player has a specific bait equipped which targets this fish. Default 0.
|-
| <samp>SpecificBaitMultiplier</samp>
| ''(Optional)'' A multiplier applied to the spawn chance when the player has a specific bait equipped which targets this fish. Default 1.66.
|-
|-
| <samp>CatchLimit</samp>
| <samp>CatchLimit</samp>
| ''(Optional)'' The maximum number of this fish which can be caught by each player. This limit is permanent (i.e. once it's reached, that fish will never appear again). For example, legendary fish set this to one. Default -1 (no limit).
| ''(Optional)'' The maximum number of this fish which can be caught by each player. This limit is permanent (i.e. once it's reached, that fish will never appear again). For example, legendary fish set this to one. Default -1 (no limit).
|-
| <samp>CanUseTrainingRod</samp>
| ''(Optional)'' Whether the player can catch this fish using a training rod. This can be <samp>true</samp> (always allowed), <samp>false</samp> (never allowed), or <samp>null</samp> (apply default logic, i.e. allowed for difficulty ratings under 50). Default null.
|-
|-
| <samp>IsBossFish</samp>
| <samp>IsBossFish</samp>
|-
|-
| <samp>CanBeInherited</samp>
| <samp>CanBeInherited</samp>
| ''(Optional)'' Whether this fish can be spawned in another location via the <samp>LOCATION_FISH</samp> [[#Item queries|item query]]. Default true.
| ''(Optional)'' Whether this fish can be spawned in another location via the <samp>LOCATION_FISH</samp> [[Modding:Item queries|item query]]. Default true.
|-
|-
| <samp>SetFlagOnCatch</samp>
| <samp>SetFlagOnCatch</samp>
|-
|-
| <samp>ChanceModifiers</samp>
| <samp>ChanceModifiers</samp>
| ''(Optional)'' [[#Quantity modifiers|Quantity modifiers]] applied to the <samp>Chance</samp> value. Default none.
| ''(Optional)'' [[Modding:Migrate to Stardew Valley 1.6#Quantity modifiers|Quantity modifiers]] applied to the <samp>Chance</samp> value. Default none.
|-
|-
| <samp>ChanceModifierMode</samp>
| <samp>ChanceModifierMode</samp>
| ''(Optional)'' [[#Quantity modifiers|quantity modifier modes]] which indicate what to do if multiple modifiers in the <samp>ChanceModifiers</samp> field apply at the same time. Default <samp>Stack</samp>.
| ''(Optional)'' [[Modding:Migrate to Stardew Valley 1.6#Quantity modifiers|quantity modifier modes]] which indicate what to do if multiple modifiers in the <samp>ChanceModifiers</samp> field apply at the same time. Default <samp>Stack</samp>.
|}
|}
|-
|-
|-
|-
| ''common fields''
| ''common fields''
| See [[#Item spawn fields|item spawn fields]] for the generic item fields supported by forage items.
| See [[Modding:Item queries#Item spawn fields|item spawn fields]] for the generic item fields supported by forage items.
This must return an <samp>Object</samp> (<samp>(O)</samp>)-type item. If it uses an [[#Item queries|item query]] that returns multiple items, one will be selected at random. If it returns null or a non-<samp>Object</samp> item, the spawn attempt will be skipped (with a logged warning if the item type is invalid).
This must return an <samp>Object</samp> (<samp>(O)</samp>)-type item. If it uses an [[Modding:Item queries|item query]] that returns multiple items, one will be selected at random. If it returns null or a non-<samp>Object</samp> item, the spawn attempt will be skipped (with a logged warning if the item type is invalid).
|-
|-
| <samp>Chance</samp>
| <samp>Chance</samp>
|}
|}
===Music===
{| class="wikitable" style="margin-left: 2em;"
{| class="wikitable"
|-
|-
! field
! field
|-
|-
| <samp>Id</samp>
| <samp>Id</samp>
| A key which uniquely identifies this entry within the list. The ID should only contain alphanumeric/underscore/dot characters. For custom entries for vanilla locations, this should be prefixed with your mod ID like <samp>Example.ModId_MusicId</samp>.
| ''(Optional)'' A [[Modding:Common data field types#Unique string ID|unique string ID]] which identifies this entry within the list. Defaults to the <samp>Track</samp> value.
|-
| <samp>Track</samp>
| The [[Modding:Migrate to Stardew Valley 1.6#Custom audio|audio track ID]] to play.
|-
|-
| <samp>Condition</samp>
| <samp>Condition</samp>
| ''(Optional)'' A [[#Game state queries|game state query]] which indicates whether this entry applies. Default true.
| ''(Optional)'' A [[Modding:Game state queries|game state query]] which indicates whether this entry applies. Default true.
|}
|}
|-
|-
|}
|}
===Advanced===
{| class="wikitable" style="margin-left: 2em;"
{| class="wikitable"
|-
|-
! field
! field
|-
|-
| <samp>CustomFields</samp>
| <samp>CustomFields</samp>
| The [[#Custom data fields|custom fields]] for this entry.
| ''(Optional)'' The [[Modding:Common data field types#Custom fields|custom fields]] for this entry.
|-
| <samp>FormerLocationNames</samp>
| ''(Optional)'' The former location names which may appear in save data. See ''[[#Can I rename a location?|Can I rename a location?]]'' in the FAQs for more info.
|}
|}
====<samp>Default</samp> entry====
==Default entry==
The <samp>Data/Locations</samp> asset has a location with the key <samp>Default</samp>. The <samp>ArtifactSpots</samp>, <samp>Fish</samp>, and <samp>Forage</samp> fields for this entry are added to every other location's equivalent fields, so this lets you add artifact spots / fish / forage in all locations.
==FAQs==
===How do I get to a custom location in-game?===
Adding a location to <samp>Data/Locations</samp> only adds the location to the game. Don't forget to give players some way to reach it, usually by adding warps from another map using <samp>EditMap</samp> in a [[Modding:Content Patcher|Content Patcher content pack]].
For a quick test, you can run the <code>debug warp {{t|location name}}</code> [[Modding:Console commands|console command]] to warp directly into it.
===Can I make the location conditional?===
There's many ways you can decide when players have access. For example, you can use <samp>EditMap</samp> in a [[Modding:Content Patcher|Content Patcher content pack]] to add warps conditionally or to add some form of roadblock that must be cleared (e.g. a landslide).
'''Note:''' don't make the existence of the location itself conditional, just make it unreachable. Removing the location will permanently delete everything inside it.
===Can I rename a location?===
'''Renaming a location will permanently lose player changes made for the old name if you're not careful.'''
You can avoid that by setting the <samp>FormerLocationNames</samp> field in <samp>Data/Locations</samp>. If a location in save data has a name which (a) matches one of the <samp>FormerLocationNames</samp> and (b) doesn't match the name of a loaded location, its data will be loaded into the location which specified the <samp>FormerLocationNames</samp> field instead.
For example:
<syntaxhighlight lang="js">
"FormerLocationNames": [ "Custom_SomeOldName" ]
</syntaxhighlight>
Legacy names can have any format, but they must be '''globally''' unique. They can't match the <samp>Name</samp> or <samp>FormerLocationNames</samp> of any other location in <samp>Data/Locations</samp> (whether vanilla or custom).
==Location names==
==Location names==