Modding:Event data

From Stardew Valley Wiki
Revision as of 16:48, 14 June 2024 by Pathoschild (talk | contribs) (link to audio page instead of directly to older spreadsheet)
Jump to navigation Jump to search


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

Raw data

Events are stored in Content\Data\Events\*.xnb (one file per location), which can be unpacked to edit. Here's the raw data for events in Pam's trailer as of 1.5.1 for reference:

  "35/f Penny 1000/p Penny": "50s/-1000 -1000/farmer -30 30 0 Penny 12 7 0 Pam -100 -100 0/skippable/specificTemporarySprite pennyMess/viewport 12 7 true/pause 1000/speak Penny \"Ughh... It's so dirty in here.$s\"/pause 500/warp farmer 12 9/playSound doorClose/pause 500/faceDirection Penny 2/pause 500/emote Penny 16/pause 300/speak Penny \"@! Um... Sorry that it's such a mess. I was about to clean up.$u\"/pause 500/move farmer 0 -1 0/pause 600/emote Penny 32/pause 300/speak Penny \"You'll help me? You really mean it?$h\"/pause 500/faceDirection Penny 1/faceDirection farmer 1/speak Penny \"Okay, you can get started over there. I'll clean the kitchen.\"/move farmer 2 0 1/move farmer 0 -2 1/move farmer 1 0 1/move Penny -1 0 0/animate Penny false true 100 24 25/animate farmer false true 100 35/pause 200/playSound dwop/removeSprite 16 6/pause 200/move Penny -1 0 0/animate Penny false true 100 24 25/stopAnimation farmer/faceDirection farmer 0/pause 1200/stopAnimation Penny/removeSprite 10 5/playSound dwop/move Penny -1 0 0/animate Penny false true 100 24 25/pause 900/animate farmer false true 100 41/pause 300/playSound dwop/removeSprite 15 5/stopAnimation farmer/pause 1400/stopAnimation Penny/move Penny 1 0 0/pause 800/warp Pam 12 9/playSound doorClose/stopMusic/move Pam 0 -1 0/faceDirection Penny 2/faceDirection farmer 3/faceDirection Pam 1/pause 500/faceDirection Pam 3/speak Pam \"Whaddya think you're doing?!$u\"/faceDirection Pam 1/faceDirection Pam 3/faceDirection Pam 0/speak Pam \"Stop it! I had everything just the way I like it!$u\"/move Penny 2 0 2/pause 500/emote Penny 28/pause 500/speak Penny \"Mom, the house is a total mess. @ and I were just trying to tidy things up a bit.#$b#*sniff* *sniff*... Were you at the saloon just now? You smell like beer...$s\"/pause 300/move Pam -1 0 3/emote Pam 12/pause 400/speak Pam \"It's none of your damn business where I go!$4\"/pause 500/speak Penny \"It IS my business! I don't want you destroying yourself!$a#$b#Don't you realize your choices have an effect on me? Stop being so selfish!$a\"/faceDirection Pam 0/shake Pam 5000/pause 600/speak Pam \"Selfish? I put a roof over your head and clothes on your back and you call me selfish!? You ungrateful little...$u\"/pause 500/emote farmer 28/pause 500/faceDirection Pam 1/faceDirection Penny 1/move farmer -2 0 2/move farmer 0 2 3/pause 500/speak Pam \"You'd better go. I'm sorry you had to see this, kid.$4\"/pause 500/move farmer -1 0 2/move farmer 0 1 2/pause 500/faceDirection farmer 0/faceDirection Penny 2/pause 700/faceDirection farmer 2/pause 500/warp farmer -40 -40/playSound doorClose/pause 500/move Pam 0 -1 1/pause 300/faceDirection Penny 3/speak Pam \"He's a nice young man...^She's a nice young lady...\"/speak Pam \"But I don't want you tellin' others to clean up my house! It's embarrassing! You understand?$4\"/pause 300/faceDirection Penny 2/pause 600/showFrame Penny 23/pause 700/speak Penny \"...Yes, mother.$s\"/pause 1000/mail PennyCleanTrailer/end warpOut",
  "36/f Penny 1500/p Penny": "musicboxsong/9 7/farmer -30 30 0 Penny 9 7 0/skippable/pause 1000/playSound doorClose/warp farmer 12 9/pause 400/faceDirection Penny 2/pause 300/speak Penny \"@, you came at a good time!#$b#I'm just about finished cooking a new recipe I invented!$h\"/pause 400/move farmer 0 -2 3/faceDirection Penny 1/move farmer -2 0 3/speak Penny \"Let me just finish up real quick.\"/pause 200/faceDirection Penny 0/pause 200/animate Penny false true 120 29 30/playSound crafting/pause 320/playSound crafting/pause 320/playSound crafting/pause 320/playSound crafting/pause 320/stopAnimation Penny/pause 500/playSound openBox/showFrame Penny 29/pause 400/playSound furnace/showFrame Penny 30/pause 1500/playSound clank/faceDirection Penny 0/pause 500/faceDirection Penny 1 true/showFrame Penny 28/speak Penny \"Here, give that a little taste.\"/pause 800/faceDirection farmer 2/farmerEat 200/showFrame Penny 4/pause 2500/stopAnimation farmer/pause 500/playSound gulp/animate farmer false true 350 104 105/pause 500/specificTemporarySprite pennyCook/pause 1500/faceDirection farmer 2/pause 500/speak Penny \"$q 72 null#...well?#$r 72 50 event_cook1#(Lie) Mmm! That was delicious!#$r 73 -50 event_cook2#Uh... can I get the rest to go?#$r 73 0 event_cook3#Well it's definitely unique... how did you get it so rubbery?\"/pause 500/speak Penny \"$p 72#Hey, since you're the first person to try it, I'm going to name this one 'Chili de @'.$h|Well, I guess this recipe was a failure...$s\"/stopAnimation farmer/faceDirection farmer 3/pause 600/speak Penny \"Um... so how about we watch a movie or something?\"/pause 500/move farmer 5 0 0 true/move Penny 5 0 0 true/globalFade/viewport -1000 -1000/end dialogue Penny \"Thanks for being my taste-tester.$h\"",
  "963313/n pamPotatoJuice": "playful/10 7/farmer -100 -100 0 Pam 10 7 0/mail pamNewChannel/skippable/pause 3000/speak Pam \"Heheh... I see the delivery came in.$h\"/pause 500/speak Pam \"Let's have a little taste.$h\"/pause 1000/playSound coin/showFrame Pam 32/pause 2000/animate Pam false true 400 33 34/playSound glug/pause 800/playSound glug/pause 800/playSound glug/pause 800/playSound glug/pause 790/stopAnimation Pam/showFrame Pam 32/pause 400/emote Pam 40/pause 800/showFrame Pam 35/textAboveHead Pam \"Ptooey!\"/playSound slimedead/shake Pam 2000/pause 2000/animate Pam false true 400 28 29/speak Pam \"I said potato, not fermented baboon kidney!$u\"/pause 2000/end dialogue Pam \"The juice? Yeah, I tried it, kid. $4#$b#How'd it taste? ...Some things are better left unsaid. Let's just leave it at that.$4\""

