16
edits
Changes
mLine 4:
Line 4: − + − + Line 65:
Line 65: − + − + − + − + + + + − + − + + + + + + + − + − | NPCs to spawn when the festival loads. This is specified as four space-delimited fields in the form <tt>{{t|NPC name}} {{t|tile X}} {{t|tile Y}} {{t|facing direction}}</tt>, repeated for each NPC to add. The {{t|facing direction}}</tt> can be one of <tt>up</tt> or <tt>0</tt>, <tt>down</tt> or <tt>2</tt>, <tt>left</tt> or <tt>3</tt>, and <tt>right</tt> or <tt>1</tt>. These are additional to the NPCs spawned via the [[#Map|map file]]. For example, this adds Abigail and Leah side-by-side facing down: <syntaxhighlight lang="javascript">"Set-Up_additionalCharacters": "Abigail 15 6 down Leah 16 6 down"</syntaxhighlight>+ − + − + − + − + − Several fields allow annual variants (specifically <tt>set-up</tt>, <tt>{{t|NPC name}}</tt>, and <tt>{{t|NPC name}}_spouse</tt>). These work by prefixing <tt>_y{{t|year modulo}}</tt> to the key, where the {{t|year modulo}} is an incrementing number starting at 1 with no upper limit. For example, two entries <tt>set-up_y1</tt> and <tt>set-up_y2</tt> will alternate between the two set-ups each year (<tt>set-up_y1</tt> in year 1, <tt>set-up_y2</tt> in year 2, <tt>set-up_y1</tt> in year 3, etc). If annual variants are defined, the original key is ignored (e.g. <tt>set-up</tt> will never be used if <tt>set-up_y*</tt> entries are defined).+ − Any other entry is [[Modding:Event_data|event data]] for a cutscene during the festival. In some cases like the [[Luau]], these are linked together when played in the game.+ + + − + Line 100:
Line 111: − + − + − + − + − + − Most festivals use a separate [[Modding:Maps|map file]] located in the <tt>Content/Maps</tt> folder. The map to use is specified in the [[#Data file|data file]]'s <tt>set-up</tt> field using the <tt>changeToTemporaryMap</tt> command.+ + + + + + + + − + + +
→Year variants: Minor wording change on the coordination problem warning.
==Data file==
==Data file==
Each festival has a data file located at <tt>Content/Data/Festivals/<season><day of month></tt>. The game uses this asset to determine whether there's a festival today (if the asset exists), where and when it happens, and NPC placement/dialogue/behavior.
Each festival has a data file located at <samp>Content/Data/Festivals/<season><day of month></samp>. The game uses this asset to determine whether there's a festival today (if the asset exists), where and when it happens, and NPC placement/dialogue/behavior.
===Raw data===
===Raw data===
The festival data file can be [[Modding:Editing XNB files#unpacking|unpacked for editing]]. For example, here's the raw data from <tt>Content/Data/Festivals/fall16</tt> as of {{version|1.5.4}} for reference:
The festival data file can be [[Modding:Editing XNB files#unpacking|unpacked for editing]]. For example, here's the raw data from <samp>Content/Data/Festivals/fall27</samp> as of {{version|1.5.4}} for reference:
{{collapse|Data|content=<syntaxhighlight lang="json">
{{collapse|Data|content=<syntaxhighlight lang="json">
{
{
! explanation
! explanation
|-
|-
| <tt>name</tt>
| <samp>name</samp>
| The festival name. This is used in display text like the calendar tooltip or the festival-is-ready message.
| The festival name. This is used in display text like the calendar tooltip or the festival-is-ready message.
|-
|-
| <tt>conditions</tt>
| <samp>conditions</samp>
| When and where the festival takes place. The format is <tt>{{t|location}}{{t|start time}} {{t|end time}}</tt>, where {{t|location}} is the internal location name and the times are specified in 26-hour format (i.e. 600 for 6am to 2600 for 2am).
| When and where the festival takes place. The format is <samp>{{t|location}}/{{t|start time}} {{t|end time}}</samp>, where {{t|location}} is the internal location name and the times are specified in 26-hour format (''i.e.,'' 600 for 6am to 2600 for 2am).
|-
|-
| <tt>shop</tt>
| <samp>mainEvent</samp>
| The main event script. This is triggered when the player asks the festival host (usually Lewis) to begin the festival. This is absent for events that do not have a prompt or where speaking to Lewis does not trigger a new scene.
|-
| <samp>shop</samp>
| The items the festival shop sells. See ''[[#Shop format|shop format]]'' below.
| The items the festival shop sells. See ''[[#Shop format|shop format]]'' below.
|-
|-
| <tt>set-up</tt>
| <samp>set-up</samp>
| The [[Modding:Event data|event script]] that's run when the player first enters the festival. This includes moving the player to the festival map.
| The [[Modding:Event data|event script]] that's run when the player first enters the festival. This includes moving the player to the festival map. This field supports [[#Year variants|year variants]].
|-
| <samp>Set-Up_additionalCharacters</samp>
| NPCs to spawn when the festival loads. This is specified as four space-delimited fields in the form <samp>{{t|NPC name}} {{t|tile X}} {{t|tile Y}} {{t|facing direction}}</samp>, repeated for each NPC to add with a <code>/</code> between each NPC. The {{t|facing direction}}</samp> can be one of <samp>up</samp> or <samp>0</samp>, <samp>down</samp> or <samp>2</samp>, <samp>left</samp> or <samp>3</samp>, and <samp>right</samp> or <samp>1</samp>. These are additional to the NPCs spawned via the [[#Map|map file]]. For example, this adds Abigail and Leah side-by-side facing down: <syntaxhighlight lang="javascript">"Set-Up_additionalCharacters": "Abigail 15 6 down/Leah 16 6 down"</syntaxhighlight>This field supports [[#Year variants|year variants]].
|-
| <samp>MainEvent_additionalCharacters</samp>, or<br><samp>Main-Event_additionalCharacters</samp> for the [[Festival of Ice|Festival of Ice]]
| NPCs to spawn when the festival's <code>mainEvent</code> script is run. Just like <code>mainEvent</code>, this is absent for events that do not have a prompt to start a new scene. The format is identical to <code>Set-Up_additionalCharacters</code>, above.<br>This field supports [[#Year variants|year variants]].
|-
|-
| <tt>Set-Up_additionalCharacters</tt>
| <samp>{{t|NPC name}}_roommate</samp>
| The [[Modding:Dialogue#Format|dialog line]] the named NPC will say when the player talks to them, if they're roommates with the player. This field supports [[#Year variants|year variants]], doesn't work on the Flower Dance festival, and doesn't support <samp>#$e#</samp> breaks. If not specified, the <samp>{{t|NPC name}}_spouse</samp> will be used next.
|-
|-
| <tt>{{t|NPC name}}_spouse</tt>
| <samp>{{t|NPC name}}_spouse</samp>
| The [[Modding:Dialogue#Format|dialog line]] the named NPC will say when the player talks to them, if they're married to the player.
| The [[Modding:Dialogue#Format|dialog line]] the named NPC will say when the player talks to them, if they're married to the player. This field supports [[#Year variants|year variants]], doesn't work on the Flower Dance festival, and doesn't support <samp>#$e#</samp> breaks.
|-
|-
| <tt>{{t|NPC name}}</tt>
| <samp>{{t|NPC name}}</samp>
| The [[Modding:Dialogue#Format|dialog line]] the named NPC will say when the player talks to them, if <tt>{{t|NPC name}}_spouse</code></tt> doesn't exist or apply.
| The [[Modding:Dialogue#Format|dialog line]] the named NPC will say when the player talks to them, if <samp>{{t|NPC name}}_spouse</code></samp> doesn't exist or apply. This field supports [[#Year variants|year variants]].
|}
|}
Any other entry is [[Modding:Event data|event data]] for a cutscene during the festival. In some cases like the [[Luau]], these are linked together when played in the game.
===Year variants===
Several fields allow annual variants (documented in the table above). These work by adding <samp>_y{{t|year variant}}</samp> to the end of key, where the {{t|year variant}} is an incrementing number starting at 1 with no upper limit. For example, two entries <samp>set-up_y1</samp> and <samp>set-up_y2</samp> will alternate (<samp>set-up_y1</samp> in year 1, <samp>set-up_y2</samp> in year 2, <samp>set-up_y1</samp> in year 3, etc). If year variants are defined for a key, the original key is ignored (''e.g.,'' <samp>set-up</samp> will never be used if <samp>set-up_y*</samp> entries are defined).
{{note box|'''It is recommended to use the year variants for the <samp>Set-Up_additionalCharacters</samp> and <samp>MainEvent_additionalCharacters</samp> fields, even if you don't wish to spawn your custom NPC in different locations on odd and even years.'''<br>These keys are global to the festival data, and if <strong>any</strong> mod appends to them, the game will use those keys instead of the non-variant keys. This will cause any NPCs not using the year variant keys to fail to spawn.}}
===Shop format===
===Shop format===
The shop data for a festival is stored as four space-separated values in the format <tt>{{t|item type}} {{t|item ID}} {{t|cost}} {{t|count available}}</tt>, which is repeated for each item. Field formats:
The shop data for a festival is stored as four space-separated values in the format <samp>{{t|item type}} {{t|item ID}} {{t|cost}} {{t|count available}}</samp>, which is repeated for each item. Field formats:
{| class="wikitable"
{| class="wikitable"
|-
|-
| {{t|item type}}
| {{t|item type}}
| The item type. The valid values are <tt>B</tt> (boots), <tt>BL</tt> (blueprint), <tt>BBL</tt> or <tt>BBl</tt> (big blueprint), <tt>BO</tt> (bigcrafable object), <tt>F</tt> (furniture), <tt>H</tt> (hat), <tt>O</tt> (object), <tt>R</tt> (ring), or <tt>W</tt> (weapon).
| The item type. The valid values are <samp>B</samp> or <samp>Boots</samp> (boots), <samp>BL</samp> or <samp>Blueprint</samp> (blueprint), <samp>BBL</samp>, <samp>BBl</samp> or <samp>BigBlueprint</samp> (big blueprint), <samp>BO</samp> or <samp>BigObject</samp> (bigcraftable object), <samp>F</samp> (furniture), <samp>H</samp> or <samp>Hat</samp> (hat), <samp>O</samp> or <samp>Object</samp> (object), <samp>R</samp> or <samp>Ring</samp> (ring), or <samp>W</samp> or <samp>Weapon</samp> (weapon).
|-
|-
| <tt>{{t|item id}}</tt>
| <samp>{{t|item id}}</samp>
| The item's spritesheet index.
| The item's spritesheet index.
|-
|-
| <tt>{{t|cost}}</tt>
| <samp>{{t|cost}}</samp>
| The purchase price in gold. For seeds, this is modified based on the [[Multiplayer#Profit margins|profit margin]].
| The purchase price in gold. For seeds, this is modified based on the [[Multiplayer#Profit margins|profit margin]].
|-
|-
| <tt>{{t|count available}}</tt>
| <samp>{{t|count available}}</samp>
| How many of that item can be purchased from the shop, or <tt>-1</tt> for unlimited.
| How many of that item can be purchased from the shop, or <samp>-1</samp> for unlimited.
|}
|}
==Map==
==Map==
Many festivals use a separate [[Modding:Maps|map file]] located in the <samp>Content/Maps</samp> folder. The map to use is specified in the [[#Data file|data file]]'s <samp>set-up</samp> field using the <samp>changeToTemporaryMap</samp> command.
===Spawned NPCs===
{{note box|'''This is fragile and not recommended for custom NPCs or festivals.'''<br />Consider using the [[#Data file|data file]]'s <samp>Set-Up_additionalCharacters</samp> field instead.}}
NPCs can be added to festivals using map tile indexes on a specific layer. This is enabled in the [[#Data file|data file]]'s <samp>set-up</samp> field using the <samp>loadActors {{t|layer name}}</samp> command. For each tile which exists on the layer, the tile index is mapped to the NPC's index in the <samp>Data\NPCDispositions</samp> asset multiplied by four, with an offset which determines the facing direction (0 = up, 1 = right, 2 = down, or 3 = left).
For example, let's say the layer has a tile with tilesheet index 61. That's the NPC at index <samp>61 / 4 = 15</samp> in <samp>Data\NPCDispositions</samp>, ''i.e.,'' the 16th NPC, ''i.e.,'' Leah. The offset is <samp>61 % 4 = 1</samp>, so she's facing right. When the festival is loaded, Leah will be added to that tile position facing right.
==Hardcoded logic==
==Hardcoded logic==
Several vanilla events have hardcoded scripted logic in the game code. For example, Lewis judging the farmer's grange display at the [[Stardew Valley Fair]] is handled in the game code, not the content assets documented here.
Several vanilla events have hardcoded scripted logic in the game code. For example, Lewis judging the farmer's grange display at the [[Stardew Valley Fair]] is handled in the game code, not the content assets documented here.
The [[Night Market]] is also handled differently from other festivals. While there are separate Night Market maps, the NPC data doesn't exist on these. Instead, NPCs dynamically enter and leave the festival via schedule data. The raw data for the schedule destinations of each NPC during the Night Market can be found below.
The [[Night Market]] is also handled differently from other festivals. While there are separate Night Market maps, the NPC data doesn't exist on these. Instead, NPCs dynamically enter and leave the festival via schedule data.
[[Category:Modding]]
[[Category:Modding]]
[[ru:Модификации:Фестивали]]