Difference between revisions of "Modding:World map"
Pathoschild (talk | contribs) (copy from Modding:Migrate to Stardew Valley 1.6 (only author is User:Pathoschild)) |
Pathoschild (talk | contribs) (restructure into non-migration-guide format) |
||
Line 7: | Line 7: | ||
'''To edit location maps, see [[Modding:Maps]]. See also [[Modding:Index#Creating mods|an intro to making mods]].''' | '''To edit location maps, see [[Modding:Maps]]. See also [[Modding:Index#Creating mods|an intro to making mods]].''' | ||
− | == | + | ==Overview== |
+ | You can change the world map by editing the <samp>Data/WorldMap</samp> asset. You can add custom maps for certain locations, apply texture overlays, add/edit tooltips, set player marker positioning, etc. | ||
+ | |||
+ | ===Basic concepts=== | ||
[[File:Modding map area.png|thumb|The default world map. The entire map is the Valley region, and the highlighted portion is an area with its own texture, tooltip/name, and player marker positioning.]] | [[File:Modding map area.png|thumb|The default world map. The entire map is the Valley region, and the highlighted portion is an area with its own texture, tooltip/name, and player marker positioning.]] | ||
− | |||
− | |||
− | |||
The game divides the world map into three main concepts (see example at right): | The game divides the world map into three main concepts (see example at right): | ||
Line 26: | Line 26: | ||
The game will find the first <samp>WorldPositions</samp> entry which matches the current location, and assume you're in the region and map area which contains it. If there's none found, it defaults to the farm. | The game will find the first <samp>WorldPositions</samp> entry which matches the current location, and assume you're in the region and map area which contains it. If there's none found, it defaults to the farm. | ||
− | ====Format | + | ===Real-time positioning=== |
+ | The world map generally shows players' actual positions within the world in real-time. If the location drawn on the map closely matches the in-game location, this happens automatically based on the <samp>PixelArea</samp> and <samp>LocationName</samp> fields in <samp>Data/WorldMap</samp>. For complex locations whose tile layout doesn't match the drawn map, you can specify pixel + tile areas in the <samp>WorldLocations</samp> field to allow real-time positions. | ||
+ | |||
+ | ==Data== | ||
+ | ===Format=== | ||
The <samp>Data/WorldMap</samp> data asset consists of a string → model lookup, where... | The <samp>Data/WorldMap</samp> data asset consists of a string → model lookup, where... | ||
* The key is a unique identifier for the region. This should only contain alphanumeric/underscore/dot characters. For custom regions, this should be prefixed with your mod ID like <samp>Example.ModId_RegionName</samp>. | * The key is a unique identifier for the region. This should only contain alphanumeric/underscore/dot characters. For custom regions, this should be prefixed with your mod ID like <samp>Example.ModId_RegionName</samp>. | ||
Line 222: | Line 226: | ||
|} | |} | ||
− | + | ===Example=== | |
This [[Modding:Content Patcher|Content Patcher]] content pack adds a new world map for [[Ginger Island]]. If the player unlocked the [[Ginger Island#Beach Resort|beach resort]], it applies the beach resort texture. | This [[Modding:Content Patcher|Content Patcher]] content pack adds a new world map for [[Ginger Island]]. If the player unlocked the [[Ginger Island#Beach Resort|beach resort]], it applies the beach resort texture. | ||
Line 279: | Line 283: | ||
] | ] | ||
}</nowiki>|lang=javascript}} | }</nowiki>|lang=javascript}} | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
[[Category:Modding]] | [[Category:Modding]] |
Revision as of 00:07, 6 September 2023
← Index
This page explains how to edit the world map shown in the game menu.
To edit location maps, see Modding:Maps. See also an intro to making mods.
Overview
You can change the world map by editing the Data/WorldMap asset. You can add custom maps for certain locations, apply texture overlays, add/edit tooltips, set player marker positioning, etc.
Basic concepts
The game divides the world map into three main concepts (see example at right):
- A region is a large-scale part of the world containing everything shown on the map. For example, the default world map is the Valley region.
- A map area is a subset of the world map which optionally add tooltips, scroll text, texture overlays, and player marker positioning info.
- A map area position matches in-game locations and tile coordinates to the drawn world map. The game uses this to automatically position player markers at a relative position on the world map (e.g. so you can watch other players move across the location on the map).
In the data model:
- each entry is a region;
- each entry's MapAreas are the region's map area;
- and each map area's WorldPositions are the world map positions.
The game will find the first WorldPositions entry which matches the current location, and assume you're in the region and map area which contains it. If there's none found, it defaults to the farm.
Real-time positioning
The world map generally shows players' actual positions within the world in real-time. If the location drawn on the map closely matches the in-game location, this happens automatically based on the PixelArea and LocationName fields in Data/WorldMap. For complex locations whose tile layout doesn't match the drawn map, you can specify pixel + tile areas in the WorldLocations field to allow real-time positions.
Data
Format
The Data/WorldMap data asset consists of a string → model lookup, where...
- The key is a unique identifier for the region. This should only contain alphanumeric/underscore/dot characters. For custom regions, this should be prefixed with your mod ID like Example.ModId_RegionName.
- The value is a model with the fields listed below.
field | effect | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
BaseTexture | (Optional) The base texture to draw for the map, if any. The first matching texture is applied. If map areas provide their own texture too, they're drawn on top of this base texture.
This consists of a list of models with these fields:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
MapAreas | The areas to draw on top of the BaseTexture. These can provide tooltips, scroll text, texture overlays, and player marker positioning info.
This consists of a list of models with these fields:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
MapNeighborIdAliases | (Optional) A set of aliases that can be used in tooltip fields like LeftNeighbor instead of the specific values they represent. Aliases can't be recursive.
For example, this lets you use Beach/FishShop in neighbor fields instead of specifying the specific tooltip IDs each time: "MapNeighborIdAliases": {
"Beach/FishShop": "Beach/FishShop_DefaultHours, Beach/FishShop_ExtendedHours"
}
|
Example
This Content Patcher content pack adds a new world map for Ginger Island. If the player unlocked the beach resort, it applies the beach resort texture.
{
"Format": "2.0.0",
"Changes": [
// add world map edits
{
"Action": "EditData",
"Target": "Data/WorldMap",
"Entries": {
"GingerIsland": {
"BaseTexture": [
{
"Id": "Default",
"Texture": "{{InternalAssetKey: assets/ginger-island.png}}"
}
],
"MapAreas": [
// the Island South (dock) area
{
// basic info for the area within the map
"Id": "IslandSouth",
"PixelArea": { "X": 105, "Y": 105, "Width": 231, "Height": 240 },
"ScrollText": "Dock", // example only, should usually be translated
// a tooltip shown when hovering over the area on the map
"Tooltips": [
{
"Id": "Dock",
"Text": "Dock" // example only, should usually be translated
}
],
// if the resort is unlocked, overlay a custom texture on top of the default Ginger Island map
"Textures": [
{
"Id": "Resort",
"Texture": "{{InternalAssetKey: assets/resort.png}}",
"Condition": "PLAYER_HAS_FLAG Any Island_Resort"
}
],
// the in-game locations that are part of this world map area
"WorldAreas": [
{
"LocationName": "IslandSouth"
}
]
}
]
}
}
}
]
}