Event preconditions

Each event has a key which includes an event ID and any preconditions. Event IDs are a max of 10 digits, with a maximum value of 2147483647 (based on the game coding).

You may use any ID for testing BUT When you are ready to publish, you are recommended to use the four or five digit mod ID you get from Nexus (found in the mod page URL) as the prefix instead. Note that any other id (like last 4 digit of user id is not guarenteed to be unique across other mods) You can actually reserve an ID for your mod in Nexus by creating the page without clicking "Publish". Of course, this is not a rule, but a good convention to prevent mods from clashing. If uploading to Moddrop or another site instead, adjust according to the number of digits found in that site's IDs.

Event preconditions include any number of the following arguments (separated by /). For example, Clint's Saloon heart event preconditions are 97/f Clint 750/t 1900 2300/d Tue Wed Thu Fri Sat Sun, which (per the tables below) means event #97, requires 3 hearts with Clint, between 7pm and 11pm on Monday.


  • 'NPC name' means their internal English name, not the translatable display name.
  • Most text is case-sensitive (e.g., Mon is not the same as mon).
  • The game's logic for these codes is in GameLocation::checkEventPrecondition.


These check the current time, date, weather, etc. They're not player-specific.

syntax precondition
A <dialogue ID> The special dialogue event with the given ID (including Conversation Topics) is not in progress. This can be a custom event ID, but these are the in-game IDs: cc_Begin, cc_Boulder, cc_Bridge, cc_Bus, cc_Complete, cc_Greenhouse, cc_Minecart, dumped_Girls, dumped_Guys, Introduction, joja_Begin, pamHouseUpgrade, pamHouseUpgradeAnonymous, secondChance_Girls, secondChance_Guys, shaneSaloon1, shaneSaloon2, willyCrabs.
F Today is not a festival day.
U <day count> There are no festivals within the specified number of days from today.
d <day of week> Today is not one of the specified days (may specify multiple days). Valid values: Mon, Tue, Wed, Thu, Fri, Sat, Sun.
r <number> A random probability check, where <number> is the probability between 0 and 1 (e.g., 0.2 for 20% chance).
v <name> The specified NPC is not invisible (regardless of whether they're on-screen).
w <weather> Current weather matches <weather>. Valid values: rainy, sunny.
y <year> If <year> is 1, must be in the first year. Otherwise, year must be at least this value.
z <season> Current season is not <season>.
N <number> The players in total have found at least this many golden walnuts.

Current player

These check the current player (the one playing this instance of the game).

syntax precondition
B Current player has a double bed in the farmhouse if married; single bed if roommates (Krobus excluded).
D <name> Current player is dating the given NPC name.
J Current player has finished the Joja Warehouse.
L Event is in the FarmHouse and the FarmHouse has been upgraded at least twice (has nursery but not necessarily cellar). Only works inside the FarmHouse, always false outside.
M <number> Current player has at least this much money.
O <name> Current player is married to that NPC.
S <secret note ID> Current player has seen the Secret Note with the given ID.
a <x> <y> Current player entered the map on that tile position. Note that since events are only checked for while entering a map, you can only use tiles that other maps warp to.
b <number> Current player has reached the bottom floor of the Mines at least that many times.
c <number> Current player has at least that many free inventory slots.
e <event ID> Current player has seen the specified event (may contain multiple event IDs).

Usage: /e <event ID> means has seen that event, then /e <event ID> <event ID> means has seen EITHER events, and /e <event ID>/e <event ID> means has seen BOTH events.

f <name> <number> Current player has at least <number> friendship points with the <name> NPC. Can specify multiple name and number pairs, in which case the player must meet all of them.
g <gender> Current player is the specified gender (male or female).
h <pet> Current player does not already have a pet, and their preference matches <pet> ("cat" or "dog").
i <item ID> Current player has specified item in their inventory.
j <number> Current player has played more than <number> days.
k <event ID> Current player has not seen that event (may contain multiple event IDs).
l <letter ID> Current player has not received that mail letter or non-mail flag.
m <number> Current player has earned at least this much money (regardless of how much they currently have).
n <letter ID> Current player has received that mail letter or non-mail flag.
o <name> Current player is not married to that NPC.
p <name> Specified NPC is in the current player's location.
q <dialogue ID> Current player has chosen the given answer in a dialogue. May contain multiple dialogue IDs, in which case they must all have been selected.
s <item ID> <number> Current player has shipped at least <number> of the specified item. Can specify multiple item and number pairs, in which case all of them must be met. This only works for the items tracked by the game for shipping stats (shown in the shipping collections menu).
t <min time> <max time> Current time is between between the specified times. Can range from 600 to 2600.
u <day of month> Current day of month is one of the specified values (may contain multiple days).
x <letter ID> For the current player: mark this event as seen, add the specified letter to tomorrow's mail, then return false (so that nothing further happens). Use the format "x letterid true" to send the letter immediately.

Host player

These check the host player (the one running a multiplayer farm, not necessarily the current player). If single-player, this is always the current player.

syntax precondition
C Host player has finished the Community Center or Joja Warehouse.
X Host player has not finished the Community Center or Joja Warehouse.
H Current player is the host player.
Hl <letter ID> Host player has not received that mail letter or non-mail flag.
Hn <letter ID> Host player has received that mail letter or non-mail flag.
*l <letter ID> Host player and current player have not received that mail letter or non-mail flag.
*n <letter ID> Host player and current player have received that mail letter or non-mail flag.

Event scripts

Basic format

Each event has a value which is the event script. This specifies what happens in the event — everything from lighting and music to NPC movement and dialogue. The script consists of multiple commands separated by / characters.

Every script must start with three commands in this exact order:

index syntax description
0 <music ID> The background music or ambient background track to play. Can be changed later using playMusic <newmusic>, or stopped entirely using stopMusic. This can also be none (which stops any existing music and uses the default ambient background noise for the location), or continue (which keeps playing the current background song).
1 <x> <y> The tile coordinates the camera should center on at the start of the event.
2 [<character ID> <x> <y> <direction>]+ Initialises one or more characters' starting tile positions and directions. The character ID can be farmer or an NPC name like Abigail.

Those three commands may be followed by any sequence of the following commands:

command description
addBigProp <x> <y> <object ID> Adds an object at the specified tile from the TileSheets\Craftables.png sprite sheet.
addConversationTopic <ID> [length] Starts a conversation topic with the given ID and day length (or 4 days if no length given). Setting length as 0 will have the topic last only for the current day.
addCookingRecipe <recipe> Adds the specified cooking recipe to the player.
addCraftingRecipe <recipe> Adds the specified crafting recipe to the player.
addFloorProp <prop index> <x> <y> [solid width] [solid height] [display height] Add a non-solid prop from the current festival texture. Default solid width/height is 1. Default display height is solid height.
addLantern <row in texture> <x> <y> <light radius> Adds a glowing temporary sprite at the specified tile from the Maps\springobjects.png sprite sheet. A light radius of 0 just places the sprite.
addMailReceived <letter ID> Set a letter as received.
addObject <x> <y> <sprite index> [layer] Adds a temporary sprite at the specified tile from the Maps\springobjects.png sprite sheet.
addProp <prop index> <x> <y> [solid width] [solid height] [display height] Add a solid prop from the current festival texture. Default solid width/height is 1. Default display height is solid height.
addQuest <quest ID> Add the specified quest to the quest log.
addTemporaryActor <character> <sprite width> <sprite height> <tile x> <tile y> <facing> [breather] [Character|Animal|Monster] [animal name] Add a temporary actor. 'breather' is boolean. The category determines where the texture will be loaded from, default is Character. Animal name only applies to animal.
addToTable <x> <y> <object ID> Places on object on the furniture at a position. UNLESS the location is FarmHouse, then it will always try to place an item onto the first piece of furniture, regardless if it's a table or not (and probably throw an error if there's no furniture.) It'll also actually replace the item on that piece of furniture if there was one previously. Not recommended for use in the farmhouse. May not be used by vanilla at all.
addTool <Sword|Wand> Adds either a Battered Sword or Return Scepter to the player's inventory. The Battered Sword is unobtainable in vanilla and is incomplete and not implemented.
advancedMove <actor> <loop> <x y>... OR <direction duration> Set multiple movements for an actor. You can set True to have the actor walk the path continuously. Example: /advancedMove Robin false 0 3 2 0 0 2 -2 0 0 -2 2 0/

