Difference between revisions of "Modding:Location data"

From Stardew Valley Wiki
Jump to navigation Jump to search
m (Adding more location descriptions.)
(→‎Contents: update for 1.6.4 (added SpecificBaitBuff + SpecificBaitMultiplier + CanUseTrainingRod))
 
(19 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
← [[Modding:Index]]
 
← [[Modding:Index]]
  
−
Data/Locations controls many things about locations.
+
This page explains how to create and edit in-game locations.
  
−
Here is an example location:
+
==Terminology==
 +
A few terms may be used interchangeably or have different meanings depending on the context. In the context of Stardew Valley:
  
−
<syntaxhighlight lang="json">
+
* A '''location''' is part of the game code and save data. It manages the in-game area and everything inside it (including non-map entities like players). The location is read/written to the save file, and is only loaded when loading the save file.
−
"Beach": "372 .9 718 .1 719 .3 723 .3/372 .9 394 .5 718 .1 719 .3 723 .3/372 .9 718 .1 719 .3 723 .3/372 .4 392 .8 718 .05 719 .2 723 .2/129 -1 131 -1 147 -1 148 -1 152 -1 708 -1 267 -1/128 -1 130 -1 146 -1 149 -1 150 -1 152 -1 155 -1 708 -1 701 -1 267 -1/129 -1 131 -1 148 -1 150 -1 152 -1 154 -1 155 -1 705 -1 701 -1/708 -1 130 -1 131 -1 146 -1 147 -1 150 -1 151 -1 152 -1 154 -1 705 -1/384 .08 589 .09 102 .15 390 .25 330 1",
+
* A '''[[Modding:Maps|map]]''' is an asset which describes the tile layout, tilesheets, and map/tile properties for the in-game area. The map is reloaded each time you load a save, and each time a mod changes the map.
 +
* A '''[[Modding:World map|world map]]''' is the image shown for a world region in the in-game menu.
 +
 
 +
In other words, a ''location'' (part of the game code) references the ''map'' (loaded from the <samp>Content</samp> folder):
 +
 
 +
<pre>
 +
┌─────────────────────────────────┐
 +
│ Location                        │
 +
│  - objects                    │
 +
│  - furniture                  │
 +
│  - crops                      │
 +
│  - bushes and trees            │
 +
│  - NPCs and players            │
 +
│  - etc                        │
 +
│                                │
 +
│  ┌─────────────────────────┐  │
 +
│  │ Map asset              │  │
 +
│  │  - tile layout        │  │
 +
│  │  - map/tile properties │  │
 +
│  │  - tilesheets          │  │
 +
│  └─────────────────────────┘  │
 +
└─────────────────────────────────┘
 +
</pre>
 +
 
 +
==Data format==
 +
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"
 +
|-
 +
! field
 +
! effect
 +
|-
 +
| <samp>DisplayName</samp>
 +
| ''(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>
 +
| ''(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>
 +
| ''(Optional)'' If set, the location will be created automatically when the save is loaded using this data.
 +
 
 +
This consists of a model with these fields:
 +
 
 +
{| class="wikitable"
 +
|-
 +
! field
 +
! effect
 +
|-
 +
| <samp>MapPath</samp>
 +
| The asset name for the map to use for this location.
 +
|-
 +
| <samp>AlwaysActive</samp>
 +
| ''(Optional)'' Whether this location is always synchronized to farmhands in multiplayer, even if they're not in the location. Any location which allows building cabins '''must''' have this enabled to avoid breaking game logic.
 +
|-
 +
| <samp>Type</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"
 +
|-
 +
! field
 +
! effect
 +
|-
 +
| <samp>ArtifactSpots</samp>
 +
| ''(Optional)'' The items that can be found when digging [[Artifact Spot|artifact spots]] in this location.
 +
 
 +
An artifact spot is selected by combining this field with the equivalent field on the <samp>Default</samp> entry, sorting by <samp>Precedence</samp> value, and then choosing the first entry whose fields match. (Artifact spot drops can also be listed in [[Modding:Items#Objects|<samp>Data/Objects</samp>]]'s <samp>Miscellaneous</samp> field; those are applied by the <samp>RANDOM_ARTIFACT_FOR_DIG_SPOT</samp> entry in <samp>DefaultArtifactSpots</samp>.)
 +
 
 +
This consists of a list of models with these fields:
 +
{| class="wikitable"
 +
|-
 +
! field
 +
! effect
 +
|-
 +
| ''common fields''
 +
| See [[Modding:Item queries#Item spawn fields|item spawn fields]] for the generic item fields supported by artifact spot drops.
 +
 
 +
If set to an [[Modding:Item queries|item query]] which returns multiple items, one of them will be selected at random.
 +
|-
 +
| <samp>Chance</samp>
 +
| ''(Optional)'' The probability that the item will be dropped if the other fields match, as a decimal value between 0 (never) and 1 (always). Default 1.
 +
|-
 +
| <samp>ApplyGenerousEnchantment</samp>
 +
| ''(Optional)'' Whether to apply the 'Generous' [[Forge#Enchantments|enchantment]], which adds a 50% chance of the item dropping twice. If the enchantment is applied, the item's fields are rerolled for the second drop (e.g. a new random value between <samp>MinStack</samp> and <samp>MaxStack</samp> is selected). Default true.
 +
|-
 +
| <samp>OneDebrisPerDrop</samp>
 +
| ''(Optional)'' Whether to split the dropped item stack into multiple floating debris that each have a stack size of one. For example, if the dropped item has a stack size of 3, this will spawn three separate item stacks. Default true.
 +
|-
 +
| <samp>ContinueOnDrop</samp>
 +
| ''(Optional)'' Whether to continue checking for more items to drop when this item is dropped. Default false.
 +
|-
 +
| <samp>Precedence</samp>
 +
| ''(Optional)'' The order in which this entry should be checked, where lower values are checked first. This can be a negative value. Artifact spots with the same precedence are checked in the order listed. Default 0.
 +
 
 +
For consistency, vanilla artifact drops mostly use these values:
 +
* <samp>-1000</samp>: location items which should override the global priority items (e.g. fossils on Ginger Island);
 +
* <samp>-100</samp>: global priority items (e.g. Qi Beans);
 +
* <samp>0</samp>: normal items;
 +
* <samp>100</samp>: global fallback items (e.g. clay).
 +
|}
 +
 
 +
For example, a location with this field will drop 2-4 pufferfish with a 50% chance on summer days:
 +
<syntaxhighlight lang="js">
 +
"ArtifactSpots": [
 +
    {
 +
          "Condition": "LOCATION_SEASON Here summer",
 +
          "ItemId": "(O)128",
 +
          "MinStack": 2,
 +
          "MaxStack": 4
 +
    }
 +
]
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
|-
 +
| <samp>FishAreas</samp>
 +
| ''(Optional)'' The distinct [[fishing]] areas within the location. These can be referenced by fish via <samp>FishAreaId</samp>, and determine which fish are collected by [[Crab Pot|crab pots]].
  
−
Breaking it down:
+
This consists of a string → model lookup, where the key is the fish area ID and the value consists of a list of models with these fields:
 
{| class="wikitable"
 
{| class="wikitable"
−
! Index
 
−
! Entry
 
−
! Explanation
 
 
|-
 
|-
−
| 0
+
! field
−
| "372 .9 718 .1 719 .3 723 .3"
+
! effect
−
| Spring forage. Item ID chance. No particular order required.
 
 
|-
 
|-
−
| 1
+
| <samp>Position</samp>
−
| "372 .9 394 .5 718 .1 719 .3 723 .3"
+
| ''(Optional)'' The tile position and size covered by this fishing area, specified as an object with <samp>X</samp>, <samp>Y</samp>, <samp>Width</samp>, and <samp>Height</samp> fields. This area will apply for crab pots placed within it, or when the fishing rod bobber lands within it. Default null (anywhere).
−
| Summer forage. As above.
+
 
 +
Areas with a <samp>Position</samp> value have priority over those without.
 
|-
 
|-
−
| 2
+
| <samp>CrabPotFishTypes</samp>
−
| "372 .9 718 .1 719 .3 723 .3"
+
| ''(Optional)'' A list of fish types that can be caught by crab pots within the area. This is matched against field index 4 in [[Modding:Fish data|<samp>Data/Fish</samp>]] for 'trap' (i.e. crab pot) fish. The vanilla types are <samp>freshwater</samp> and <samp>ocean</samp>. If omitted, defaults to <samp>freshwater</samp>.
−
| Fall forage. As above.
 
 
|-
 
|-
−
| 3
+
| <samp>CrabPotJunkChance</samp>
−
| "372 .4 392 .8 718 .05 719 .2 723 .2"
+
| ''(Optional)'' The chance that crab pots within the area will find junk instead of a fish each time they produce a harvest. This is ignored if the player has the [[Fishing#Fishing Skill|Mariner]] profession. Default <samp>0.2</samp> (20%).
−
| Winter forage. As above.
+
|}
 +
|-
 +
| <samp>Fish</samp>
 +
| ''(Optional)'' The fish that can be caught in the location.
 +
 
 +
A fish is selected by combining this field with the equivalent field on the <samp>Default</samp> entry, sorting by <samp>Precedence</samp> value (and randomly shuffling entries with the same precedence), and then choosing the first entry whose fields match.
 +
 
 +
Note: the produced item ID is saved to recreate the fish later. Any item info that's not based on the item ID is ignored (like stack size, quality, flavored variants like Blueberry Wine vs Wine, and the is-recipe flag).
 +
 
 +
This consists of a list of models with these fields:
 +
{| class="wikitable"
 +
|-
 +
! field
 +
! effect
 
|-
 
|-
−
| 4
+
| ''common fields''
−
| "129 -1 131 -1 147 -1 148 -1 152 -1 708 -1 267 -1"
+
| See [[Modding:Item queries#Item spawn fields|item spawn fields]] for the generic item fields supported by forage items.
−
| Fish data for spring. Fish is ID zoneNumber ID zoneNumber. Some locations have multiple fishing locations. To seperate fish, the zoneNumber is used. It starts at -1, and some locations have 0, or even 1, to indicate the zone. For more information, see [[Modding:Fish_data]]
+
 
 +
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.
 
|-
 
|-
−
| 5
+
| <samp>Chance</samp>
−
| "128 -1 130 -1 146 -1 149 -1 150 -1 152 -1 155 -1 708 -1 701 -1 267 -1"
+
| ''(Optional)'' The probability that the fish will spawn if selected, as a decimal value between 0 (never) and 1 (always). Default 1.
−
| Fish data for summer
 
 
|-
 
|-
−
| 6
+
| <samp>Season</samp>
−
| "129 -1 131 -1 148 -1 150 -1 152 -1 154 -1 155 -1 705 -1 701 -1"
+
| ''(Optional)'' If set, the specific season when the fish can be caught. This is much more efficient than using <samp>Condition</samp>, but only supports a single season. Defaults to <samp>null</samp> (all seasons).
−
| Fish data for autumn
 
 
|-
 
|-
−
| 7
+
| <samp>FishAreaId</samp>
−
| "708 -1 130 -1 131 -1 146 -1 147 -1 150 -1 151 -1 152 -1 154 -1 705 -1"
+
| ''(Optional)'' If set, the fish area in which the fish can be caught (as an area ID defined under <samp>FishAreas</samp>). Defaults to <samp>null</samp> (all zones).
−
| Fish data for winter
 
 
|-
 
|-
−
| 8
+
| <samp>BobberPosition</samp>
−
| "384 .08 589 .09 102 .15 390 .25 330 1"  
+
| ''(Optional)'' If set, the tile area within the location where the fishing rod's bobber must land to catch the fish. Default <samp>null</samp> (anywhere).
−
| Artifact data. (Article data TBA): Artifacts should be added in increasing likelihood, and in format: ID chance ID chance, with chance being addressed in 0 to 1.
+
|-
 +
| <samp>PlayerPosition</samp>
 +
| ''(Optional)'' If set, the tile area within the location where the player must be standing to catch the fish. Default <samp>null</samp> (anywhere).
 +
|-
 +
| <samp>MinFishingLevel</samp>
 +
| ''(Optional)'' The minimum fishing level needed for the fish to appear. Default 0.
 +
|-
 +
| <samp>ApplyDailyLuck</samp>
 +
| ''(Optional)'' Whether to add the player's [[Luck|daily luck]] to the spawn chance. This affects both the <samp>Chance</samp> field and the <samp>Data\Fish</samp> chance, if applicable. Default false.
 +
|-
 +
| <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).
 +
|-
 +
| <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>
 +
| ''(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>
 +
| ''(Optional)'' Whether this is a 'boss fish' catch. This shows a crowned fish sprite in the fishing minigame and gives five times normal XP, like [[Legendary Fish|legendary fish]].
 +
|-
 +
| <samp>RequireMagicBait</samp>
 +
| ''(Optional)'' Whether the player must fish with Magic Bait for this fish to spawn. Default false.
 +
|-
 +
| <samp>MinDistanceFromShore</samp>
 +
| ''(Optional)'' The minimum distance from the nearest shore (measured in tiles) at which the fish can be caught, where zero is water directly adjacent to shore.
 +
|-
 +
| <samp>MaxDistanceFromShore</samp>
 +
| ''(Optional)'' The maximum distance from the nearest shore (measured in tiles) at which the fish can be caught, where zero is water directly adjacent to shore. Default -1 (no limit).
 +
|-
 +
| <samp>Precedence</samp>
 +
| ''(Optional)'' The order in which this entry should be checked, where lower values are checked first. This can be a negative value. Fish with the same precedence are shuffled randomly. Default 0.
 +
 
 +
For consistency, vanilla fish mostly use values in these ranges:
 +
* <samp>-1100</samp> to <samp>-1000</samp>: global priority items (e.g. Qi Beans);
 +
* <samp>-200</samp> to <samp>-100</samp>: unique location items (e.g. legendary fish or secret items);
 +
* <samp>-50</samp> to <samp>-1</samp>: normal high-priority items;
 +
* <samp>0</samp>: normal items;
 +
* <samp>1</samp> to <samp>100</samp>: normal low-priority items;
 +
* <samp>1000+</samp>: global fallback items (e.g. trash).
 +
|-
 +
| <samp>IgnoreFishDataRequirements</samp>
 +
| ''(Optional)'' Whether to ignore spawn requirements listed in [[Modding:Fish data|<samp>Data/Fish</samp>]], if applicable.
 +
 
 +
The <samp>Data/Fish</samp> requirements are ignored regardless of this field for non-object (<samp>(O)</samp>)-type items, or objects whose ID isn't listed in <samp>Data/Fish</samp>.
 +
|-
 +
| <samp>CanBeInherited</samp>
 +
| ''(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>
 +
| ''(Optional)'' The mail flag to set for the current player when this fish is successfully caught. Default none.
 +
|-
 +
| <samp>ChanceModifiers</samp>
 +
| ''(Optional)'' [[Modding:Migrate to Stardew Valley 1.6#Quantity modifiers|Quantity modifiers]] applied to the <samp>Chance</samp> value. Default none.
 +
|-
 +
| <samp>ChanceModifierMode</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>.
 +
|}
 +
|-
 +
| <samp>Forage</samp>
 +
| ''(Optional)'' The [[forage]] that can spawn in the location.
 +
 
 +
Notes:
 +
* Unlike other item spawn lists, these entries aren't checked sequentially. Instead, the game...
 +
*# combines this list with any forage in the <samp>Default</samp> location entry;
 +
*# adds every forage entry whose <samp>Condition</samp> and <samp>Season</samp> match to a spawn pool;
 +
*# chooses a random number of spawn ''opportunities'' (between 1 and 4);
 +
*# for each spawn opportunity, chooses a random tile position and forage to spawn. If the spawn fails (e.g. the tile is water/occupied or the forage's <samp>Chance</samp> doesn't pass), the game will make nine other attempts with a re-randomized tile & forage before skipping this spawn opportunity.
 +
* The stack size is ignored.
 +
 
 +
This consists of a list of models with these fields:
 +
{| class="wikitable"
 +
|-
 +
! field
 +
! effect
 +
|-
 +
| ''common fields''
 +
| 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 [[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>
 +
| ''(Optional)'' The probability that the item will spawn if selected, as a decimal value between 0 (never) and 1 (always). Default 1.
 +
|-
 +
| <samp>Season</samp>
 +
| ''(Optional)'' The specific season when the forage should apply. This is more efficient than using <samp>Condition</samp>, but only supports a single season. Defaults to <samp>null</samp> (all seasons).
 +
|}
 +
|-
 +
| <samp>MinDailyWeeds</samp><br /><samp>MaxDailyWeeds</samp>
 +
| ''(Optional)'' The minimum and maximum number of weeds to spawn in a day, if applicable. Default 1 and 5 respectively.
 +
|-
 +
| <samp>FirstDayWeedMultiplier</samp>
 +
| ''(Optional)'' On the first day of each year, a multiplier to apply to the number of daily weeds spawned. Default 15.
 +
|-
 +
| <samp>MinDailyForageSpawn</samp><br /><samp>MaxDailyForageSpawn</samp>
 +
| ''(Optional)'' The minimum and maximum number of forage to try spawning in one day, if applicable and the location has fewer than <samp>MaxSpawnedForageAtOnce</samp> forage. Default 1 and 4 respectively.
 +
|-
 +
| <samp>MaxSpawnedForageAtOnce</samp>
 +
| ''(Optional)'' The maximum number of spawned forage that can be present at once on the map before they stop spawning. Default 6.
 +
|-
 +
| <samp>ChanceForClay</samp>
 +
| ''(Optional)'' The probability that digging a tile will produce clay, as a value between 0 (never) and 1 (always).
 +
|}
 +
 
 +
===Music===
 +
{| class="wikitable"
 +
|-
 +
! field
 +
! effect
 +
|-
 +
| <samp>Music</samp>
 +
| ''(Optional)'' The music to play when the player enters the location (subject to the other fields like <samp>MusicContext</samp>).
 +
 
 +
The first matching entry is used. If none match, falls back to <samp>MusicDefault</samp>.
 +
 
 +
This consists of a list of models with these fields:
 +
{| class="wikitable"
 +
|-
 +
! field
 +
! effect
 +
|-
 +
| <samp>Id</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>
 +
| ''(Optional)'' A [[Modding:Game state queries|game state query]] which indicates whether this entry applies. Default true.
 +
|}
 +
|-
 +
| <samp>MusicDefault</samp>
 +
| ''(Optional)'' The music to play if none of the options in <samp>Music</samp> matched. If this is null, falls back to the <samp>Music</samp> [[Modding:Maps|map property]] (if set).
 +
|-
 +
| <samp>MusicContext</samp>
 +
| ''(Optional)'' The music context for this location. The recommended values are <samp>Default</samp> or <samp>SubLocation</samp>. Default <samp>Default</samp>.
 +
 
 +
Setting <samp>SubLocation</samp> has two effects:
 +
* <samp>SubLocation</samp> has a lower priority than <samp>Default</samp>. In split-screen mode, that means if player A is at a location with a <samp>Default</samp> music context, and player B is a location with a <samp>SubLocation</samp> context, the game will choose player A's music.
 +
* When the player leaves a location with <samp>SubLocation</samp> music, the music will be stopped unless the new location has the same music and music context set.
 +
|-
 +
| <samp>MusicIgnoredInRain</samp>
 +
| ''(Optional)'' Whether the location music is ignored when it's raining in this location. Default false.
 +
|-
 +
| <samp>MusicIgnoredInSpring</samp><br /><samp>MusicIgnoredInSummer</samp><br /><samp>MusicIgnoredInFall</samp><br /><samp>MusicIgnoredInWinter</samp>
 +
| ''(Optional)'' Whether the location music is ignored in the given season. Default false.
 +
|-
 +
| <samp>MusicIgnoredInFallDebris</samp>
 +
| ''(Optional)'' Whether the location music is ignored in fall during windy weather. Default false.
 +
|-
 +
| <samp>MusicIsTownTheme</samp>
 +
| ''(Optional)'' Whether to use 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 <samp>Music</samp> and <samp>MusicIsTownTheme</samp> values. Default false.
 
|}
 
|}
  
−
Note that not all fields are required: If you have no fish, you can just put -1 for the relevant fields, and if you have no forage, you can just put -1 for the relevant fields.  
+
===Advanced===
 +
{| class="wikitable"
 +
|-
 +
! field
 +
! effect
 +
|-
 +
| <samp>CustomFields</samp>
 +
| ''(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.
 +
|}
 +
 
 +
==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).
  
−
Examples are:
+
'''Note:''' don't make the existence of the location itself conditional, just make it unreachable. Removing the location will permanently delete everything inside it.
  
−
<pre>
+
===Can I rename a location?===
−
  "Farm": "-1/-1/-1/-1/-1/-1/-1/-1/382 .05 770 .1 390 .25 330 1",
+
'''Renaming a location will permanently lose player changes made for the old name if you're not careful.'''
−
</pre>
+
 
 +
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.
  
−
This has no forage or fishing data (handled programmatically) so it's just -1.
+
For example:
 +
<syntaxhighlight lang="js">
 +
"FormerLocationNames": [ "Custom_SomeOldName" ]
 +
</syntaxhighlight>
  
−
In order to have artifacts work, custom locations need to add their data to this file, which can be done with mods such as Content Patcher.
+
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).
  
−
==GameLocation Names==
+
==Location names==
 +
In-game locations like the farm or beach are represented by the [[Modding:Modder Guide/Game Fundamentals#GameLocation et al|<samp>GameLocation</samp> class]] (or a subclass), and are identified by a unique name.
  
−
<samp>[[Modding:Modder_Guide/Game_Fundamentals#GameLocation_et_al|GameLocation]]</samp> objects represent an area that the player can move around in, such as the Farm, Beach, or Saloon. They all have names as strings. Some are represented by subclasses of <samp>GameLocation</samp>. The following table lists several <samp>GameLocation</samp> objects in vanilla Stardew Valley:
+
Here are some of the vanilla locations:
  
 
{| class="wikitable sortable"
 
{| class="wikitable sortable"
 
|-
 
|-
−
! style="position: sticky; top: 0;"|Name
+
! style="position: sticky; top: 0;"| Name
−
! style="position: sticky; top: 0;"|Class
+
! style="position: sticky; top: 0;"| Class
−
! style="position: sticky; top: 0;"|Description
+
! style="position: sticky; top: 0;"| Description
 
|-  
 
|-  
 
| <samp>Farm</samp>
 
| <samp>Farm</samp>
Line 108: Line 428:
 
| <samp>ManorHouse</samp>
 
| <samp>ManorHouse</samp>
 
| <samp>StardewValley.Locations.ManorHouse</samp>
 
| <samp>StardewValley.Locations.ManorHouse</samp>
−
| Mayor [[Lewis]]'s house.
+
| Mayor [[Lewis]]' house.
 
|-
 
|-
 
| <samp>SeedShop</samp>
 
| <samp>SeedShop</samp>
Line 116: Line 436:
 
| <samp>Saloon</samp>
 
| <samp>Saloon</samp>
 
| <samp>StardewValley.GameLocation</samp>
 
| <samp>StardewValley.GameLocation</samp>
−
| [[The Stardrop Saloon]] (and [[Gus]]'s house)
+
| [[The Stardrop Saloon]] (and [[Gus]]' house)
 
|-
 
|-
 
| <samp>Trailer</samp>
 
| <samp>Trailer</samp>
Line 124: Line 444:
 
| <samp>Hospital</samp>
 
| <samp>Hospital</samp>
 
| <samp>StardewValley.GameLocation</samp>
 
| <samp>StardewValley.GameLocation</samp>
−
| [[Harvey's_Clinic|Harvey's clinic.]]
+
| [[Harvey's Clinic|Harvey's clinic.]]
 
|-
 
|-
 
| <samp>HarveyRoom</samp>
 
| <samp>HarveyRoom</samp>
Line 132: Line 452:
 
| <samp>Beach</samp>
 
| <samp>Beach</samp>
 
| <samp>StardewValley.Locations.Beach</samp>
 
| <samp>StardewValley.Locations.Beach</samp>
−
| [[The_Beach|The beach]] south of Pelican Town.
+
| [[The Beach|The beach]] south of Pelican Town.
 
|-
 
|-
 
| <samp>ElliottHouse</samp>
 
| <samp>ElliottHouse</samp>
Line 140: Line 460:
 
| <samp>Mountain</samp>
 
| <samp>Mountain</samp>
 
| <samp>StardewValley.Locations.Mountain</samp>
 
| <samp>StardewValley.Locations.Mountain</samp>
−
| The [[The_Mountain|outdoor mountain area]] where the Carpenter, Linus' tent, and Adventurer's Guild are.
+
| The [[The Mountain|outdoor mountain area]] where the Carpenter, Linus' tent, and Adventurer's Guild are.
 
|-
 
|-
 
| <samp>ScienceHouse</samp>
 
| <samp>ScienceHouse</samp>
 
| <samp>StardewValley.GameLocation</samp>
 
| <samp>StardewValley.GameLocation</samp>
−
|
+
| The [[Carpenter's Shop]].
 
|-
 
|-
 
| <samp>SebastianRoom</samp>
 
| <samp>SebastianRoom</samp>
Line 152: Line 472:
 
| <samp>Tent</samp>
 
| <samp>Tent</samp>
 
| <samp>StardewValley.GameLocation</samp>
 
| <samp>StardewValley.GameLocation</samp>
−
| [[Linus]]' tent.
+
| [[Linus]]' [[tent]].
 
|-
 
|-
 
| <samp>Forest</samp>
 
| <samp>Forest</samp>
 
| <samp>StardewValley.Locations.Forest</samp>
 
| <samp>StardewValley.Locations.Forest</samp>
−
| Cindersap [[Cindersap_Forest|forest]] south of the farm.
+
| Cindersap [[Cindersap Forest|forest]] south of the farm.
 
|-
 
|-
 
| <samp>WizardHouse</samp>
 
| <samp>WizardHouse</samp>
 
| <samp>StardewValley.Locations.WizardHouse</samp>
 
| <samp>StardewValley.Locations.WizardHouse</samp>
−
| The [[Wizard|wizard/Rasmodius]]'s [[Wizard's_Tower|tower]]
+
| The [[Wizard|wizard/Rasmodius]]'s [[Wizard's Tower|tower]]
 
|-
 
|-
 
| <samp>AnimalShop</samp>
 
| <samp>AnimalShop</samp>
 
| <samp>StardewValley.GameLocation</samp>
 
| <samp>StardewValley.GameLocation</samp>
−
|
+
| [[Marnie's Ranch]]
 
|-
 
|-
 
| <samp>LeahHouse</samp>
 
| <samp>LeahHouse</samp>
 
| <samp>StardewValley.GameLocation</samp>
 
| <samp>StardewValley.GameLocation</samp>
−
| [[Leah]]'s cabin.
+
| [[Leah's Cottage]].
 
|-
 
|-
 
| <samp>BusStop</samp>
 
| <samp>BusStop</samp>
 
| <samp>StardewValley.Locations.BusStop</samp>
 
| <samp>StardewValley.Locations.BusStop</samp>
−
| The bus stop area between the farm and Pelican Town.
+
| The [[Bus Stop|bus stop]] area between the farm and Pelican Town.
 
|-
 
|-
 
| <samp>Mine</samp>
 
| <samp>Mine</samp>
 
| <samp>StardewValley.Locations.Mine</samp>
 
| <samp>StardewValley.Locations.Mine</samp>
−
| The first room of [[The_Mines|the mines]], where the [[dwarf]]'s shop is.
+
| The first room of [[The Mines|the mines]], where the [[dwarf]]'s shop is.
 
|-
 
|-
 
| <samp>Sewer</samp>
 
| <samp>Sewer</samp>
 
| <samp>StardewValley.Locations.Sewer</samp>
 
| <samp>StardewValley.Locations.Sewer</samp>
−
| The [[sewers]] where [[Krobus]]'s shop is.
+
| The [[The Sewers|sewers]] where [[Krobus]]' shop is.
 
|-
 
|-
 
| <samp>BugLand</samp>
 
| <samp>BugLand</samp>
 
| <samp>StardewValley.Locations.BugLand</samp>
 
| <samp>StardewValley.Locations.BugLand</samp>
−
| The [[Mutant_Bug_Lair|mutant bug lair]] in the sewers.
+
| The [[Mutant Bug Lair|mutant bug lair]] in the sewers.
 
|-
 
|-
 
| <samp>Desert</samp>
 
| <samp>Desert</samp>
 
| <samp>StardewValley.Locations.Desert</samp>
 
| <samp>StardewValley.Locations.Desert</samp>
−
| [[Desert|Calico Desert]] where [[Sandy]]'s [[Oasis]] shop and the [[Skull_Cavern|skull cavern]] are.
+
| [[The Desert|Calico Desert]] where [[Sandy]]'s [[Oasis]] shop and the [[Skull Cavern|skull cavern]] are.
 
|-
 
|-
 
| <samp>Club</samp>
 
| <samp>Club</samp>
Line 204: Line 524:
 
| <samp>WizardHouseBasement</samp>
 
| <samp>WizardHouseBasement</samp>
 
| <samp>StardewValley.GameLocation</samp>
 
| <samp>StardewValley.GameLocation</samp>
−
|
+
| The basement of the [[Wizard's Tower]]
 
|-
 
|-
 
| <samp>AdventureGuild</samp>
 
| <samp>AdventureGuild</samp>
 
| <samp>StardewValley.Locations.AdventureGuild</samp>
 
| <samp>StardewValley.Locations.AdventureGuild</samp>
−
| The [[Adventurer's_Guild|Adventurer's Guild]], home of [[Marlon]] and [[Gil]].
+
| The [[Adventurer's Guild]], home of [[Marlon]] and [[Gil]].
 
|-
 
|-
 
| <samp>Woods</samp>
 
| <samp>Woods</samp>
 
| <samp>StardewValley.Locations.Woods</samp>
 
| <samp>StardewValley.Locations.Woods</samp>
−
| The [[Secret_Woods|secret woods]] in Cindersap forest blocked by a large log.
+
| The [[Secret Woods|secret woods]] in Cindersap forest blocked by a large log.
 
|-
 
|-
 
| <samp>Railroad</samp>
 
| <samp>Railroad</samp>
Line 220: Line 540:
 
| <samp>WitchSwamp</samp>
 
| <samp>WitchSwamp</samp>
 
| <samp>StardewValley.GameLocation</samp>
 
| <samp>StardewValley.GameLocation</samp>
−
| The [[Witch's_Swamp|swamp]] area where the Witch's Hut is.
+
| The [[Witch's Swamp|swamp]] area where the Witch's Hut is.
 
|-
 
|-
 
| <samp>WitchHut</samp>
 
| <samp>WitchHut</samp>
 
| <samp>StardewValley.GameLocation</samp>
 
| <samp>StardewValley.GameLocation</samp>
−
| The interior of the [[Witch's_Hut|Witch's Hut]].
+
| The interior of the [[Witch's Hut]].
 
|-
 
|-
 
| <samp>WitchWarpCave</samp>
 
| <samp>WitchWarpCave</samp>
 
| <samp>StardewValley.GameLocation</samp>
 
| <samp>StardewValley.GameLocation</samp>
−
| The cave accessible behind the railroad, which warps to the Witch's swamp.
+
| The cave accessible at the top right of the railroad, which warps to the Witch's swamp.
 
|-
 
|-
 
| <samp>Summit</samp>
 
| <samp>Summit</samp>
 
| <samp>StardewValley.Locations.Summit</samp>
 
| <samp>StardewValley.Locations.Summit</samp>
−
| The [[The_Summit|summit]] north of the railroad.
+
| The [[The Summit|summit]] north of the railroad.
 
|-
 
|-
 
| <samp>FishShop</samp>
 
| <samp>FishShop</samp>
 
| <samp>StardewValley.Locations.FishShop</samp>
 
| <samp>StardewValley.Locations.FishShop</samp>
−
| [[Willy]]'s [[Fish_Shop|shop]].
+
| [[Willy]]'s [[Fish Shop|shop]].
 
|-
 
|-
 
| <samp>BathHouse_Entry</samp>
 
| <samp>BathHouse_Entry</samp>
 
| <samp>StardewValley.GameLocation</samp>
 
| <samp>StardewValley.GameLocation</samp>
−
| The entrance room in the [[spa]], leading to the men and women's locker room.
+
| The entrance room in the [[spa]], leading to the men's and women's locker rooms.
 
|-
 
|-
 
| <samp>BathHouse_MensLocker</samp>
 
| <samp>BathHouse_MensLocker</samp>
Line 256: Line 576:
 
| <samp>CommunityCenter</samp>
 
| <samp>CommunityCenter</samp>
 
| <samp>StardewValley.Locations.CommunityCenter</samp>
 
| <samp>StardewValley.Locations.CommunityCenter</samp>
−
| The inside of the [[Community_Center|Community Center]].
+
| The inside of the [[Community Center]].
 
|-
 
|-
 
| <samp>JojaMart</samp>
 
| <samp>JojaMart</samp>
 
| <samp>StardewValley.Locations.JojaMart</samp>
 
| <samp>StardewValley.Locations.JojaMart</samp>
−
| The inside of Pelican Town's [[JojaMart|Joja Mart]].
+
| The inside of Pelican Town's [[JojaMart]].
 
|-
 
|-
 
| <samp>Greenhouse</samp>
 
| <samp>Greenhouse</samp>
Line 276: Line 596:
 
| <samp>Tunnel</samp>
 
| <samp>Tunnel</samp>
 
| <samp>StardewValley.GameLocation</samp>
 
| <samp>StardewValley.GameLocation</samp>
−
| The dark [[The_Tunnel|bus tunnel]] to the west of the bus stop.
+
| The dark [[The Tunnel|bus tunnel]] to the west of the bus stop.
 
|-
 
|-
 
| <samp>Trailer_Big</samp>
 
| <samp>Trailer_Big</samp>
 
| <samp>StardewValley.GameLocation</samp>
 
| <samp>StardewValley.GameLocation</samp>
−
| The inside of Pam/Penny's house after the [[Trailer#Community_Upgrade|Community Upgrade]].
+
| The inside of Pam/Penny's house after the [[Trailer#Community Upgrade|Community Upgrade]].
 
|-
 
|-
 
| <samp>Cellar</samp>
 
| <samp>Cellar</samp>
Line 300: Line 620:
 
| <samp>BeachNightMarket</samp>
 
| <samp>BeachNightMarket</samp>
 
| <samp>StardewValley.Locations.BeachNightMarket</samp>
 
| <samp>StardewValley.Locations.BeachNightMarket</samp>
−
| The beach south of Pelican Town during the [[Night_Market|Night Market]].
+
| The beach south of Pelican Town during the [[Night Market]].
 
|-
 
|-
 
| <samp>MermaidHouse</samp>
 
| <samp>MermaidHouse</samp>
 
| <samp>StardewValley.Locations.MermaidHouse</samp>
 
| <samp>StardewValley.Locations.MermaidHouse</samp>
−
|
+
| The interior of the [[Night Market#Mermaid Boat|mermaid boat]] at the [[Night Market]].
 
|-
 
|-
 
| <samp>Submarine</samp>
 
| <samp>Submarine</samp>
 
| <samp>StardewValley.Locations.Submarine</samp>
 
| <samp>StardewValley.Locations.Submarine</samp>
−
| The interior of the [[Night_Market#Fishing_Submarine|fishing submarine]] during the Night Market.
+
| The interior of the [[Night Market#Fishing Submarine|fishing submarine]] during the Night Market.
 
|-
 
|-
 
| <samp>AbandonedJojaMart</samp>
 
| <samp>AbandonedJojaMart</samp>
 
| <samp>StardewValley.Locations.AbandonedJojaMart</samp>
 
| <samp>StardewValley.Locations.AbandonedJojaMart</samp>
−
| The small interior of the [[Bundles#Abandoned_JojaMart|abandoned JojaMart]] where the Missing Bundle is.
+
| The small interior of the [[Bundles#Abandoned JojaMart|abandoned JojaMart]] where the Missing Bundle is.
 
|-
 
|-
 
| <samp>MovieTheater</samp>
 
| <samp>MovieTheater</samp>
 
| <samp>StardewValley.Locations.MovieTheater</samp>
 
| <samp>StardewValley.Locations.MovieTheater</samp>
−
| The interior of the [[Movie_Theater|Movie Theater]] that replaces JojaMart.
+
| The interior of the [[Movie Theater]] that replaces JojaMart.
 
|-
 
|-
 
| <samp>Sunroom</samp>
 
| <samp>Sunroom</samp>
Line 324: Line 644:
 
| <samp>BoatTunnel</samp>
 
| <samp>BoatTunnel</samp>
 
| <samp>StardewValley.Locations.BoatTunnel</samp>
 
| <samp>StardewValley.Locations.BoatTunnel</samp>
−
| Where [[Fish_Shop#Willy.27s_Boat|Willy's Boat]] is, in back of the fish shop.
+
| Where [[Fish Shop#Willy's Boat|Willy's Boat]] is, in back of the fish shop.
 
|-
 
|-
 
| <samp>IslandSouth</samp>
 
| <samp>IslandSouth</samp>
 
| <samp>StardewValley.Locations.IslandSouth</samp>
 
| <samp>StardewValley.Locations.IslandSouth</samp>
−
| Ginger Island, [[Ginger_Island#Island_South|where the player first lands]] and where the beach resort is.
+
| Ginger Island, [[Ginger Island#Island South|the docks]] where the player first lands and where the beach resort is.
 
|-
 
|-
 
| <samp>IslandSouthEast</samp>
 
| <samp>IslandSouthEast</samp>
 
| <samp>StardewValley.Locations.IslandSouthEast</samp>
 
| <samp>StardewValley.Locations.IslandSouthEast</samp>
−
| Ginger Island, [[Ginger_Island#Island_Southeast|where the mermaid and pirate cove are]].
+
| Ginger Island, [[Ginger Island#Island Southeast|where the mermaid and pirate cove are]].
 
|-
 
|-
 
| <samp>IslandSouthEastCave</samp>
 
| <samp>IslandSouthEastCave</samp>
 
| <samp>StardewValley.Locations.IslandSouthEastCave</samp>
 
| <samp>StardewValley.Locations.IslandSouthEastCave</samp>
−
| The [[Ginger_Island#Pirate_Cove|pirate cove]].
+
| The [[Ginger Island#Pirate Cove|pirate cove]].
 
|-
 
|-
 
| <samp>IslandEast</samp>
 
| <samp>IslandEast</samp>
 
| <samp>StardewValley.Locations.IslandEast</samp>
 
| <samp>StardewValley.Locations.IslandEast</samp>
−
| [[Ginger_Island#Island_East|Ginger Island jungle]], where [[Leo]]'s hut is.
+
| [[Ginger Island#Island East|Ginger Island jungle]], where [[Leo]]'s hut is.
 
|-
 
|-
 
| <samp>IslandWest</samp>
 
| <samp>IslandWest</samp>
 
| <samp>StardewValley.Locations.IslandWest</samp>
 
| <samp>StardewValley.Locations.IslandWest</samp>
−
| Ginger Island, [[Ginger_Island#Island_West|where the farm and Birdie's Shack are]].
+
| Ginger Island, [[Ginger Island#Island West|Island West]], where the farm and Birdie's Shack are.
 
|-
 
|-
 
| <samp>IslandNorth</samp>
 
| <samp>IslandNorth</samp>
 
| <samp>StardewValley.Locations.IslandNorth</samp>
 
| <samp>StardewValley.Locations.IslandNorth</samp>
−
| Ginger Island, [[Ginger_Island#Island_North|where the volcano and Professor Snail's tent are]].
+
| Ginger Island, [[Ginger Island#Island North|Island North]], where the volcano and Professor Snail's tent are.
 
|-
 
|-
 
| <samp>IslandHut</samp>
 
| <samp>IslandHut</samp>
 
| <samp>StardewValley.Locations.IslandHut</samp>
 
| <samp>StardewValley.Locations.IslandHut</samp>
−
|  
+
| The interior of [[Leo]]'s hut on [[Ginger Island]].
 
|-
 
|-
 
| <samp>IslandWestCave1</samp>
 
| <samp>IslandWestCave1</samp>
 
| <samp>StardewValley.Locations.IslandWestCave1</samp>
 
| <samp>StardewValley.Locations.IslandWestCave1</samp>
−
|
+
| The Ginger Island cave where the [[Ginger Island#Colored Crystals Puzzle|colored crystals puzzle]] can be found.
 
|-
 
|-
 
| <samp>IslandNorthCave1</samp>
 
| <samp>IslandNorthCave1</samp>
 
| <samp>StardewValley.Locations.IslandLocation</samp>
 
| <samp>StardewValley.Locations.IslandLocation</samp>
−
|
+
| The [[Ginger Island#Dig Site|mushroom cave]] on Ginger Island where Professor Snail is initially blocked in by a boulder.
 
|-
 
|-
 
| <samp>IslandFieldOffice</samp>
 
| <samp>IslandFieldOffice</samp>
 
| <samp>StardewValley.Locations.IslandFieldOffice</samp>
 
| <samp>StardewValley.Locations.IslandFieldOffice</samp>
−
| The interior of Professor Snail's Island Field Office tent.
+
| The interior of Professor Snail's [[Island Field Office]] tent.
 
|-
 
|-
 
| <samp>IslandFarmHouse</samp>
 
| <samp>IslandFarmHouse</samp>
 
| <samp>StardewValley.Locations.IslandFarmHouse</samp>
 
| <samp>StardewValley.Locations.IslandFarmHouse</samp>
−
| The interior of the farm house on Ginger Island.
+
| The interior of the [[Island Farmhouse|farm house]] on Ginger Island.
 
|-
 
|-
 
| <samp>CaptainRoom</samp>
 
| <samp>CaptainRoom</samp>
 
| <samp>StardewValley.Locations.IslandLocation</samp>
 
| <samp>StardewValley.Locations.IslandLocation</samp>
−
|  
+
| The interior of the [[Ginger Island#Shipwreck|shipwreck]] on Ginger Island West.
 
|-
 
|-
 
| <samp>IslandShrine</samp>
 
| <samp>IslandShrine</samp>
 
| <samp>StardewValley.Locations.IslandShrine</samp>
 
| <samp>StardewValley.Locations.IslandShrine</samp>
−
|
+
| The [[Ginger Island#Gem Birds|area East of the jungle]] on Ginger Island.
 
|-
 
|-
 
| <samp>IslandFarmCave</samp>
 
| <samp>IslandFarmCave</samp>
 
| <samp>StardewValley.Locations.IslandFarmCave</samp>
 
| <samp>StardewValley.Locations.IslandFarmCave</samp>
−
|
+
| The interior of [[Ginger Island#Gourmand Frog|Gourmand Frog's cave]] on Ginger Island.
 
|-
 
|-
 
| <samp>Caldera</samp>
 
| <samp>Caldera</samp>
Line 388: Line 708:
 
| <samp>LeoTreeHouse</samp>
 
| <samp>LeoTreeHouse</samp>
 
| <samp>StardewValley.GameLocation</samp>
 
| <samp>StardewValley.GameLocation</samp>
−
| Leo's tree house home.
+
| Leo's [[Treehouse|tree house]] home.
 
|-
 
|-
 
| <samp>QiNutRoom</samp>
 
| <samp>QiNutRoom</samp>
 
| <samp>StardewValley.Locations.IslandLocation</samp>
 
| <samp>StardewValley.Locations.IslandLocation</samp>
−
| [[Qi's_Walnut_Room|Mr. Qi's Walnut Room]]
+
| [[Qi's Walnut Room|Mr. Qi's Walnut Room]]
 +
|-
 
|}
 
|}
  
−
 
+
[[Category:Modding]]
−
 
 
  
 
[[ru:Модификации:Местоположение]]
 
[[ru:Модификации:Местоположение]]
−
[[Category:Modding]]
 

Latest revision as of 15:25, 19 April 2024

← Modding:Index

This page explains how to create and edit in-game locations.

Terminology

A few terms may be used interchangeably or have different meanings depending on the context. In the context of Stardew Valley:

  • A location is part of the game code and save data. It manages the in-game area and everything inside it (including non-map entities like players). The location is read/written to the save file, and is only loaded when loading the save file.
  • A map is an asset which describes the tile layout, tilesheets, and map/tile properties for the in-game area. The map is reloaded each time you load a save, and each time a mod changes the map.
  • A world map is the image shown for a world region in the in-game menu.

In other words, a location (part of the game code) references the map (loaded from the Content folder): 

┌─────────────────────────────────┐
│ Location                        │
│   - objects                     │
│   - furniture                   │
│   - crops                       │
│   - bushes and trees            │
│   - NPCs and players            │
│   - etc                         │
│                                 │
│   ┌─────────────────────────┐   │
│   │ Map asset               │   │
│   │   - tile layout         │   │
│   │   - map/tile properties │   │
│   │   - tilesheets          │   │
│   └─────────────────────────┘   │
└─────────────────────────────────┘

Data format

You can add or edit locations by editing the Data/Locations asset.

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

  • The key is the unique string ID of the location (i.e. "internal name"), which will also be used as the location's Name (not DisplayName) field. (The farm will use Farm_<type key> for a vanilla farm type, or Farm_<type ID> for a custom farm type, or Farm_Standard if no type-specific entry was found.)
  • The value is a model with the fields listed below.

Basic info

field effect
DisplayName (Optional but strongly recommended) A tokenizable string for the translated location name. This is used anytime the location name is shown in-game for base game logic or mods.
DefaultArrivalTile (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).
CreateOnLoad (Optional) If set, the location will be created automatically when the save is loaded using this data.

This consists of a model with these fields:

field effect
MapPath The asset name for the map to use for this location.
AlwaysActive (Optional) Whether this location is always synchronized to farmhands in multiplayer, even if they're not in the location. Any location which allows building cabins must have this enabled to avoid breaking game logic.
Type (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 StardewValley.GameLocation (default value) and StardewValley.Locations.DecoratableLocation.
CanPlantHere (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.
ExcludeFromNpcPathfinding (Optional) Whether NPCs should ignore this location when pathfinding between locations. Default false.

Contents

field effect
ArtifactSpots (Optional) The items that can be found when digging artifact spots in this location.

An artifact spot is selected by combining this field with the equivalent field on the Default entry, sorting by Precedence value, and then choosing the first entry whose fields match. (Artifact spot drops can also be listed in Data/Objects's Miscellaneous field; those are applied by the RANDOM_ARTIFACT_FOR_DIG_SPOT entry in DefaultArtifactSpots.)

This consists of a list of models with these fields:

field effect
common fields See item spawn fields for the generic item fields supported by artifact spot drops.

If set to an item query which returns multiple items, one of them will be selected at random.

Chance (Optional) The probability that the item will be dropped if the other fields match, as a decimal value between 0 (never) and 1 (always). Default 1.
ApplyGenerousEnchantment (Optional) Whether to apply the 'Generous' enchantment, which adds a 50% chance of the item dropping twice. If the enchantment is applied, the item's fields are rerolled for the second drop (e.g. a new random value between MinStack and MaxStack is selected). Default true.
OneDebrisPerDrop (Optional) Whether to split the dropped item stack into multiple floating debris that each have a stack size of one. For example, if the dropped item has a stack size of 3, this will spawn three separate item stacks. Default true.
ContinueOnDrop (Optional) Whether to continue checking for more items to drop when this item is dropped. Default false.
Precedence (Optional) The order in which this entry should be checked, where lower values are checked first. This can be a negative value. Artifact spots with the same precedence are checked in the order listed. Default 0.

For consistency, vanilla artifact drops mostly use these values:

  • -1000: location items which should override the global priority items (e.g. fossils on Ginger Island);
  • -100: global priority items (e.g. Qi Beans);
  • 0: normal items;
  • 100: global fallback items (e.g. clay).

For example, a location with this field will drop 2-4 pufferfish with a 50% chance on summer days: 

"ArtifactSpots": [
     {
          "Condition": "LOCATION_SEASON Here summer",
          "ItemId": "(O)128",
          "MinStack": 2,
          "MaxStack": 4
     }
]
FishAreas (Optional) The distinct fishing areas within the location. These can be referenced by fish via FishAreaId, and determine which fish are collected by crab pots.

This consists of a string → model lookup, where the key is the fish area ID and the value consists of a list of models with these fields:

field effect
Position (Optional) The tile position and size covered by this fishing area, specified as an object with X, Y, Width, and Height fields. This area will apply for crab pots placed within it, or when the fishing rod bobber lands within it. Default null (anywhere).

Areas with a Position value have priority over those without.

CrabPotFishTypes (Optional) A list of fish types that can be caught by crab pots within the area. This is matched against field index 4 in Data/Fish for 'trap' (i.e. crab pot) fish. The vanilla types are freshwater and ocean. If omitted, defaults to freshwater.
CrabPotJunkChance (Optional) The chance that crab pots within the area will find junk instead of a fish each time they produce a harvest. This is ignored if the player has the Mariner profession. Default 0.2 (20%).
Fish (Optional) The fish that can be caught in the location.

A fish is selected by combining this field with the equivalent field on the Default entry, sorting by Precedence value (and randomly shuffling entries with the same precedence), and then choosing the first entry whose fields match.

Note: the produced item ID is saved to recreate the fish later. Any item info that's not based on the item ID is ignored (like stack size, quality, flavored variants like Blueberry Wine vs Wine, and the is-recipe flag).

This consists of a list of models with these fields:

field effect
common fields See item spawn fields for the generic item fields supported by forage items.

This must return an Object item (or subclass of Object). If set to an item query which returns multiple items, one of them will be selected at random.

Chance (Optional) The probability that the fish will spawn if selected, as a decimal value between 0 (never) and 1 (always). Default 1.
Season (Optional) If set, the specific season when the fish can be caught. This is much more efficient than using Condition, but only supports a single season. Defaults to null (all seasons).
FishAreaId (Optional) If set, the fish area in which the fish can be caught (as an area ID defined under FishAreas). Defaults to null (all zones).
BobberPosition (Optional) If set, the tile area within the location where the fishing rod's bobber must land to catch the fish. Default null (anywhere).
PlayerPosition (Optional) If set, the tile area within the location where the player must be standing to catch the fish. Default null (anywhere).
MinFishingLevel (Optional) The minimum fishing level needed for the fish to appear. Default 0.
ApplyDailyLuck (Optional) Whether to add the player's daily luck to the spawn chance. This affects both the Chance field and the Data\Fish chance, if applicable. Default false.
CuriosityLureBuff (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 Chance field and the Data\Fish chance, if applicable. Default -1, which keeps the default behavior (i.e. no effect on the Chance field and a scaled boost to the Data\Fish chance).
SpecificBaitBuff (Optional) A flat increase to the spawn chance when the player has a specific bait equipped which targets this fish. Default 0.
SpecificBaitMultiplier (Optional) A multiplier applied to the spawn chance when the player has a specific bait equipped which targets this fish. Default 1.66.
CatchLimit (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).
CanUseTrainingRod (Optional) Whether the player can catch this fish using a training rod. This can be true (always allowed), false (never allowed), or null (apply default logic, i.e. allowed for difficulty ratings under 50). Default null.
IsBossFish (Optional) Whether this is a 'boss fish' catch. This shows a crowned fish sprite in the fishing minigame and gives five times normal XP, like legendary fish.
RequireMagicBait (Optional) Whether the player must fish with Magic Bait for this fish to spawn. Default false.
MinDistanceFromShore (Optional) The minimum distance from the nearest shore (measured in tiles) at which the fish can be caught, where zero is water directly adjacent to shore.
MaxDistanceFromShore (Optional) The maximum distance from the nearest shore (measured in tiles) at which the fish can be caught, where zero is water directly adjacent to shore. Default -1 (no limit).
Precedence (Optional) The order in which this entry should be checked, where lower values are checked first. This can be a negative value. Fish with the same precedence are shuffled randomly. Default 0.

For consistency, vanilla fish mostly use values in these ranges:

  • -1100 to -1000: global priority items (e.g. Qi Beans);
  • -200 to -100: unique location items (e.g. legendary fish or secret items);
  • -50 to -1: normal high-priority items;
  • 0: normal items;
  • 1 to 100: normal low-priority items;
  • 1000+: global fallback items (e.g. trash).
IgnoreFishDataRequirements (Optional) Whether to ignore spawn requirements listed in Data/Fish, if applicable.

The Data/Fish requirements are ignored regardless of this field for non-object ((O))-type items, or objects whose ID isn't listed in Data/Fish.

CanBeInherited (Optional) Whether this fish can be spawned in another location via the LOCATION_FISH item query. Default true.
SetFlagOnCatch (Optional) The mail flag to set for the current player when this fish is successfully caught. Default none.
ChanceModifiers (Optional) Quantity modifiers applied to the Chance value. Default none.
ChanceModifierMode (Optional) quantity modifier modes which indicate what to do if multiple modifiers in the ChanceModifiers field apply at the same time. Default Stack.
Forage (Optional) The forage that can spawn in the location.

Notes:

  • Unlike other item spawn lists, these entries aren't checked sequentially. Instead, the game...
    1. combines this list with any forage in the Default location entry;
    2. adds every forage entry whose Condition and Season match to a spawn pool;
    3. chooses a random number of spawn opportunities (between 1 and 4);
    4. for each spawn opportunity, chooses a random tile position and forage to spawn. If the spawn fails (e.g. the tile is water/occupied or the forage's Chance doesn't pass), the game will make nine other attempts with a re-randomized tile & forage before skipping this spawn opportunity.
  • The stack size is ignored.

This consists of a list of models with these fields:

field effect
common fields See item spawn fields for the generic item fields supported by forage items.

This must return an Object ((O))-type item. If it uses an item query that returns multiple items, one will be selected at random. If it returns null or a non-Object item, the spawn attempt will be skipped (with a logged warning if the item type is invalid).

Chance (Optional) The probability that the item will spawn if selected, as a decimal value between 0 (never) and 1 (always). Default 1.
Season (Optional) The specific season when the forage should apply. This is more efficient than using Condition, but only supports a single season. Defaults to null (all seasons).
MinDailyWeeds
MaxDailyWeeds 		(Optional) The minimum and maximum number of weeds to spawn in a day, if applicable. Default 1 and 5 respectively.
FirstDayWeedMultiplier (Optional) On the first day of each year, a multiplier to apply to the number of daily weeds spawned. Default 15.
MinDailyForageSpawn
MaxDailyForageSpawn 		(Optional) The minimum and maximum number of forage to try spawning in one day, if applicable and the location has fewer than MaxSpawnedForageAtOnce forage. Default 1 and 4 respectively.
MaxSpawnedForageAtOnce (Optional) The maximum number of spawned forage that can be present at once on the map before they stop spawning. Default 6.
ChanceForClay (Optional) The probability that digging a tile will produce clay, as a value between 0 (never) and 1 (always).

Music

field effect
Music (Optional) The music to play when the player enters the location (subject to the other fields like MusicContext).

The first matching entry is used. If none match, falls back to MusicDefault.

This consists of a list of models with these fields:

field effect
Id (Optional) A unique string ID which identifies this entry within the list. Defaults to the Track value.
Track The audio track ID to play.
Condition (Optional) A game state query which indicates whether this entry applies. Default true.
MusicDefault (Optional) The music to play if none of the options in Music matched. If this is null, falls back to the Music map property (if set).
MusicContext (Optional) The music context for this location. The recommended values are Default or SubLocation. Default Default.

Setting SubLocation has two effects:

  • SubLocation has a lower priority than Default. In split-screen mode, that means if player A is at a location with a Default music context, and player B is a location with a SubLocation context, the game will choose player A's music.
  • When the player leaves a location with SubLocation music, the music will be stopped unless the new location has the same music and music context set.
MusicIgnoredInRain (Optional) Whether the location music is ignored when it's raining in this location. Default false.
MusicIgnoredInSpring
MusicIgnoredInSummer
MusicIgnoredInFall
MusicIgnoredInWinter 		(Optional) Whether the location music is ignored in the given season. Default false.
MusicIgnoredInFallDebris (Optional) Whether the location music is ignored in fall during windy weather. Default false.
MusicIsTownTheme (Optional) Whether to use 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 values. Default false.

Advanced

field effect
CustomFields (Optional) The custom fields for this entry.
FormerLocationNames (Optional) The former location names which may appear in save data. See Can I rename a location? in the FAQs for more info.

Default entry

The Data/Locations asset has a location with the key Default. The ArtifactSpots, Fish, and Forage 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 Data/Locations 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 EditMap in a Content Patcher content pack.

For a quick test, you can run the debug warp <location name> 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 EditMap in a 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 FormerLocationNames field in Data/Locations. If a location in save data has a name which (a) matches one of the FormerLocationNames and (b) doesn't match the name of a loaded location, its data will be loaded into the location which specified the FormerLocationNames field instead.

For example: 

"FormerLocationNames": [ "Custom_SomeOldName" ]

Legacy names can have any format, but they must be globally unique. They can't match the Name or FormerLocationNames of any other location in Data/Locations (whether vanilla or custom).

Location names

In-game locations like the farm or beach are represented by the GameLocation class (or a subclass), and are identified by a unique name.

Here are some of the vanilla locations:

Name Class Description
Farm StardewValley.Farm The outdoor area of the Pelican Town farm.
FarmHouse StardewValley.Locations.FarmHouse The interior of the farm house.
FarmCave StardewValley.Locations.FarmCave The bats/mushroom cave on the farm.
Town StardewValley.Locations.Town The outdoor area of Pelican Town.
JoshHouse StardewValley.GameLocation Alex/George/Evelyn's house. (Josh was the old name for the Alex character.)
HaleyHouse StardewValley.GameLocation Haley/Emily's house.
SamHouse StardewValley.GameLocation Sam/Jodi/Kent/Vincent's house.
Blacksmith StardewValley.GameLocation Clint's blacksmith shop.
ManorHouse StardewValley.Locations.ManorHouse Mayor Lewis' house.
SeedShop StardewValley.Locations.SeedShop Pierre's general store (also Caroline/Abigail's house and church)
Saloon StardewValley.GameLocation The Stardrop Saloon (and Gus' house)
Trailer StardewValley.GameLocation Pam/Penny's trailer.
Hospital StardewValley.GameLocation Harvey's clinic.
HarveyRoom StardewValley.GameLocation Harvey's room upstairs from the clinic.
Beach StardewValley.Locations.Beach The beach south of Pelican Town.
ElliottHouse StardewValley.GameLocation Elliott's cabin on the beach.
Mountain StardewValley.Locations.Mountain The outdoor mountain area where the Carpenter, Linus' tent, and Adventurer's Guild are.
ScienceHouse StardewValley.GameLocation The Carpenter's Shop.
SebastianRoom StardewValley.GameLocation Sebastian's room in the basement of the carpenter house.
Tent StardewValley.GameLocation Linus' tent.
Forest StardewValley.Locations.Forest Cindersap forest south of the farm.
WizardHouse StardewValley.Locations.WizardHouse The wizard/Rasmodius's tower
AnimalShop StardewValley.GameLocation Marnie's Ranch
LeahHouse StardewValley.GameLocation Leah's Cottage.
BusStop StardewValley.Locations.BusStop The bus stop area between the farm and Pelican Town.
Mine StardewValley.Locations.Mine The first room of the mines, where the dwarf's shop is.
Sewer StardewValley.Locations.Sewer The sewers where Krobus' shop is.
BugLand StardewValley.Locations.BugLand The mutant bug lair in the sewers.
Desert StardewValley.Locations.Desert Calico Desert where Sandy's Oasis shop and the skull cavern are.
Club StardewValley.Locations.Club Mr. Qi's casino in Sandy's Oasis shop.
SandyHouse StardewValley.GameLocation The Oasis, Sandy's shop in Calico Desert.
ArchaeologyHouse StardewValley.Locations.LibraryMuseum The Museum in Pelican Town, south of the Blacksmith.
WizardHouseBasement StardewValley.GameLocation The basement of the Wizard's Tower
AdventureGuild StardewValley.Locations.AdventureGuild The Adventurer's Guild, home of Marlon and Gil.
Woods StardewValley.Locations.Woods The secret woods in Cindersap forest blocked by a large log.
Railroad StardewValley.Locations.Railroad The railroad north of the mountains, where the spa is located.
WitchSwamp StardewValley.GameLocation The swamp area where the Witch's Hut is.
WitchHut StardewValley.GameLocation The interior of the Witch's Hut.
WitchWarpCave StardewValley.GameLocation The cave accessible at the top right of the railroad, which warps to the Witch's swamp.
Summit StardewValley.Locations.Summit The summit north of the railroad.
FishShop StardewValley.Locations.FishShop Willy's shop.
BathHouse_Entry StardewValley.GameLocation The entrance room in the spa, leading to the men's and women's locker rooms.
BathHouse_MensLocker StardewValley.GameLocation The men's locker room in the spa.
BathHouse_WomensLocker StardewValley.GameLocation The women's locker room in the spa.
BathHouse_Pool StardewValley.Locations.BathHousePool The bathhouse pool in the spa.
CommunityCenter StardewValley.Locations.CommunityCenter The inside of the Community Center.
JojaMart StardewValley.Locations.JojaMart The inside of Pelican Town's JojaMart.
Greenhouse StardewValley.GameLocation The Greenhouse on the player's farm.
SkullCave StardewValley.GameLocation The entrance of the Skull Cavern in Calico desert.
Backwoods StardewValley.GameLocation The backwoods area north of the farm/west of the bus stop, leading to the bus tunnel or to the mountains.
Tunnel StardewValley.GameLocation The dark bus tunnel to the west of the bus stop.
Trailer_Big StardewValley.GameLocation The inside of Pam/Penny's house after the Community Upgrade.
Cellar StardewValley.Locations.Cellar
Cellar2 StardewValley.Locations.Cellar
Cellar3 StardewValley.Locations.Cellar
Cellar4 StardewValley.Locations.Cellar
BeachNightMarket StardewValley.Locations.BeachNightMarket The beach south of Pelican Town during the Night Market.
MermaidHouse StardewValley.Locations.MermaidHouse The interior of the mermaid boat at the Night Market.
Submarine StardewValley.Locations.Submarine The interior of the fishing submarine during the Night Market.
AbandonedJojaMart StardewValley.Locations.AbandonedJojaMart The small interior of the abandoned JojaMart where the Missing Bundle is.
MovieTheater StardewValley.Locations.MovieTheater The interior of the Movie Theater that replaces JojaMart.
Sunroom StardewValley.GameLocation Caroline's sunroom inside Pierre's General Store.
BoatTunnel StardewValley.Locations.BoatTunnel Where Willy's Boat is, in back of the fish shop.
IslandSouth StardewValley.Locations.IslandSouth Ginger Island, the docks where the player first lands and where the beach resort is.
IslandSouthEast StardewValley.Locations.IslandSouthEast Ginger Island, where the mermaid and pirate cove are.
IslandSouthEastCave StardewValley.Locations.IslandSouthEastCave The pirate cove.
IslandEast StardewValley.Locations.IslandEast Ginger Island jungle, where Leo's hut is.
IslandWest StardewValley.Locations.IslandWest Ginger Island, Island West, where the farm and Birdie's Shack are.
IslandNorth StardewValley.Locations.IslandNorth Ginger Island, Island North, where the volcano and Professor Snail's tent are.
IslandHut StardewValley.Locations.IslandHut The interior of Leo's hut on Ginger Island.
IslandWestCave1 StardewValley.Locations.IslandWestCave1 The Ginger Island cave where the colored crystals puzzle can be found.
IslandNorthCave1 StardewValley.Locations.IslandLocation The mushroom cave on Ginger Island where Professor Snail is initially blocked in by a boulder.
IslandFieldOffice StardewValley.Locations.IslandFieldOffice The interior of Professor Snail's Island Field Office tent.
IslandFarmHouse StardewValley.Locations.IslandFarmHouse The interior of the farm house on Ginger Island.
CaptainRoom StardewValley.Locations.IslandLocation The interior of the shipwreck on Ginger Island West.
IslandShrine StardewValley.Locations.IslandShrine The area East of the jungle on Ginger Island.
IslandFarmCave StardewValley.Locations.IslandFarmCave The interior of Gourmand Frog's cave on Ginger Island.
Caldera StardewValley.Locations.Caldera The volcano caldera on Ginger Island at the end of the volcano dungeon.
LeoTreeHouse StardewValley.GameLocation Leo's tree house home.
QiNutRoom StardewValley.Locations.IslandLocation Mr. Qi's Walnut Room
Retrieved from "https://stardewvalleywiki.com/mediawiki/index.php?title=Modding:Location_data&oldid=168095"