59
edits
Changes
Jump to navigation
Jump to search
draft of maps page editing phase 1
← [[Modding:Index|Index]]
This page explains how to edit maps. This is an advanced guide for modders.
==Intro==
===Basic concepts===
<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...
{| class="wikitable"
|-
! layer name
! typical contents
|-
| Back
| Terrain, water, and basic features (like permanent paths).
|-
| Buildings
| Placeholders for buildings (like the farmhouse). Any tiles placed on this layer will act like a wall unless the tile property has a "Passable" "T".
|-
| Paths
| Flooring, paths, grass, and debris (like stones, weeds, and stumps from the 'paths' tilesheet) which can be removed by the player.
|-
| Front
| Objects that are drawn on top of things behind them, like most trees. These objects will be drawn on top of the player if the player is North of them but behind the player if the player is south of them.
|-
| AlwaysFront
| Objects that are always drawn on top of other layers as well as the player. This is typically used for foreground effects like foliage cover.
|}</li>
[[File:MapLayers.png]]
<li>(Using Tiled) There are 2 different types of layers along with the 5 main layers, Objects Layer (cloud-like icon) and Tile Layer (grid icon). The Tile Layer is where you make map edits (placing and removing tiles) and the Objects Layers is where you add and edit tile data. Your layers must match the ones above. Note that depending on the map, they may be missing a Paths or AlwaysFront layer</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 (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>
===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]]
===Map formats===
There are two map formats used in Stardew Valley modding: <tt>.tmx</tt> (from the Tiled map editor) and <tt>.tbin</tt> (from the now-deprecated tIDE map editor). The features supported by both formats are almost identical, but there are a few differences:
{| class="wikitable"
|-
! feature
! <tt>.tmx</tt>
! <tt>.tbin</tt>
|-
| format
| ✓ XML (basically text)
| ✘ binary
|-
| edit in Tiled
| ✓ supported
| ✓ supported with plugin
|-
| edit directly
| ✓ can open in a text editor
| ✘ not supported
|-
| tile flip
| ✓ supported
| ✘ not supported
|-
| tile rotation
| ✓ supported
| ✘ not supported
|-
| source control
| ✓ efficient storage, can diff changes
| ✘ inefficient storage (need to copy entire file with each commit), can't diff changes
|}
<tt>.tmx</tt> is recommended per the above, but both formats are fine to use, and you can convert between them in Tiled by clicking ''File > Export As''.
==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:Modder Guide/Get Started|Create a SMAPI mod]].
# See ''[[#Making changes with SMAPI|Making changes with SMAPI]]'' below.
The rest of this guide assumes you're using Tiled, but many of the concepts are transferrable and you can use both Tiled and SMAPI (e.g. create/edit maps in Tiled and load/edit them in SMAPI).
===Using Tiled===
Tiled is a popular map editor that can be used to edit Stardew Valley maps, no programming needed. You need to [[Modding:Editing XNB files|unpack the map's XNB]], edit the map, and make a {{nexus mod|1915|Content Patcher}} or SMAPI mod to load your map. If you want to use this approach:
<ol>
<li>Install the [http://www.mapeditor.org/ latest version of Tiled].</li>
<li>Once installed, at the top left, go to Edit > Preferences > Plugins and enable the tbin plugin (<tt>tbin.dll</tt> on Windows, <tt>libtbin.so</tt> on Linux, or <tt>libtbin.dylib</tt> on Mac).
<li>Set the following settings:
{| class="wikitable"
|-
! setting
! value
! reason
|-
| ''View > Snapping > Snap to Grid''
| ✓ enabled
| This is required to convert objects back into the game's format.
|-
| ''View > Highlight Current Layer''
| ✓ enabled
| This makes it more clear which tile you're editing.
|}</li>
<li>See [[Modding:Editing XNB files]] for help unpacking & packing the map files.</li>
<li>See instructions below for map changes.</li>
</ol>
(If you use xnbcli to [[Modding:Editing XNB files#Unpack game files|unpack the original game maps]], you'll need the <tt>.tbin</tt> plugin even if you plan to use <tt>.tmx</tt> since xnbcli still produces <tt>.tbin</tt> files.)
===Tilesets vs Tilesheets===
<tt>Tilesheets</tt> are the <tt>.png</tt> files used as source images. Tilesheets have no animation, properties, terrains, or anything else but pixels associated with them -- they're just images. <tt>Tilesets</tt> are Tiled's XML files that contain all the information about how the map uses the source image. They are confusingly named and often used interchangeably.
==Map edits==
===Editing maps===
Important note: when making custom maps, always start with a vanilla map and edit it. Don't try to create a new map in Tiled; the game needs certain tiles, map properties, etc to be present.
# [[Modding:Editing XNB files|Unpack]] the game's <tt>Content/Maps</tt> folder and create a copy to edit your maps in. Use this copy of the folder to edit any maps in before moving them to your mod release folder.
# Use the same method to unpack the map you want to edit if it is not a vanilla one, then place the map in your editing folder.
# Open the <tt>.tbin</tt> or <tt>.tmx</tt> file via Tiled. Note: make sure the file is in the same folder as the unpacked tilesheets!
# Make your changes.
# Save the file. Don't use <tt>Save as</tt> to change folders, as your tilesheet paths will be wrong.
# Move the <tt>.tbin</tt> or <tt>.tmx</tt> file, and any custom tilesheets it needs, to your mod release folder. Place them in the <tt>assets</tt> folder.
# Load your map via SMAPI or Content Patcher (or another framework mod).
===Custom map===
You can add a new map and location to the game. The easiest option is to create the map using Tiled, then use [[Modding:Content Patcher|Content Patcher]] to [https://github.com/Pathoschild/StardewMods/blob/develop/ContentPatcher/docs/author-guide.md#custom-locations add the custom location to the game]. After loading your save, you can use this console command to jump to the map: <code>debug warp YourLocationName X Y</code>.
Note that the map must be built in a certain pattern; look at the maps in the <tt>Content/Maps</tt> folder for examples. It's often easier to start from an existing map and modify it, instead of starting from scratch.
{{note box|'''Using Content Patcher to add custom locations is strongly recommended.'''<br />You can add new locations in C# yourself, but be aware of factors like object persistence and NPC pathfinding that are easy to get wrong. If you ''really'' want to do it yourself, use the [[Modding:Modder Guide/APIs/Events#Specialised.LoadStageChanged|specialized <tt>LoadStageChanged</tt> event]] to add the location to <tt>Game1.locations</tt> during the <tt>CreatedInitialLocations</tt> or <tt>SaveAddedLocations</tt> stage.}}
===Adding tilesets===
You can add new sprites, tiles, or images to a map, from both custom and vanilla sources. If you're editing a vanilla map, make sure to [[#Tilesheet order|prefix custom tileset names with <code>z_</code>]] to avoid shifting the vanilla tilesheet indexes.
# Open the map that you created or are editing.
# Click <tt>Map</tt> then ''Add External Tileset...'' in the top menu, and open a <tt>.tsx</tt> file you have in the same folder.
# You should have a new copy of the tileset in your map, with any saved animations, properties, or terrains still intact.
====Re-using vanilla tilesets====
If you want to use a tilesheet like <tt>spring_outdoorsTileSheet.png</tt> in your map, adding a new tileset from a <tt>.png</tt> file means you need to re-animate any animated tiles, re-add properties like diggable and terrain types. You can avoid this by first exporting them from an existing map, then using external tilesets, instead.
# Open an existing map that already has the properties and animations you want.
# In the tileset pane, click the wrench to ''Edit Tileset''. It should open a new edit tab.
# In the new window that opens, click ''File'', then ''Export as...'' and save it as a .tsx file.
# Close the tileset editor.
====Replace existing tileset====
If you are already using a tilesheet image, you can replace its tileset.
# Open the map that you created or are editing.
# In the tileset pane on the right, click the tab for your existing version.
# Under that, click the ''Replace Tileset'' button.
# Choose the <tt>.tsx</tt> file you saved, and click Open.
====Adding a new custom tilesheet====
If you made a your own tilesheet and are adding it to a map the first time, you can create a new tileset from image.
# Create your spritesheet and place it in the same folder as your <tt>.tbin</tt> or <tt>.tmx</tt> map file. This should be a PNG image with images divided into 16x16 tiles (see [[Modding:Editing XNB files#Intro]] 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.
## Make sure that ''Embed in map'' is checked.
## Keep the defaults for the other settings and click ''OK''.
===Painting tiles onto your map===
## In the ''Layers'' pane, click the layer you want to edit.
## At the top left of Tiled's toolbar, click the Stamp Brush.
## In the ''Tilesets'' pane, click the tab for the tileset you want to use.
## 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), type (always 'string' in Stardew Valley), and value (which configures the property). See [[#Known properties|known properties]] below.
In 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, type (always 'string' in Stardew Valley), and value. 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.
To view tile properties:
# 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 [[#Using Tiled]]), and only one tile is selected.
# Change its Name field to <tt>TileData</tt>.
# See previous for how to edit its properties.
===Tiles===
You can edit the tiles for an existing map. See the [http://doc.mapeditor.org Tiled documentation] for more info.
===Tile animation===
[[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).
In Tiled:
:# Click the edit button (wrench icon) for the tilesheet in the ''Tilesets'' pane.
:# Select the tile you want to animate in the new view.
:# Click ''Tileset > Tile Animation Editor'' in the toolbar to show that window.
:# In the new window, drag tiles from the tilesheet into the box on the left to create a ''frame'' (one image in the sequence). If you need to delete frames, select the frame(s) and press Backspace/Delete(Windows) or fn + Backspace(Apple)
:# 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.
===Tile flip/rotation===
[[File:Tiled tile rotation.png|thumb|An example tile rotated four ways, below the Tiled flip/rotate buttons.]]
You can rotate and flip tiles without needing to create rotated/flipped versions of the tilesheet. This needs SMAPI 3.4 or later to be installed; the base game doesn't recognize tile transforms.
In Tiled:
:# With the stamp tool selected, click the tile in the tilesheet you want to use.
:# Click the flip or rotate buttons (see image at right).
:# Click the map to place the flipped/rotated tile.
{{note box|'''This only works with <tt>.tmx</tt> map files.'''<br /> Tile transforms aren't supported by the <tt>.tbin</tt> plugin. See [[#Map formats|''map formats'']] for more info.}}
==Known properties==
===Map properties===
Known map properties:¹
{| class="wikitable"
|-
! property
! explanation
|-
| <tt>AmbientLight {{t|byte r}} {{t|byte g}} {{t|byte b}}</tt><br />''(valid in indoor locations and locations that ignore outdoor lighting)''
| Sets the [[wikipedia:RGB color model|RGB colour]] that is subtracted from white (255,255,255) in order to create the ambient light.<br />''Example: <tt>AmbientLight 95 95 95</tt> for a normal indoor daytime lighting.''
|-
| <tt>BackwoodsEntry [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| The position the player is warped to when entering the farm from the Backwoods.
|-
| <tt>BrookSounds [{{t|int x}} {{t|int y}} {{t|int type}}]</tt><br />''(valid in outdoor locations)''
| Adds sound sources. The {{t|x}} {{t|y}} fields are the tile coordinates, and {{t|type}} is the ambient sound ID. The {{t|type}} of sound can be one of...
* <tt>0</tt> (babblingBrook);
* <tt>1</tt> (cracklingFire);
* <tt>2</tt> (engine);
* <tt>3</tt> (cricket).
|-
| <tt>BusStopEntry [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| The position the player is warped to when entering the farm from the Bus Stop.
|-
| <tt>CanCaskHere T</tt>²<br />''(valid in any location)''
| Allows casks to work in that location.
|-
| <tt>DayTiles [{{t|string layerName}} {{t|int x}} {{t|int y}} {{t|int tilesheetIndex}}]+</tt><br />''(valid in any location)''
| Sets tiles to appear between 6AM to 7PM. Anytime before 7pm, this finds the tile at position ({{t|x}}, {{t|y}}) on the map layer matching {{t|layerName}}, changes its tilesheet index to the specified {{t|tilesheetIndex}}, and adds a glow to simulate daylight. The glow will only be added if the location is indoors and the {{t|tilesheetIndex}} is 256, 288, 405, 469, or 1224. The parameters can be repeated to affect multiple tiles.<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><br />''(valid in indoor locations)''
| Adds functionality to interior doors. Used with <tt>Action Door</tt> tile properties. 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>FarmCaveEntry [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| The position the player is warped to when entering the farm from the farm cave.
|-
| <tt>FarmHouseEntry [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| Changes the position of the Farm House. Corresponds to the front door, or the position the player will be warped to when leaving the house.
|-
| <tt>Feed {{t|int x}} {{t|int y}}</tt><br />''(valid in coops and barns)''
| Sets the spawn location of the [[Hay Hopper]] in a coop or barn.<br />''Example: <tt>Feed 3 2</tt>.''
|-
| <tt>forceLoadPathLayerLights T</tt>²<br />''(valid in outdoor non-festival locations)''
| Whether to load lights from the <tt>Paths</tt> layer on maps where they would not normally be.<br />''Example: <tt>forceLoadPathLayerLights true</tt>.''
|-
| <tt>ForceSpawnForageables T</tt>²<br />''(valid in indoor locations)''
| Enables forage items spawning in that location.
|-
| <tt>ForestEntry [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| The position the player is warped to when entering the farm from the Cindersap Forest.
|-
| <tt>GrandpaShrineLocation [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| The position of grandpa's shrine. Corresponds to the upper left corner.
|-
| <tt>GreenhouseLocation [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| The default position of the greenhouse. Corresponds to the upper left corner of the greenhouse's foundation.
|-
| <tt>IgnoreLightingTiles T</tt>²<br />''(valid in indoor locations)''
| Whether to ignore lights on the <tt>Front</tt> and <tt>Buildings</tt> layers.<br />''Example: <tt>IgnoreLightingTiles true</tt>.''
|-
| <tt>indoorWater T</tt>²<br />''(valid in indoor locations)''
| Enables water logic (ie. fishing, etc.) in that location.
|-
| <tt>KitchenStandingLocation [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farmhouse)''
| The position the player's spouse will stand when using the kitchen.
|-
| <tt>Light [{{t|int x}} {{t|int y}} {{t|int type}}]+</tt><br />''(valid in any location)''
| 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.The {{t|type}} of light source can be one of...
* <tt>1</tt> (lantern);
* <tt>2</tt> (window);
* <tt>4</tt> (sconce);
* <tt>5</tt> (cauldron);
* <tt>6</tt> (indoor window);
* <tt>7</tt> (projector).
Any other value will crash the game.<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>LocationContext Default</tt><br />''(valid in any location)''
| Sets the map to be part of the mainland for game logic purposes, like weather.
|-
| <tt>LocationContext Island</tt><br />''(valid in any location)''
| Sets the map to be part of Ginger Island for game logic purposes, like weather.
|-
| <tt>MailboxLocation [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| The position of the player's mailbox. Corresponds to the upper left corner.
|-
| <tt>Music {{t|string name}}</tt><br />''(valid in any location)''
| 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>Music {{t|int start}} {{t|int end}} {{t|string name}}</tt><br />''(valid in any location)''
| Sets the music that plays when the player enters, where {{t|name}} is the cue name in the audio files, music will only play if the time is between {{t|int start}} (inclusive) and {{t|int end}} (exclusive).<br />''Example: <tt>Music 800 1200 MarlonsTheme</tt>.''
|-
| <tt>NightTiles [{{t|string layerName}} {{t|int x}} {{t|int y}} {{t|int tilesheetIndex}}]+</tt><br />''(valid in any location)''
| Changes the tile after 7pm. Outside, it works along <tt>DayTiles</tt>: set a <tt>DayTiles</tt> tile for the map to load between 6am to 7pm, then a <tt>NightTiles</tt> to load between 7pm to the end of the day. It is mostly used for lamps in the game.
|-
| <tt>NPCWarp [{{t|int fromX}} {{t|int fromY}} {{t|string toArea}} {{t|int toX}} {{t|int toY}}]+</tt><br />''(valid in any location)''
| Equivalent to <tt>Warp</tt>, but only usable by npcs.
|-
| <tt>Outdoors T</tt>²<br />''(valid in any location)''
| Sets whether the location is outdoors.<br />''Example: <tt>Outdoors true</tt>.''
|-
| <tt>ProduceArea {{t|int x}} {{t|int y}} {{t|int width}} {{t|int height}}</tt><br />''(valid in coops and barns)''
| Sets the area where animals can spawn within a coop or barn.<br />''Example: <tt>ProduceArea 6 4 8 7</tt>.''
|-
| <tt>ScreenshotRegion {{t|int left}} {{t|int top}} {{t|int right}} {{t|int bottom}}</tt><br />''(valid in any location)''
| Constrains the portion of the map rendered when screenshots are taken.<br />''Example: <tt>ScreenshotRegion 0 27 69 61</tt>.''
|-
| <tt>SeasonOverride [{{t|string season}}]</tt><br />''(valid in any location)''
| Assumes a specific season for most game checks. (If a crop is in season, which tilesheet to use, etc.)
|-
| <tt>ShippingBinLocation [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| The position of the default shipping bin. Corresponds to the upper left corner.
|-
| <tt>skipWeedGrowth T</tt>²<br />''(valid in any location)''
| Prevents weeds from spawning and spreading in this location.
|-
| <tt>SpouseAreaLocation [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| The position of the the outdoor spouse area. Corresponds to the upper left corner.
|-
| <tt>Stumps [{{t|int x}} {{t|int y}} {{t|unused}}]+</tt><br />''(valid in [[Secret Woods]])''
| Adds stumps to the Secret Woods map daily. The third field for each stump appears to be unused.<br />''Example: <tt>Stumps 24 6 3 29 7 3 26 10 3 46 6 3 34 26 3 41 26 3</tt>.''
|-
| <tt>TreatAsOutdoors T</tt>²<br />''(valid in indoor locations)''
| The location is treated as outdoors for the purposes of spawning anything other than lights from the <tt>Paths</tt> layer and yielding [[Coal]] from breaking rocks.<br />''Example: <tt>TreatAsOutdoors true</tt>.''
|-
| <tt>Trees [{{t|int x}} {{t|int y}} {{t|int type}}]+</tt><br />''(valid in any location)''
| 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><br />''(valid in any location)''
| Switches the portraits for the named NPCs to the unique variants for the location. An NPC <tt>Jane</tt> in location <tt>Room</tt> will switch to portrait <tt>Portraits/Jane_Room</tt>.<br/>''Example: <tt>UniquePortrait Maru</tt>.''
|-
| <tt>UniqueSprite [{{t|str name}}]+</tt><br />''(valid in any location)''
| Switches the spritesheets for the named NPCs to the unique variants for the location. An NPC <tt>Jane</tt> in location <tt>Room</tt> will switch to spritesheet <tt>Characters/Jane_Room</tt>.<br/>''Example: <tt>UniqueSprite Maru</tt>.''
|-
| <tt>ViewportFollowPlayer T</tt>²<br />''(valid in any location)''
| Forces the viewport to stay centered on the player.<br />''Example: <tt>ViewportFollowPlayer</tt>.''
|-
| <tt>Warp [{{t|int fromX}} {{t|int fromY}} {{t|string toArea}} {{t|int toX}} {{t|int toY}}]+</tt><br />''(valid in any location)''
| 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.''
|-
| <tt>WarpTotemEntry[{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| The position the player is warped to when teleporting to the farm via Warp Totem or Return Scepter.
|-
| <tt>WindowLight [{{t|int x}} {{t|int y}} {{t|int type}}]+</tt><br />''(valid in any location)''
| Adds light sources that are only lit during the day when it is not raining (like the light coming through a window). See <tt>Light</tt> for details.
|}
The following properties are used but apparently have no effect: <tt>Arch</tt>, <tt>Debris</tt>, <tt>Spouse</tt>, and <tt>Fish</tt>.
<small>¹ Map properties are primary handled in various methods of the <tt>GameLocation</tt> class, particularly <tt>resetLocalState</tt>.</small><br />
<small>² The <tt>T</tt> value (short for ''true'') is conventional, but any non-empty value will work too.</small>
===Tile properties===
Known tile properties (excluding specialised properties like <tt>TouchAction WomensLocker</tt>):¹
{| class="wikitable"
|-
! layer
! property
! explanation
|-
| <tt>Back</tt>
| <tt>Bed T</tt>²
| If the player stands on this tile, they're considered in bed for the purposes of stamina regen (in multiplayer) and pass-out logic.
|-
| <tt>Back</tt>
| <tt>Buildable T</tt>²
| Allows farm buildings to be placed on this tile if there are no other obstructions.
|-
| <tt>Back</tt>
| <tt>DefaultBedPosition T</tt>²
| Used in the farmhouse for the initial placement of the starting bed.
|-
| <tt>Back</tt>
| <tt>DefaultChildBedPosition T</tt>²
| Used in the upgraded farmhouse for the initial placement of the child beds.
|-
| <tt>Back</tt>
| <tt>Diggable T</tt>²
| Marks the tile as diggable with the hoe and enables planting crops. Also allows [[grass]] to spread to this tile.
|-
| <tt>Back</tt>
| <tt>NoFishing T</tt>²
| Prevents the player from casting the line onto this tile when fishing.
|-
| <tt>Back</tt>
| <tt>NoFurniture T</tt>²
| Prevents the player from placing furniture on this tile.
|-
| <tt>Back</tt>
| <tt>NoPath</tt>
| Excludes this tile from NPC pathing, making them go around it if necesssary.
|-
| <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>NoSprinklers T</tt>²
| Prevents sprinklers from being placed on this tile.
|-
| <tt>Back</tt>
| <tt>NPCBarrier T</tt>²
| Prevents NPCs from crossing this tile when used on the Farm (including coops, barns, and slime hutches), UndergroundMine, or the island. Also prevents some spawns on this tile, in those locations.
|-
| <tt>Back</tt>
| <tt>Passable T</tt>²
| Prevents players from walking or placing objects on this tile, even if they'd normally be able to do. (Direct opposite of <tt>Buildings Passable T</tt> below.) Commonly used on certain water tiles for bordering the sides of bridges, to prevent players from walking off into open water. Can be added as a single TileData object for a specific tile, or (more commonly) to every instance of a tile by editing the tileset and adding it to the tile index.
|-
| <tt>Back</tt>
| <tt>Placeable T</tt>²
| '''Prevents''' players from placing objects on this tile.
|-
| <tt>Back</tt>
| <tt>TemporaryBarrier T</tt>²
| Used only briefly when doors open. Marks this tile impassable to a player, while NPCs will treat it as an obstacle to pause before rushing through.
|-
| <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 (i.e. items splash into it, can refill watering can from it, can possibly fish in it, can possibly place crab pots in it, will water nearby paddy crops, will block most open-tile checks, will regenerate health in it if indoors, and will draw animated overlay over it if outdoors; if in the Mines, Sewer, or Submarine; or otherwise not in the Desert).
|-
| <tt>Back</tt>
| <tt>WaterSource T</tt>²
| Lets the player refill the watering can from this tile.
|-
| <tt>Buildings</tt>
| <tt>NPCPassable T</tt>²
| NPC-only version of <tt>Passable</tt> below. Allows NPCs to pass through this tile.
|-
| <tt>Buildings</tt>
| <tt>Passable T</tt>²
| Allows passing through a tile, even though Buildings tiles can't normally be walked through. Often used for small footbridges that need to be on Buildings, over water. Direct opposite of <tt>Back Passable T</tt> above. Can be added as a single TileData object for a specific tile, or (more commonly) to every instance of a tile by editing the tileset and adding it to the tile index.
|-
| <tt>Buildings</tt>
| <tt>Shadow T</tt>²
| Player-only version of <tt>Passable</tt> above. Allows the player to pass through this tile, but not NPCs.
|-
| <tt>Paths</tt>
| <tt>Order {{T|I}}</tt>
| To place on index 29 and 30 of the Paths tilsheet. Set the order the cabins will spawn at the creation of a Multiplayer save.
|}
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 Bus</tt>
| Starts the Bus Ride to the Desert mini-cutscene, works in conjunction with Action BusTicket.
|-
| <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 DesertBus</tt>
| Lets you ride the bus back to the Bus Stop..
|-
| <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 legendarySword</tt>
| Gives them the [[Galaxy Sword]] when holding a [[Prismatic Shard]].
|-
| <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 Blacksmith</tt>
| Opens Clint's shop menu, if Clint is nearby.
|-
| <tt>Buildings</tt>
| <tt>Action BrokenBeachBridge</tt>
| Prompts you to use wood to repair the bridge.
|-
| <tt>Buildings</tt>
| <tt>Action BusTicket</tt>
| Offers to let you go to the Calico Desert if the Bus has been repaired. Works in conjunction with TouchAction Bus.
|-
| <tt>Buildings</tt>
| <tt>Action BuyQiCoins</tt>
| Shows a dialogue which lets the player buy 100 Casino club coins.
|-
| <tt>Buildings</tt>
| <tt>Action Concessions</tt>
| Opens the snack shop in the theater. (Only from inside the theater.)
|-
| <tt>Buildings</tt>
| <tt>Action Carpenter</tt>
| Opens the carpenter menu, if Robin is nearby.
|-
| <tt>Buildings</tt>
| <tt>Action ColaMachine</tt>
| Offers to let the player buy a Joja cola.
|-
| <tt>Buildings</tt>
| <tt>Action ClubCards</tt><br /><tt>Action Blackjack</tt>
| Shows the casino blackjack minigame.
|-
| <tt>Buildings</tt>
| <tt>Action ClubComputer</tt><br /><tt>Action FarmerFile</tt>
| Shows a dialogue with play stats (steps taken, gifts given, dirt hoed, etc).
|-
| <tt>Buildings</tt>
| <tt>Action ClubSeller</tt>
| Shows a dialogue which lets the player buy a [[Statue of Endless Fortune]] for one million gold.
|-
| <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 Dialogue {{t|text}}</tt>
| Shows a generic dialogue box with the given text. See [[Modding:Dialogue|dialogue format]].<br />''Example: Action Dialogue Hi there @!''
|-
| <tt>Buildings</tt>
| <tt>Action DivorceBook</tt>
| Shows divorce options for the player's current marriage status (as if they clicked the [[Marriage#Divorce|divorce book]]).
|-
| <tt>Buildings</tt>
| <tt>Action Door {{t|npcName}} {{o|npcName}}</tt>
| Sets up an interior door that cannot be opened unless the player has two or more hearts of friendship with any of the named NPC(s). Placed on the lower of the two door tiles. See [[Modding:Dialogue|dialogue format]].<br />''Example: Action Door Abigail''
|-
| <tt>Buildings</tt>
| <tt>Action ElliotBook</tt>
| TODO: Explain what this does.
|-
| <tt>Buildings</tt>
| <tt>Action ElliotPiano</tt>
| TODO: Explain what this does.
|-
| <tt>Buildings</tt>
| <tt>Action EnterSewer</tt>
| Warps you to the sewer if you have obtained the key.
|-
| <tt>Buildings</tt>
| <tt>Action EvilShrineLeft</tt>
| Turns your kids into doves for a prismatic shard.
|-
| <tt>Buildings</tt>
| <tt>Action EvilShrineCenter</tt>
| Erases your ex-spouses memory of you.
|-
| <tt>Buildings</tt>
| <tt>Action EvilShrineRight</tt>
| Toggles monster spawning for your farm.
|-
| <tt>Buildings</tt>
| <tt>Action Garbage {{t|ID}}</tt>
| Has a chance to give a specific item to the player based on the {{t|ID}}. Can only be clicked once per day. TODO: Explain what each {{t|ID}} means.
|-
| <tt>Buildings</tt>
| <tt>Action Gunther</tt>
| Opens the museum menu where you can donate artifacts or claim rewards.
|-
| <tt>Buildings</tt>
| <tt>Action HMGTF</tt>
| Gives you "[[??HMTGF??]]" when you have a [[Super Cucumber]] in your hand.
|-
| <tt>Buildings</tt>
| <tt>Action IceCreamStand</tt>
| If Summer, shows the Ice Cream Stand shopping screen. Otherwise, the player will be told to come back in the summer. (Needs an NPC behind the stand.)
|-
| <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, if you're in the Farmhouse.
|-
| <tt>Buildings</tt>
| <tt>Action Letter {{t|string messageKey}}</tt>
| Loads a message with the given key from the ''Content\Strings\StringsFromMaps.xnb'' file and displays it on-screen as a letter. Uses the same syntax as ''Data\mail.xnb''.
|-
| <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 LuauSoup</tt>
| Used for the Luau Festival, this is where you insert a food item for the soup.
|-
| <tt>Buildings</tt>
| <tt>Action MagicInk</tt>
| Adds the Magic Ink to your wallet.
|-
| <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 Message {{t|string messageKey}}</tt>
| Loads a message with the given key from the ''Content\Strings\StringsFromMaps.xnb'' file and displays it in a dialogue box.
|-
| <tt>Buildings</tt>
| <tt>Action MessageOnce {{t|int eventID}} {{t|string message}}</tt>
| If the player hasn't seen the event with ID {{t|eventID}}, marks that event seen and displays the given message text in a dialogue box. This does ''not'' parse [[Modding:Dialogue|dialogue format]].
|-
| <tt>Buildings</tt>
| <tt>Action MessageSpeech {{t|string messageKey}}</tt>
| Identical to <tt>Action Message</tt>, but replaces the usual inspection cursor with a speech cursor.
|-
| <tt>Buildings</tt>
| <tt>Action MineSign {{t|string message}}</tt>
| Shows a mini-dialogue box with the given raw message text. This does ''not'' parse [[Modding:Dialogue|dialogue format]].
|-
| <tt>Buildings</tt>
| <tt>Action MinecartTransport</tt>
| Shows the minecart destination menu (or a message if not unlocked).
|-
| <tt>Buildings</tt>
| <tt>Action MineElevator</tt>
| Shows the mine elevator menu (to warp to a mine level) if the player has reached mine level 5+, else a mine elevator not working message.
|-
| <tt>Buildings</tt>
| <tt>Action NextMineLevel</tt>
| Warps the player to the next mine level (or level 1 if they're not in the mine).
|-
| <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 NPCMessage {{t|str name}} "{{t|str dialogueKey}}"</tt>
| If the named NPC is within 14 tiles of the player, reads dialogue with the given key from the string files and displays a dialogue box. See [[Modding:Dialogue|dialogue format]].<br />''Example: Action NPCMessage Abigail "Strings\\StringsFromCSFiles:Event.cs.1022"''
|-
| <tt>Buildings</tt>
| <tt>Action playSound {{t|str cueName}}</tt>
| Play the sound or music with the given name.
|-
| <tt>Buildings</tt>
| <tt>Action QiCoins</tt>
| Shows a dialogue which lets the player buy 10 Casino club coins if they have none, else shows how many they have.
|-
| <tt>Buildings</tt>
| <tt>Action Saloon</tt>
| Opens the Saloon menu, if Gus is nearby.
|-
| <tt>Buildings</tt>
| <tt>Action SandDragon</tt>
| Used for Part 3 of the Mysterious Mr. Qi Quest.
|-
| <tt>Buildings</tt>
| <tt>Action Shop</tt>
| On festival maps, opens the festival shop. No effect on non-festival maps.
|-
| <tt>Buildings</tt>
| <tt>Action Theater_BoxOffice</tt>
| Opens the ticket menu for the theater, if you have it unlocked.
|-
| <tt>Buildings</tt>
| <tt>Action TownMailbox {{t|ID}}</tt>
| TODO: Explain what this does.
|-
| <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 76 9 Mountain''
|-
| <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 WarpGreenhouse</tt>
| Warps the player to the inside of their greenhouse if they've unlocked it, else shows a message about the greenhouse ruins.
|-
| <tt>Buildings</tt>
| <tt>Action WizardBook</tt>
| If unlocked, you buy buildings from the wizard here.
|-
| <tt>Buildings</tt>
| <tt>Action WizardHatch</tt>
| If you're good enough friends with the wizard you warp to his basement, if not you get told you can't go in.
|-
| <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>
==Paths layer==
The <tt>Paths</tt> layer has icon tiles from the <tt>paths</tt> tilesheet which affect game behavior on the map:
[[File:PathsExplanation.png|thumb|The tile indexes shown in the table.]]
{| class="wikitable"
|-
! tile index
! explanation
! restrictions
|-
| 0–7
| No effect? TODO: verify how the pathing logic uses it.
|
|-
| 8
| Add this tile to the [[#Map properties 2|<tt>Light</tt> map property]] with light type 4 (sconce).
| Indoors and festivals only.²
|-
| 9–12
| Spawn a [[trees|tree]] when the location is created. Outside the farm, 50% chance to respawn each day. (See also 31–32.)<br />Available trees: oak (9), maple (10), pine (11), and palm 1 (12).
| Outdoors only.
|-
| 13–18
| Spawn debris when the location is created, or randomly each day. Outside the farm, respawn in spring.<br />Available debris: [[weeds|seasonal weed]] (13–15), rock (16–17), twig (18).
| Outdoors only.
|-
| 19
| Spawn a [[Large Log|large log]] when the farm is created, with the top-left corner on this tile.
| Farm only.
|-
| 20
| Spawn a [[boulder]] the farm is created, with the top-left corner on this tile..
| Farm only.
|-
| 21
| Spawn a [[Large Stump|hardwood stump]] when the farm is created (and every day on the forest farm), with the top-left corner on this tile.
| Farm only.
|-
| 22
| Spawn [[grass]] when the location is created, or randomly afterwards.
| Outdoors only.
|-
| 23
| Spawn a random oak, maple, or pine [[trees|tree]] at growth stage 2–3 when the location is created.
| Outdoors only.
|-
| 24–26
| Spawn a normal bush when the location is created. Medium bushes grow [[blackberry|blackberries]] and [[salmonberry|salmonberries]].<br />Available bushes: large (24), medium (25), small (26).
| Outdoors only.
|-
| 27
| When the location is created, add this tile to the [[#Map properties 2|<tt>BrookSounds</tt> map property]] with the <tt>babblingBrook</tt> sound.
| Outdoors only.
|-
| 28
| Spawn a [[grub]] here (33% chance per day, unless the map already has 50 grubs).
| [[Mutant Bug Lair]] only.
|-
| 29–30
| Place prebuilt [[cabin]]s in [[multiplayer]] based on the layout (29=nearby or 30=separate) and [[#Tile properties 2|<tt>Order</tt> tile property]], with the top-left corner on this tile.
| Farm only.
|-
| 31–32
| Spawn a [[trees|tree]] when the location is created. Outside the farm, 50% chance to respawn each day. (See also 9–12.)<br />Available trees: palm 2 (31), mahogany (32).
| Outdoors only.
|-
| 33
| Spawn a [[Golden Walnut|golden walnut]] bush when the location is created.
| Outdoors only.
|}
Notes:
# In the [[Mutant Bug Lair]], debris spawn rate is reduced to 33% chance per day.
# Restriction can be overridden with <tt>forceLoadPathLayerLights</tt> map property.
==Potential issues==
===Tilesheet order===
When you replace a vanilla map, '''don't''' change the order or IDs of the original tilesheets. Prefix new tilesheet IDs with <code>z_</code> to avoid changing the original order.
; Why this causes problems
: For example, let's say you replace a map which normally has these tilesheets in Tiled:
: [[File:Tiled tileset order A.png|thumb|none|The original tilesheet order.]]
: When you add a new tilesheet, note that the order changes from ''[paths, untitled tile sheet]'' to ''[customSheet, paths, untitled tile sheet]'':
: [[File:Tiled tileset order B.png|thumb|none|'''Wrong''' way to add a new tilesheet (changes the original order).]]
: If the game tries to access a tile from the first tilesheet, it will get it from <tt>customSheet</tt> instead of the expected <tt>Paths</tt> tilesheet. That can cause anything from visual glitches (e.g. showing the wrong tile images) to outright crashes (especially if the new tilesheet is smaller than the one it expected).
: To avoid that, always keep the original tilesheets in the same order and prefix new tilesheets with <code>z_</code> so they're added at the end:
: [[File:Tiled tileset order C.png|thumb|none|Correct way to add a new tilesheet.]]
; How to fix an affected tilesheet
: See ''[[#"mod reordered the original tilesheets"|"mod reordered the original tilesheets"]]'' below.
===Local copy of a vanilla tilesheet===
When editing a map in Tiled, you may need to copy vanilla tilesheets like <tt>path.png</tt> or <tt>spring_town.png</tt> into the map folder for Tiled to find. If the tilesheet is still there when you load the game, SMAPI will use it for your map instead of the game's vanilla tilesheet, which may have unintended effects (e.g. edits from recolor mods won't work in your map).
To avoid issues, you can either...
* Delete vanilla tilesheets from the folder before testing or releasing the mod.
* Rename the tilesheet file to start with a dot (like <tt>.spring_town.png</tt>) and reference that. When SMAPI loads the map in-game, it'll automatically ignore the dot and look for <tt>spring_town.png</tt> in the local files or <tt>Content/Maps</tt> folder.
===Map-specific issues===
The game makes some assumptions about maps which may break for modded maps. These are the known issues:
{| class="wikitable"
|-
! affected maps
! issue
|-
| <tt>Maps/Farm</tt><br /><tt>Maps/Farm_Combat</tt><br /><tt>Maps/Farm_Fishing</tt><br /><tt>Maps/Farm_Foraging</tt><br /><tt>Maps/Farm_Mining</tt>
|  
* The farm's <tt>Paths</tt> layer must have at least one tile with index 22 (grass spawn). This is used to initialise the grass code when the save is loaded, even if no grass is spawned.<ref>The grass sound is set in <tt>Grass::loadSprite</tt>, which is called from <tt>GameLocation::loadObjects</tt> if the <tt>Paths</tt> layer has tile index 22. (The game spawns a grass for each such tile, and later removes them.)</ref>
|-
| <tt>Maps/FarmHouse*</tt>
|  
* The two bed tiles where the player can walk must have two properties: <tt>Bed T</tt> (used to decide if the player is in bed) and <tt>TouchAction Sleep</tt>.
* Deleting or changing the wallpapers and floors will cause a game crash.
* The <tt>DayTiles</tt> and <tt>NightTiles</tt> map properties are cleared when loading the spouse room, so custom values for those properties won't work for married players.
|-
| <tt>Maps/SpouseRooms</tt>
|  
* If you add or resize any tilesheet, you must also edit <tt>Maps/FarmHouse1_marriage</tt> and <tt>Maps/FarmHouse2_marriage</tt> to have the same changes (even if you don't make any other changes to the farmhouse). This is needed because the tilesheet references and sizes are stored as part of the map file.
|}
<small><references /></small>
==='Save as' in Tiled===
When you use 'save as' in Tiled, never save into a different folder. That will change all the tilesheet references to point to the old folder, so it'll no longer work in-game. Instead, copy/move the map files to a different folder if needed.
===Locating tilesheets in Tiled===
When a map tilesheet is missing, never use the locate option to use a tilesheet from a different folder. That will add a complex tilesheet path which won't work in-game. Instead copy the tilesheets into the same folder as the map, and reference them from there.
==Troubleshooting==
See also [[#Potential issues|''potential issues'']] above for common issues.
==="Tilesheet paths must be a relative path without directory climbing (../)"===
; What does this mean?
: Your map uses a tilesheet that's outside its folder root. That might happen if you [[#'Save as' in Tiled|used 'save as' in Tiled to save into a different folder]], copied & pasted tiles between maps in different folders, or manually added a tilesheet from a different folder.
: For example:
<pre style="margin-left: 2em;">
📁 Stardew Valley/
📁 Content/
📁 Maps/
🗎 townInterior <──┐
📁 Mods/ │
📁 YourModName/ │ ../../../Content/Maps/townInterior
📁 assets/ │
🗎 your-map.tmx ───┘
</pre>
: This isn't allowed since it's very fragile (e.g. players might install your mod in a different folder path).
; How do I fix it?
:# Copy the tilesheets you're using into the same folder as the map.
:# For unchanged vanilla tilesheets, rename them to start with a dot (like <tt>.townInterior.png</tt>). This tells SMAPI to ignore the file when loading the map in-game, and load the one in the <tt>Content</tt> folder instead.
:# In Tiled, click the edit icon under the tilesheet.
:# In the tab that opens, click ''Tileset > Tileset Properties''.
:# Click the 'Image' field, then the 'Edit' button to locate the tilesheet in the same folder.
For a screenshot guide of steps 3-5, [https://imgur.com/a/rukygAr see these images] provided by Discord user foggywizard#7430.
: After fixing it, the above example would look like this:
<pre style="margin-left: 2em;">
📁 Stardew Valley/
📁 Mods/
📁 YourModName/
📁 assets/
🗎 your-map.tmx ───┐
🗎 .townInterior.png <──┘ .townInterior.png
</pre>
==="mod reordered the original tilesheets"===
; What does this mean?
: See [[#Tilesheet order|''tilesheet order'']] for more info.
; How do I fix it?
: Always keep the original tilesheets in the same order and prefix new tilesheets with <code>z_</code> so they're added at the end:
: [[File:Tiled tileset order C.png|thumb|none|Correct way to add a new tilesheet.]]
: To rename an affected tilesheet in Tiled:
<gallery style="margin-left: 2em;">
File:Tiled rename tileset A.png|In the tileset pane, click the tab for the tileset and then click the edit icon.
File:Tiled rename tileset B.png|Click ''Tileset > Tileset Properties'' from the top menu to show the properties pane.
File:Tiled rename tileset C.png|Change the name in the ''Name'' field.
</gallery>
==="mod has no tilesheet with ID '<name>'"===
; What does this mean?
: You replaced one of the vanilla maps, but your custom map doesn't have all of the original map's tilesheets (or you changed their names in Tiled). This will cause a crash if the game tries to access the missing tilesheet.
; How do I fix it?
: Compare the original and custom maps in Tiled. For each tilesheet in the original map, make sure it's also in the custom map '''and''' has the same name (even if you're not using it).
: If you need to rename a tilesheet:
:# In the tileset pane, click the tab for the tileset and then click the edit icon.
:# Click ''Tileset > Tileset Properties'' from the top menu to show the properties pane.
:# Change the ''Name'' field to match the original map's tilesheet name.
==Making changes with SMAPI==
This page mainly covers editing maps with Tiled, but you can make the same changes programmatically using a [[Modding:Modder Guide/Get Started|C# SMAPI mod]]. There are two main approaches to changing a location in C# code.
===Using an asset editor===
Most map edits should be applied using an [[Modding:Modder Guide/APIs/Content|asset editor]], so your changes aren't lost if another mod reloads the map. This works with the <tt>Map</tt> asset directly before it's used by the [[Modding:Modder Guide/Game Fundamentals#GameLocation et al|in-game location]], so you can't use location methods at this point.
First you'll need to set up an asset editor, which mainly involves implementing <tt>IAssetEditor</tt> on your mod class. For example, this mod code edits the town map:
<syntaxhighlight lang="C#">
/// <summary>The mod entry point.</summary>
internal class ModEntry : Mod, IAssetEditor
{
/// <inheritdoc />
public override void Entry(IModHelper helper) { }
/// <inheritdoc />
public bool CanEdit<T>(IAssetInfo asset)
{
return asset.AssetNameEquals("Maps/Town");
}
/// <inheritdoc />
public void Edit<T>(IAssetData asset)
{
IAssetDataForMap editor = asset.AsMap();
Map map = editor.Data;
// your code here
}
/// <summary>Get a tile from the map.</summary>
/// <param name="map">The map instance.</param>
/// <param name="layerName">The name of the layer from which to get a tile.</param>
/// <param name="tileX">The X position measured in tiles.</param>
/// <param name="tileY">The Y position measured in tiles.</param>
/// <returns>Returns the tile if found, else <c>null</c>.</returns>
private Tile GetTile(Map map, string layerName, int tileX, int tileY)
{
Layer layer = map.GetLayer(layerName);
Location pixelPosition = new Location(tileX * Game1.tileSize, tileY * Game1.tileSize);
return layer.PickTile(pixelPosition, Game1.viewport.Size);
}
}
</syntaxhighlight>
Now you can make any changes you want to the map before it's loaded by location. For example, you can...
<ul>
<li>Add a custom tilesheet:
<syntaxhighlight lang="C#">
map.AddTileSheet(new TileSheet(
id: "z_custom-tilesheet", // always prefix custom tilesheets with z_ to avoid reordering vanilla tilesheets
map: map,
imageSource: this.Helper.Content.GetActualAssetKey("assets/tilesheet.png", ContentSource.ModFolder), // get a unique asset name for local mod file which can be passed to the game
sheetSize: new Size(32, 64), // the size in tiles for the tilesheet image
tileSize: new Size(16) // the size of each tile in pixels, should always be 16
));
</syntaxhighlight></li>
<li>Manage map properties:
<syntaxhighlight lang="C#">
// get a property value
string currentMusic = map.Properties.TryGetValue("Music", out PropertyValue rawMusic)
? rawMusic.ToString()
: null;
// add/replace a property
map.Properties["Music"] = "MarlonsTheme";
// delete a property
map.Properties.Remove("Music");
</syntaxhighlight></li>
<li>Manage tile properties:
<syntaxhighlight lang="C#">
// get tile
Tile tile = this.GetTile(map, layerName: "Back", tileX: 10, tileY: 20);
if (tile == null)
return; // you should handle the tile not being there to avoid errors
// get a property value
string diggable = tile.TileIndexProperties.TryGetValue("Diggable", out PropertyValue rawDiggable) || tile.Properties.TryGetValue("Diggable", out rawDiggable)
? rawDiggable?.ToString()
: null;
// set a property
tile.Properties["Diggable"] = "T";
// delete a property
tile.Properties.Remove("Diggable");
</syntaxhighlight></li>
<li>Add new tiles:
<syntaxhighlight lang="C#">
int tileX = 10;
int tileY = 20;
Layer layer = map.GetLayer("Back");
// add a static tile
layer.Tiles[tileX, tileY] = new StaticTile(
layer: layer,
tileSheet: map.GetTileSheet("z_custom-tilesheet"),
tileIndex: 100, // the sprite index in the tilesheet
blendMode: BlendMode.Alpha // should usually be Alpha
);
// add an animated tile
layer.Tiles[tileX, tileY] = new AnimatedTile(
layer: layer,
tileFrames: new StaticTile[]
{
new StaticTile(...),
new StaticTile(...),
new StaticTile(...),
},
frameInterval: 100 // frame duration in milliseconds
);
</syntaxhighlight></li>
<li>Delete tiles:
<syntaxhighlight lang="C#">
layer.Tiles[tileX, tileY] = null;
</syntaxhighlight></li>
<li>Apply tile transformations:
<syntaxhighlight lang="C#">
Tile tile = this.GetTile(map, layerName: "Back", tileX, tileY);
tile.Properties["@Rotation"] = 45; // rotate it 45° clockwise
tile.Properties["@Flip"] = 1; // flip the tile: 0 (normal), 1 (horizontal), 2 (vertical)
</syntaxhighlight></li>
</ul>
See also [[Modding:Modder Guide/APIs/Content#Edit a map|SMAPI's map edit helper]], which lets you do things like merge a custom map area into the map.
===After location is loaded===
After the [[Modding:Modder Guide/Game Fundamentals#GameLocation et al|in-game location]] is loaded, you can edit locations and their maps using the game's helpers. Be careful doing this though: another mod (or sometimes the game itself) may reload the location at any time, which would lose your changes if you're not careful.
For example, within any [[Modding:Modder Guide/APIs/Events|in-game events]] you can...
<ul>
<li>Access the map to use the methods described above:
<syntaxhighlight lang="C#">
Map map = location.map;
</syntaxhighlight></li>
<li>Manage tile properties:
<syntaxhighlight lang="C#">
Town town = (Town)Game1.getLocationFromName("Town");
int tileX = 10;
int tileY = 20;
// get property value
string diggable = town.doesTileHaveProperty(tileX, tileY, "Diggable", "Back");
// set property value
location.setTileProperty(tileX, tileY, "Back", "Diggable", "T");
</syntaxhighlight></li>
<li>Manage tiles:
<syntaxhighlight lang="C#">
location.removeTile(tileX, tileY, "Back");
</syntaxhighlight></li>
</ul>
==See also==
* Discord user foggywizard#7430 [https://imgur.com/a/l1Ql16D annotated some screenshot guides for using Tiled]. These include an annotated overview, how to find where the coordinates are, and how to rename a tilesheet.
[[Category:Modding]]
[[ru:Модификации:Карты]]
This page explains how to edit maps. This is an advanced guide for modders.
==Intro==
===Basic concepts===
<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...
{| class="wikitable"
|-
! layer name
! typical contents
|-
| Back
| Terrain, water, and basic features (like permanent paths).
|-
| Buildings
| Placeholders for buildings (like the farmhouse). Any tiles placed on this layer will act like a wall unless the tile property has a "Passable" "T".
|-
| Paths
| Flooring, paths, grass, and debris (like stones, weeds, and stumps from the 'paths' tilesheet) which can be removed by the player.
|-
| Front
| Objects that are drawn on top of things behind them, like most trees. These objects will be drawn on top of the player if the player is North of them but behind the player if the player is south of them.
|-
| AlwaysFront
| Objects that are always drawn on top of other layers as well as the player. This is typically used for foreground effects like foliage cover.
|}</li>
[[File:MapLayers.png]]
<li>(Using Tiled) There are 2 different types of layers along with the 5 main layers, Objects Layer (cloud-like icon) and Tile Layer (grid icon). The Tile Layer is where you make map edits (placing and removing tiles) and the Objects Layers is where you add and edit tile data. Your layers must match the ones above. Note that depending on the map, they may be missing a Paths or AlwaysFront layer</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 (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>
===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]]
===Map formats===
There are two map formats used in Stardew Valley modding: <tt>.tmx</tt> (from the Tiled map editor) and <tt>.tbin</tt> (from the now-deprecated tIDE map editor). The features supported by both formats are almost identical, but there are a few differences:
{| class="wikitable"
|-
! feature
! <tt>.tmx</tt>
! <tt>.tbin</tt>
|-
| format
| ✓ XML (basically text)
| ✘ binary
|-
| edit in Tiled
| ✓ supported
| ✓ supported with plugin
|-
| edit directly
| ✓ can open in a text editor
| ✘ not supported
|-
| tile flip
| ✓ supported
| ✘ not supported
|-
| tile rotation
| ✓ supported
| ✘ not supported
|-
| source control
| ✓ efficient storage, can diff changes
| ✘ inefficient storage (need to copy entire file with each commit), can't diff changes
|}
<tt>.tmx</tt> is recommended per the above, but both formats are fine to use, and you can convert between them in Tiled by clicking ''File > Export As''.
==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:Modder Guide/Get Started|Create a SMAPI mod]].
# See ''[[#Making changes with SMAPI|Making changes with SMAPI]]'' below.
The rest of this guide assumes you're using Tiled, but many of the concepts are transferrable and you can use both Tiled and SMAPI (e.g. create/edit maps in Tiled and load/edit them in SMAPI).
===Using Tiled===
Tiled is a popular map editor that can be used to edit Stardew Valley maps, no programming needed. You need to [[Modding:Editing XNB files|unpack the map's XNB]], edit the map, and make a {{nexus mod|1915|Content Patcher}} or SMAPI mod to load your map. If you want to use this approach:
<ol>
<li>Install the [http://www.mapeditor.org/ latest version of Tiled].</li>
<li>Once installed, at the top left, go to Edit > Preferences > Plugins and enable the tbin plugin (<tt>tbin.dll</tt> on Windows, <tt>libtbin.so</tt> on Linux, or <tt>libtbin.dylib</tt> on Mac).
<li>Set the following settings:
{| class="wikitable"
|-
! setting
! value
! reason
|-
| ''View > Snapping > Snap to Grid''
| ✓ enabled
| This is required to convert objects back into the game's format.
|-
| ''View > Highlight Current Layer''
| ✓ enabled
| This makes it more clear which tile you're editing.
|}</li>
<li>See [[Modding:Editing XNB files]] for help unpacking & packing the map files.</li>
<li>See instructions below for map changes.</li>
</ol>
(If you use xnbcli to [[Modding:Editing XNB files#Unpack game files|unpack the original game maps]], you'll need the <tt>.tbin</tt> plugin even if you plan to use <tt>.tmx</tt> since xnbcli still produces <tt>.tbin</tt> files.)
===Tilesets vs Tilesheets===
<tt>Tilesheets</tt> are the <tt>.png</tt> files used as source images. Tilesheets have no animation, properties, terrains, or anything else but pixels associated with them -- they're just images. <tt>Tilesets</tt> are Tiled's XML files that contain all the information about how the map uses the source image. They are confusingly named and often used interchangeably.
==Map edits==
===Editing maps===
Important note: when making custom maps, always start with a vanilla map and edit it. Don't try to create a new map in Tiled; the game needs certain tiles, map properties, etc to be present.
# [[Modding:Editing XNB files|Unpack]] the game's <tt>Content/Maps</tt> folder and create a copy to edit your maps in. Use this copy of the folder to edit any maps in before moving them to your mod release folder.
# Use the same method to unpack the map you want to edit if it is not a vanilla one, then place the map in your editing folder.
# Open the <tt>.tbin</tt> or <tt>.tmx</tt> file via Tiled. Note: make sure the file is in the same folder as the unpacked tilesheets!
# Make your changes.
# Save the file. Don't use <tt>Save as</tt> to change folders, as your tilesheet paths will be wrong.
# Move the <tt>.tbin</tt> or <tt>.tmx</tt> file, and any custom tilesheets it needs, to your mod release folder. Place them in the <tt>assets</tt> folder.
# Load your map via SMAPI or Content Patcher (or another framework mod).
===Custom map===
You can add a new map and location to the game. The easiest option is to create the map using Tiled, then use [[Modding:Content Patcher|Content Patcher]] to [https://github.com/Pathoschild/StardewMods/blob/develop/ContentPatcher/docs/author-guide.md#custom-locations add the custom location to the game]. After loading your save, you can use this console command to jump to the map: <code>debug warp YourLocationName X Y</code>.
Note that the map must be built in a certain pattern; look at the maps in the <tt>Content/Maps</tt> folder for examples. It's often easier to start from an existing map and modify it, instead of starting from scratch.
{{note box|'''Using Content Patcher to add custom locations is strongly recommended.'''<br />You can add new locations in C# yourself, but be aware of factors like object persistence and NPC pathfinding that are easy to get wrong. If you ''really'' want to do it yourself, use the [[Modding:Modder Guide/APIs/Events#Specialised.LoadStageChanged|specialized <tt>LoadStageChanged</tt> event]] to add the location to <tt>Game1.locations</tt> during the <tt>CreatedInitialLocations</tt> or <tt>SaveAddedLocations</tt> stage.}}
===Adding tilesets===
You can add new sprites, tiles, or images to a map, from both custom and vanilla sources. If you're editing a vanilla map, make sure to [[#Tilesheet order|prefix custom tileset names with <code>z_</code>]] to avoid shifting the vanilla tilesheet indexes.
# Open the map that you created or are editing.
# Click <tt>Map</tt> then ''Add External Tileset...'' in the top menu, and open a <tt>.tsx</tt> file you have in the same folder.
# You should have a new copy of the tileset in your map, with any saved animations, properties, or terrains still intact.
====Re-using vanilla tilesets====
If you want to use a tilesheet like <tt>spring_outdoorsTileSheet.png</tt> in your map, adding a new tileset from a <tt>.png</tt> file means you need to re-animate any animated tiles, re-add properties like diggable and terrain types. You can avoid this by first exporting them from an existing map, then using external tilesets, instead.
# Open an existing map that already has the properties and animations you want.
# In the tileset pane, click the wrench to ''Edit Tileset''. It should open a new edit tab.
# In the new window that opens, click ''File'', then ''Export as...'' and save it as a .tsx file.
# Close the tileset editor.
====Replace existing tileset====
If you are already using a tilesheet image, you can replace its tileset.
# Open the map that you created or are editing.
# In the tileset pane on the right, click the tab for your existing version.
# Under that, click the ''Replace Tileset'' button.
# Choose the <tt>.tsx</tt> file you saved, and click Open.
====Adding a new custom tilesheet====
If you made a your own tilesheet and are adding it to a map the first time, you can create a new tileset from image.
# Create your spritesheet and place it in the same folder as your <tt>.tbin</tt> or <tt>.tmx</tt> map file. This should be a PNG image with images divided into 16x16 tiles (see [[Modding:Editing XNB files#Intro]] 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.
## Make sure that ''Embed in map'' is checked.
## Keep the defaults for the other settings and click ''OK''.
===Painting tiles onto your map===
## In the ''Layers'' pane, click the layer you want to edit.
## At the top left of Tiled's toolbar, click the Stamp Brush.
## In the ''Tilesets'' pane, click the tab for the tileset you want to use.
## 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), type (always 'string' in Stardew Valley), and value (which configures the property). See [[#Known properties|known properties]] below.
In 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, type (always 'string' in Stardew Valley), and value. 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.
To view tile properties:
# 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 [[#Using Tiled]]), and only one tile is selected.
# Change its Name field to <tt>TileData</tt>.
# See previous for how to edit its properties.
===Tiles===
You can edit the tiles for an existing map. See the [http://doc.mapeditor.org Tiled documentation] for more info.
===Tile animation===
[[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).
In Tiled:
:# Click the edit button (wrench icon) for the tilesheet in the ''Tilesets'' pane.
:# Select the tile you want to animate in the new view.
:# Click ''Tileset > Tile Animation Editor'' in the toolbar to show that window.
:# In the new window, drag tiles from the tilesheet into the box on the left to create a ''frame'' (one image in the sequence). If you need to delete frames, select the frame(s) and press Backspace/Delete(Windows) or fn + Backspace(Apple)
:# 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.
===Tile flip/rotation===
[[File:Tiled tile rotation.png|thumb|An example tile rotated four ways, below the Tiled flip/rotate buttons.]]
You can rotate and flip tiles without needing to create rotated/flipped versions of the tilesheet. This needs SMAPI 3.4 or later to be installed; the base game doesn't recognize tile transforms.
In Tiled:
:# With the stamp tool selected, click the tile in the tilesheet you want to use.
:# Click the flip or rotate buttons (see image at right).
:# Click the map to place the flipped/rotated tile.
{{note box|'''This only works with <tt>.tmx</tt> map files.'''<br /> Tile transforms aren't supported by the <tt>.tbin</tt> plugin. See [[#Map formats|''map formats'']] for more info.}}
==Known properties==
===Map properties===
Known map properties:¹
{| class="wikitable"
|-
! property
! explanation
|-
| <tt>AmbientLight {{t|byte r}} {{t|byte g}} {{t|byte b}}</tt><br />''(valid in indoor locations and locations that ignore outdoor lighting)''
| Sets the [[wikipedia:RGB color model|RGB colour]] that is subtracted from white (255,255,255) in order to create the ambient light.<br />''Example: <tt>AmbientLight 95 95 95</tt> for a normal indoor daytime lighting.''
|-
| <tt>BackwoodsEntry [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| The position the player is warped to when entering the farm from the Backwoods.
|-
| <tt>BrookSounds [{{t|int x}} {{t|int y}} {{t|int type}}]</tt><br />''(valid in outdoor locations)''
| Adds sound sources. The {{t|x}} {{t|y}} fields are the tile coordinates, and {{t|type}} is the ambient sound ID. The {{t|type}} of sound can be one of...
* <tt>0</tt> (babblingBrook);
* <tt>1</tt> (cracklingFire);
* <tt>2</tt> (engine);
* <tt>3</tt> (cricket).
|-
| <tt>BusStopEntry [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| The position the player is warped to when entering the farm from the Bus Stop.
|-
| <tt>CanCaskHere T</tt>²<br />''(valid in any location)''
| Allows casks to work in that location.
|-
| <tt>DayTiles [{{t|string layerName}} {{t|int x}} {{t|int y}} {{t|int tilesheetIndex}}]+</tt><br />''(valid in any location)''
| Sets tiles to appear between 6AM to 7PM. Anytime before 7pm, this finds the tile at position ({{t|x}}, {{t|y}}) on the map layer matching {{t|layerName}}, changes its tilesheet index to the specified {{t|tilesheetIndex}}, and adds a glow to simulate daylight. The glow will only be added if the location is indoors and the {{t|tilesheetIndex}} is 256, 288, 405, 469, or 1224. The parameters can be repeated to affect multiple tiles.<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><br />''(valid in indoor locations)''
| Adds functionality to interior doors. Used with <tt>Action Door</tt> tile properties. 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>FarmCaveEntry [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| The position the player is warped to when entering the farm from the farm cave.
|-
| <tt>FarmHouseEntry [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| Changes the position of the Farm House. Corresponds to the front door, or the position the player will be warped to when leaving the house.
|-
| <tt>Feed {{t|int x}} {{t|int y}}</tt><br />''(valid in coops and barns)''
| Sets the spawn location of the [[Hay Hopper]] in a coop or barn.<br />''Example: <tt>Feed 3 2</tt>.''
|-
| <tt>forceLoadPathLayerLights T</tt>²<br />''(valid in outdoor non-festival locations)''
| Whether to load lights from the <tt>Paths</tt> layer on maps where they would not normally be.<br />''Example: <tt>forceLoadPathLayerLights true</tt>.''
|-
| <tt>ForceSpawnForageables T</tt>²<br />''(valid in indoor locations)''
| Enables forage items spawning in that location.
|-
| <tt>ForestEntry [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| The position the player is warped to when entering the farm from the Cindersap Forest.
|-
| <tt>GrandpaShrineLocation [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| The position of grandpa's shrine. Corresponds to the upper left corner.
|-
| <tt>GreenhouseLocation [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| The default position of the greenhouse. Corresponds to the upper left corner of the greenhouse's foundation.
|-
| <tt>IgnoreLightingTiles T</tt>²<br />''(valid in indoor locations)''
| Whether to ignore lights on the <tt>Front</tt> and <tt>Buildings</tt> layers.<br />''Example: <tt>IgnoreLightingTiles true</tt>.''
|-
| <tt>indoorWater T</tt>²<br />''(valid in indoor locations)''
| Enables water logic (ie. fishing, etc.) in that location.
|-
| <tt>KitchenStandingLocation [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farmhouse)''
| The position the player's spouse will stand when using the kitchen.
|-
| <tt>Light [{{t|int x}} {{t|int y}} {{t|int type}}]+</tt><br />''(valid in any location)''
| 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.The {{t|type}} of light source can be one of...
* <tt>1</tt> (lantern);
* <tt>2</tt> (window);
* <tt>4</tt> (sconce);
* <tt>5</tt> (cauldron);
* <tt>6</tt> (indoor window);
* <tt>7</tt> (projector).
Any other value will crash the game.<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>LocationContext Default</tt><br />''(valid in any location)''
| Sets the map to be part of the mainland for game logic purposes, like weather.
|-
| <tt>LocationContext Island</tt><br />''(valid in any location)''
| Sets the map to be part of Ginger Island for game logic purposes, like weather.
|-
| <tt>MailboxLocation [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| The position of the player's mailbox. Corresponds to the upper left corner.
|-
| <tt>Music {{t|string name}}</tt><br />''(valid in any location)''
| 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>Music {{t|int start}} {{t|int end}} {{t|string name}}</tt><br />''(valid in any location)''
| Sets the music that plays when the player enters, where {{t|name}} is the cue name in the audio files, music will only play if the time is between {{t|int start}} (inclusive) and {{t|int end}} (exclusive).<br />''Example: <tt>Music 800 1200 MarlonsTheme</tt>.''
|-
| <tt>NightTiles [{{t|string layerName}} {{t|int x}} {{t|int y}} {{t|int tilesheetIndex}}]+</tt><br />''(valid in any location)''
| Changes the tile after 7pm. Outside, it works along <tt>DayTiles</tt>: set a <tt>DayTiles</tt> tile for the map to load between 6am to 7pm, then a <tt>NightTiles</tt> to load between 7pm to the end of the day. It is mostly used for lamps in the game.
|-
| <tt>NPCWarp [{{t|int fromX}} {{t|int fromY}} {{t|string toArea}} {{t|int toX}} {{t|int toY}}]+</tt><br />''(valid in any location)''
| Equivalent to <tt>Warp</tt>, but only usable by npcs.
|-
| <tt>Outdoors T</tt>²<br />''(valid in any location)''
| Sets whether the location is outdoors.<br />''Example: <tt>Outdoors true</tt>.''
|-
| <tt>ProduceArea {{t|int x}} {{t|int y}} {{t|int width}} {{t|int height}}</tt><br />''(valid in coops and barns)''
| Sets the area where animals can spawn within a coop or barn.<br />''Example: <tt>ProduceArea 6 4 8 7</tt>.''
|-
| <tt>ScreenshotRegion {{t|int left}} {{t|int top}} {{t|int right}} {{t|int bottom}}</tt><br />''(valid in any location)''
| Constrains the portion of the map rendered when screenshots are taken.<br />''Example: <tt>ScreenshotRegion 0 27 69 61</tt>.''
|-
| <tt>SeasonOverride [{{t|string season}}]</tt><br />''(valid in any location)''
| Assumes a specific season for most game checks. (If a crop is in season, which tilesheet to use, etc.)
|-
| <tt>ShippingBinLocation [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| The position of the default shipping bin. Corresponds to the upper left corner.
|-
| <tt>skipWeedGrowth T</tt>²<br />''(valid in any location)''
| Prevents weeds from spawning and spreading in this location.
|-
| <tt>SpouseAreaLocation [{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| The position of the the outdoor spouse area. Corresponds to the upper left corner.
|-
| <tt>Stumps [{{t|int x}} {{t|int y}} {{t|unused}}]+</tt><br />''(valid in [[Secret Woods]])''
| Adds stumps to the Secret Woods map daily. The third field for each stump appears to be unused.<br />''Example: <tt>Stumps 24 6 3 29 7 3 26 10 3 46 6 3 34 26 3 41 26 3</tt>.''
|-
| <tt>TreatAsOutdoors T</tt>²<br />''(valid in indoor locations)''
| The location is treated as outdoors for the purposes of spawning anything other than lights from the <tt>Paths</tt> layer and yielding [[Coal]] from breaking rocks.<br />''Example: <tt>TreatAsOutdoors true</tt>.''
|-
| <tt>Trees [{{t|int x}} {{t|int y}} {{t|int type}}]+</tt><br />''(valid in any location)''
| 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><br />''(valid in any location)''
| Switches the portraits for the named NPCs to the unique variants for the location. An NPC <tt>Jane</tt> in location <tt>Room</tt> will switch to portrait <tt>Portraits/Jane_Room</tt>.<br/>''Example: <tt>UniquePortrait Maru</tt>.''
|-
| <tt>UniqueSprite [{{t|str name}}]+</tt><br />''(valid in any location)''
| Switches the spritesheets for the named NPCs to the unique variants for the location. An NPC <tt>Jane</tt> in location <tt>Room</tt> will switch to spritesheet <tt>Characters/Jane_Room</tt>.<br/>''Example: <tt>UniqueSprite Maru</tt>.''
|-
| <tt>ViewportFollowPlayer T</tt>²<br />''(valid in any location)''
| Forces the viewport to stay centered on the player.<br />''Example: <tt>ViewportFollowPlayer</tt>.''
|-
| <tt>Warp [{{t|int fromX}} {{t|int fromY}} {{t|string toArea}} {{t|int toX}} {{t|int toY}}]+</tt><br />''(valid in any location)''
| 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.''
|-
| <tt>WarpTotemEntry[{{t|int x}} {{t|int y}}]</tt><br />''(valid in farm)''
| The position the player is warped to when teleporting to the farm via Warp Totem or Return Scepter.
|-
| <tt>WindowLight [{{t|int x}} {{t|int y}} {{t|int type}}]+</tt><br />''(valid in any location)''
| Adds light sources that are only lit during the day when it is not raining (like the light coming through a window). See <tt>Light</tt> for details.
|}
The following properties are used but apparently have no effect: <tt>Arch</tt>, <tt>Debris</tt>, <tt>Spouse</tt>, and <tt>Fish</tt>.
<small>¹ Map properties are primary handled in various methods of the <tt>GameLocation</tt> class, particularly <tt>resetLocalState</tt>.</small><br />
<small>² The <tt>T</tt> value (short for ''true'') is conventional, but any non-empty value will work too.</small>
===Tile properties===
Known tile properties (excluding specialised properties like <tt>TouchAction WomensLocker</tt>):¹
{| class="wikitable"
|-
! layer
! property
! explanation
|-
| <tt>Back</tt>
| <tt>Bed T</tt>²
| If the player stands on this tile, they're considered in bed for the purposes of stamina regen (in multiplayer) and pass-out logic.
|-
| <tt>Back</tt>
| <tt>Buildable T</tt>²
| Allows farm buildings to be placed on this tile if there are no other obstructions.
|-
| <tt>Back</tt>
| <tt>DefaultBedPosition T</tt>²
| Used in the farmhouse for the initial placement of the starting bed.
|-
| <tt>Back</tt>
| <tt>DefaultChildBedPosition T</tt>²
| Used in the upgraded farmhouse for the initial placement of the child beds.
|-
| <tt>Back</tt>
| <tt>Diggable T</tt>²
| Marks the tile as diggable with the hoe and enables planting crops. Also allows [[grass]] to spread to this tile.
|-
| <tt>Back</tt>
| <tt>NoFishing T</tt>²
| Prevents the player from casting the line onto this tile when fishing.
|-
| <tt>Back</tt>
| <tt>NoFurniture T</tt>²
| Prevents the player from placing furniture on this tile.
|-
| <tt>Back</tt>
| <tt>NoPath</tt>
| Excludes this tile from NPC pathing, making them go around it if necesssary.
|-
| <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>NoSprinklers T</tt>²
| Prevents sprinklers from being placed on this tile.
|-
| <tt>Back</tt>
| <tt>NPCBarrier T</tt>²
| Prevents NPCs from crossing this tile when used on the Farm (including coops, barns, and slime hutches), UndergroundMine, or the island. Also prevents some spawns on this tile, in those locations.
|-
| <tt>Back</tt>
| <tt>Passable T</tt>²
| Prevents players from walking or placing objects on this tile, even if they'd normally be able to do. (Direct opposite of <tt>Buildings Passable T</tt> below.) Commonly used on certain water tiles for bordering the sides of bridges, to prevent players from walking off into open water. Can be added as a single TileData object for a specific tile, or (more commonly) to every instance of a tile by editing the tileset and adding it to the tile index.
|-
| <tt>Back</tt>
| <tt>Placeable T</tt>²
| '''Prevents''' players from placing objects on this tile.
|-
| <tt>Back</tt>
| <tt>TemporaryBarrier T</tt>²
| Used only briefly when doors open. Marks this tile impassable to a player, while NPCs will treat it as an obstacle to pause before rushing through.
|-
| <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 (i.e. items splash into it, can refill watering can from it, can possibly fish in it, can possibly place crab pots in it, will water nearby paddy crops, will block most open-tile checks, will regenerate health in it if indoors, and will draw animated overlay over it if outdoors; if in the Mines, Sewer, or Submarine; or otherwise not in the Desert).
|-
| <tt>Back</tt>
| <tt>WaterSource T</tt>²
| Lets the player refill the watering can from this tile.
|-
| <tt>Buildings</tt>
| <tt>NPCPassable T</tt>²
| NPC-only version of <tt>Passable</tt> below. Allows NPCs to pass through this tile.
|-
| <tt>Buildings</tt>
| <tt>Passable T</tt>²
| Allows passing through a tile, even though Buildings tiles can't normally be walked through. Often used for small footbridges that need to be on Buildings, over water. Direct opposite of <tt>Back Passable T</tt> above. Can be added as a single TileData object for a specific tile, or (more commonly) to every instance of a tile by editing the tileset and adding it to the tile index.
|-
| <tt>Buildings</tt>
| <tt>Shadow T</tt>²
| Player-only version of <tt>Passable</tt> above. Allows the player to pass through this tile, but not NPCs.
|-
| <tt>Paths</tt>
| <tt>Order {{T|I}}</tt>
| To place on index 29 and 30 of the Paths tilsheet. Set the order the cabins will spawn at the creation of a Multiplayer save.
|}
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 Bus</tt>
| Starts the Bus Ride to the Desert mini-cutscene, works in conjunction with Action BusTicket.
|-
| <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 DesertBus</tt>
| Lets you ride the bus back to the Bus Stop..
|-
| <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 legendarySword</tt>
| Gives them the [[Galaxy Sword]] when holding a [[Prismatic Shard]].
|-
| <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 Blacksmith</tt>
| Opens Clint's shop menu, if Clint is nearby.
|-
| <tt>Buildings</tt>
| <tt>Action BrokenBeachBridge</tt>
| Prompts you to use wood to repair the bridge.
|-
| <tt>Buildings</tt>
| <tt>Action BusTicket</tt>
| Offers to let you go to the Calico Desert if the Bus has been repaired. Works in conjunction with TouchAction Bus.
|-
| <tt>Buildings</tt>
| <tt>Action BuyQiCoins</tt>
| Shows a dialogue which lets the player buy 100 Casino club coins.
|-
| <tt>Buildings</tt>
| <tt>Action Concessions</tt>
| Opens the snack shop in the theater. (Only from inside the theater.)
|-
| <tt>Buildings</tt>
| <tt>Action Carpenter</tt>
| Opens the carpenter menu, if Robin is nearby.
|-
| <tt>Buildings</tt>
| <tt>Action ColaMachine</tt>
| Offers to let the player buy a Joja cola.
|-
| <tt>Buildings</tt>
| <tt>Action ClubCards</tt><br /><tt>Action Blackjack</tt>
| Shows the casino blackjack minigame.
|-
| <tt>Buildings</tt>
| <tt>Action ClubComputer</tt><br /><tt>Action FarmerFile</tt>
| Shows a dialogue with play stats (steps taken, gifts given, dirt hoed, etc).
|-
| <tt>Buildings</tt>
| <tt>Action ClubSeller</tt>
| Shows a dialogue which lets the player buy a [[Statue of Endless Fortune]] for one million gold.
|-
| <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 Dialogue {{t|text}}</tt>
| Shows a generic dialogue box with the given text. See [[Modding:Dialogue|dialogue format]].<br />''Example: Action Dialogue Hi there @!''
|-
| <tt>Buildings</tt>
| <tt>Action DivorceBook</tt>
| Shows divorce options for the player's current marriage status (as if they clicked the [[Marriage#Divorce|divorce book]]).
|-
| <tt>Buildings</tt>
| <tt>Action Door {{t|npcName}} {{o|npcName}}</tt>
| Sets up an interior door that cannot be opened unless the player has two or more hearts of friendship with any of the named NPC(s). Placed on the lower of the two door tiles. See [[Modding:Dialogue|dialogue format]].<br />''Example: Action Door Abigail''
|-
| <tt>Buildings</tt>
| <tt>Action ElliotBook</tt>
| TODO: Explain what this does.
|-
| <tt>Buildings</tt>
| <tt>Action ElliotPiano</tt>
| TODO: Explain what this does.
|-
| <tt>Buildings</tt>
| <tt>Action EnterSewer</tt>
| Warps you to the sewer if you have obtained the key.
|-
| <tt>Buildings</tt>
| <tt>Action EvilShrineLeft</tt>
| Turns your kids into doves for a prismatic shard.
|-
| <tt>Buildings</tt>
| <tt>Action EvilShrineCenter</tt>
| Erases your ex-spouses memory of you.
|-
| <tt>Buildings</tt>
| <tt>Action EvilShrineRight</tt>
| Toggles monster spawning for your farm.
|-
| <tt>Buildings</tt>
| <tt>Action Garbage {{t|ID}}</tt>
| Has a chance to give a specific item to the player based on the {{t|ID}}. Can only be clicked once per day. TODO: Explain what each {{t|ID}} means.
|-
| <tt>Buildings</tt>
| <tt>Action Gunther</tt>
| Opens the museum menu where you can donate artifacts or claim rewards.
|-
| <tt>Buildings</tt>
| <tt>Action HMGTF</tt>
| Gives you "[[??HMTGF??]]" when you have a [[Super Cucumber]] in your hand.
|-
| <tt>Buildings</tt>
| <tt>Action IceCreamStand</tt>
| If Summer, shows the Ice Cream Stand shopping screen. Otherwise, the player will be told to come back in the summer. (Needs an NPC behind the stand.)
|-
| <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, if you're in the Farmhouse.
|-
| <tt>Buildings</tt>
| <tt>Action Letter {{t|string messageKey}}</tt>
| Loads a message with the given key from the ''Content\Strings\StringsFromMaps.xnb'' file and displays it on-screen as a letter. Uses the same syntax as ''Data\mail.xnb''.
|-
| <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 LuauSoup</tt>
| Used for the Luau Festival, this is where you insert a food item for the soup.
|-
| <tt>Buildings</tt>
| <tt>Action MagicInk</tt>
| Adds the Magic Ink to your wallet.
|-
| <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 Message {{t|string messageKey}}</tt>
| Loads a message with the given key from the ''Content\Strings\StringsFromMaps.xnb'' file and displays it in a dialogue box.
|-
| <tt>Buildings</tt>
| <tt>Action MessageOnce {{t|int eventID}} {{t|string message}}</tt>
| If the player hasn't seen the event with ID {{t|eventID}}, marks that event seen and displays the given message text in a dialogue box. This does ''not'' parse [[Modding:Dialogue|dialogue format]].
|-
| <tt>Buildings</tt>
| <tt>Action MessageSpeech {{t|string messageKey}}</tt>
| Identical to <tt>Action Message</tt>, but replaces the usual inspection cursor with a speech cursor.
|-
| <tt>Buildings</tt>
| <tt>Action MineSign {{t|string message}}</tt>
| Shows a mini-dialogue box with the given raw message text. This does ''not'' parse [[Modding:Dialogue|dialogue format]].
|-
| <tt>Buildings</tt>
| <tt>Action MinecartTransport</tt>
| Shows the minecart destination menu (or a message if not unlocked).
|-
| <tt>Buildings</tt>
| <tt>Action MineElevator</tt>
| Shows the mine elevator menu (to warp to a mine level) if the player has reached mine level 5+, else a mine elevator not working message.
|-
| <tt>Buildings</tt>
| <tt>Action NextMineLevel</tt>
| Warps the player to the next mine level (or level 1 if they're not in the mine).
|-
| <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 NPCMessage {{t|str name}} "{{t|str dialogueKey}}"</tt>
| If the named NPC is within 14 tiles of the player, reads dialogue with the given key from the string files and displays a dialogue box. See [[Modding:Dialogue|dialogue format]].<br />''Example: Action NPCMessage Abigail "Strings\\StringsFromCSFiles:Event.cs.1022"''
|-
| <tt>Buildings</tt>
| <tt>Action playSound {{t|str cueName}}</tt>
| Play the sound or music with the given name.
|-
| <tt>Buildings</tt>
| <tt>Action QiCoins</tt>
| Shows a dialogue which lets the player buy 10 Casino club coins if they have none, else shows how many they have.
|-
| <tt>Buildings</tt>
| <tt>Action Saloon</tt>
| Opens the Saloon menu, if Gus is nearby.
|-
| <tt>Buildings</tt>
| <tt>Action SandDragon</tt>
| Used for Part 3 of the Mysterious Mr. Qi Quest.
|-
| <tt>Buildings</tt>
| <tt>Action Shop</tt>
| On festival maps, opens the festival shop. No effect on non-festival maps.
|-
| <tt>Buildings</tt>
| <tt>Action Theater_BoxOffice</tt>
| Opens the ticket menu for the theater, if you have it unlocked.
|-
| <tt>Buildings</tt>
| <tt>Action TownMailbox {{t|ID}}</tt>
| TODO: Explain what this does.
|-
| <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 76 9 Mountain''
|-
| <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 WarpGreenhouse</tt>
| Warps the player to the inside of their greenhouse if they've unlocked it, else shows a message about the greenhouse ruins.
|-
| <tt>Buildings</tt>
| <tt>Action WizardBook</tt>
| If unlocked, you buy buildings from the wizard here.
|-
| <tt>Buildings</tt>
| <tt>Action WizardHatch</tt>
| If you're good enough friends with the wizard you warp to his basement, if not you get told you can't go in.
|-
| <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>
==Paths layer==
The <tt>Paths</tt> layer has icon tiles from the <tt>paths</tt> tilesheet which affect game behavior on the map:
[[File:PathsExplanation.png|thumb|The tile indexes shown in the table.]]
{| class="wikitable"
|-
! tile index
! explanation
! restrictions
|-
| 0–7
| No effect? TODO: verify how the pathing logic uses it.
|
|-
| 8
| Add this tile to the [[#Map properties 2|<tt>Light</tt> map property]] with light type 4 (sconce).
| Indoors and festivals only.²
|-
| 9–12
| Spawn a [[trees|tree]] when the location is created. Outside the farm, 50% chance to respawn each day. (See also 31–32.)<br />Available trees: oak (9), maple (10), pine (11), and palm 1 (12).
| Outdoors only.
|-
| 13–18
| Spawn debris when the location is created, or randomly each day. Outside the farm, respawn in spring.<br />Available debris: [[weeds|seasonal weed]] (13–15), rock (16–17), twig (18).
| Outdoors only.
|-
| 19
| Spawn a [[Large Log|large log]] when the farm is created, with the top-left corner on this tile.
| Farm only.
|-
| 20
| Spawn a [[boulder]] the farm is created, with the top-left corner on this tile..
| Farm only.
|-
| 21
| Spawn a [[Large Stump|hardwood stump]] when the farm is created (and every day on the forest farm), with the top-left corner on this tile.
| Farm only.
|-
| 22
| Spawn [[grass]] when the location is created, or randomly afterwards.
| Outdoors only.
|-
| 23
| Spawn a random oak, maple, or pine [[trees|tree]] at growth stage 2–3 when the location is created.
| Outdoors only.
|-
| 24–26
| Spawn a normal bush when the location is created. Medium bushes grow [[blackberry|blackberries]] and [[salmonberry|salmonberries]].<br />Available bushes: large (24), medium (25), small (26).
| Outdoors only.
|-
| 27
| When the location is created, add this tile to the [[#Map properties 2|<tt>BrookSounds</tt> map property]] with the <tt>babblingBrook</tt> sound.
| Outdoors only.
|-
| 28
| Spawn a [[grub]] here (33% chance per day, unless the map already has 50 grubs).
| [[Mutant Bug Lair]] only.
|-
| 29–30
| Place prebuilt [[cabin]]s in [[multiplayer]] based on the layout (29=nearby or 30=separate) and [[#Tile properties 2|<tt>Order</tt> tile property]], with the top-left corner on this tile.
| Farm only.
|-
| 31–32
| Spawn a [[trees|tree]] when the location is created. Outside the farm, 50% chance to respawn each day. (See also 9–12.)<br />Available trees: palm 2 (31), mahogany (32).
| Outdoors only.
|-
| 33
| Spawn a [[Golden Walnut|golden walnut]] bush when the location is created.
| Outdoors only.
|}
Notes:
# In the [[Mutant Bug Lair]], debris spawn rate is reduced to 33% chance per day.
# Restriction can be overridden with <tt>forceLoadPathLayerLights</tt> map property.
==Potential issues==
===Tilesheet order===
When you replace a vanilla map, '''don't''' change the order or IDs of the original tilesheets. Prefix new tilesheet IDs with <code>z_</code> to avoid changing the original order.
; Why this causes problems
: For example, let's say you replace a map which normally has these tilesheets in Tiled:
: [[File:Tiled tileset order A.png|thumb|none|The original tilesheet order.]]
: When you add a new tilesheet, note that the order changes from ''[paths, untitled tile sheet]'' to ''[customSheet, paths, untitled tile sheet]'':
: [[File:Tiled tileset order B.png|thumb|none|'''Wrong''' way to add a new tilesheet (changes the original order).]]
: If the game tries to access a tile from the first tilesheet, it will get it from <tt>customSheet</tt> instead of the expected <tt>Paths</tt> tilesheet. That can cause anything from visual glitches (e.g. showing the wrong tile images) to outright crashes (especially if the new tilesheet is smaller than the one it expected).
: To avoid that, always keep the original tilesheets in the same order and prefix new tilesheets with <code>z_</code> so they're added at the end:
: [[File:Tiled tileset order C.png|thumb|none|Correct way to add a new tilesheet.]]
; How to fix an affected tilesheet
: See ''[[#"mod reordered the original tilesheets"|"mod reordered the original tilesheets"]]'' below.
===Local copy of a vanilla tilesheet===
When editing a map in Tiled, you may need to copy vanilla tilesheets like <tt>path.png</tt> or <tt>spring_town.png</tt> into the map folder for Tiled to find. If the tilesheet is still there when you load the game, SMAPI will use it for your map instead of the game's vanilla tilesheet, which may have unintended effects (e.g. edits from recolor mods won't work in your map).
To avoid issues, you can either...
* Delete vanilla tilesheets from the folder before testing or releasing the mod.
* Rename the tilesheet file to start with a dot (like <tt>.spring_town.png</tt>) and reference that. When SMAPI loads the map in-game, it'll automatically ignore the dot and look for <tt>spring_town.png</tt> in the local files or <tt>Content/Maps</tt> folder.
===Map-specific issues===
The game makes some assumptions about maps which may break for modded maps. These are the known issues:
{| class="wikitable"
|-
! affected maps
! issue
|-
| <tt>Maps/Farm</tt><br /><tt>Maps/Farm_Combat</tt><br /><tt>Maps/Farm_Fishing</tt><br /><tt>Maps/Farm_Foraging</tt><br /><tt>Maps/Farm_Mining</tt>
|  
* The farm's <tt>Paths</tt> layer must have at least one tile with index 22 (grass spawn). This is used to initialise the grass code when the save is loaded, even if no grass is spawned.<ref>The grass sound is set in <tt>Grass::loadSprite</tt>, which is called from <tt>GameLocation::loadObjects</tt> if the <tt>Paths</tt> layer has tile index 22. (The game spawns a grass for each such tile, and later removes them.)</ref>
|-
| <tt>Maps/FarmHouse*</tt>
|  
* The two bed tiles where the player can walk must have two properties: <tt>Bed T</tt> (used to decide if the player is in bed) and <tt>TouchAction Sleep</tt>.
* Deleting or changing the wallpapers and floors will cause a game crash.
* The <tt>DayTiles</tt> and <tt>NightTiles</tt> map properties are cleared when loading the spouse room, so custom values for those properties won't work for married players.
|-
| <tt>Maps/SpouseRooms</tt>
|  
* If you add or resize any tilesheet, you must also edit <tt>Maps/FarmHouse1_marriage</tt> and <tt>Maps/FarmHouse2_marriage</tt> to have the same changes (even if you don't make any other changes to the farmhouse). This is needed because the tilesheet references and sizes are stored as part of the map file.
|}
<small><references /></small>
==='Save as' in Tiled===
When you use 'save as' in Tiled, never save into a different folder. That will change all the tilesheet references to point to the old folder, so it'll no longer work in-game. Instead, copy/move the map files to a different folder if needed.
===Locating tilesheets in Tiled===
When a map tilesheet is missing, never use the locate option to use a tilesheet from a different folder. That will add a complex tilesheet path which won't work in-game. Instead copy the tilesheets into the same folder as the map, and reference them from there.
==Troubleshooting==
See also [[#Potential issues|''potential issues'']] above for common issues.
==="Tilesheet paths must be a relative path without directory climbing (../)"===
; What does this mean?
: Your map uses a tilesheet that's outside its folder root. That might happen if you [[#'Save as' in Tiled|used 'save as' in Tiled to save into a different folder]], copied & pasted tiles between maps in different folders, or manually added a tilesheet from a different folder.
: For example:
<pre style="margin-left: 2em;">
📁 Stardew Valley/
📁 Content/
📁 Maps/
🗎 townInterior <──┐
📁 Mods/ │
📁 YourModName/ │ ../../../Content/Maps/townInterior
📁 assets/ │
🗎 your-map.tmx ───┘
</pre>
: This isn't allowed since it's very fragile (e.g. players might install your mod in a different folder path).
; How do I fix it?
:# Copy the tilesheets you're using into the same folder as the map.
:# For unchanged vanilla tilesheets, rename them to start with a dot (like <tt>.townInterior.png</tt>). This tells SMAPI to ignore the file when loading the map in-game, and load the one in the <tt>Content</tt> folder instead.
:# In Tiled, click the edit icon under the tilesheet.
:# In the tab that opens, click ''Tileset > Tileset Properties''.
:# Click the 'Image' field, then the 'Edit' button to locate the tilesheet in the same folder.
For a screenshot guide of steps 3-5, [https://imgur.com/a/rukygAr see these images] provided by Discord user foggywizard#7430.
: After fixing it, the above example would look like this:
<pre style="margin-left: 2em;">
📁 Stardew Valley/
📁 Mods/
📁 YourModName/
📁 assets/
🗎 your-map.tmx ───┐
🗎 .townInterior.png <──┘ .townInterior.png
</pre>
==="mod reordered the original tilesheets"===
; What does this mean?
: See [[#Tilesheet order|''tilesheet order'']] for more info.
; How do I fix it?
: Always keep the original tilesheets in the same order and prefix new tilesheets with <code>z_</code> so they're added at the end:
: [[File:Tiled tileset order C.png|thumb|none|Correct way to add a new tilesheet.]]
: To rename an affected tilesheet in Tiled:
<gallery style="margin-left: 2em;">
File:Tiled rename tileset A.png|In the tileset pane, click the tab for the tileset and then click the edit icon.
File:Tiled rename tileset B.png|Click ''Tileset > Tileset Properties'' from the top menu to show the properties pane.
File:Tiled rename tileset C.png|Change the name in the ''Name'' field.
</gallery>
==="mod has no tilesheet with ID '<name>'"===
; What does this mean?
: You replaced one of the vanilla maps, but your custom map doesn't have all of the original map's tilesheets (or you changed their names in Tiled). This will cause a crash if the game tries to access the missing tilesheet.
; How do I fix it?
: Compare the original and custom maps in Tiled. For each tilesheet in the original map, make sure it's also in the custom map '''and''' has the same name (even if you're not using it).
: If you need to rename a tilesheet:
:# In the tileset pane, click the tab for the tileset and then click the edit icon.
:# Click ''Tileset > Tileset Properties'' from the top menu to show the properties pane.
:# Change the ''Name'' field to match the original map's tilesheet name.
==Making changes with SMAPI==
This page mainly covers editing maps with Tiled, but you can make the same changes programmatically using a [[Modding:Modder Guide/Get Started|C# SMAPI mod]]. There are two main approaches to changing a location in C# code.
===Using an asset editor===
Most map edits should be applied using an [[Modding:Modder Guide/APIs/Content|asset editor]], so your changes aren't lost if another mod reloads the map. This works with the <tt>Map</tt> asset directly before it's used by the [[Modding:Modder Guide/Game Fundamentals#GameLocation et al|in-game location]], so you can't use location methods at this point.
First you'll need to set up an asset editor, which mainly involves implementing <tt>IAssetEditor</tt> on your mod class. For example, this mod code edits the town map:
<syntaxhighlight lang="C#">
/// <summary>The mod entry point.</summary>
internal class ModEntry : Mod, IAssetEditor
{
/// <inheritdoc />
public override void Entry(IModHelper helper) { }
/// <inheritdoc />
public bool CanEdit<T>(IAssetInfo asset)
{
return asset.AssetNameEquals("Maps/Town");
}
/// <inheritdoc />
public void Edit<T>(IAssetData asset)
{
IAssetDataForMap editor = asset.AsMap();
Map map = editor.Data;
// your code here
}
/// <summary>Get a tile from the map.</summary>
/// <param name="map">The map instance.</param>
/// <param name="layerName">The name of the layer from which to get a tile.</param>
/// <param name="tileX">The X position measured in tiles.</param>
/// <param name="tileY">The Y position measured in tiles.</param>
/// <returns>Returns the tile if found, else <c>null</c>.</returns>
private Tile GetTile(Map map, string layerName, int tileX, int tileY)
{
Layer layer = map.GetLayer(layerName);
Location pixelPosition = new Location(tileX * Game1.tileSize, tileY * Game1.tileSize);
return layer.PickTile(pixelPosition, Game1.viewport.Size);
}
}
</syntaxhighlight>
Now you can make any changes you want to the map before it's loaded by location. For example, you can...
<ul>
<li>Add a custom tilesheet:
<syntaxhighlight lang="C#">
map.AddTileSheet(new TileSheet(
id: "z_custom-tilesheet", // always prefix custom tilesheets with z_ to avoid reordering vanilla tilesheets
map: map,
imageSource: this.Helper.Content.GetActualAssetKey("assets/tilesheet.png", ContentSource.ModFolder), // get a unique asset name for local mod file which can be passed to the game
sheetSize: new Size(32, 64), // the size in tiles for the tilesheet image
tileSize: new Size(16) // the size of each tile in pixels, should always be 16
));
</syntaxhighlight></li>
<li>Manage map properties:
<syntaxhighlight lang="C#">
// get a property value
string currentMusic = map.Properties.TryGetValue("Music", out PropertyValue rawMusic)
? rawMusic.ToString()
: null;
// add/replace a property
map.Properties["Music"] = "MarlonsTheme";
// delete a property
map.Properties.Remove("Music");
</syntaxhighlight></li>
<li>Manage tile properties:
<syntaxhighlight lang="C#">
// get tile
Tile tile = this.GetTile(map, layerName: "Back", tileX: 10, tileY: 20);
if (tile == null)
return; // you should handle the tile not being there to avoid errors
// get a property value
string diggable = tile.TileIndexProperties.TryGetValue("Diggable", out PropertyValue rawDiggable) || tile.Properties.TryGetValue("Diggable", out rawDiggable)
? rawDiggable?.ToString()
: null;
// set a property
tile.Properties["Diggable"] = "T";
// delete a property
tile.Properties.Remove("Diggable");
</syntaxhighlight></li>
<li>Add new tiles:
<syntaxhighlight lang="C#">
int tileX = 10;
int tileY = 20;
Layer layer = map.GetLayer("Back");
// add a static tile
layer.Tiles[tileX, tileY] = new StaticTile(
layer: layer,
tileSheet: map.GetTileSheet("z_custom-tilesheet"),
tileIndex: 100, // the sprite index in the tilesheet
blendMode: BlendMode.Alpha // should usually be Alpha
);
// add an animated tile
layer.Tiles[tileX, tileY] = new AnimatedTile(
layer: layer,
tileFrames: new StaticTile[]
{
new StaticTile(...),
new StaticTile(...),
new StaticTile(...),
},
frameInterval: 100 // frame duration in milliseconds
);
</syntaxhighlight></li>
<li>Delete tiles:
<syntaxhighlight lang="C#">
layer.Tiles[tileX, tileY] = null;
</syntaxhighlight></li>
<li>Apply tile transformations:
<syntaxhighlight lang="C#">
Tile tile = this.GetTile(map, layerName: "Back", tileX, tileY);
tile.Properties["@Rotation"] = 45; // rotate it 45° clockwise
tile.Properties["@Flip"] = 1; // flip the tile: 0 (normal), 1 (horizontal), 2 (vertical)
</syntaxhighlight></li>
</ul>
See also [[Modding:Modder Guide/APIs/Content#Edit a map|SMAPI's map edit helper]], which lets you do things like merge a custom map area into the map.
===After location is loaded===
After the [[Modding:Modder Guide/Game Fundamentals#GameLocation et al|in-game location]] is loaded, you can edit locations and their maps using the game's helpers. Be careful doing this though: another mod (or sometimes the game itself) may reload the location at any time, which would lose your changes if you're not careful.
For example, within any [[Modding:Modder Guide/APIs/Events|in-game events]] you can...
<ul>
<li>Access the map to use the methods described above:
<syntaxhighlight lang="C#">
Map map = location.map;
</syntaxhighlight></li>
<li>Manage tile properties:
<syntaxhighlight lang="C#">
Town town = (Town)Game1.getLocationFromName("Town");
int tileX = 10;
int tileY = 20;
// get property value
string diggable = town.doesTileHaveProperty(tileX, tileY, "Diggable", "Back");
// set property value
location.setTileProperty(tileX, tileY, "Back", "Diggable", "T");
</syntaxhighlight></li>
<li>Manage tiles:
<syntaxhighlight lang="C#">
location.removeTile(tileX, tileY, "Back");
</syntaxhighlight></li>
</ul>
==See also==
* Discord user foggywizard#7430 [https://imgur.com/a/l1Ql16D annotated some screenshot guides for using Tiled]. These include an annotated overview, how to find where the coordinates are, and how to rename a tilesheet.
[[Category:Modding]]
[[ru:Модификации:Карты]]