To make the actor move along the x axis (left/right), use the number of tiles to move and 0. For example, -3 0 will cause the actor to walk three tiles to the left while facing left. 2 0 will cause the actor to walk two tiles to the right while facing right.

To make the actor move along the y axis (up/down), use 0 and the number of tiles to move. For example, 0 1 will cause the actor to walk one tile down while facing down. 0 -5 will cause the actor to walk five tiles up while facing up.

To make an actor pause, use the direction to face and the number of milliseconds to pause. 1 is right, 2 is down, 3 is left, and 4 is up. The reason 4 is up and not 0 is so that advancedMove can tell the difference between a pause command and a move up/down command.

The code can tell the difference between a move command and a pause command because a move command must have 0 for either x or y. A pause command must have non-zero numbers for both numbers in the pair.

Example: /advancedMove Clint true 4 0 2 5000 -4 0 1 3000/ Clint will have continuous movement moving 4 tiles to the right, facing down upon arriving, waiting for 5 seconds, then moving 4 tiles to the left, facing right upon arriving, then waiting for 3 seconds, then loops because the loop was set to true(see above).

Example: /advancedMove Pam true 5 0 0 3 3 5000 -6 0 0 -4/ Pam first moves 5 tiles to the right, then directly moves 3 tiles downward, faces the to the left upon arriving then waits 5 seconds before moving 6 tiles to the left then moves up 4 tiles directly.

