Difference between revisions of "Modding:Festival data"

From Stardew Valley Wiki
Jump to navigation Jump to search
m (fixed typo)
(expand/correct/copyedit info; reorganize so we can better document the map features)
Line 3: Line 3:
 
This page explains how the game stores and uses festival data. This is an advanced guide for mod developers.
 
This page explains how the game stores and uses festival data. This is an advanced guide for mod developers.
  
−
==Overview==
+
==Data file==
−
Festivals are complex events with both content and code components. The festival data files are named for the date they occur on, and include when and where the festival occurs, as well as character dialog, cutscenes, and other information.  For the majority of festivals, there exist special map files with location data for villager placements.  These are located within Content/Maps like other map files.  For scripted events that play during the festival (such as Lewis judging the farmer's grange display), the event is usually handled in code.
+
Each festival has a data file located at <tt>Content/Data/Festivals/&lt;season&gt;&lt;day of month&gt;</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.
  
−
==Data Keys==
+
===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:
 +
{{collapse|Data|content=<syntaxhighlight lang="json">
 +
{
 +
  "name": "Spirit's Eve",
 +
  "conditions": "Town/2200 2350",
 +
  "shop": "BO 113 5000 1 O 746 750 5 BL 746 2000 1 BO 47 350 -1 F 2870 4000 -1",
 +
  "set-up": "spirits_eve/-1000 -1000/farmer 12 54 1/changeToTemporaryMap Town-Halloween/loadActors Set-Up/advancedMove Maru true 0 2 2 0 0 3 -11 0 0 -7 5 0 0 2 4 0/advancedMove Alex true -4 0 4 4000 4 0 4 5000/advancedMove Jas true 1 1500 4 1000/advancedMove Pam true 0 1 1 5000 0 -1 1 5000/advancedMove Shane true -7 0 0 2 2 9000 0 -2 7 0 4 9000/advancedMove Demetrius true 3 18000 4 3000/addTemporaryActor Skeleton 16 32 30 59 2 false Monster/advancedMove Skeleton true 0 1 3 4000 2 0 0 -1 4 2000 -1 0 3 1000 2 2000 0 -1 4 4000 -1 0 0 1 2 5000/addTemporaryActor Skeleton 16 32 35 58 2 false Monster/playerControl halloween",
 +
  "Abigail_spouse": "You'll have to tell me what's beyond, I can't go on... spiders...$s",
 +
  "Leah_spouse": "I may have had a little too much pumpkin ale...",
 +
  "Maru_spouse": "I'm confused... you go on ahead and let me figure this out.",
 +
  "Penny_spouse": "Oh... These vapors... Hmmm... You look nice tonight.$l",
 +
  "Haley_spouse": "I get scared easily... I think I'm just going to stay right here.$s",
 +
  "Sebastian_spouse": "It would be interesting to have one of these on the farm.",
 +
  "Sam_spouse": "Hey, I was wondering when you'd show up!$h",
 +
  "Harvey_spouse": "Hi... I was hoping you'd find me here...$l",
 +
  "Elliott_spouse": "Mmph... I believe I've eaten a few too many slices of pumpkin pie.",
 +
  "Abigail": "I can't go on... spiders...$s",
 +
  "Robin": "Well, winter's almost here. It's a great time to stockpile wood and stone.",
 +
  "Demetrius": "I haven't seen Maru in hours... I hope she's alright.",
 +
  "Maru": "I think I've already been this way... no, wait...$s#$e#I'm lost...$s",
 +
  "Sebastian": "I have no idea how these skeletons are walking... creepy.#$e#It's pretty cool though.",
 +
  "Pierre": "??",
 +
  "Caroline": "I get scared very easily. I'll leave the haunted maze to the younger people.",
 +
  "Linus": "Good show, old friend.",
 +
  "Alex": "There's something weird over there. But how do I get to it?#$e#There's gotta be a secret passage somewhere around here.",
 +
  "George": "Hmm... smoked turkey haunch? I guess this festival isn't all bad.$h",
 +
  "Evelyn": "I wish Gus would include a vegetarian option. Some zucchini skewers, maybe?",
 +
  "Lewis": "Good evening, @. Have you ventured into the haunted maze yet? It's quite spooky.#$e#That strange man who lives in the tower set it all up himself. He wouldn't let anyone near while he was working on it.",
 +
  "Clint": "One of my iridium-infused maces would make quick work of these things.",
 +
  "Emily": "Do you like the jack-o-lanterns? I carved them myself.",
 +
  "Penny": "The vapor from this cauldron... it's making my head spin, but I can't seem to leave...$u",
 +
  "Pam": "I'll come to any event with free grub! You won't see me in the haunted maze, though.",
 +
  "Haley": "Eek! I'm too scared.$s",
 +
  "Jodi": "Vincent's upset that I won't let him go into the haunted maze... but he's just a little boy!",
 +
  "Kent": "Hey, @. Nice evening, isn't it?",
 +
  "Sam": "That's odd... It's just a dead end up ahead.#$e#I could've sworn there was someone ahead of me when I went through the maze, though. Where'd they go?",
 +
  "Leah": "Mm, hi. Sorry... mouth full of blackberries.",
 +
  "Marnie": "Hi, @. Have you had a productive fall?#$e#It's starting to get quite cold... crops won't hold out for much longer.",
 +
  "Elliott": "Why, hello @. It's chilly, isn't it?",
 +
  "Gus": "It's a lot of fun to cook with pumpkin. Such an interesting fruit.",
 +
  "Dwarf": "You say it's raining up above? *gasp*#$e#Rain... It's almost mythical to us. Some of us live our entire lives without ever experiencing it.",
 +
  "Wizard": "The affairs of mundane folk matter little to me, but the elementals like a chance to see you up close.#$e#It was for them that I created this silly maze.",
 +
  "Harvey": "Oh! You found me...$8#$b#The truth is, I got too scared so I came here to hide. Don't tell anyone.$s",
 +
  "Shane": "Why is there no more pumpkin ale?",
 +
  "Sandy": "I heard it's raining back home. Is that why you came here?$h#$e#I kind of miss the rain, actually...$s",
 +
  "Jas": "But Aunt Marnie! I wanna go in the maze! I'm not scared!$s",
 +
  "Vincent": "Mother won't let me go in the maze. *sob*$s",
 +
  "Marlon": "Don't get too close to the cage.",
 +
  "Leo": "%Leo's unblinking eyes are glued to the screen. You're unable to get his attention."
 +
}
 +
</syntaxhighlight>}}
 +
 
 +
===Format===
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
−
! entry
+
! field key
 
! explanation
 
! explanation
 
|-
 
|-
 
| <tt>name</tt>
 
| <tt>name</tt>
−
| The name of the event. Used to tell the player when the festival is ready.
+
| The festival name. This is used in display text like the calendar tooltip or the festival-is-ready message.
 
|-
 
|-
 
| <tt>conditions</tt>
 
| <tt>conditions</tt>
−
| When and where the festival takes place. Format is <code><location>/<start time> <end time></code>.
+
| 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).
 
