Difference between revisions of "Modding:Editing XNB files"

From Stardew Valley Wiki
Jump to navigation Jump to search
(→‎First-time setup: edit format a bit)
m (Atom has been deprecated since 2022 and is not recommended to be used in any way.)
 
(66 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.
−
 
 
−
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, [[Modding:Creating a SMAPI mod|creating a SMAPI mod]] is recommended instead if feasible.
 
−
 
 
−
For more details, see [[Modding:Index#Using mods|using mods]] for an introduction.
 
  
−
===Where can I get help?===
+
==<span id="unpacking">Unpack game files</span>==
−
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].
+
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.
  
−
==Getting started==
+
===StardewXnbHack===
−
===First-time setup===
+
{{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]].
−
Before you start, you should install these:
 
  
−
:; on Windows
+
To unpack files:
  
−
::* '''[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>
+
# [[Modding:Player Guide/Getting Started|Install SMAPI]].
−
::* '''[http://www.getpaint.net/download.html Paint.NET]''' to edit image files (or use your favourite image editor).
+
# {{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!)
−
::* To edit maps:
+
# 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}}.
−
::** '''[https://cdn.discordapp.com/attachments/156109690059751424/249890421805678592/tIDESetup208.msi 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 <tt>.tbin</tt> files and the <tt>.tmx</tt> files we'll be editing. It fixes an issue where exporting to <tt>.tmx</tt> would lose tile data like animations.
+
# 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.
−
::** '''[http://www.mapeditor.org/ 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.
 
  
−
:; on Linux/Mac
+
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]].
  
−
::* '''[https://www.winehq.org/download Wine 1.7 or later]''' lets you run Windows programs like XNB Extract.
+
===xnbcli===
−
::* '''[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.
+
{{github|LeonBlade/xnbcli#readme|xnbcli}} is an open-source and crossplatform tool for packing and unpacking XNB files.
−
::* '''[https://www.gimp.org/downloads/ GIMP]''' to edit image files (or use your favourite image editor).
 
−
::* Editing maps on Linux isn't supported yet.
 
  
−
You should also back up your game's <tt>Content</tt> folder, so you can recover the original files if you make a mistake.
+
This supports XNB files for other games too, but it can't handle some files specific to Stardew Valley. [[#StardewXnbHack|StardewXnbHack]] is recommended instead.
  
−
===Unpack & pack game files===
+
{{collapse|content=
−
<span id="unpacking"></span>
+
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.
  
−
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:
+
To unpack files:
  
−
# Download XNB Extract (see [[#First-time setup]]).
+
<ol>
−
# Unpack the file for editing:
+
<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>
−
## Find the file you want to edit in the <tt>Contents</tt> folder.
+
<li>Unpack the file for editing:
−
## Copy it into XNB Extract's <tt>Packed</tt> folder.
+
# Find the file you want to edit in the [[Modding:Player Guide/Getting Started#Find your game folder|game's <samp>Content</samp> folder]].
−
## Double-click <tt>UnpackFiles.bat</tt> (Windows) or <tt>UnpackFiles.sh</tt> (Linux/Mac).
+
# Copy it into xnbcli's <samp>packed</samp> folder.
−
# Edit the unpacked file (see below).
+
# Double-click <samp>unpack.bat</samp> (Windows), <samp>unpack.sh</samp> (Linux), or <samp>unpack.command</samp> (Mac).
−
# Repack the file for the game:
+
# 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.)
−
## Double-click <tt>PackFiles.bat</tt> (Windows) or <tt>PackFiles.sh</tt> (Linux/Mac).
+
</li>
−
## Move the repacked <tt>.xnb</tt> file back to the original location.
+
<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>
  
−
==Editing a spritesheet==
+
'''Troubleshooting:'''
−
===Basic concepts===
+
* If you get permission denied on Linux/Mac:
−
A spritesheet is just an image file that contains many smaller images in a regular grid pattern:
+
*# 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!
 +
}}
  
−
[[File:Modding - creating an XNB mod - example tilesheet.png]]
+
==Pack game files==
 +
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>.
  
−
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:
+
If you really want to repack the files, you'll need to use [[#xnbcli|xnbcli]]:
  
−
[[File:Modding - creating an XNB mod - example tile 1.png]]
+
# Find the file you want to repack.
 +
# Copy it into xnbcli's <samp>unpacked</samp> folder.
 +
# Double-click <samp>pack.bat</samp> (Windows), <samp>pack.sh</samp> (Linux), or <samp>pack.command</samp> (Mac).
 +
# Move the repacked <samp>.xnb</samp> file back to the original location.
  
−
Note that sprites might be drawn next to each other to create the illusion of a larger object:
+
==Making changes==
 +
===Data===
 +
Each data XNB has its own format. See the documentation at [[Modding:Index#Advanced topics]].
  
−
[[File:Modding - creating an XNB mod - example tile 2.png]]
+
===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]]]]
 +
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 <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 '''portrait''' is a sprite from the <samp>Content\Characters\*.xnb</samp> spritesheets.
  
−
===Making changes===
 
 
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 Paint.NET (or your preferred image editor).
+
# 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 92: Line 130:
 
That's it! You can launch the game to see your changes.
 
That's it! You can launch the game to see your changes.
  
−
==Editing a map==
+
===Maps===
−
===Basic concepts===
+
See [[Modding:Maps]].
−
<ul>
 
−
<li>A '''map''' is the layout of the terrain (like water, cliffs, and land), terrain features (like bushes), buildings, paths, and triggers for a particular area. When you reach the edge of an area or enter a building, and the screen fades to black during the transition, you're moving between maps.</li>
 
−
 
 
−
<li>Each map consists of several '''layers''' stacked one in front of the other. Objects in a layer closer to the front will hide objects in layers behind them. From back to front, the standard layers are...
 
  
 +
===Content editing===
 +
Note that prices for software listed below are subject to change.
 +
====Pixel Art software====
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
−
! layer name
+
! Software
−
! typical contents
+
! Price (USD)
 +
! OS
 +
! Notes
 
|-
 
|-
−
| Back
+
| [https://www.aseprite.org/ Aseprite]
−
| Terrain, water, and basic features (like permanent paths).
+
| $19.99
 +
| Windows, macOS, Linux
 +
| Free if you compile yourself from the [https://github.com/aseprite/aseprite source code]
 
|-
 
|-
−
| Buildings
+
| [https://www.adobe.com/products/photoshop.html Photoshop]
−
| Placeholders for buildings (like the farmhouse).
+
| $9.99/mo
 +
| Windows, macOS
 +
| Subscription based service
 
|-
 
|-
−
| Paths
+
| [https://www.getpaint.net/ PAINT.NET]
−
| Flooring, paths, grass, and debris (like stones, weeds, and stumps) which can be removed by the player.
+
| Free and $6.99 on Microsoft Store
 +
| Windows
 +
|
 
|-
 
|-
−
| Front
+
| [https://www.gimp.org/ GIMP]
−
| Objects that are drawn on top of things behind them, like most trees.
+
| Free
 +
| Windows, macOS, Linux
 +
|
 
|-
 
|-
−
| AlwaysFront
+
| [https://krita.org/en/ Krita]
−
| Objects that are always drawn on top of other layers. This is typically used for foreground effects like foliage cover.
+
| Free and $9.99 on Steam
−
|}</li>
+
| Windows, macOS, Linux
−
 
+
|  
−
<li>Each layer consists of many '''tiles''', which are 16×16 pixel squares placed in a grid to form the visible map. Each tile can have properties (e.g. passable / blocked), special logic (e.g. an action to perform when the player steps on them), and a picture to show. The picture is represented by a sprite index (or tile index), which is its position in an associated spritesheet (see next).</li>
 
−
 
 
−
<li>Each map has one or more [spritesheets](#editing-a-spritesheet) (also known as tilesheets when talking about mods), which contains the available tiles that are put together to form the visible map.</li>
 
−
</ul>
 
−
 
 
−
===Recommended Tiled settings===
 
−
The following settings in Tiled are strongly recommended:
 
−
 
 
−
{| class="wikitable"
 
 
|-
 
|-
−
! setting
+
| [https://pyxeledit.com/ Pyxel Edit]
−
! value
+
| $9.00
−
! reason
+
| Windows
 +
| Currently in beta, subject to a price increase upon full release
 
|-
 
|-
−
| ''View > Snap to Grid''
+
| [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]
−
| ✓ enabled
+
| Free - In App Purchases on Android
−
| This is required to convert objects back into the game's format.
+
| Android, Windows
 +
|  
 
|-
 
|-
−
| ''Highlight Current Layer''
 
−
| ✓ enabled
 
−
| This makes it more clear which tile you're editing.
 
 
|}
 
|}
  
−
===Making changes===
+
====Text editing software====
−
Here's how to edit a Stardew Valley map:
 
−
 
 
−
# '''Get the file for editing:'''
 
−
## [[#unpacking|Unpack the file]] you want to change.
 
−
## Open the unpacked <tt>.tbin</tt> file in tIDE.
 
−
## Resave the file as "Tiled XML Map Files (*.tmx)".
 
−
## When asked how to store the layer data, choose "CSV".
 
−
# '''Make your changes:'''
 
−
## Open the <tt>.tmx</tt> file in Tiled.
 
−
## Make the desired changes (see the [http://doc.mapeditor.org/ Tiled documentation] and next sections).
 
−
## Save the file.
 
−
# '''Repack the file for the game:'''
 
−
## Open the <tt>.tmx</tt> file in tIDE.
 
−
## Resave the file as "tIDE Binary Map Files (*.tbin)".
 
−
## [[#unpacking|Repack the file]] and copy it back to the original location.
 
−
 
 
−
The [http://doc.mapeditor.org/ 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:
 
−
 
 
−
[[File:Modding - creating an XNB mod - tile coordinates.png]]
 
−
 
 
−
===Using custom sprites===
 
−
You can add custom sprites (images) to a map:
 
−
 
 
−
# Create your spritesheet. This should be a PNG image with images divided into 16x16 tiles (see [[#Basic concepts]] for examples).
 
−
# Open the map in Tiled.
 
−
# Add the custom spritesheet:
 
−
## In the ''Tilesets'' pane, click the [[File:Modding - creating an XNB mod - Tiled 'new tilesheet' button.png]] button.
 
−
## Give it a descriptive name (like 'cute bugs') and choose the image source.
 
−
## Keep the default settings and click ''OK''.
 
−
# Add custom sprites to the map:
 
−
## In the ''Layers'' pane, click the layer you want to edit.
 
−
## In the ''Tilesets'' pane, click the tab for your custom spritesheet.
 
−
## In the ''Tilesets'' pane, click one tile to select it. To choose multiple, click and drag the cursor.
 
−
## Move the cursor to the map, and you'll see an overlay with the tiles you selected.
 
−
## 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 properties¹:
 
−
 
 
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
−
! property
+
! Software
−
! explanation
+
! Price (USD)
−
|-
+
! OS
−
| <tt>AmbientLight {{t|int r}} {{t|int g}} {{t|int b}}</tt>
+
! Notes
−
| Sets the [[wikipedia:RGB color model|RGB colour]] of the ambient light.<br />''Example: <tt>AmbientLight 95 95 95</tt> for a normal indoor daytime lighting.''
 
−
|-
 
−
| <tt>BrookSounds [{{t|int x}} {{t|int y}} {{t|int sound}}]</tt>
 
−
| Adds sound sources. The {{t|x}} {{t|y}} fields are the tile coordinates, and {{t|sound}} is the ambient sound ID.
 
−
|-
 
−
| <tt>DayTiles [{{t|string layer}} {{t|int x}} {{t|int y}} {{t|int type}}]+</tt>
 
−
| Sets which tiles should glow during the day to simulate sunlight streaming through windows. The {{t|layer}} field is the map layer name, {{t|x}} {{t|y}} are the tile coordinates, and {{t|type}} specifies the glow type (e.g. 256 and 288 for an upper and lower window).<br />''Example: <tt>DayTiles Front 3 1 256 Front 3 2 288</tt>.''
 
−
|-
 
−
| <tt>Doors {{t|int x}} {{t|int y}} {{t|string sheetID}} {{t|int tileID}}</tt>
 
−
| Adds a door. The {{t|x}} {{t|y}} fields are the tile coordinates, {{t|sheetID}} is the name of the sheet containing the door sprite, and {{t|tileID}} is the tile index in the spritesheet.
 
−
|-
 
−
| <tt>Fall_Objects T</tt>²<br /><tt>Spring_Objects T</tt>²<br /><tt>Summer_Objects T</tt>²<br /><tt>Winter_Objects T</tt>²
 
−
| Whether to spawn seasonal objects on spawnable tiles based on the data in <tt>Data\Locations.xnb</tt>.<br />''Example: <tt>Fall_Objects</tt>.''
 
−
|-
 
−
| <tt>Light [{{t|int x}} {{t|int y}} {{t|int type}}]+</tt>
 
−
| Adds light sources. The {{t|type}} field is the kind of light source (e.g. 4 for twin candles), and {{t|x}} {{t|y}} are the tile coordinates.<br />''Example: <tt>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</tt> (Adventurer's Guild).''
 
−
|-
 
−
| <tt>Music {{t|string name}}</tt>
 
−
| Sets the music that plays when the player enters, where {{t|name}} is the cue name in the audio files.<br />''Example: <tt>Music MarlonsTheme</tt>.''
 
−
|-
 
−
| <tt>NightTiles [{{t|string layer}} {{t|int x}} {{t|int y}} {{t|int type}}]+</tt>
 
−
| Like <tt>DayTiles</tt>, but for moonlight at night.
 
−
|-
 
−
| <tt>Outdoors T</tt>²
 
−
| Sets whether the location is outdoors.<br />''Example: <tt>Outdoors true</tt>.''
 
−
|-
 
−
| <tt>TreatAsOutdoors T</tt>²
 
−
| ?
 
−
|-
 
−
| <tt>Trees [{{t|int x}} {{t|int y}} {{t|int type}}]+</tt>
 
−
| Adds trees to the map. The {{t|x}} {{t|y}} fields are the tile coordinates, and {{t|type}} is the tree type (1: oak, 2: maple, 3: pine, 6: palm, 7: mushroom tree).<br />''Example: <tt>Trees 17 18 2 20 31 2</tt>.''
 
 
|-
 
|-
−
| <tt>UniquePortrait [{{t|str name}}]+</tt>
+
| [https://www.sublimetext.com/ Sublime Text]
−
| ?
+
| $99.00
 +
| Windows, macOS, Linux
 +
| Unlimited free trial
 
|-
 
|-
−
| <tt>UniqueSprite [{{t|str name}}]+</tt>
+
| [https://notepad-plus-plus.org/downloads/ Notepad++]
−
| ?
+
| Free
 +
| Windows
 +
|  
 
|-
 
|-
−
| <tt>ViewportFollowPlayer T</tt>²
+
| [https://code.visualstudio.com/ Visual Studio Code]
−
| Forces the viewport to stay centered on the player.<br />''Example: <tt>ViewportFollowPlayer</tt>.''
+
| Free
 +
| Windows, macOS, Linux
 +
|
 
|-
 
|-
−
| <tt>Warp [{{t|int fromX}} {{t|int fromY}} {{t|string toArea}} {{t|int toX}} {{t|int toY}}]+</tt>
 
−
| Sets the tiles which warp the player to another map (e.g. doors). The {{t|fromX}} {{t|fromY}} fields are the tile coordinates that initiate the warp, and {{t|toArea}} {{t|toX}} {{t|toY}} are the name of the in-game location to warp to and the tile coordinates within it.<br />''Example: 6 20 Mountain 76 9.''
 
 
|}
 
|}
  
−
The following properties are used but apparently have no effect:
+
[[Category:Modding]]
−
 
 
−
* <tt>Arch</tt>
 
−
* <tt>Debris</tt>
 
−
* <tt>Fish</tt>
 
−
 
 
−
<small>¹ Map properties are handled in <tt>GameLocation::resetForPlayerEntry</tt> and <tt>GameLocation::loadObjects</tt>.</small> 
 
−
<small>² The <tt>T</tt> value (short for ''true'') is conventional, but any non-empty value will work too.</small>
 
−
 
 
−
===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:
 
−
 
 
−
# Select the object layer in the _Layers_ pane.
 
−
# Choose the [[File:Modding - creating an XNB mod - Tiled 'select object' button.png]] ''select object'' tool in the toolbar.
 
−
# Click the object whose properties you want to view. Objects are represented with a gray selection box on the map:<br />[[File:Modding - creating an XNB mod - map object.png]]
 
−
# The object properties will be shown in the _Properties_ pane.<br />[[File:Modding - creating an XNB mod - Tiled tile properties pane.png]]
 
−
 
 
−
To edit properties for an existing object:
 
−
* Change a value: click the value field and enter the new value.
 
−
* Change a name: select the property and click the [[File:Modding - creating an XNB mod - Tiled 'edit' button.png]] icon.
 
−
* Add a property: click the [[File:Modding - creating an XNB mod - Tiled 'add' button.png]] icon, enter the property name, make sure the selected type is "string", and click OK.
 
−
 
 
−
To add a new object:
 
  
−
# Select the object layer in the ''Layers'' pane.<br />''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.''
+
[[es:Modding:Edición de archivos XNB]]
−
# Choose the [[File:Modding - creating an XNB mod - Tiled 'insert rectangle' button.png]] ''insert rectangle'' tool from the toolbar.
+
[[pt:Modificações:Editando arquivos XNB]]
−
# Click and drag the rectangle over the tile you want to edit. Make sure it snaps to the tile grid (see [[#Recommended Tiled settings]]), and only one tile is selected.
+
[[ru:Модификации:Редактирование XNB файлов]]
−
## See previous for how to edit its properties.
+
[[zh:模组:编辑 XNB 文件]]
−
 
 
−
====Known properties====
 
−
Known tile properties (excluding specialised properties like <tt>TouchAction WomensLocker</tt>):¹
 
−
 
 
−
{| class="wikitable"
 
−
|-
 
−
! layer
 
−
! property
 
−
! explanation
 
−
|-
 
−
| <tt>Back</tt>
 
−
| <tt>Diggable T</tt>²
 
−
| Marks the tile as diggable with the hoe and enables planting crops.
 
−
|-
 
−
| <tt>Back</tt>
 
−
| <tt>NoFurniture T</tt>²
 
−
| Prevents the player from placing furniture on this tile.
 
−
|-
 
−
| <tt>Back</tt>
 
−
| <tt>NoSpawn All</tt><br /><tt>NoSpawn True</tt>
 
−
| Combines <tt>NoSpawn Grass</tt> and <tt>NoSpawn Tree</tt>.
 
−
|-
 
−
| <tt>Back</tt>
 
−
| <tt>NoSpawn Grass</tt>
 
−
| Prevents debris (e.g. weeds or stones) from spawning on this tile.
 
−
|-
 
−
| <tt>Back</tt>
 
−
| <tt>NoSpawn Tree</tt>
 
−
| 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.
 
−
|-
 
−
| <tt>Back</tt>
 
−
| <tt>NPCBarrier T</tt>²
 
−
| Prevents NPCs from crossing this tile.
 
−
|-
 
−
| <tt>Back</tt>
 
−
| <tt>Type {{t|str type}}</tt>
 
−
| Sets the tile type for various game logic (e.g. step sounds or planting crops), where {{t|type}} is one of ''Dirt'', ''Stone'', ''Grass'', or ''Wood''.
 
−
|-
 
−
| <tt>Back</tt>
 
−
| <tt>Water T</tt>²
 
−
| 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).
 
−
|-
 
−
| <tt>Back</tt>
 
−
| <tt>WaterSource T</tt>²
 
−
| Lets the player refill the watering can from this tile.
 
−
|}
 
−
 
 
−
The <tt>TouchAction</tt> property makes something happen when the player steps on the tile:
 
−
 
 
−
{| class="wikitable"
 
−
|-
 
−
! layer
 
−
! property
 
−
! explanation
 
−
|-
 
−
| <tt>Back</tt>
 
−
| <tt>TouchAction ChangeIntoSwimsuit</tt>
 
−
| Changes the player into their swimsuit and disables running.
 
−
|-
 
−
| <tt>Back</tt>
 
−
| <tt>TouchAction ChangeOutOfSwimsuit</tt>
 
−
| Changes the player into their regular clothes and enables running.
 
−
|-
 
−
| <tt>Back</tt>
 
−
| <tt>TouchAction Door {{t|string npc}}</tt>
 
−
| If the player doesn't have 2+ friendship hearts with the villager named by the {{t|npc}} field: stops the player, marks the tile as impassible, and displays a door-locked message.
 
−
|-
 
−
| <tt>Back</tt>
 
−
| <tt>TouchAction Emote {{t|string npc}} {{t|int emoteID}}</tt>
 
−
| Finds the NPC whose name matches the {{t|npc}} field, and causes them to show the given {{t|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).
 
−
|-
 
−
| <tt>Back</tt>
 
−
| <tt>TouchAction FacingDirection {{t|string npc}} {{t|int direction}}</tt>
 
−
| Finds the NPC whose name matches the {{t|npc}} field, and make them face the given direction (0: up, 1: right, 2: down, 3: left).
 
−
|-
 
−
| <tt>Back</tt>
 
−
| <tt>TouchAction MagicWarp {{t|string area}} {{t|int x}} {{t|int y}} {{o|string prerequisite}}</tt>
 
−
| Warps the player to the {{t|x}} {{t|y}} tile coordinates in the given {{t|area}} with a magic sound and effects. If the {{o|prerequisite}} field is specified, only occurs if that flag is set via <tt>Game1.player.mailReceived</tt>.
 
−
|-
 
−
| <tt>Back</tt>
 
−
| <tt>TouchAction PoolEntrance</tt>
 
−
| Switches the player between swimming and walking mode.
 
−
|-
 
−
| <tt>Back</tt>
 
−
| <tt>TouchAction Sleep</tt>
 
−
| Ends the day if the player confirms.
 
−
|}
 
−
 
 
−
The <tt>Action</tt> property makes something happen when the player interacts (e.g. clicks) with the tile:
 
−
 
 
−
{| class="wikitable"
 
−
|-
 
−
! layer
 
−
! property
 
−
! explanation
 
−
|-
 
−
| <tt>Buildings</tt>
 
−
| <tt>Action AdventureShop</tt>
 
−
| Shows the Adventurer's Guild shop screen.
 
−
|-
 
−
| <tt>Buildings</tt>
 
−
| <tt>Action Arcade_Prairie</tt>
 
−
| Shows the ''Journey of the Prairie King'' arcade game.
 
−
|-
 
−
| <tt>Buildings</tt>
 
−
| <tt>Action Arcade_Minecart</tt>
 
−
| Shows the ''Junimo Kart'' arcade game.
 
−
|-
 
−
| <tt>Buildings</tt>
 
−
| <tt>Action BuyBackpack</tt>
 
−
| Shows a menu which lets the player upgrade their backpack if an upgrade is available.
 
−
|-
 
−
| <tt>Buildings</tt>
 
−
| <tt>Action Billboard</tt>
 
−
| Shows the calendar menu.
 
−
|-
 
−
| <tt>Buildings</tt>
 
−
| <tt>Action ColaMachine</tt>
 
−
| Offers to let the player buy a Joja cola.
 
−
|-
 
−
| <tt>Buildings</tt>
 
−
| <tt>Action ClubShop</tt>
 
−
| Shows the casino shop menu.
 
−
|-
 
−
| <tt>Buildings</tt>
 
−
| <tt>Action ClubSlots</tt>
 
−
| Shows the casino slots minigame.
 
−
|-
 
−
| <tt>Buildings</tt>
 
−
| <tt>Action JojaShop</tt>
 
−
| Shows the Joja shopping screen.
 
−
|-
 
−
| <tt>Buildings</tt>
 
−
| <tt>Action Jukebox</tt>
 
−
| Shows the jukebox menu to choose the ambient music.
 
−
|-
 
−
| <tt>Buildings</tt>
 
−
| <tt>Action kitchen</tt>
 
−
| Shows the cooking menu.
 
−
|-
 
−
| <tt>Buildings</tt>
 
−
| <tt>Action Letter {{t|string text}}</tt>
 
−
| Shows the letter menu on-screen with the given text, with the syntax used by <tt>Data\mail.xnb</tt>.<br />''Example: <tt>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 %%</tt>''.
 
−
|-
 
−
| <tt>Buildings</tt>
 
−
| <tt>Action LockedDoorWarp [{{t|int toX}} {{t|int toY}} {{t|string toArea}} {{t|int openTime}} {{t|int closeTime}}]</tt>
 
−
| 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. <br />''Example: 6 29 SeedShop 900 2100.''
 
−
|-
 
−
| <tt>Buildings</tt>
 
−
| <tt>Action Mailbox</tt>
 
−
| Shows the next letter from the player's mailbox (if any).
 
−
|-
 
−
| <tt>Buildings</tt>
 
−
| <tt>Action Material</tt>
 
−
| Shows a summary of the player's stockpiled wood and stone.
 
−
|-
 
−
| <tt>Buildings</tt>
 
−
| <tt>Action MinecartTransport</tt>
 
−
| Shows the minecart destination menu (or a message if not unlocked).
 
−
|-
 
−
| <tt>Buildings</tt>
 
−
| <tt>Action Notes {{t|int noteID}}</tt>
 
−
| If the player has found the specified lost book, displays its museum note text and marks it read.<br />''Example: Action Notes 17.''
 
−
|-
 
−
| <tt>Buildings</tt>
 
−
| <tt>Action Warp {{t|int x}} {{t|int y}} {{t|str area}}</tt>
 
−
| Warps the player to the {{t|x}} {{t|y}} tile coordinate in the {{t|area}} game location.<br />''Example: Action Warp Mountain 76 9.''
 
−
|-
 
−
| <tt>Buildings</tt>
 
−
| <tt>Action WarpCommunityCenter</tt>
 
−
| Warps the player to the inside of the Community Center if they have access (else show an "it's locked" message).
 
−
|-
 
−
| <tt>Buildings</tt>
 
−
| <tt>Action WizardShrine</tt>
 
−
| Shows the character customisation menu normally available from the Wizard's tower.
 
−
|}
 
−
 
 
−
<small>¹ Tile properties are handled throughout the codebase using <tt>GameLocation::doesTileHaveProperty</tt>. Actions and touch actions are handled by <tt>GameLocation::performAction</tt> and <tt>GameLocation::performTouchAction</tt> respectively. Emote IDs are listed as <tt>Character</tt> constants.</small><br />
 
−
<small>² The <tt>T</tt> value (short for ''true'') is conventional, but any non-empty value will work too.</small>
 
−
 
 
−
===Animating tiles===
 
−
You can animate tiles to create effects like Gil in his rocking chair:
 
−
 
 
−
[[File:Modding - creating an XNB mod - example animation.gif]]
 
−
 
 
−
Here's how to do it in Tiled:
 
−
# Select the tile you want to animate in the ''Tilesets'' pane.
 
−
# Click ''View > Tile Animation Editor'' in the toolbar to show that pane.
 
−
# 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).
 
−
# 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:<br />[[File:Modding - creating an XNB mod - Tiled example animation pane.gif]]
 
−
## When you're done, close the pane.
 
−
## The animated tiles in the ''Tilesets'' pane will now have a little symbol in the bottom-right corner:<br />[[File:Modding - creating an XNB mod - Tiled example animation tileset.png]]<br />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 [[Modding:Creating a SMAPI mod|SMAPI mod]]:
 
−
 
 
−
<source lang="c#">
 
−
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");
 
−
var tilesheet = location.map.GetTilesheet("tilesheet name");
 
−
layer.Tiles[tileX, tileY] = new StaticTile(layer, tilesheet, BlendMode.Alpha, tileID);
 
−
</source>
 
−
 
 
−
[[Category:Modding]]
 

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"