ambientLight <r> <g> <b> Modifies the ambient light level, with RGB values from 0 to 255.
animalNaming Show the animal naming menu if no other menu is open. Uses the current location as Coop. Appears to only work for 'hatched' animals.
animate <actor> <flip> <loop> <frame duration> <frames...> Animate a named actor, using one or more <frames> from their sprite sheet, for <frame duration> milliseconds per frame. <frames> are indexed numerically, based on 16x32 pieces of the image. This index increases as you go from left to right, starting from 0. <flip> indicates whether to flip the sprites along the Y axis; <loop> indicates whether to repeat the animation until stopAnimation is used. If you're animating the farmer, it may be helpful to reference Modding:Farmer_sprite#Sprite_Index_Breakdown
attachCharacterToTempSprite <actor> Attach an actor to the most recent temporary sprite.
awardFestivalPrize Awards the festival prize to the winner for the easter egg hunt and ice fishing contest.
awardFestivalPrize <item type> Awards the specified item to the player. Possible item types are "pan", "sculpture", "rod", "sword", "hero", "joja", "slimeegg", "emilyClothes", and "jukebox".
beginSimultaneousCommand This command states that the next event commands will all be done at the same time. Must also have endSimultaneousCommand after the commands needed to execute at the same time.
broadcastEvent [local] Makes the event a "broadcast event", forcing others players connected to also see it. Any players connected will be forced to warp to this event. This is used in some vanilla events like when Lewis shows the farmer the abandoned Community Center.

