Difference between revisions of "Modding:Editing XNB files"

From Stardew Valley Wiki
Jump to navigation Jump to search
(→‎XNB vs SMAPI mods: update link)
m (Atom has been deprecated since 2022 and is not recommended to be used in any way.)
 
(55 intermediate revisions by 13 users not shown)
Line 1: Line 1:
 
← [[Modding:Index|Index]]
 
← [[Modding:Index|Index]]
  
−
This page explains how to create a mod which replaces game files in order to change game data, images, and maps.
+
This page explains how to edit the game files to change in-game data, images, and maps.
  
 
==Intro==
 
==Intro==
−
===How XNB mods work===
+
===What are XNB files?===
−
The game stores data in a compressed format with the <tt>.xnb</tt> file extension inside its <tt>Content</tt> folder. For example, Abigail's portrait shown during dialogue is from <tt>Content\Portraits\Abigail.xnb</tt>. Each <tt>.xnb</tt> 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 <tt>Content\Portraits\Abigail.xnb</tt>:
+
The game stores data, maps, and textures in a compressed format with the <samp>.xnb</samp> file extension inside its <samp>Content</samp> folder. For example, Abigail's portrait shown during dialogue is from <samp>Content\Portraits\Abigail.xnb</samp>. Unpacking that file gives you an <samp>Abigail.png</samp> like this:<br />[[File:Modding - creating an XNB mod - example portraits.png]]
  
−
<pre>
+
===How do I get my changes in the game?===
−
Abigail.xnb
+
There are three ways to get your changes in the game:
−
  Abigail.png
 
−
  Abigail.yaml
 
−
</pre>
 
  
−
In the above example:
+
# [[Modding:Content Patcher|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.
 +
# [[Modding:Modder Guide/Get Started|Create a SMAPI mod]] and use the [[Modding:Modder_Guide/APIs/Content|Content API]]. This requires programming, though.
 +
# Create an XNB mod by replacing the original game files. This is no longer recommended and not documented here; see [[Modding:using XNB mods|using XNB mods]] for more info.
  
−
* <tt>Abigail.png</tt> contains Abigail's portraits. This is the file you would edit if you wanted to change her portraits in the game:<br />[[File:Modding - creating an XNB mod - example portraits.png]]
+
===Where can I get help?===
−
* <tt>Abigail.yaml</tt> contains metadata about <tt>Abigail.png</tt> (like what type of file it is). You don't need to worry about this file, since you generally won't be changing it.
+
The Stardew Valley modding community is very welcoming. Feel free to [[Modding:Community|ask the community]] for help.
 +
 
 +
==<span id="unpacking">Unpack game files</span>==
 +
You can't edit an <samp>.xnb</samp> 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.
  
