« back to index

Creating an XNB mod

This page explains how to create a mod which replaces game files in order to change game data, images, and maps.


How XNB mods work

The game stores data in a compressed format with the .xnb file extension inside its Content folder. For example, Abigail’s portrait shown during dialogue is from Content\Portraits\Abigail.xnb. Each .xnb file contains two files: the data file (like an image), and a metadata file (information about the data file). For example, here’s what’s inside Content\Portraits\Abigail.xnb:


In the above example:

An XNB mod replaces some of the game’s XNB data files, which lets you change images (like portraits, NPCs, or buildings), data (like crop information or dialogue), or maps (including map behaviour like warps and minigames). XNB mods can also add entirely new content (like new NPCs).

XNB mods versus SMAPI mods

SMAPI is a modding API that lets you change the game using code. SMAPI mods are more powerful, easier to install and remove, and allow multiple mods to change the same content. On the other hand, SMAPI requires you to write code and some things (like changing images) are easier with XNB mods.

If you have programming experience, creating a SMAPI mod is recommended instead if feasible.

For more details, see using mods for an introduction.

Where can I get help?

The Stardew Valley modding community is very welcoming. Feel free come chat on Discord or post in the forums.

Getting started

First-time setup

  1. Before you start, you should install these:
    • XNB Extract 0.2.2 is a toolkit for unpacking and packing the game’s XNB files. (See forum post.)
    • To edit images:
      • Paint.NET lets you edit image files. (If you already have a favourite image editor, feel free to use that instead.)
    • To edit maps:
      • tIDE 2.0.8 is a map editor for the game’s map format. This version was customised by Kithi to enable conversion between the game’s .tbin files and the .tmx files we’ll be editing. It fixes an issue where exporting to .tmx would lose tile data like animations.
      • Tiled is the map editor we’ll use to edit the game’s maps. It has some advantages over tIDE like automatic edge-fixing, better performance, fewer bugs when editing Stardew Valley maps, and features like copying & pasting between maps.
  2. You should back up your game’s Content folder now, so you can recover the original files if you make a mistake.

Unpack & pack game files

You can’t edit an .xnb file itself, you need to edit the file that’s inside it. Pulling out that inner file is called unpacking, and putting it back is called packing. Here’s how to do it:

  1. Download XNB Extract (see first-time setup).
  2. Unpack the file for editing:
    1. Find the file you want to edit in the Contents folder.
    2. Copy it into XNB Extract’s Packed folder.
    3. On Windows, double-click UnpackFiles.bat.
      On Linux/Mac, run the command inside UNPACK FILES.bat.
  3. Edit the unpacked file (see below).
  4. Repack the file for the game:
    1. On Windows, double-click PackFiles.bat.
      On Linux/Mac, run the command inside PackFiles.bat.
    2. Move the repacked .xnb file back to the original location.

Editing a spritesheet

Basic concepts

A spritesheet is just an image file that contains many smaller images in a regular grid pattern:


Each square in the spritesheet’s grid pattern is called a sprite, and is typically 16×16 pixels. For example, here’s a single sprite from the above spritesheet:


Note that sprites might be drawn next to each other to create the illusion of a larger object:


Making changes

Spritesheets are easy to edit:

  1. Unpack the file you want to change.
  2. Open the unpacked .png file in Paint.NET (or your preferred image editor).
  3. Make changes directly to the image.
  4. Repack the file and copy it back to the original location.

That’s it! You can launch the game to see your changes.

Editing a map

Basic concepts

The following settings in Tiled are strongly recommended:

setting value reason
View > Snap to Grid ✓ enabled This is required to convert objects back into the game’s format.
Highlight Current Layer ✓ enabled This makes it more clear which tile you’re editing.

Making changes

Here’s how to edit a Stardew Valley map:

  1. Get the file for editing:
    1. Unpack the file you want to change.
    2. Open the unpacked .tbin file in tIDE.
    3. Resave the file as “Tiled XML Map Files (*.tmx)”.
    4. When asked how to store the layer data, choose “CSV”.
  2. Make your changes:
    1. Open the .tmx file in Tiled.
    2. Make the desired changes (see the Tiled documentation and next sections).
    3. Save the file.
  3. Repack the file for the game:
    1. Open the .tmx file in tIDE.
    2. Resave the file as “tIDE Binary Map Files (*.tbin)”.
    3. Repack the file and copy it back to the original location.