|-
 
|-
 
| <tt>shop</tt>
 
| <tt>shop</tt>
−
| The items the festival shop sells. See [[#shop format|Shop Format]] for more information.
+
| The items the festival shop sells. See ''[[#Shop format|shop format]]'' below.
 
|-
 
|-
 
| <tt>set-up</tt>
 
| <tt>set-up</tt>
−
| The [[Modding:Event_data|event data]] that is 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.
 
|-
 
|-
−
| <tt>{{t|string npcName}}</tt>
+
| <tt>{{t|NPC name}}_spouse</code></tt>
−
| The default event [[Modding:Dialogue#Format|dialog]] for that npc.
+
| The [[Modding:Dialogue#Format|dialog line]] the named NPC will say when the player talks to them, if they're married to the player.
 
|-
 
|-
−
| <tt><code><string npcName>_spouse</code></tt>
+
| <tt>{{t|NPC name}}</tt>
−
| The event [[Modding:Dialogue#Format|dialog]] for that npc when they are married to the player.
+
| 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.
 
|}
 
|}
−
Any other entry is [[Modding:Event_data|event data]] for a cutscene that is used during the event. In some cases, like the luau, these are linked together when played in the game.
+
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.
 +
 
 +
===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:
  
−
==Shop Format==
 
−
Shop data for festivals is stored as a space-separated list. Each group of four values is one entry for the shop. The meanings of each value are explained here:
 
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
−
! allowed values
+
! field
 
! explanation
 
! explanation
 
|-
 
|-
−
|
+
| {{t|item type}}
−
* <tt>B/Boot</tt>  
+
| 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).
−
* <tt>BL/Blueprint</tt>  
 
−
* <tt>BBL/BBl/BigBlueprint</tt>
 
−
* <tt>BO/BigObject</tt>
 
−
* <tt>F</tt>
 
−
* <tt>H/Hat</tt>
 
−
* <tt>O/Object</tt>
 
−
* <tt>R/Ring</tt>
 
−
* <tt>W/Weapon</tt>
 
−
| Item type.<br/>Boots,<br/>Blueprint,<br/>BigBlueprint,<br/>BigObject,<br/>Furniture,<br/>Hat,<br/>Object,<br/>Ring,<br/>or Weapon, accordingly.
 
 
|-
 
|-
−
| <tt>{{t|int id}}</tt>
+
| <tt>{{t|item id}}</tt>
−
| Item ID.
+
| The item's spritesheet index.
 
|-
 
|-
−
| <tt>{{t|int cost}}</tt>
+
| <tt>{{t|cost}}</tt>
−
| Cost in shop. (For seeds, this is modified based on profit margin.)
+
| The purchase price in gold. For seeds, this is modified based on the [[Multiplayer#Profit margins|profit margin]].
 
|-
 
|-
−
| <tt>{{t|int amount}}</tt>
+
| <tt>{{t|count available}}</tt>
−
| How many of that item is available from the shop, or -1 for unlimited.
+
| How many of that item can be purchased from the shop, or <tt>-1</tt> for unlimited.
 
|}
 
|}
  
−
==Night Market==
+
==Map==
−
The Night Market is a special festival, as it is handled differently than other festivals.  While there are separate Night Market maps, the NPC data does not 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.
+
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.
  
−
===Raw Data===
+
==Hardcoded logic==
−
{{collapse|Data|content=<syntaxhighlight lang="json">
+
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.
−
{
 
−
  Winter 15:
 
−
Abigail: Beach 30 34
 
−
Shane: Beach 20 24
 
−
Penny: Beach 35 36
 
−
Linus: Beach 19 4
 
−
Leah: Beach 41 35
 
−
Jas: Beach 19 24
 
−
Harvey: Beach 37 31
 
−
Emily: Beach 25 36
 
−
Clint: Beach 37 33
 
−
  Winter 16:
 
−
Vincent: Beach 19 24
 
−
Sebastian: Beach 10 39
 
−
Robin: Beach 13 31
 
−
Maru: Beach 11 33
 
−
Marnie: Beach 37 31
 
−
Lewis: Beach 40 34
 
−
Haley: Beach 27 34
 
−
Demetrius: Beach 11 32
 
−
Caroline: Beach 24 32
 
−
  Winter 17:
 
−
Sam: Beach 11 34
 
−
Jodi: Beach 20 24
 
−
George: Beach 11 39
 
−
Evelyn: Beach 12 39
 
−
Elliot: Beach 38 36
 
−
Alex: Beach 27 24
 
−
}
 
−
</syntaxhighlight>}}
 
  
 +
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.
  
 
[[Category:Modding]]
 
[[Category:Modding]]

Revision as of 17:26, 9 May 2021

← Index

This page explains how the game stores and uses festival data. This is an advanced guide for mod developers.

Data file

Each festival has a data file located at Content/Data/Festivals/<season><day of month>. 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

The festival data file can be unpacked for editing. For example, here's the raw data from Content/Data/Festivals/fall16 as of 1.5.4 for reference:

Data  
{
  "name": "Spirit's Eve",
  "conditions": "Town/2200 2350",
  "shop": "BO 113 5000 1 O 746 750 5 BL 746 2000 1 BO 47 350 -1 F 2870 4000 -1",
  "set-up": "spirits_eve/-1000 -1000/farmer 12 54 1/changeToTemporaryMap Town-Halloween/loadActors Set-Up/advancedMove Maru true 0 2 2 0 0 3 -11 0 0 -7 5 0 0 2 4 0/advancedMove Alex true -4 0 4 4000 4 0 4 5000/advancedMove Jas true 1 1500 4 1000/advancedMove Pam true 0 1 1 5000 0 -1 1 5000/advancedMove Shane true -7 0 0 2 2 9000 0 -2 7 0 4 9000/advancedMove Demetrius true 3 18000 4 3000/addTemporaryActor Skeleton 16 32 30 59 2 false Monster/advancedMove Skeleton true 0 1 3 4000 2 0 0 -1 4 2000 -1 0 3 1000 2 2000 0 -1 4 4000 -1 0 0 1 2 5000/addTemporaryActor Skeleton 16 32 35 58 2 false Monster/playerControl halloween",
  "Abigail_spouse": "You'll have to tell me what's beyond, I can't go on... spiders...$s",
  "Leah_spouse": "I may have had a little too much pumpkin ale...",
  "Maru_spouse": "I'm confused... you go on ahead and let me figure this out.",
  "Penny_spouse": "Oh... These vapors... Hmmm... You look nice tonight.$l",
  "Haley_spouse": "I get scared easily... I think I'm just going to stay right here.$s",
  "Sebastian_spouse": "It would be interesting to have one of these on the farm.",
  "Sam_spouse": "Hey, I was wondering when you'd show up!$h",
  "Harvey_spouse": "Hi... I was hoping you'd find me here...$l",
  "Elliott_spouse": "Mmph... I believe I've eaten a few too many slices of pumpkin pie.",
  "Abigail": "I can't go on... spiders...$s",
  "Robin": "Well, winter's almost here. It's a great time to stockpile wood and stone.",
  "Demetrius": "I haven't seen Maru in hours... I hope she's alright.",
  "Maru": "I think I've already been this way... no, wait...$s#$e#I'm lost...$s",
  "Sebastian": "I have no idea how these skeletons are walking... creepy.#$e#It's pretty cool though.",
  "Pierre": "??",
  "Caroline": "I get scared very easily. I'll leave the haunted maze to the younger people.",
  "Linus": "Good show, old friend.",
  "Alex": "There's something weird over there. But how do I get to it?#$e#There's gotta be a secret passage somewhere around here.",
  "George": "Hmm... smoked turkey haunch? I guess this festival isn't all bad.$h",
  "Evelyn": "I wish Gus would include a vegetarian option. Some zucchini skewers, maybe?",
  "Lewis": "Good evening, @. Have you ventured into the haunted maze yet? It's quite spooky.#$e#That strange man who lives in the tower set it all up himself. He wouldn't let anyone near while he was working on it.",
  "Clint": "One of my iridium-infused maces would make quick work of these things.",
  "Emily": "Do you like the jack-o-lanterns? I carved them myself.",
  "Penny": "The vapor from this cauldron... it's making my head spin, but I can't seem to leave...$u",
  "Pam": "I'll come to any event with free grub! You won't see me in the haunted maze, though.",
  "Haley": "Eek! I'm too scared.$s",
  "Jodi": "Vincent's upset that I won't let him go into the haunted maze... but he's just a little boy!",
  "Kent": "Hey, @. Nice evening, isn't it?",
  "Sam": "That's odd... It's just a dead end up ahead.#$e#I could've sworn there was someone ahead of me when I went through the maze, though. Where'd they go?",
  "Leah": "Mm, hi. Sorry... mouth full of blackberries.",
  "Marnie": "Hi, @. Have you had a productive fall?#$e#It's starting to get quite cold... crops won't hold out for much longer.",
  "Elliott": "Why, hello @. It's chilly, isn't it?",
  "Gus": "It's a lot of fun to cook with pumpkin. Such an interesting fruit.",
  "Dwarf": "You say it's raining up above? *gasp*#$e#Rain... It's almost mythical to us. Some of us live our entire lives without ever experiencing it.",
  "Wizard": "The affairs of mundane folk matter little to me, but the elementals like a chance to see you up close.#$e#It was for them that I created this silly maze.",
  "Harvey": "Oh! You found me...$8#$b#The truth is, I got too scared so I came here to hide. Don't tell anyone.$s",
  "Shane": "Why is there no more pumpkin ale?",
  "Sandy": "I heard it's raining back home. Is that why you came here?$h#$e#I kind of miss the rain, actually...$s",
  "Jas": "But Aunt Marnie! I wanna go in the maze! I'm not scared!$s",
  "Vincent": "Mother won't let me go in the maze. *sob*$s",
  "Marlon": "Don't get too close to the cage.",
  "Leo": "%Leo's unblinking eyes are glued to the screen. You're unable to get his attention."
}

Format

field key explanation
name The festival name. This is used in display text like the calendar tooltip or the festival-is-ready message.
conditions When and where the festival takes place. The format is <location><start time> <end time>, where <location> is the internal location name and the times are specified in 26-hour format (i.e. 600 for 6am to 2600 for 2am).
shop The items the festival shop sells. See shop format below.
set-up The event script that's run when the player first enters the festival. This includes moving the player to the festival map.
<NPC name>_spouse The dialog line the named NPC will say when the player talks to them, if they're married to the player.
<NPC name> The dialog line the named NPC will say when the player talks to them, if <NPC name>_spouse doesn't exist or apply.

Any other entry is event data for a cutscene during the festival. In some cases like the Luau, these are linked together when played in the game.

Shop format

The shop data for a festival is stored as four space-separated values in the format <item type> <item ID> <cost> <count available>, which is repeated for each item. Field formats:

field explanation
<item type> The item type. The valid values are B (boots), BL (blueprint), BBL or BBl (big blueprint), BO (bigcrafable object), F (furniture), H (hat), O (object), R (ring), or W (weapon).
<item id> The item's spritesheet index.
<cost> The purchase price in gold. For seeds, this is modified based on the profit margin.
<count available> How many of that item can be purchased from the shop, or -1 for unlimited.

Map

Most festivals use a separate map file located in the Content/Maps folder. The map to use is specified in the data file's set-up field using the changeToTemporaryMap command.

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.

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.

Retrieved from "https://stardewvalleywiki.com/mediawiki/index.php?title=Modding:Festival_data&oldid=120354"