−
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).
+
===StardewXnbHack===
 +
{{github|Pathoschild/StardewXnbHack#readme|StardewXnbHack}} is an open-source and crossplatform tool for unpacking XNB files. It can't pack files back into <samp>.xnb</samp>, but you [[Modding:Content Patcher|rarely need to]].
  
−
===XNB vs SMAPI mods===
+
To unpack files:
−
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 which some modders aren't comfortable with. If you have programming experience, [[Modding:Creating a SMAPI mod|creating a SMAPI mod]] is recommended instead if feasible.
 
  
−
See [[Modding:Player FAQs]] for more info about the two kinds of mod.
+
# [[Modding:Player Guide/Getting Started|Install SMAPI]].
 +
# {{github|Pathoschild/StardewXnbHack/releases|Download StardewXnbHack}}. (Make sure you download the file for your OS, such as <samp>StardewXnbHack-*-for-windows.zip</samp>, not the source code!)
 +
# Unzip the download into [[Modding:Player Guide/Getting Started#Find your game folder|your game folder]], so {{executable name|StardewXnbHack}} is in the same folder as {{executable name|StardewValley}}.
 +
# Double-click {{executable name|StardewXnbHack}} (on Windows), <code>StardewXnbHack.sh</code> (on Linux), or <code>StardewXnbHack.command</code> (on MacOS) to unpack your game's entire <samp>Content</samp> folder.
  
−
===Where can I get help?===
+
That's it! It'll unpack the files into a <samp>Content (unpacked)</samp> folder. The unpacked files will already be compatible with [[Modding:Content Patcher|Content Patcher]].
−
The Stardew Valley modding community is very welcoming. Feel free [https://discord.gg/kH55QXP come chat on Discord] or [http://community.playstarbound.com/forums/mods.215/ post in the forums].
 
  
−
==Getting started==
+
===xnbcli===
−
===First-time setup===
+
{{github|LeonBlade/xnbcli#readme|xnbcli}} is an open-source and crossplatform tool for packing and unpacking XNB files.
−
Before you start, you should install these:
 
  
−
:; on Windows
+
This supports XNB files for other games too, but it can't handle some files specific to Stardew Valley. [[#StardewXnbHack|StardewXnbHack]] is recommended instead.
  
−
::* '''[https://www.mediafire.com/?b86xecd27yti6f6 XNB Extract 0.2.2]''' to unpack and pack the game's XNB files. <small>(See [http://community.playstarbound.com/threads/beginners-guide-to-xnb-node-and-graphics-editing.110976/ forum post].)</small>
+
{{collapse|content=
−
::* '''[http://www.getpaint.net/download.html Paint.NET]''' to edit image files (or use your favourite image editor).
+
Special notes:
 +
* It can't unpack XNB files containing data models (like <samp>Data\FishPondData</samp> or <samp>Data\Movies</samp>); use [[#StardewXnbHack|StardewXnbHack]] if you need those.
 +
* You'll need to edit unpacked data files manually to work with mods like Content Patcher.
 +
* When unpacking an image with xnbcli, you'll get extra <samp>.json</samp> file next to the image. That's only used to convert it back into an <samp>.xnb</samp> later, and you generally don't need to change it.
  
−
:; on Linux/Mac
+
To unpack files:
  
−
::* '''[https://www.winehq.org/download Wine 1.7 or later]''' to run Windows programs like XNB Extract.
+
<ol>
−
::* '''[https://www.dropbox.com/s/oj5tch8np74nk4d/XNBExtract0.2.2.zip?dl=0 XNB Extract 0.2.2 for Linux/Mac]''' to unpack and pack the game's XNB files.
+
<li>{{github|LeonBlade/xnbcli/releases|Download xnbcli}}. (Make sure you download the file for your OS, such as <samp>xnbcli-windows-x64.zip</samp>, not the source code!)</li>
−
::* '''[https://www.gimp.org/downloads/ GIMP]''' to edit image files (or use your favourite image editor).
+
<li>Unpack the file for editing:
 +
# Find the file you want to edit in the [[Modding:Player Guide/Getting Started#Find your game folder|game's <samp>Content</samp> folder]].
 +
# Copy it into xnbcli's <samp>packed</samp> folder.
 +
# Double-click <samp>unpack.bat</samp> (Windows), <samp>unpack.sh</samp> (Linux), or <samp>unpack.command</samp> (Mac).
 +
# Check the <samp>Unpacked</samp> 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 xnbcli can't handle; for some data files you'll need to use [[#StardewXnbHack|StardewXnbHack]] instead.)
 +
</li>
 +
<li>Edit the unpacked file (see below).</li>
 +
<li>If this is a data file (not an image or map), there's one more step if you want to replace or edit the file with [[Modding:Content Patcher|Content Patcher]]: removing the XNB metadata. Your current JSON file should look something like this:
 +
<syntaxhighlight lang="js">
 +
{
 +
    "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."
 +
    }
 +
}
 +
</syntaxhighlight>
 +
Just remove everything except the content field, so it looks like this:
 +
<syntaxhighlight lang="js">
 +
{
 +
    "0": "Weeds/0/-1/Basic/Weeds/A bunch of obnoxious weeds."
 +
}
 +
</syntaxhighlight></li>
 +
</ol>
  
−
You should also back up your game's <tt>Content</tt> folder, so you can recover the original files if you make a mistake.
+
'''Troubleshooting:'''
 +
* If you get permission denied on Linux/Mac:
 +
*# Open a terminal. (In MacOS, search 'Terminal' in Spotlight.)
 +
*# Type <code>chmod +x&nbsp;</code>, ''with a space at the end''. Don't press enter yet.
 +
*# Drag the <samp>unpack.sh</samp> (Linux) or <samp>unpack.command</samp> (Mac) file onto the terminal to paste its path.
 +
*# Hit enter. If you did it correctly, the terminal won't show any message but the permission error should be gone.
 +
*# Repeat for <samp>pack.sh</samp> (Linux) or <samp>pack.command</samp> (Mac).
 +
* If you get unrecognized command on Windows:
 +
*# Make sure you didn't download the source code zip by mistake. If the folder path refers to "master", it's the wrong one!
 +
}}
  
−
===Unpack & pack game files===
+
==Pack game files==
−
<span id="unpacking"></span>
+
There's no need to repack game files if you're using [[Modding:Content Patcher|Content Patcher]]! Just use the <samp>.json</samp>, <samp>.png</samp>, <samp>.tmx</samp>, or <samp>.tbin</samp> file directly in your <samp>content.json</samp>.
  
−
You can't edit an <tt>.xnb</tt> 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:
+
If you really want to repack the files, you'll need to use [[#xnbcli|xnbcli]]:
  
−
# Download XNB Extract (see [[#First-time setup]]).
+
# Find the file you want to repack.
−
# Unpack the file for editing:
+
# Copy it into xnbcli's <samp>unpacked</samp> folder.
−
## Find the file you want to edit in the <tt>Contents</tt> folder.
+
# Double-click <samp>pack.bat</samp> (Windows), <samp>pack.sh</samp> (Linux), or <samp>pack.command</samp> (Mac).
−
## Copy it into XNB Extract's <tt>Packed</tt> folder.
+
# Move the repacked <samp>.xnb</samp> file back to the original location.
−
## Double-click <tt>UnpackFiles.bat</tt> (Windows) or <tt>UnpackFiles.sh</tt> (Linux/Mac).
 
−
# Edit the unpacked file (see below).
 
−
# Repack the file for the game:
 
−
## Double-click <tt>PackFiles.bat</tt> (Windows) or <tt>PackFiles.sh</tt> (Linux/Mac).
 
−
## Move the repacked <tt>.xnb</tt> file back to the original location.
 
  
 
==Making changes==
 
==Making changes==
−
===Spritesheets, tilesheets, or portraits===
+
===Data===
 +
Each data XNB has its own format. See the documentation at [[Modding:Index#Advanced topics]].
 +
 
 +
===Images===
 
[[File:Modding - creating an XNB mod - example tilesheet.png|thumb|An example tilesheet, which consists of a grid of tiles like this: [[File:Modding - creating an XNB mod - example tile 1.png]]]]
 
[[File:Modding - creating an XNB mod - example tilesheet.png|thumb|An example tilesheet, which consists of a grid of tiles like this: [[File:Modding - creating an XNB mod - example tile 1.png]]]]
−
Definitions:
+
A few definitions:
−
* A '''spritesheet''' is a PNG file containing small images 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 <tt>Content\Maps\spring_objects.xnb</tt>.
+
* 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 <samp>Content\Maps\spring_objects.xnb</samp>.
 
* 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 '''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 <tt>Content\Characters\*.xnb</tt> spritesheets.
+
* A '''portrait''' is a sprite from the <samp>Content\Characters\*.xnb</samp> spritesheets.
  
 
Spritesheets are easy to edit:
 
Spritesheets are easy to edit:
 
# [[#unpacking|Unpack the file]] you want to change.
 
# [[#unpacking|Unpack the file]] you want to change.
−
# Open the unpacked <tt>.png</tt> file in an image editor (see [[#Getting started]]).
+
# Open the unpacked <samp>.png</samp> file in an image editor (like [http://www.getpaint.net/download.html Paint.NET] on Windows, or [https://www.gimp.org/downloads/ 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.''
 
# Make changes directly to the image.
 
# Make changes directly to the image.
 
# [[#unpacking|Repack the file]] and copy it back to the original location.
 
# [[#unpacking|Repack the file]] and copy it back to the original location.
Line 78: Line 132:
 
===Maps===
 
===Maps===
 
See [[Modding:Maps]].
 
See [[Modding:Maps]].
 +
 +
===Content editing===
 +
Note that prices for software listed below are subject to change.
 +
====Pixel Art software====
 +
{| class="wikitable"
 +
|-
 +
! Software
 +
! Price (USD)
 +
! OS
 +
! Notes
 +
|-
 +
| [https://www.aseprite.org/ Aseprite]
 +
| $19.99
 +
| Windows, macOS, Linux
 +
| Free if you compile yourself from the [https://github.com/aseprite/aseprite source code]
 +
|-
 +
| [https://www.adobe.com/products/photoshop.html Photoshop]
 +
| $9.99/mo
 +
| Windows, macOS
 +
| Subscription based service
 +
|-
 +
| [https://www.getpaint.net/ PAINT.NET]
 +
| Free and $6.99 on Microsoft Store
 +
| Windows
 +
|
 +
|-
 +
| [https://www.gimp.org/ GIMP]
 +
| Free
 +
| Windows, macOS, Linux
 +
|
 +
|-
 +
| [https://krita.org/en/ Krita]
 +
| Free and $9.99 on Steam
 +
| Windows, macOS, Linux
 +
|
 +
|-
 +
| [https://pyxeledit.com/ Pyxel Edit]
 +
| $9.00
 +
| Windows
 +
| Currently in beta, subject to a price increase upon full release
 +
|-
 +
| [https://play.google.com/store/apps/details?id=com.PixelStudio Pixel Studio Android] or [https://store.steampowered.com/app/1204050/Pixel_Studio_for_pixel_art/ Pixel Studio Steam]
 +
| Free - In App Purchases on Android
 +
| Android, Windows
 +
|
 +
|-
 +
|}
 +
 +
====Text editing software====
 +
{| class="wikitable"
 +
|-
 +
! Software
 +
! Price (USD)
 +
! OS
 +
! Notes
 +
|-
 +
| [https://www.sublimetext.com/ Sublime Text]
 +
| $99.00
 +
| Windows, macOS, Linux
 +
| Unlimited free trial
 +
|-
 +
| [https://notepad-plus-plus.org/downloads/ Notepad++]
 +
| Free
 +
| Windows
 +
|
 +
|-
 +
| [https://code.visualstudio.com/ Visual Studio Code]
 +
| Free
 +
| Windows, macOS, Linux
 +
|
 +
|-
 +
|}
  
 
[[Category:Modding]]
 
[[Category:Modding]]
 +
 +
[[es:Modding:Edición de archivos XNB]]
 +
[[pt:Modificações:Editando arquivos XNB]]
 +
[[ru:Модификации:Редактирование XNB файлов]]
 +
[[zh:模组:编辑 XNB 文件]]

Latest revision as of 13:22, 3 February 2024

← 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, maps, and textures 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. Unpacking that file gives you an Abigail.png like this:
Modding - creating an XNB mod - example portraits.png

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.

StardewXnbHack

StardewXnbHack is an open-source and crossplatform tool for unpacking XNB files. It can't pack files back into .xnb, but you rarely need to.

To unpack files:

  1. Install SMAPI.
  2. Download StardewXnbHack. (Make sure you download the file for your OS, such as StardewXnbHack-*-for-windows.zip, not the source code!)
  3. Unzip the download into your game folder, so StardewXnbHack.exe is in the same folder as Stardew Valley executable icon.png StardewValley.exe.
  4. 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.

xnbcli

xnbcli is an open-source and crossplatform tool for packing and unpacking XNB files.

This supports XNB files for other games too, but it can't handle some files specific to Stardew Valley. StardewXnbHack is recommended instead.

Details 
Special notes:
  • It can't unpack XNB files containing data models (like Data\FishPondData or Data\Movies); use StardewXnbHack if you need those.
  • You'll need to edit unpacked data files manually to work with mods like Content Patcher.
  • When unpacking an image with xnbcli, you'll get extra .json file next to the image. That's only used to convert it back into an .xnb later, and you generally don't need to change it.

To unpack files:

  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 xnbcli can't handle; for some data files you'll 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 or edit the file with Content Patcher: 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!

Pack game files

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

If you really want to repack the files, you'll need to use xnbcli:

  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: Modding - creating an XNB mod - example tile 1.png

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.

Content editing

Note that prices for software listed below are subject to change.

Pixel Art software

Software Price (USD) OS Notes
Aseprite $19.99 Windows, macOS, Linux Free if you compile yourself from the source code
Photoshop $9.99/mo Windows, macOS Subscription based service
PAINT.NET Free and $6.99 on Microsoft Store Windows
GIMP Free Windows, macOS, Linux
Krita Free and $9.99 on Steam Windows, macOS, Linux
Pyxel Edit $9.00 Windows Currently in beta, subject to a price increase upon full release
Pixel Studio Android or Pixel Studio Steam Free - In App Purchases on Android Android, Windows

Text editing software

Software Price (USD) OS Notes
Sublime Text $99.00 Windows, macOS, Linux Unlimited free trial
Notepad++ Free Windows
Visual Studio Code Free Windows, macOS, Linux
Retrieved from "https://stardewvalleywiki.com/mediawiki/index.php?title=Modding:Editing_XNB_files&oldid=153109"