The Tiled documentation might help with questions about using it.

Tile coordinates

Each tile has an (x, y) coordinate which represents its position on the map, where (0, 0) is the top-left tile. The x value increases towards the right, and y increases downwards. For example:

Using custom sprites

You can add custom sprites (images) to a map:

  1. Create your spritesheet. This should be a PNG image with images divided into 16x16 tiles (see basic concepts for examples).
  2. Open the map in Tiled.
  3. Add the custom spritesheet:
    1. In the Tilesets pane, click the new tilesheet button.
    2. Give it a descriptive name (like ‘cute bugs’) and choose the image source.
    3. Keep the default settings and click OK.
  4. Add custom sprites to the map:
    1. In the Layers pane, click the layer you want to edit.
    2. In the Tilesets pane, click the tab for your custom spritesheet.
    3. In the Tilesets pane, click one tile to select it. To choose multiple, click and drag the cursor.
    4. Move the cursor to the map, and you’ll see an overlay with the tiles you selected.
    5. Click the map to place those tiles on the selected layer.

Map properties

Each map can have multiple map properties, which define attributes and behaviour associated with the map like lighting, music, warp points, etc. Each property has a name (which defines the type of property) and value (which configures the property).

To view and edit map properties in Tiled, click Map on the toolbar and choose Map Properties.

Known map properties1:

property explanation
AmbientLight {int r} {int g} {int b} Sets the RGB colour of the ambient light.
Example: AmbientLight 95 95 95 for a normal indoor daytime lighting.
BrookSounds [{int x} {int y} {int sound}] Adds sound sources. The x y fields are the tile coordinates, and sound is the ambient sound ID.
DayTiles [{string layer} {int x} {int y} {int type}]+ Sets which tiles should glow during the day to simulate sunlight streaming through windows. The layer field is the map layer name, x y are the tile coordinates, and type specifies the glow type (e.g. 256 and 288 for an upper and lower window).
Example: DayTiles Front 3 1 256 Front 3 2 288.
Doors {int x} {int y} {string sheetID} {int tileID} Adds a door. The x y fields are the tile coordinates, sheetID is the name of the sheet containing the door sprite, and tileID is the tile index in the spritesheet.
Fall_Objects T2
Spring_Objects T2
Summer_Objects T2
Winter_Objects T2
Whether to spawn seasonal objects on spawnable tiles based on the data in Data\Locations.xnb.
Example: Fall_Objects.
Light [{int x} {int y} {int type}]+ Adds light sources. The type field is the kind of light source (e.g. 4 for twin candles), and x y are the tile coordinates.
Example: Light 3 8 4 6 8 4 11 8 4 3 2 5 10 2 5 6 19 5 5 15 5 5 11 5 11 12 5 (Adventurer’s Guild).
Music {str name} Sets the music that plays when the player enters, where name is the cue name in the audio files.
Example: Music MarlonsTheme.
NightTiles [{string layer} {int x} {int y} {int type}]+ Like DayTiles for moonlight at night.
Outdoors T2 Sets whether the location is outdoors.
Example: Outdoors true.
TreatAsOutdoors T2 ?
Trees [{int x} {int y} {int type}]+ Adds trees to the map. The x y fields are the tile coordinates, and type is the tree type (1: oak, 2: maple, 3: pine, 6: palm, 7: mushroom tree).
Example: Trees 17 18 2 20 31 2.
UniquePortrait [{str name}]+ ?
UniqueSprite [{str name}]+ ?
ViewportFollowPlayer T2 Forces the viewport to stay centered on the player.
Example: ViewportFollowPlayer.
Warp [{int fromX} {int fromY} {string toArea} {int toX} {int toY}]+ Sets the tiles which warp the player to another map (e.g. doors). The fromX fromY fields are the tile coordinates that initiate the warp, and toArea toX toY are the name of the in-game location to warp to and the tile coordinates within it.
Example: 6 20 Mountain 76 9.

