translators
8,403
edits
Changes
Jump to navigation
Jump to search
Line 1:
Line 1: − + − − − ===How XNB mods work=== − 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>: − − <pre> − Abigail.xnb − Abigail.png − Abigail.yaml − </pre> − − In the above example: − − * <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]] − * <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. − − 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?=== − 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== − ===First-time setup=== − Before you start, you should install these: − − :; on Windows − − ::* '''[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> − ::* '''[http://www.getpaint.net/download.html Paint.NET]''' to edit image files (or use your favourite image editor). − ::* '''[https://thorbjorn.itch.io/tiled/devlog/5540/small-snapshot-update Tiled snapshot 2017.07.17] <!--[http://www.mapeditor.org/ Tiled 1.0.2 or later]-->''' to edit maps. ('''Note:''' once installed, go to ''Edit > Preferences > Plugins'' and enable the <tt>tbin.dll</tt> plugin.) − − :; on Linux/Mac − − ::* '''[https://www.winehq.org/download Wine 1.7 or later]''' to run Windows programs like XNB Extract. − ::* '''[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. − ::* '''[https://www.gimp.org/downloads/ GIMP]''' to edit image files (or use your favourite image editor). − ::* '''[https://thorbjorn.itch.io/tiled/devlog/5540/small-snapshot-update Tiled snapshot 2017.07.17]''' to edit maps. − − You should also back up your game's <tt>Content</tt> folder, so you can recover the original files if you make a mistake. − − ===Unpack & pack game files=== − <span id="unpacking"></span> − − 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: − − # Download XNB Extract (see [[#First-time setup]]). − # Unpack the file for editing: − ## Find the file you want to edit in the <tt>Contents</tt> folder. − ## Copy it into XNB Extract's <tt>Packed</tt> folder. − ## 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. − − ==Editing a spritesheet== − ===Basic concepts=== − A spritesheet is just an image file that contains many smaller images in a regular grid pattern: − − [[File:Modding - creating an XNB mod - example 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: − − [[File:Modding - creating an XNB mod - example tile 1.png]] − − Note that sprites might be drawn next to each other to create the illusion of a larger object: − − [[File:Modding - creating an XNB mod - example tile 2.png]] − − ===Making changes=== − Spritesheets are easy to edit: − − # [[#unpacking|Unpack the file]] you want to change. − # Open the unpacked <tt>.png</tt> file in Paint.NET (or your preferred image editor). − # Make changes directly to the image. − # [[#unpacking|Repack the file]] and copy it back to the original location. − − That's it! You can launch the game to see your changes. − − ==Editing a map== Line 120:
Line 33: − + − + − + + + + + + + + + + + + + + + + + + Line 139:
Line 69: − + + + + + + + + + + + + + + + − + − Here's how to edit a Stardew Valley map:+ + + + − # [[#unpacking|Unpack the file]] you want to change.+ − # Open the unpacked <tt>.tbin</tt> file in Tiled.+ − # Make the desired changes (see the [http://doc.mapeditor.org/ Tiled documentation] and next sections) and save. − # [[#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.+ + − + − 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]]+ + − + − You can add custom sprites (images) to a map:+ + + + + + + + + + + − + − + − + − + − + − + − + − + − + − + − + − + + − + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + − To view and edit map properties in Tiled, click ''Map'' on the toolbar and choose ''Map Properties''.+ + − Known map properties¹:+ + + + + + + + + + Line 230:
Line 279: − + − − * <tt>Arch</tt> − * <tt>Debris</tt> − * <tt>Fish</tt> Line 240:
Line 285: − 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.'' − # Choose the [[File:Modding - creating an XNB mod - Tiled 'insert rectangle' button.png]] ''insert rectangle'' tool from the toolbar. − # 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. − ## See previous for how to edit its properties. − − ====Known properties==== Line 502:
Line 522: − − ===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>
expand, add SMAPI instructions, rewrite to focus on map changes
← [[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 maps. This is an advanced guide for modders.
==Intro==
==Intro==
===Basic concepts===
===Basic concepts===
<ul>
<ul>
<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 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>
<li>Each map has one or more spritesheets (also known as tilesheets when talking about mods), which contains the available tiles and images that are put together to form the visible map.</li>
</ul>
</ul>
===Recommended Tiled settings===
===Tile coordinates===
The following settings in Tiled are strongly recommended:
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]]
==Getting started==
There are two main ways to edit a map.
===Using SMAPI===
Creating a SMAPI mod requires programming, but it's much more powerful and multiple SMAPI mods can edit the same map. If you want to use this approach:
# [[Modding:Creating a SMAPI mod|Create a SMAPI mod]].
# See instructions below for map changes.
===Using Tiled===
Creating an XNB Mod doesn't require programming, but it's less flexible and players can't install two XNB mods that change the same map. You'll need to unpack the game's map file, change it using a map editor, and repack it. If you want to use this approach:
<ol>
<li>Install the latest [https://thorbjorn.itch.io/tiled/devlog/5540/small-snapshot-update Tiled snapshot version] (''not'' the stable version).</li>
<li>Once installed, go to ''Edit > Preferences > Plugins'' and enable the <tt>tbin</tt> plugin.</li>
<li>Set the following settings:
{| class="wikitable"
{| class="wikitable"
|-
|-
| ✓ enabled
| ✓ enabled
| This makes it more clear which tile you're editing.
| This makes it more clear which tile you're editing.
|}
|}</li>
<li>See [[Modding:Creating an XNB mod]] for help unpacking & packing the map files.</li>
<li>See instructions below for map changes.</li>
</ol>
==Map edits==
===Custom map===
You can add a new map and location to the game.
If you're using SMAPI:
:<source lang="C#">
public void Entry(IModHelper helper)
{
// load a map.tbin file from your mod's folder.
Map map = helper.Content.Load<Map>("map.tbin", ContentSource.ModFolder);
===Making changes===
// add the new location
GameLocation location = new GameLocation(map, "YourLocationName") { IsOutdoors = false, IsFarm = false };
Game1.locations.Add(location);
}
</source>
If you're using Tiled:
: You can create the map in Tiled, but you need SMAPI to add it to the game.
===Custom tilesheet===
You can add custom sprites, tiles, or images to a map.
===Tile coordinates===
If you're using SMAPI:
:<source lang="c#">
public void Entry(IModHelper helper)
{
// This gets the asset key for a tilesheet.png file from your mod's folder. You can also load a game tilesheet like
// this: helper.Content.GetActualAssetKey("spring_town", ContentSource.GameContent).
string tilesheetPath = helper.Content.GetActualAssetKey("tilesheet.png", ContentSource.ModFolder);
// Get an instance of the in-game location you want to patch. For the farm, use Game1.getFarm() instead.
GameLocation location = Game1.getLocationFromName("Town");
===Using custom sprites===
// Add the tilesheet.
TileSheet tilesheet = new TileSheet(
id: "your-custom-spritesheet", // a unique ID for the tilesheet
map: location.map,
imageSource: tilesheetPath,
sheetSize: new xTile.Dimensions.Size(32, 62), // the pixel size of your tilesheet image.
tileSize: new xTile.Dimensions.Size(16, 16) // should always be 16x16 for maps
);
location.map.AddTileSheet(tilesheet);
location.map.LoadTileSheet(Game1.mapDisplayDevice);
}
</source>
# Create your spritesheet. This should be a PNG image with images divided into 16x16 tiles (see [[#Basic concepts]] for examples).
If you're using Tiled:
# Open the map in Tiled.
:# Create your spritesheet. This should be a PNG image with images divided into 16x16 tiles (see [[Modding:Creating an XNB mod#Basic concepts]] for examples).
# Add the custom spritesheet:
:# Open the map in Tiled.
## In the ''Tilesets'' pane, click the [[File:Modding - creating an XNB mod - Tiled 'new tilesheet' button.png]] button.
:# Add the custom spritesheet:
## Give it a descriptive name (like 'cute bugs') and choose the image source.
:## In the ''Tilesets'' pane, click the [[File:Modding - creating an XNB mod - Tiled 'new tilesheet' button.png]] button.
## Keep the default settings and click ''OK''.
:## Give it a descriptive name (like 'cute bugs') and choose the image source.
# Add custom sprites to the map:
:## Keep the default settings and click ''OK''.
## In the ''Layers'' pane, click the layer you want to edit.
:# Add custom sprites to the map:
## In the ''Tilesets'' pane, click the tab for your custom spritesheet.
:## In the ''Layers'' pane, click the layer you want to edit.
## In the ''Tilesets'' pane, click one tile to select it. To choose multiple, click and drag the cursor.
:## In the ''Tilesets'' pane, click the tab for your custom spritesheet.
## Move the cursor to the map, and you'll see an overlay with the tiles you selected.
:## In the ''Tilesets'' pane, click one tile to select it. To choose multiple, click and drag the cursor.
## Click the map to place those tiles on the selected layer.
:## 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===
===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).
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). See [[#Known properties]] below.
If you're using SMAPI:
: <source lang="c#">
public void Entry(IModHelper helper)
{
// get the 'Music' value
Game1.currentLocation.map.Properties.TryGetValue("Music", out string value);
// set the 'Music' value
Game1.currentLocation.map.Properties["Music"] = "MarlonsTheme";
}
</source>
If you're using Tiled:
:# Click ''Map'' on the toolbar and choose ''Map Properties''.
:# View and edit properties using the GUI.
===Tile properties===
Tile properties are set on individual map tiles. They can change game behaviour (like whether the player can cross them), or perform actions when the player steps on or clicks the tile. Each property has a name and value.
If you're using SMAPI:
: <source lang="C#">
public void Entry(IModHelper helper)
{
// get
string value = Game1.currentLocation.doesTileHaveProperty(tileX, tileY, "Diggable", "Back");
// add or set value
Game1.currentLocation.setTileProperty(tileX, tileY, "Back", "Diggable", "T");
}
</source>
If you're using Tiled:
: 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.
:# 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.''
:# Choose the [[File:Modding - creating an XNB mod - Tiled 'insert rectangle' button.png]] ''insert rectangle'' tool from the toolbar.
:# 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.
:## See previous for how to edit its properties.
===Tiles===
You can edit the tiles for an existing map.
If you're using SMAPI:
:<source lang="c#">
public void Entry(IModHelper helper)
{
// remove tile from layer
location.removeTile(tileX, tileY, "Back");
// add tile
Layer layer = location.map.GetLayer("Back");
TileSheet tilesheet = location.map.GetTilesheet("tilesheet name");
layer.Tiles[tileX, tileY] = new StaticTile(layer, tilesheet, BlendMode.Alpha, tileID);
// toggle water tile behaviour
location.waterTiles[tileX, tilyY] = false; // true: water, false: not water
}
</source>
If you're using Tiled:
: See [http://doc.mapeditor.org Tiled documentation].
===Animated tiles===
[[File:Modding - creating an XNB mod - example animation.gif|right]]
You can animate tiles to create effects like Gil in his rocking chair (see example at right).
If you're using SMAPI:
: <span style="color:red;">'''TODO'''</span>
If you're using 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.
==Known properties==
===Map properties===
Known map properties:¹
{| class="wikitable"
{| class="wikitable"
|-
|-
|}
|}
The following properties are used but apparently have no effect:
The following properties are used but apparently have no effect: <tt>Arch</tt>, <tt>Debris</tt>, and <tt>Fish</tt>.
<small>¹ Map properties are handled in <tt>GameLocation::resetForPlayerEntry</tt> and <tt>GameLocation::loadObjects</tt>.</small>
<small>¹ Map properties are handled in <tt>GameLocation::resetForPlayerEntry</tt> and <tt>GameLocation::loadObjects</tt>.</small>
===Tile properties===
===Tile properties===
Known tile properties (excluding specialised properties like <tt>TouchAction WomensLocker</tt>):¹
Known tile properties (excluding specialised properties like <tt>TouchAction WomensLocker</tt>):¹
<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>¹ 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>
<small>² The <tt>T</tt> value (short for ''true'') is conventional, but any non-empty value will work too.</small>
[[Category:Modding]]
[[Category:Modding]]