If the "local" option is given (not a boolean), then client players will see the event as if the "farmer" actor was their own farmer instead of the Host farmer. The "local" option isn't used anywhere in the vanilla game.

catQuestion Trigger question about adopting your pet.
cave Trigger the question for the farm cave type. This will work again later, however changing from bats to mushrooms will not remove the mushroom spawning objects.
changeLocation <location> Change to another location and run the remaining event script there.
changeMapTile <layer> <x> <y> <tile index> Change the specified tile to a particular value.
changeName <actor> <displayName> Sets the display name of the actor to displayName, with underscores replaced by spaces.
changePortrait <npc> <portrait> Change the NPC's portrait to be from "Portraits/<actor>_<portrait>".
changeSprite <actor> <sprite> Change the actor's sprite to be from "Characters/<actor>_<sprite>".
changeToTemporaryMap <map> [pan] Change the location to a temporary one loaded from the map file specified by <map>. If the [pan] argument is omitted, also pan to tile coordinates 0, 0 on the new map. If any value is given for [pan], no panning occurs.
changeYSourceRectOffset <npc> <offset> Changes the NPC's vertical texture offset. Example: changeYSourceRectOffset Abigail 96 will offset her sprite sheet, showing her looking left instead of down. This persists for the rest of the event. This is only used in Emily's Clothing Therapy event to display the various outfits properly.
characterSelect Seemingly unused. Sets Game1.gameMode to 5 and Game1.menuChoice = 0.
cutscene <cutscene> Activate a cutscene. See cutscene list.
doAction <x> <y> Acts as if the player had clicked the specified x/y coordinate and triggers any relevant action. It is commonly used to open doors from inside events, but it can be used for other purposes. If you use it on an NPC you will talk to them, and if the player is holding an item they will give that item as a gift. doAction activates objects in the main game world (their actual location outside of the event), so activating NPCs like this is very tricky, and their reaction varies depending on what the player is holding.
dump <group> Starts the special "cold shoulder" and "second chance" dialogue events for the given group (women if group is girls and men if it is anything else.) The cold shoulder event has an id of dumped_Girls or dumped_Guys and lasts 7 days; the second chance event has an id of secondChance_Girls or secondChance_Guys and lasts 14 days. During open beta testing of version 1.3 there was a second parameter which determined the amount of hearts lost, but support for that parameter was removed before release.
endSimultaneousCommand Sets the end of all commands that are to be done simultaneously. Format: beginSimultaneousCommand/<Event Commands>.../endSimultaneousCommand
elliotbooktalk Elliot book talk.
emote <actor> <emote ID> [continue] Make the given NPC name perform an emote, which is a little icon shown above the NPC's head. If continue is specified, the next command will play out immediately. Emotes are stored in Content\TileSheets\emotes.xnb; see list of emotes.
end Ends the current event by fading out, then resumes the game world and places the player on the square where they entered the zone. All end parameters do this by default unless otherwise stated.
end bed Same as end, but warps the player to the x/y coordinate of their most recent bed. This does not warp them to the farmhouse, only to the x/y coordinate of the bed regardless of map.
end beginGame Used only during the introduction sequence in the bus stop event. It sets the game mode to playingGameMode, warps the player to the farmhouse (9, 9), ends the current event, and starts a new day.
end credits Not used in any normal events. Clears debris weather, changes the music to wedding music, sets game mode to creditsMode and ends the current event.
end dialogue <NPC> <"Text for next chat"> Same as end, and additionally clears the existing NPC dialogue for the day and replaces it with the line(s) specified at the end of the command. Example usage: end dialogue Abigail "It was fun talking to you today.$h"
end dialogueWarpOut <NPC> <"Text for next chat"> See end dialogue and end warpOut.
end invisible <NPC> Same as end, and additionally turns the specified NPC invisible (cannot be interacted with until the next day).
end invisibleWarpOut <NPC> See end invisible and end warpOut.
end newDay Ends both the event and the day (warping player to their bed, saving the game, selling everything in the shipping box, etc).
end position <x> <y> Same as end, and additionally warps the player to the map coordinates specified in x y.
end warpOut Same as end, and additionally finds the first warp out of the current location (second warp if male and in the bathhouse), and warps the player to its endpoint.
end wedding Used only in the hardcoded wedding event. Changes the character's clothes back to normal, sets Lewis' post-event chat to "That was a beautiful ceremony. Congratulations!$h", and warps the player to their farm.
extendSourceRect <actor> reset Resets the actors sprite.
extendSourceRect <actor> <horizontal> <vertical> [ignoreUpdates] TODO: Explain Character.extendSourceRect
eyes <eyes> <blink> Change the player's eyes. Eyes is represented by and Integer from 0 - 5 (open, closed, right, left, half closed, wide open). Blink is a timer that is represented with a negative number. -1000 is the default timer.
faceDirection <actor> <direction> [continue] Make a named NPC face a direction. If no parameter is supplied for [continue], the game will pause.
fade [unfade] Fades out to black if no parameter is supplied. If the parameter is unfade (not true), fades in from black.
farmerAnimation <anim> Briefly sets the farmer's sprite to <anim> for a variable (depending on sprite) interval. Only used once in vanilla events. Using showFrame farmer <sprite> twice (to set a new frame and back) is more powerful as it lets you control the interval using pause n.
farmerEat <object ID> Make the player eat an object. (The farmer actually does eat the object, so buffs will apply, healing will occur, etc.)
fork [req] <event ID> End the current command script and starts a different script with the given ID, but only if the [req] condition is met. (Example: /fork choseWizard finalBossWizard in the "Necromancer" script of Sebastian's 6-heart event.) The [req] condition can be a mail ID or dialogue answer ID; if not specified, it checks if the specialEventVariable1 variable was set (e.g., by a question event command or %fork dialogue command). The new script should have the same format as a normal event script, but without the mandatory three start fields.
friendship <npc> <amount> Add the given number of friendship points with the named NPC. (There are 250 points per heart.)
globalFade [speed] [continue] Fade to black at a particular speed (default 0.007). If continue is specified, the event continues as the fade occurs, else the event pauses until the fade is finished. The fade effect disappears when this command is done; to avoid that, use the viewport command to move the camera off-screen.
globalFadeToClear [speed] [continue] Fade to clear (unfade?) at a particular speed (default 0.007). If continue is specified, the event continues as the fade occurs, else the event pauses until the fade is finished.
glow <r> <g> <b> <hold> Make the screen glow once, fading into and out of the <r> <g> <b> values over the course of a second. If <hold> is true it will fade to and hold that color until stopGlowing is used.
grandpaCandles Do grandpa candles
grandpaEvaluation Do grandpa evaluation
grandpaEvaluation2 Do grandpa evaluation (manually resummoned)
halt Make everyone stop.
hideShadow <actor> <true/false> Hide the shadow of the named actor. False unhides it.
ignoreCollisions <character ID> Make a character ignore collisions when moving for the remainder of the event. For example, they'll walk through walls if needed to reach their destination. The character ID can be farmer or an NPC name like Abigail.
ignoreEventTileOffset Tile positions in farm events are offset to match the farmhouse position. If an event shouldn't be based on the farmhouse position, add an ignoreEventTileOffset command to disable the offset for that event. This must be the 4th command (after the 3 initial setup ones) to take effect.
itemAboveHead [type] Show an item above the player's head. The [type] can be "pan", "hero", "sculpture", "joja", "slimeEgg", "rod", "sword", or "ore". If no item is specified, then they will 'hold' nothing? Arbitrary items are not supported.
jump <actor> [intensity] Make a the named NPC jump. The default intensity is 8.
loadActors <layer> Load the actors from a layer in the map file.
makeInvisible <x> <y> [x-dimension] [y-dimension] Temporarily hides selected objects or terrain features: the tile(s) will become passable for the duration of the event. Useful for clearing a walking area during events, especially in the FarmHouse. (Example: /makeInvisible 8 14 hides any object or terrain feature at tile 8, 14 in the current map.) The optional [x-dimension] and [y-dimension] arguments allow you to specify a larger area to be cleared. (Example: /makeInvisible 68 36 13 7 in Leah's 14-heart event clears a 13 × 7 tile rectangular area with the top-left corner at coordinate 68, 36.). Known bugs: some furniture may not re-appear immediately?
mail <letter ID> Queue a letter to be received tomorrow (see Content\Data\mail.xnb for available mail).
message "<text>" Show a dialogue box (no speaker). See dialogue format for the <text> format.
minedeath TODO.
money <amount> Adds/removes the specified amount of money.
move <actor> <x> <y> <facing> <continue> Make a named NPC move by the given tile offset from their current position (along one axis only), and face the given direction when they're done. To move along multiple axes, you must specify multiple move commands. By default the event pauses while a move command is occurring, but if <continue> is set to true the movement is asynchronous and will run simultaneously with other event commands. You can also move multiple people at a time in a single event command with move - an example of /move Abigail 1 0 1 Sam 0 1 1 Sebastian 2 0 1/ will have Abigail, Sam, and Sebastian all move at the same time in their respective directions.
pause <duration> Pause the game for the given number of milliseconds.
playMusic <track> Play the specified music track ID. If the track is 'samBand', the track played will change depend on certain dialogue answers (76-79).
playSound <sound> Play a given sound ID from the game's sound bank.
playerControl Give the player control back.
positionOffset <actor> <x> <y> Offset the position of the named NPC by the given number of pixels. This happens instantly, with no walking animation.
proceedPosition <actor> TODO: Explain
question null "<question>#<answer1>#<answer2>" Show a dialogue box with some answers and an optional question. When the player chooses an answer, the event script continues with no other effect.
question fork<answer index> "<question>#<answer 0>#<answer 1>#..." Show a dialogue with some answers and an optional question. When the player chooses the answer matching the fork<answer index> (like fork0 for the first answer), the specialEventVariable1 variable is set. Usually followed by a fork command. Example:
.../question fork0 \"#answer0#answer1#answer3\"/fork eventidhere/..."
quickQuestion <question>#<answer1>#<answer2>#<answer3>(break)<answer1 script>(break)<answer2 script>(break)<answer3 script> Show a dialogue box with an optional question and some answers. The answer scripts are sequences of commands separated by \\. When the player chooses an answer, the relevant answer script is executed and then the event continues. Usually used when an NPC's response will depend on the answer chosen but nothing else in the event has to depend on it.
  • Note: If quickQuestion is used immediately at the start of an event block (Example: "ExampleEvent": "quickQuestion [rest of the event]"), it will cause a dialogue loop. Adding another command in front of quickQuestion resolves this issue (Example: "ExampleEvent": "pause 1/quickQuestion [rest of the event]").
removeItem <object ID> Remove the first of an object from a player's inventory.
removeObject <x> <y> Remove the prop at a position.
removeQuest <quest ID> Remove the specified quest from the quest log.
removeSprite <x> <y> Remove the temporary sprite at a position.
removeTemporarySprites Remove all temporary sprites.
removeTile <x> <y> <layer> Remove a tile from the specified layer.
resetVariable Set the specialEventVariable1 to false.
rustyKey Gives the player the rusty key. (Sewer key)
screenFlash <alpha> Flashes the screen white for an instant. An alpha value from 0 to 1 adjusts the brightness, and values from 1 and out flashes pure white for x seconds.
setRunning Set the player as running.
shake <actor> <duration> Shake the named NPC for the given number of milliseconds.
showFrame farmer <frame> <flip> Flip the farmer's current sprite along the Y axis. Farmer looks strange if not facing the correct direction prior to 1.6. Flip is a true/false value.
showFrame <actor> <frame ID> Set the named NPC's current frame in their Content\Characters\*.xnb spritesheet. Note that setting the farmer's sprite only changes parts of the sprite (some times arms, some times arms and legs and torso but not the head, etc). To rotate the whole sprite, use faceDirection farmer <0/1/2/3> first before modifying the sprite with showFrame. Frame ID starts from 0. If farmer is the one whose frame is being set, "farmer" can be eliminated, i.e., both showFrame farmer <frame ID> and showFrame <frame ID> would work.
showRivalFrame <frame> Set the 'rival' actor's sprite to a specific frame.
skippable Allow skipping this event.
speak <character> "<text>" Show dialogue text from a named NPC; see dialogue format.
specificTemporarySprite <sprite> [other params] Shows the given temporary sprite. Parameters change depending on the sprite. These are quite hardcoded and probably not easily reusable, other than the little heart.
speed farmer <modifier> Add a speed modifier to the farmer. Is persistent and you will have to use the command again to return to normal speed.
speed <actor> <speed> Sets the named NPC's speed (default speed is 3). Not applicable to the farmer. Applies only through the end of the next movement or animation on that NPC.
splitSpeak <actor> "<text>" Dialogue, but chosen based on previous answer. ('~' is the separator used.)
startJittering Make the player start jittering.
stopAdvancedMoves Stop movement from advancedMove.
stopAnimation farmer Stop the farmer's current animation.
stopAnimation <actor> [end frame] Stop the named NPC's current animation. Not applicable to the farmer.
stopGlowing Make the screen stop glowing.
stopJittering Make the player stop jittering.
stopMusic Stop any currently playing music.
stopRunning Make the farmer stop running.
stopSwimming <actor> Make an actor stop swimming.
swimming <actor> Make an actor start swimming.
switchEvent <event ID> Changes the current event (ie. event commands) to another event in the same location.
taxvote Trigger voting for or against a 3% shipping tax. (No effect on game?)
temporarySprite <x> <y> <row in texture> <animation length> <animation interval> <flipped> <layer depth> Create a temporary sprite with the given parameters, from the resource TileSheets/animations.
temporaryAnimatedSprite <texturename> <source_x> <source_y> <source_width> <source_height> <interval> <length> <loops> <tile_x> <tile_y> <flicker> <flip> <depth> <fade> <scale> <scale_change> <rotation> <rotation_change> + Creates a temporary sprite with the given parameters. Can also accept the following optional, named parameters afterwards, in space-separated pairs. <color> <hold_last_frame> <ping_pong> <motion> <acceleration> <acceleration_change>
textAboveHead <actor> \"<text>\" Show a small text bubble over the named NPC's head with the given text; see dialogue format.
tutorialMenu Show the tutorial menu if no other menu is open.
updateMinigame <event data> Send an event to the current minigame.
viewport move <x> <y> <duration> Pan the the camera in the direction (and with the velocity) defined by x/y for the given duration in milliseconds. Example: "viewport move 2 -1 5000" moves the camera 2 pixels right and 1 pixel up for 5 seconds. The total distance moved is based on framerate, rather than time, and may be inconsistent.
viewport <x> <y> [true [unfreeze]|clamp [true|unfreeze]] Instantly reposition the camera to center on the given X, Y tile position. TODO: explain other parameters.
waitForAllStationary Waits for all actors to stop moving before executing the next command.
waitForOtherPlayers Wait for other players (vanilla MP).
warp <actor> <x> <y> Warp the named NPC to a position to the given X, Y tile coordinate. This can be used to warp characters off-screen.
weddingSprite <frame> Sets the actor known as 'WeddingOutfits' to a particular frame.

Some commands are broken or unusable:

command description
grabObject <object ID> Broken. Triggers a generic animation. The item ID is ignored and the item isn't added.
end busIntro Supposed to start the bus intro scene, presumably the one that was cut before release.


A command which begins with -- is ignored. This can be used to insert comments or to disable commands temporarily while debugging an event. The comment ends at the next slash delimiter (/), so it can't contain slashes.

For example:

"666/": "none/-1000 -1000/farmer 5 7 0/skippable/viewport 5 7 10/--set viewport near door/pause 2000/end"


When event commands refer to a facing direction, they'll use one of these values:

Value Meaning
0 looking up
1 looking right
2 looking down
3 looking left


The cutscene command will accept the following values:

Value In-game scene
AbigailGame Sets up Journey of the Praire King mini-game with Abigail
addSecretSantaItem Feast of the Winter Star gift scene
balloonChangeMap Changes to the "in the balloon" map for Harvey's 10 heart event
balloonDepart Balloon taking off in Harvey's 10 heart event
bandFork Plays correct scene for Sam's 8 heart event, based on response given in 2 heart event
boardGame Sets up Solarion Chronicles mini-game
clearTempSprites Removes all temporary sprites from map
eggHuntWinner Egg Hunt winner scene
governorTaste Luau soup scene
greenTea Caroline sunroom scene from her 2 heart event
haleyCows Haley meeting the cows from her 8 heart event
iceFishingWinner Festival of Ice fishing contest winner scene
iceFishingWinnerMP Sets up text message displayed when leaving Festival of Ice
linusMoneyGone ??? (seems to be unused)
marucomet Maru Comet scene from her 14 heart event
plane Plane flying by from Harvey's 8 heart scene
robot MarILDA taking off from Maru's 10 heart scene

Dialogue format

See Modding:Dialogue#Format.

Common values


An emote is an animated icon bubble shown above an NPC's head to indicate a mood or reaction. Emote icons are stored in the TileSheets\emotes asset.

ID Character constant
4 emptyCanEmote
8 questionMarkEmote
12 angryEmote
16 exclamationEmote
20 heartEmote
24 sleepEmote
28 sadEmote
32 happyEmote
36 xEmote
40 pauseEmote
44 unused
48 unused
52 videoGameEmote
56 musicNoteEmote
60 blushEmote

See also