The following properties are used but apparently have no effect:

property explanation
Arch ignored?
Debris ignored?
Fish ignored?

1 Map properties are handled in GameLocation::resetForPlayerEntry and GameLocation::loadObjects.
2 The T value (short for true) is conventional, but any non-empty value will work too.

Tile properties

You can set tile properties to perform actions when the player steps on the tile or interacts with it. Each property has a name (which defines the type of property) and value (which configures the property).

In Tiled these are represented by two types: object properties only apply to the selected tile, while tile properties apply to every instance of that tile. In general you’ll always set object properties, so we’ll only cover those.

View & edit properties

To view object properties in Tiled:

  1. Select the object layer in the Layers pane.
  2. Choose the select object tool in the toolbar.
  3. Click the object whose properties you want to view. Objects are represented with a gray selection box on the map:
  4. The object properties will be shown in the Properties pane.

To edit properties for an existing object:

To add a new object:

  1. Select the object layer in the Layers pane.
    There should be one object layer for each tile layer. If the object layer is missing, create one with the same name as the right tile layer.
  2. Choose the insert rectangle tool from the toolbar.
  3. Click and drag the rectangle over the tile you want to edit. Make sure it snaps to the tile grid (see recommended settings), and only one tile is selected.
  4. See previous for how to edit its properties.

Known properties

Known tile properties (excluding specialised properties like TouchAction WomensLocker):1

layer property explanation
Back Diggable T2 Marks the tile as diggable with the hoe and enables planting crops.
Back NoFurniture T2 Prevents the player from placing furniture on this tile.
Back NoSpawn All
NoSpawn True
Combines NoSpawn Grass and NoSpawn Tree.
Back NoSpawn Grass Prevents debris (e.g. weeds or stones) from spawning on this tile.
Back NoSpawn Tree Prevents trees from spawning on this tile. Prevents the player from planting trees on this tile, except on the farm. If a tree is already on this tile, prevents it from growing.
Back NPCBarrier T2 Prevents NPCs from crossing this tile.
Back Type {str type} Sets the tile type for various game logic (e.g. step sounds or planting crops), where type is one of Dirt, Stone, Grass, Wood.
Back Water T2 Marks the tile as a water tile for various game logic (e.g. items splash into it, can refill watering can from it, can’t walk on it, etc).
Back WaterSource T2 Lets the player refill the watering can from this tile.

The TouchAction property makes something happen when the player steps on the tile:

layer property explanation
Back TouchAction ChangeIntoSwimsuit Changes the player into their swimsuit and disables running.
Back TouchAction ChangeOutOfSwimsuit Changes the player into their regular clothes and enables running.
Back TouchAction Door {str npc} If the player doesn’t have 2+ friendship hearts with the villager named by the npc field: stops the player, marks the tile as impassible, and displays a door-locked message.
Back TouchAction Emote {str npc} {int emoteID} Finds the NPC whose name matches the npc field, and causes them to show the given emoteID above their head (4: empty can, 8: question mark, 12: angry, 16: exclamation, 20: heart, 24: sleep, 28: sad, 32: happy, 36: x, 40: pause, 52: videogame, 56: music note, 60: blush).
Back TouchAction FacingDirection {str npc} {int direction} Finds the NPC whose name matches the npc field, and make them face the given direction (0: up, 1: right, 2: down, 3: left).
Back TouchAction MagicWarp {str area} {int x} {int y} [{str prerequisite}] Warps the player to the x y tile coordinates in the given area with a magic sound and effects. If the prerequisite field is specified, only occurs if that flag is set via Game1.player.mailReceived.
Back TouchAction PoolEntrance Switches the player between swimming and walking mode.
Back TouchAction Sleep Ends the day if the player confirms.

The Action property makes something happen when the player interacts (e.g. clicks) with the tile:

