Modding:Editing XNB files

← Index

This page explains how to edit the game files to change in-game data, images, and maps.

Intro

What are XNB files?

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:

Abigail.xnb
   Abigail.png
   Abigail.json

In the above example:

• Abigail.png contains Abigail's portraits. This is the file you would edit if you wanted to change her portraits in the game:
  
• Abigail.json contains metadata about Abigail.png (like what type of file it is). You don't need to worry about this file, since you generally won't be changing it.

How do I get my changes in the game?

There are three ways to get your changes in the game:

1. Create a Content Patcher content pack. This lets you change the game's XNB data with zero programming (just editing a JSON file) and without replacing the actual game files.
2. Create a SMAPI mod and use the Content API. This requires programming, though.
3. Create an XNB mod by replacing the original game files. This is no longer recommended and not documented here; see using XNB mods for more info.

Where can I get help?

The Stardew Valley modding community is very welcoming. Feel free to ask the community for help.

Unpack 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. There are two main XNB unpackers available.

xnbcli

xnbcli is an open-source and crossplatform tool for packing and unpacking XNB files. Note that it can't unpack XNB files containing data models (like Data\FishPondData or Data\Movies), and you'll need to edit data files manually to work with mods like Content Patcher.

Here's how:

1. Download xnbcli. (Make sure you download the file for your OS, such as xnbcli-windows-x64.zip, not the source code!)
2. Unpack the file for editing:
   1. Find the file you want to edit in the game's Content folder.
   2. Copy it into xnbcli's packed folder.
   3. Double-click unpack.bat (Windows), unpack.sh (Linux), or unpack.command (Mac).
   4. Check the Unpacked folder for your unpacked files. (If you didn't unpack many files, it may just flash onscreen and disappear again, but that's normal! Check the folder for your changes, anyway. Note that 1.4 introduced a new data model format that current unpackers have not yet been updated to handle. For movie and fish pond data you will need to use StardewXnbHack instead.)
3. Edit the unpacked file (see below).
4. If this is a data file (not an image or map), there's one more step if you want to replace the file with Content Patcher's Action: Load: removing the XNB metadata. Your current JSON file should look something like this:

   {
       "header": {
           "target": "w",
           "formatVersion": 5,
           "hidef": true,
           "compressed": true
       },
       "readers": [
           {
               "type": "Microsoft.Xna.Framework.Content.DictionaryReader`2[[System.Int32, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089],[System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089]]",
               "version": 0
           },
           {
               "type": "Microsoft.Xna.Framework.Content.Int32Reader",
               "version": 0
           },
           {
               "type": "Microsoft.Xna.Framework.Content.StringReader",
               "version": 0
           }
       ],
       "content": {
           "0": "Weeds/0/-1/Basic/Weeds/A bunch of obnoxious weeds."
       }
   }
   

   Just remove everything except the content field, so it looks like this:

   {
       "0": "Weeds/0/-1/Basic/Weeds/A bunch of obnoxious weeds."
   }
   

Troubleshooting:

• If you get permission denied on Linux/Mac:
  1. Open a terminal. (In MacOS, search 'Terminal' in Spotlight.)
  2. Type chmod +x , with a space at the end. Don't press enter yet.
  3. Drag the unpack.sh (Linux) or unpack.command (Mac) file onto the terminal to paste its path.
  4. Hit enter. If you did it correctly, the terminal won't show any message but the permission error should be gone.
  5. Repeat for pack.sh (Linux) or pack.command (Mac).
• If you get unrecognized command on Windows:
  1. Make sure you didn't download the source code zip by mistake. If the folder path refers to "master", it's the wrong one!

StardewXnbHack

StardewXnbHack is an open-source and crossplatform tool for unpacking XNB files. Note that you can't pack files back into .xnb using it (though you rarely need to).

Here's how:

1. Download StardewXnbHack. (Make sure you download the file for your OS, such as StardewXnbHack-*-for-windows.zip, not the source code!)
2. Unzip the download into your game folder, so StardewXnbHack.exe is in the same folder as StardewValley.exe.
3. Double-click StardewXnbHack.exe (on Windows), StardewXnbHack.sh (on Linux), or StardewXnbHack.command (on MacOS) to unpack your game's entire Content folder.

That's it! It'll unpack the files into a Content (unpacked) folder. The unpacked files will already be compatible with Content Patcher.

Pack game files

There's no need to repack game files if you're using Content Patcher! Just use the .json, .png, or .tbin file directly in your content.json.

If you really want to repack the files:

1. Find the file you want to repack.
2. Copy it into xnbcli's unpacked folder.
3. Double-click pack.bat (Windows), pack.sh (Linux), or pack.command (Mac).
4. Move the repacked .xnb file back to the original location.

Making changes

Data

Each data XNB has its own format. See the documentation at Modding:Index#Advanced topics.

Images

An example tilesheet, which consists of a grid of tiles like this:

A few definitions:

• A spritesheet is a PNG file containing small images (usually in a regular grid pattern). Each square in the spritesheet's grid pattern is called a sprite. For example, each in-game item has a sprite in Content\Maps\spring_objects.xnb.
• A tilesheet is a synonym for spritesheet when used for map tiles. In a tilesheet, each square is called a tile and is 16×16 pixels.
• A portrait is a sprite from the Content\Characters\*.xnb spritesheets.

Spritesheets are easy to edit:

1. Unpack the file you want to change.
2. Open the unpacked .png file in an image editor (like Paint.NET on Windows, or GIMP on Windows/Linux/Mac). Note that it's important to use an image editor that can handle transparency (a.k.a. an alpha channel), unlike Microsoft Paint.
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.

Maps

See Modding:Maps.