Difference between revisions of "Modding:Location data"
Pathoschild (talk | contribs) (integrate new 1.6 content into page) |
Pathoschild (talk | contribs) (add FAQs) |
||
Line 417: | Line 417: | ||
==Default 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. | 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?=== | ||
+ | If you rename a location, any data for that location in players' existing saves will be permanently lost. Renaming locations is not recommended. | ||
==Location names== | ==Location names== |
Revision as of 01:03, 21 November 2023
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 (Stardew Valley 1.5.6 and earlier)
Data/Locations controls many things about locations.
Here is an example location:
"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",
Breaking it down:
Index | Entry | Explanation |
---|---|---|
0 | "372 .9 718 .1 719 .3 723 .3" | Spring forage. Item ID chance. No particular order required. |
1 | "372 .9 394 .5 718 .1 719 .3 723 .3" | Summer forage. As above. |
2 | "372 .9 718 .1 719 .3 723 .3" | Fall forage. As above. |
3 | "372 .4 392 .8 718 .05 719 .2 723 .2" | Winter forage. As above. |
4 | "129 -1 131 -1 147 -1 148 -1 152 -1 708 -1 267 -1" | 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 |
5 | "128 -1 130 -1 146 -1 149 -1 150 -1 152 -1 155 -1 708 -1 701 -1 267 -1" | Fish data for summer |
6 | "129 -1 131 -1 148 -1 150 -1 152 -1 154 -1 155 -1 705 -1 701 -1" | Fish data for autumn |
7 | "708 -1 130 -1 131 -1 146 -1 147 -1 150 -1 151 -1 152 -1 154 -1 705 -1" | Fish data for winter |
8 | "384 .08 589 .09 102 .15 390 .25 330 1" | 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. |
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.
Examples are:
"Farm": "-1/-1/-1/-1/-1/-1/-1/-1/382 .05 770 .1 390 .25 330 1",
This has no forage or fishing data (handled programmatically) so it's just -1.
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.
Data format (Stardew Valley 1.6 and later)
You can add or edit locations by editing the Data/Locations asset.
This consists of a string → model lookup, where...
- The key is the internal name of the location to change, which will also be used as the location's Name (not DisplayName) field. This should only contain alphanumeric/underscore/dot characters, and custom locations' names should be prefixed with your mod ID like Example.ModId_LocationName. (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). |
ExcludeFromNpcPathfinding | (Optional) Whether NPCs should ignore this location when pathfinding between locations. Default false. |
Creation
field | effect | ||||||||
---|---|---|---|---|---|---|---|---|---|
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:
|
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:
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:
| ||||||||||||||||||||||||||||||||||||||||||
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:
| ||||||||||||||||||||||||||||||||||||||||||
Forage | (Optional) The forage that can spawn in the location.
Notes:
This consists of a list of models with these fields:
| ||||||||||||||||||||||||||||||||||||||||||
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:
| ||||||||
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:
| ||||||||
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 | The custom fields for this entry. |
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
console command to warp directly into it.
<location name>
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?
If you rename a location, any data for that location in players' existing saves will be permanently lost. Renaming locations is not recommended.
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 |