<commit_before>---
layout: default
title: Creating an XNB mod
intro: >
    This page explains how to create a mod which replaces game files in order to change game data,
    images, and maps.
    <p class="warning">
    This guide is still very new and may have inaccuracies. Use at your discretion, and
    <a href="https://github.com/Pathoschild/canimod.github.io#ways-to-contribute">feel free to contribute</a>
    any corrections and improvements.
    </p>
---

## Intro

### 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`:

```
Abigail.xnb
   Abigail.png
   Abigail.yaml
```

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:  
  ![](images/creating-an-xnb-mod/example-portraits.png)
* `Abigail.yaml` 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.

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](creating-a-smapi-mod) is recommended
instead if feasible.

For more details, see _[using mods](using-mods)_ for an introduction.

### Where can I get help?
The Stardew Valley modding community is very welcoming. Feel free [come chat on Discord](https://discord.gg/kH55QXP)
or [post in the forums](http://community.playstarbound.com/forums/mods.215/).

## Getting started

### First time-setup
<p class="warning">
This guide only covers Windows. If you know how to do this on Linux/Mac, let us know!
</p>

Before you start, you'll need these:

* **[XNB Extract by Drogean](http://community.playstarbound.com/threads/modding-guides-and-general-modding-discussion-redux.109131/)**
  is a toolkit for unpacking and packing the game's XNB files. This is a portable app — no install
  needed.
* To edit images:
  * **[Paint.NET](http://www.getpaint.net/download.html)** is a free tool that 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](https://cdn.discordapp.com/attachments/156109690059751424/249890421805678592/tIDESetup208.msi)**
    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](http://www.mapeditor.org/)** 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, and fewer bugs
    when editing Stardew Valley maps.

Backing up your game's `Content` folder at this point is strongly recommended, so you can recover
the original files if you make a mistake.

<span id="packing"></span>

### 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 in back in is called _packing_. Here's how to do it:

1. 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. Run `UNPACK FILES.bat`.
2. Edit the unpacked file (see below).
3. Repack the file for the game:
   1. Run `PACK FILES.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:

  ![tile](images/creating-an-xnb-mod/tilesheet.png)

  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:

  ![tile](images/creating-an-xnb-mod/tile-1.png)

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

  ![tile](images/creating-an-xnb-mod/tile-2.png)

### Making changes
Spritesheets are easy to edit:

1. [Unpack the file](#packing) 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](#packing) 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
* 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.

* 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...<commit_msg>copyedit merged guide, add Linux/Mac instructions where needed (#14)<commit_after>---
layout: default
title: Creating an XNB mod
intro: >
    This page explains how to create a mod which replaces game files in order to change game data,
    images, and maps.
    <p class="warning">
    This guide is still very new and may have inaccuracies. Use at your discretion, and
    <a href="https://github.com/Pathoschild/canimod.github.io#ways-to-contribute">feel free to contribute</a>
    any corrections and improvements.
    </p>
---

## Intro

### 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`:

```
Abigail.xnb
   Abigail.png
   Abigail.yaml
```

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:  
  ![](images/creating-an-xnb-mod/example-portraits.png)
* `Abigail.yaml` 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.

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](creating-a-smapi-mod) is recommended
instead if feasible.

For more details, see _[using mods](using-mods)_ for an introduction.

### Where can I get help?
The Stardew Valley modding community is very welcoming. Feel free [come chat on Discord](https://discord.gg/kH55QXP)
or [post in the forums](http://community.playstarbound.com/forums/mods.215/).

## Getting started

### First time-setup
1. Before you start, you should install these:
   * **[XNB Extract by Drogean](http://community.playstarbound.com/threads/modding-guides-and-general-modding-discussion-redux.109131/)**
     is a toolkit for unpacking and packing the game's XNB files.
   * To edit images:
     * **[Paint.NET](http://www.getpaint.net/download.html)** 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](https://cdn.discordapp.com/attachments/156109690059751424/249890421805678592/tIDESetup208.msi)**
       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](http://www.mapeditor.org/)** 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.

<span id="packing"></span>

### 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. 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 `UNPACK FILES.bat`.  
      On Linux/Mac, run the command inside `UNPACK FILES.bat`.
2. Edit the unpacked file (see below).
3. Repack the file for the game:
   1. On Windows, double-click `PACK FILES.bat`.  
      On Linux/Mac, run the command inside `PACK FILES.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:

![tile](images/creating-an-xnb-mod/tilesheet.png)

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:

![tile](images/creating-an-xnb-mod/tile-1.png)

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

![tile](images/creating-an-xnb-mod/tile-2.png)

### Making changes
Spritesheets are easy to edit:

1. [Unpack the file](#packing) 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](#packing) 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
* 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.

* 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...
{'fraction_non_alphanumeric': 0.0876284282924344, 'fraction_numerical': 0.012397045087883161, 'mean_word_length': 3.8729830368225073, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 19, 'https://': 6, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '943974', 'n_tokens_mistral': 3678, 'n_tokens_neox': 3407, 'n_words': 1658}