Modding:Location contexts - Revision history

imported>Sunbeam135 at 18:16, 6 March 2026

2026-03-06T18:16:47Z

← Older revision		Revision as of 18:16, 6 March 2026
Line 229:		Line 229:
	[[Category:Modding]]		[[Category:Modding]]

			[[ru:Модификации:Контекст локаций]]
	[[zh:模组:地点上下文]]		[[zh:模组:地点上下文]]

imported>Pathoschild: + location context IDs section for reference

2025-07-01T03:08:17Z

+ location context IDs section for reference

@@ Line 201: / Line 201: @@
 | <samp>CustomFields</samp>
 | The [[Modding:Common data field types#Custom fields|custom fields]] for this entry.
 |}
 ==For C# mods==
+* <samp>LocationContexts::Require</samp> can be used to require that a specific entry in <samp>Data/LocationContexts</samp> exists. It gets a location context by ID, throwing if the context does not exist.
 ==See also==

imported>BarleyZP: Add a "For C# mods" section based on Modding:Migrate to Stardew Valley 1.6 (main author Pathoschild)

2025-05-13T19:45:12Z

Add a "For C# mods" section based on Modding:Migrate to Stardew Valley 1.6 (main author Pathoschild)

← Older revision		Revision as of 19:45, 13 May 2025
Line 202:		Line 202:
	\| The [[Modding:Common data field types#Custom fields\|custom fields]] for this entry.		\| The [[Modding:Common data field types#Custom fields\|custom fields]] for this entry.
	\|}		\|}

			==For C# mods==

			* Vanilla location context IDs have constants defined in <samp>LocationContexts.cs</samp>. For example, <samp>LocationContexts.IslandId</samp> for the Island context.
			* <samp>LocationContexts::Require</samp> can be used to require that a specific entry in <samp>Data/LocationContexts</samp> exists. It gets a Location Context by ID, throwing if the context does not exist.

	==See also==		==See also==

imported>BarleyZP: /* Format */ add info (about removed Name field) from Modding:Migrate to Stardew Valley 1.6 (main author Pathoschild)

2025-05-13T19:01:44Z

Format: add info (about removed Name field) from Modding:Migrate to Stardew Valley 1.6 (main author Pathoschild)

← Older revision		Revision as of 19:01, 13 May 2025
Line 6:		Line 6:
	Custom contexts can be created by editing the new <samp>Data/LocationContexts</samp> asset, and setting the context name in the location's <samp>LocationContext</samp> [[Modding:Maps\|map property]].		Custom contexts can be created by editing the new <samp>Data/LocationContexts</samp> asset, and setting the context name in the location's <samp>LocationContext</samp> [[Modding:Maps\|map property]].

	The data asset consists of a string → model lookup, where the key ~~matches the <samp>Name</samp> field and~~ the ~~value is a model with these fields:~~		The data asset 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 context and the value is a model with these fields:

	~~===Required fields===~~
	~~{\| class="wikitable"~~
	\|-
	~~! field~~
	~~! effect~~
	\|-
	~~\| <samp>Name</samp>~~
	~~\| The~~ [[Modding:Common data field types#Unique string ID\|unique string ID]] ~~for~~ the location context.
	\|}

	===Player actions===		===Player actions===

imported>VulpesLucida: zh link

2025-01-20T13:04:36Z

zh link

← Older revision		Revision as of 13:04, 20 January 2025
Line 217:		Line 217:

	[[Category:Modding]]		[[Category:Modding]]

			[[zh:模组:地点上下文]]

imported>VulpesLucida at 09:16, 18 January 2025

2025-01-18T09:16:13Z

← Older revision		Revision as of 09:16, 18 January 2025
Line 1:		Line 1:
	~~===Copied from~~ [[Modding:~~Migrate to Stardew Valley 1.6]]===~~		← [[Modding:Index\|Index]]
	~~{{Migration guide doc status~~\|~~[[Modding:Location data~~]] ~~or a new doc page\|done=false}}~~

	~~====Vanilla~~ contexts~~====~~		This page explains location contexts. This is an advanced guide for modders.
	* The game previously had two hardcoded location context enums: <samp>Default</samp> (for the valley) and <samp>Island</samp> (for [[Ginger Island]]). ~~These have been replaced with data models which define the location context settings, loaded from the <samp>Data/LocationContexts</samp> asset.~~
	* [[The Desert\|The desert]] is now part of a new <samp>Desert</samp> context (instead of <samp>Default</samp>). Some of the previously hardcoded desert logic (like always sunny weather) is now just part of the context data in <samp>Data/LocationContexts</samp>.

	====Format====		==Format==
	Custom contexts can be created by editing the new <samp>Data/LocationContexts</samp> asset, and setting the context name in the location's <samp>LocationContext</samp> [[Modding:Maps\|map property]].		Custom contexts can be created by editing the new <samp>Data/LocationContexts</samp> asset, and setting the context name in the location's <samp>LocationContext</samp> [[Modding:Maps\|map property]].

	The data asset consists of a string → model lookup, where the key matches the <samp>Name</samp> field and the value is a model with these fields:		The data asset consists of a string → model lookup, where the key matches the <samp>Name</samp> field and the value is a model with these fields:

	~~<dl style~~=~~"margin-left: 2em;">~~		===Required fields===
	~~<dt>~~Required fields~~:</dt>~~
	~~<dd>~~
	{\| class="wikitable"		{\| class="wikitable"
	\|-		\|-
Line 22:		Line 17:
	\| The [[Modding:Common data field types#Unique string ID\|unique string ID]] for the location context.		\| The [[Modding:Common data field types#Unique string ID\|unique string ID]] for the location context.
	\|}		\|}
	~~</dd>~~

	~~<dt>~~Player actions~~:</dt>~~		===Player actions===
	~~<dd>~~
	{\| class="wikitable"		{\| class="wikitable"
	\|-		\|-
Line 126:		Line 119:
	If no locations are specified or none match, the player will wake up at [[Harvey's Clinic\|Harvey's clinic]].		If no locations are specified or none match, the player will wake up at [[Harvey's Clinic\|Harvey's clinic]].
	\|}		\|}
	~~</dd>~~

	~~<dt>~~Season~~:</dt>~~		===Season===
	~~<dd>~~
	{\| class="wikitable"		{\| class="wikitable"
	\|-		\|-
Line 138:		Line 129:
	\| ''(Optional)'' The season which is always active for locations within this context (one of <samp>spring</samp>, <samp>summer</samp>, <samp>fall</samp>, or <samp>winter</samp>). For example, setting <samp>summer</samp> will make it always [[summer]] there regardless of the calendar season. If not set, the calendar season applies.		\| ''(Optional)'' The season which is always active for locations within this context (one of <samp>spring</samp>, <samp>summer</samp>, <samp>fall</samp>, or <samp>winter</samp>). For example, setting <samp>summer</samp> will make it always [[summer]] there regardless of the calendar season. If not set, the calendar season applies.
	\|}		\|}
	~~</dd>~~

	~~<dt>~~Weather~~:</dt>~~		===Weather===
	~~<dd>~~
	{\| class="wikitable"		{\| class="wikitable"
	\|-		\|-
Line 170:		Line 159:
	\|}		\|}

			<!--TODO: Fix invalid link-->
	If a [[#Custom passive festivals\|passive festival]] is active in any location within this context, the weather is sunny for the entire context regardless of these fields.		If a [[#Custom passive festivals\|passive festival]] is active in any location within this context, the weather is sunny for the entire context regardless of these fields.

	~~</dd>~~		===Music===

	~~<dt>~~Music~~:</dt>~~
	~~<dd>~~
	{\| class="wikitable"		{\| class="wikitable"
	\|-		\|-
Line 215:		Line 202:
	\| ''(Optional)'' Whether to play random outdoor ambience sounds depending on factors like the season and time of day (e.g. birds, crickets, and mysterious groan sounds in the rain). This is unrelated to the <samp>DayAmbience</samp> and <samp>NightAmbience</samp> fields. Default true.		\| ''(Optional)'' Whether to play random outdoor ambience sounds depending on factors like the season and time of day (e.g. birds, crickets, and mysterious groan sounds in the rain). This is unrelated to the <samp>DayAmbience</samp> and <samp>NightAmbience</samp> fields. Default true.
	\|}		\|}
	~~</dd>~~

	~~<dt>~~Advanced~~:</dt>~~		===Advanced===
	~~<dd>~~
	{\| class="wikitable"		{\| class="wikitable"
	\|-		\|-
Line 227:		Line 212:
	\| The [[Modding:Common data field types#Custom fields\|custom fields]] for this entry.		\| The [[Modding:Common data field types#Custom fields\|custom fields]] for this entry.
	\|}		\|}
	~~</dd>~~
	~~</dl>~~		==See also==
			* [[Modding:Location data]]

			[[Category:Modding]]

imported>VulpesLucida: add info from Modding:Migrate to Stardew Valley 1.6 (main author Pathoschild)

2025-01-18T09:12:50Z

add info from Modding:Migrate to Stardew Valley 1.6 (main author Pathoschild)

New page

===Copied from [[Modding:Migrate to Stardew Valley 1.6]]===
{{Migration guide doc status|[[Modding:Location data]] or a new doc page|done=false}}

====Vanilla contexts====
* The game previously had two hardcoded location context enums: <samp>Default</samp> (for the valley) and <samp>Island</samp> (for [[Ginger Island]]). These have been replaced with data models which define the location context settings, loaded from the <samp>Data/LocationContexts</samp> asset.
* [[The Desert|The desert]] is now part of a new <samp>Desert</samp> context (instead of <samp>Default</samp>). Some of the previously hardcoded desert logic (like always sunny weather) is now just part of the context data in <samp>Data/LocationContexts</samp>.

====Format====
Custom contexts can be created by editing the new <samp>Data/LocationContexts</samp> asset, and setting the context name in the location's <samp>LocationContext</samp> [[Modding:Maps|map property]].

The data asset consists of a string → model lookup, where the key matches the <samp>Name</samp> field and the value is a model with these fields:

<dl style="margin-left: 2em;">
<dt>Required fields:</dt>
<dd>
{| class="wikitable"
|-
! field
! effect
|-
| <samp>Name</samp>
| The [[Modding:Common data field types#Unique string ID|unique string ID]] for the location context.
|}
</dd>

<dt>Player actions:</dt>
<dd>
{| class="wikitable"
|-
! field
! effect
|-
| <samp>AllowRainTotem</samp>
| ''(Optional)'' Whether a [[Rain Totem|rain totem]] can be used to force rain in this context tomorrow. If false, using a rain totem here will show a "''this item can't be used here''" message instead.
|-
| <samp>RainTotemAffectsContext</samp>
| ''(Optional)'' If set, using a rain totem here will change the weather in the given context ID. For example, rain totems in the desert change weather in the valley.
|-
| <samp>MaxPassOutCost</samp>
| ''(Optional)'' When the player passes out (due to [[energy|exhaustion]] or at 2am) in this context, the maximum amount of [[gold]] lost. If omitted or set to <samp>-1</samp>, uses the same value as the <samp>Default</samp> context ({{price|1000}} by default).
|-
| <samp>PassOutMail</samp>
| ''(Optional)'' When the player passes out (due to [[energy|exhaustion]] or at 2am) in this context, the possible [[Modding:Mail data|letter IDs]] to add to their mailbox (if they haven't received it before). If multiple letters are valid, one will be chosen randomly (unless one specifies <samp>SkipRandomSelection</samp>).

This consists of a list of models with these fields:
{| class="wikitable"
|-
! field
! effect
|-
| <samp>Id</samp>
| The [[Modding:Common data field types#Unique string ID|unique string ID]] for this entry in the list.
|-
| <samp>Mail</samp>
| The [[Modding:Mail data|letter ID]] to add.

The game will look for an existing letter ID in <samp>Data/mail</samp> in this order (where {{t|billed}} is <samp>Billed</samp> if they lost [[gold]] or <samp>NotBilled</samp> otherwise, and {{t|gender}} is <samp>Female</samp> or <samp>Male</samp>):
* <samp>{{t|letter id}}_{{t|billed}}_{{t|gender}}</samp>
* <samp>{{t|letter id}}_{{t|billed}}</samp>
* <samp>{{t|letter id}}</samp>

If no match is found in <samp>Data/mail</samp>, the game will send <samp>passedOut2</samp> instead.

If the mail ID starts with <samp>passedOut</samp>, <samp>{0}</samp> in the letter text will be replaced with the gold amount lost, and it won't appear in the [[collections]] page.
|-
| <samp>MaxPassOutCost</samp>
| ''(Optional)'' The maximum amount of [[gold]] lost. This is applied after the context's <samp>MaxPassOutCost</samp> (i.e. the context's value is used to calculate the random amount, then this field caps the result). Defaults to unlimited.
|-
| <samp>Condition</samp>
| ''(Optional)'' A [[Modding:Game state queries|game state query]] which indicates whether this entry is active. Defaults to always true.
|-
| <samp>SkipRandomSelection</samp>
| ''(Optional)'' If true, send this mail if the <samp>Condition</samp> matches instead of choosing a random valid mail. Default false.
|}
|-
| <samp>PassOutLocations</samp>
| ''(Optional)'' When the player passes out (due to [[energy|exhaustion]] or at 2am) in this context ''and'' they started the day in a different location context, the locations where they'll wake up. (If the player started the day in the same context, they'll wake up in the last bed they slept in instead.)

If the selected location doesn't contain a bed and doesn't have the [[#New map properties|<samp>AllowWakeUpWithoutBed</samp> map property]], the player will wake up in the farmhouse instead.

This consists of a list of models with these fields:
{| class="wikitable"
|-
! field
! effect
|-
| <samp>Id</samp>
| The [[Modding:Common data field types#Unique string ID|unique string ID]] for this entry in the list.
|-
| <samp>Location</samp>
| The internal location name.
|-
| <samp>Position</samp>
| The ''default'' tile position within the location, specified as an object with <samp>X</samp> and <samp>Y</samp> fields. If the location has any bed furniture, they'll be placed in the first bed found instead.
|-
| <samp>Condition</samp>
| ''(Optional)'' A [[Modding:Game state queries|game state query]] which indicates whether this entry is active. Defaults to always applied.
|}

If no locations are specified or none match, the player will wake up in their bed at home.
|-
| <samp>ReviveLocations</samp>
| ''(Optional)'' If the player just got knocked out in combat, the location names where they'll wake up.

This consists of a list of models with these fields:
{| class="wikitable"
|-
! field
! effect
|-
| <samp>Id</samp>
| The [[Modding:Common data field types#Unique string ID|unique string ID]] for this entry in the list.
|-
| <samp>Location</samp>
| The internal location name.
|-
| <samp>Position</samp>
| The tile position within the location, specified as an object with <samp>X</samp> and <samp>Y</samp> fields.
|-
| <samp>Condition</samp>
| ''(Optional)'' A [[Modding:Game state queries|game state query]] which indicates whether this entry is active. Defaults to always applied.
|}

If the selected location has a standard [[Modding:Event data|event]] with the exact key <samp>PlayerKilled</samp> (with no <samp>/</samp> or preconditions in the key), that event will play when the player wakes up and the game will apply the lost items or [[gold]] logic. The game won't track this event, so it'll repeat each time the player is revived. If there's no such event, the player will wake up without an event, and no items or gold will be lost.

If no locations are specified or none match, the player will wake up at [[Harvey's Clinic|Harvey's clinic]].
|}
</dd>

<dt>Season:</dt>
<dd>
{| class="wikitable"
|-
! field
! effect
|-
| <samp>SeasonOverride</samp>
| ''(Optional)'' The season which is always active for locations within this context (one of <samp>spring</samp>, <samp>summer</samp>, <samp>fall</samp>, or <samp>winter</samp>). For example, setting <samp>summer</samp> will make it always [[summer]] there regardless of the calendar season. If not set, the calendar season applies.
|}
</dd>

<dt>Weather:</dt>
<dd>
{| class="wikitable"
|-
! field
! effect
|-
| <samp>WeatherConditions</samp>
| ''(Optional)'' The weather logic to apply for locations in this context (ignored if <samp>CopyWeatherFromLocation</samp> is set). Defaults to always sunny. If multiple are specified, the first matching weather is applied.

This consists of a list of models with these fields:
{| class="wikitable"
|-
! field
! effect
|-
| <samp>Id</samp>
| The [[Modding:Common data field types#Unique string ID|unique string ID]] for this entry in the list.
|-
| <samp>Weather</samp>
| The [[#Custom weather|weather ID]] to set.
|-
| <samp>Condition</samp>
| ''(Optional)'' A [[Modding:Game state queries|game state query]] which indicates whether to apply the weather. Defaults to always applied.
|}
|-
| <samp>CopyWeatherFromLocation</samp>
| ''(Optional)'' The <samp>Name</samp> (i.e. unique ID) of the location context from which to inherit weather.
|}

If a [[#Custom passive festivals|passive festival]] is active in any location within this context, the weather is sunny for the entire context regardless of these fields.

</dd>

<dt>Music:</dt>
<dd>
{| class="wikitable"
|-
! field
! effect
|-
| <samp>DefaultMusic</samp>
| ''(Optional)'' The [[Modding:Audio|cue ID]] for the music to play when the player is in the location, unless overridden by a <samp>Music</samp> map property. Despite the name, this has a higher priority than the seasonal music fields below. Ignored if omitted.
|-
| <samp>DefaultMusicCondition</samp>
| ''(Optional)'' A [[Modding:Game state queries|game state query]] which returns whether the <samp>DefaultMusic</samp> field should be applied (if more specific music isn't playing). Defaults to always true.
|-
| <samp>DefaultMusicDelayOneScreen</samp>
| ''(Optional)'' When the player warps and the music changes, whether to silence the music and play the ambience (if any) until the next warp (similar to the default valley locations). Default false.
|-
| <samp>Music</samp>
| ''(Optional)'' A list of [[Modding:Audio|cue IDs]] to play before noon in this location unless it's raining, there's a <samp>Music</samp> map property, or the context has a <samp>DefaultMusic</samp> value. If multiple values are specified, the game will play one per day in sequence.

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>DayAmbience</samp><br /><samp>NightAmbience</samp>
| ''(Optional)'' The [[Modding:Audio|cue ID]] for the background ambience to play when there's no music active, depending on the [[Day Cycle|time of day]]. Both default to none.
|-
| <samp>PlayRandomAmbientSounds</samp>
| ''(Optional)'' Whether to play random outdoor ambience sounds depending on factors like the season and time of day (e.g. birds, crickets, and mysterious groan sounds in the rain). This is unrelated to the <samp>DayAmbience</samp> and <samp>NightAmbience</samp> fields. Default true.
|}
</dd>

<dt>Advanced:</dt>
<dd>
{| class="wikitable"
|-
! field
! effect
|-
| <samp>CustomFields</samp>
| The [[Modding:Common data field types#Custom fields|custom fields]] for this entry.
|}
</dd>
</dl>