Modding:Editing XNB files

From Stardew Valley Wiki
Revision as of 05:48, 26 January 2018 by Pathoschild (talk | contribs) (→‎Getting started: + experimental instructions for the new xnbcli)
Jump to navigation Jump to search

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.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:
    Modding - 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.

What are XNB mods?

An XNB mod replaces some of the game's XNB files to 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 new content (like new NPCs).

Note: creating SMAPI mods is recommended instead if feasible. 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. They do require writing code though. See Modding:Player FAQs for more info about the two kinds of mod.

Where can I get help?

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

Getting started

First-time setup

Before you start, you should install these:

on Windows
on Linux/Mac

You should also back up your game's Content folder, 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. Double-click UnpackFiles.bat (Windows) or UnpackFiles.sh (Linux/Mac).
  3. Edit the unpacked file (see below).
  4. Repack the file for the game:
    1. Double-click PackFiles.bat (Windows) or PackFiles.sh (Linux/Mac).
    2. Move the repacked .xnb file back to the original location.

Getting started (experimental alternative)

xnbcli is a new tool for packing and unpacking XNB files. It's open-source and natively crossplatform, but still new. Try it out and let us know how it goes!

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 xnbcli.
  2. Unpack the file for editing:
    1. Find the file you want to edit in the Contents folder.
    2. Copy it into xnbcli's packed folder.
    3. Double-click unpack.bat (Windows) or unpack.sh (Linux/Mac).
  3. Edit the unpacked file (see below).
  4. Repack the file for the game:
    1. Double-click pack.bat (Windows) or pack.sh (Linux/Mac).
    2. 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 Linux/Mac).
  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.