layer property explanation
Buildings Action AdventureShop Shows the Adventurer’s Guild shop screen.
Buildings Action Arcade_Prairie Shows the Journey of the Prairie King arcade game.
Buildings Action Arcade_Minecart Shows the Junimo Kart arcade game.
Buildings Action BuyBackpack Shows a menu which lets the player upgrade their backpack if an upgrade is available.
Buildings Action Billboard Shows the calendar menu.
Buildings Action ColaMachine Offers to let the player buy a Joja cola.
Buildings Action ClubShop Shows the casino shop menu.
Buildings Action ClubSlots Shows the casino slots minigame.
Buildings Action JojaShop Shows the Joja shopping screen.
Buildings Action Jukebox Shows the jukebox menu to choose the ambient music.
Buildings Action kitchen Shows the cooking menu.
Buildings Action Letter {str text} Shows the letter menu on-screen with the given text, with the syntax used by Data\mail.xnb.
Example: Action Letter Hey there!^I had some extra wood lying around... I thought maybe you could use it. Take care! ^ -Robin %item object 388 50 %%.
Buildings Action LockedDoorWarp [{int toX} {int toY} {string toArea} {int openTime} {int closeTime}] Creates an activation warp normally used on doors with a time window for when it can be used. Note that you must use 24-hour times, i.e. 2000 for 8pm.
Example: 6 29 SeedShop 900 2100.
Buildings Action Mailbox Shows the next letter from the player’s mailbox (if any).
Buildings Action Material Shows a summary of the player’s stockpiled wood and stone.
Buildings Action MinecartTransport Shows the minecart destination menu (or a message if not unlocked).
Buildings Action Notes {int noteID} If the player has found the specified lost book, displays its museum note text and marks it read.
Example: Action Notes 17.
Buildings Action Warp {int x} {int y} {str area} Warps the player to the x y tile coordinate in the area game location.
Example: Action Warp Mountain 76 9.
Buildings Action WarpCommunityCenter Warps the player to the inside of the Community Center if they have access (else show an “it’s locked” message).
Buildings Action WizardShrine Shows the character customisation menu normally available from the Wizard’s tower.

1 Tile properties are handled throughout the codebase using GameLocation::doesTileHaveProperty. Actions and touch actions are handled by GameLocation::performAction and GameLocation::performTouchAction respectively. Emote IDs are listed as Character constants.
2 The T value (short for true) is conventional, but any non-empty value will work too.

Animating tiles

You can animate tiles to create effects like Gil in his rocking chair:

Here’s how to do it in Tiled:

  1. Select the tile you want to animate in the Tilesets pane.
  2. Click View > Tile Animation Editor in the toolbar to show that pane.
  3. In the Tile Animation Editor pane, drag tiles from the tilesheet into the box on the left to create a frame (one image in the sequence).
  4. Double-click the numbers to change how long each frame stays on the screen before the next one (in milliseconds). Make sure every frame has the same time; the game can’t handle variable frame times. For example, here’s the animation editor showing one of the tiles of Gil rocking:
  5. When you’re done, close the pane.
  6. The animated tiles in the Tilesets pane will now have a little symbol in the bottom-right corner:

    The animation is now part of that tile. Every instance of that tile on the map will now have the same animation.

Editing maps from a SMAPI mod

The previous sections describe how to edit a map by editing its file, but you can also edit it programmatically at runtime in a SMAPI mod:

GameLocation location = Game1.currentLocation;

** Manage map properties
// get
string value = location.map.Properties.ContainsKey("Music")
    ? location.map.Properties["Music"].ToString()
    : null;

// set
location.map.Properties["Music"] = "MarlonsTheme";

** Manage tile properties
// get
string value = location.doesTileHaveProperty(tileX, tileY, "Diggable", "Back");

// set
location.setTileProperty(tileX, tileY, "Back", "Diggable", "T");

** Edit tiles
// remove tile
location.removeTile(tileX, tileY, "Back");
location.waterTiles[tileX, tilyY] = false;

// add tile
var layer = location.map.GetLayer("Back");
layer.Tiles[tileX, tileY] = new StaticTile(layer, "tilesheet name", BlendMode.Alpha, tileID);