translators
8,403
edits
Changes
Jump to navigation
Jump to search
Line 85:
Line 85: − + − Note that this doesn't preclude using Tiled too. You can create/edit maps in Tiled, then load/edit them in SMAPI.+ Line 120:
Line 120: − If you're using Tiled: Line 139:
Line 138: − If you're using SMAPI:+ − :<syntaxhighlight lang="c#">+ − public override void Entry(IModHelper helper)+ − {+ − helper.Events.GameLoop.SaveLoaded += this.OnSaveLoaded;+ − }+ − + − private void OnSaveLoaded(object sender, SaveLoadedEventArgs args)+ − {+ − // This gets the asset key for a tilesheet.png file from your mod's folder. You can also load a game tilesheet like+ − // this: helper.Content.GetActualAssetKey("spring_town", ContentSource.GameContent).+ − string tilesheetPath = this.Helper.Content.GetActualAssetKey("tilesheet.png", ContentSource.ModFolder);+ − + − // Get an instance of the in-game location you want to patch. For the farm, use Game1.getFarm() instead. − GameLocation location = Game1.getLocationFromName("Town"); − − // Add the tilesheet. − TileSheet tilesheet = new TileSheet( − id: "z_your-custom-spritesheet", // a unique ID for the tilesheet − map: location.map, − imageSource: tilesheetPath, − sheetSize: new xTile.Dimensions.Size(32, 64), // the tile size of your tilesheet image. − tileSize: new xTile.Dimensions.Size(16, 16) // should always be 16x16 for maps − ); − location.map.AddTileSheet(tilesheet); − location.map.LoadTileSheets(Game1.mapDisplayDevice); − } − </syntaxhighlight> − : To change tiles using the new tilesheet, see [[#Tiles]] below. − − If you're using Tiled: − :# 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''. − :# Add custom sprites to the map: − :## In the ''Layers'' pane, click the layer you want to edit. − :## In the ''Tilesets'' pane, click the tab for your custom spritesheet. − :## In the ''Tilesets'' pane, click one tile to select it. To choose multiple, click and drag the cursor. − :## Move the cursor to the map, and you'll see an overlay with the tiles you selected. − :## Click the map to place those tiles on the selected layer. − If you're using SMAPI:+ − : <syntaxhighlight lang="c#">+ − public override void Entry(IModHelper helper)+ − { − helper.Events.GameLoop.SaveLoaded += this.OnSaveLoaded; − } − − private void OnSaveLoaded(object sender, SaveLoadedEventArgs args) − { − // get the 'Music' value − string currentMusic = Game1.currentLocation.map.Properties.TryGetValue("Music", out PropertyValue rawMusic) − ? rawMusic.ToString() − : null; − − // add or set the 'Music' value − Game1.currentLocation.map.Properties["Music"] = "MarlonsTheme"; − − // remove the 'Music' value − Game1.currentLocation.map.Properties.Remove("Music"); − } − </syntaxhighlight> − − If you're using Tiled: − :# Click ''Map'' on the toolbar and choose ''Map Properties''. − :# View and edit properties using the GUI. − + − If you're using SMAPI:+ − + − public override void Entry(IModHelper helper)+ − {+ − helper.Events.GameLoop.SaveLoaded += this.OnSaveLoaded;+ − } − private void OnSaveLoaded(object sender, SaveLoadedEventArgs args)+ − {+ − // example location & tile coordinate+ − GameLocation location = Game1.currentLocation;+ − int tileX = 10; − int tileY = 20; − // get property+ − string value = location.doesTileHaveProperty(tileX, tileY, "Diggable", "Back");+ − + − // add or set property+ − location.setTileProperty(tileX, tileY, "Back", "Diggable", "T");+ − + − // remove tile property − Layer layer = location.map.GetLayer("Back"); − Tile tile = layer.PickTile(new xTile.Dimensions.Location(tileX, tileY) * Game1.tileSize, Game1.viewport.Size); − tile.Properties.Remove("Diggable"); − //tile.TileIndexProperties.Remove("Diggable"); // NOTE: removing a tile index property will affect all tiles of this type − } − </syntaxhighlight> − − If you're using Tiled: − : In Tiled these are represented by two types: ''object properties'' only apply to the selected tile, while ''tile properties'' apply to every instance of that tile. In general you'll always set ''object properties'', so we'll only cover those. − :# Select the object layer in the ''Layers'' pane. − :# Choose the [[File:Modding - creating an XNB mod - Tiled 'select object' button.png]] ''select object'' tool in the toolbar. − :# Click the object whose properties you want to view. Objects are represented with a gray selection box on the map:<br />[[File:Modding - creating an XNB mod - map object.png]] − :# The object properties will be shown in the ''Properties'' pane.<br />[[File:Modding - creating an XNB mod - Tiled tile properties pane.png]] − − : To edit properties for an existing object: − :* Change a value: click the value field and enter the new value. − :* Change a name: select the property and click the [[File:Modding - creating an XNB mod - Tiled 'edit' button.png]] icon. − :* Add a property: click the [[File:Modding - creating an XNB mod - Tiled 'add' button.png]] icon, enter the property name, make sure the selected type is "string", and click OK. − − : To add a new object: − :# Select the object layer in the ''Layers'' pane.<br />''There should be one object layer for each tile layer. If the object layer is missing, create one with the same name as the right tile layer.'' − :# Choose the [[File:Modding - creating an XNB mod - Tiled 'insert rectangle' button.png]] ''insert rectangle'' tool from the toolbar. − :# Click and drag the rectangle over the tile you want to edit . Make sure it snaps to the tile grid (see [[#Using Tiled]]), and only one tile is selected. − :# Rename it TileData in <tt>Name</tt> − :## See previous for how to edit its properties. − + − − If you're using SMAPI: − :<syntaxhighlight lang="c#"> − public override void Entry(IModHelper helper) − { − helper.Events.GameLoop.SaveLoaded += this.OnSaveLoaded; − } − − private void OnSaveLoaded(object sender, SaveLoadedEventArgs args) − { − // example location & tile coordinate − GameLocation location = Game1.currentLocation; − int tileX = 10; − int tileY = 20; − − // remove tile from layer − location.removeTile(tileX, tileY, "Back"); − − // add tile − Layer layer = location.map.GetLayer("Back"); − TileSheet tilesheet = location.map.GetTileSheet("tilesheet name"); − layer.Tiles[tileX, tileY] = new StaticTile(layer, tilesheet, BlendMode.Alpha, tileIndex: 100); // change tile index − − // toggle water tile behaviour − location.waterTiles[tileX, tileY] = false; // true: water, false: not water − } − </syntaxhighlight> − − If you're using Tiled: − : See [http://doc.mapeditor.org Tiled documentation]. Line 300:
Line 187: − If you're using SMAPI:+ − :<syntaxhighlight lang="c#"> − public override void Entry(IModHelper helper) − { − helper.Events.GameLoop.SaveLoaded += this.OnSaveLoaded; − } − − private void OnSaveLoaded(object sender, SaveLoadedEventArgs args) − { − GameLocation location = Game1.currentLocation; − − // add animated tile − Layer layer = location.map.GetLayer("Buildings"); − TileSheet tilesheet = location.map.GetTilesheet("tilesheet name"); − layer.Tiles[tileX, tileY] = new AnimatedTile( − layer, − new StaticTile[] { − new StaticTile(layer, tilesheet, BlendMode.Alpha, tileID), − new StaticTile(layer, tilesheet, BlendMode.Alpha, tileID), − new StaticTile(layer, tilesheet, BlendMode.Alpha, tileID), − new StaticTile(layer, tilesheet, BlendMode.Alpha, tileID) − }, − 250 // interval in milliseconds − ); − } − </syntaxhighlight> − − If you're using Tiled: Line 341:
Line 201: − If you're using SMAPI:+ − :<syntaxhighlight lang="c#"> − public override void Entry(IModHelper helper) − { − helper.Events.GameLoop.SaveLoaded += this.OnSaveLoaded; − } − − private void OnSaveLoaded(object sender, SaveLoadedEventArgs args) − { − // get a tile − GameLocation location = Game1.currentLocation; − Layer layer = location.map.GetLayer("Buildings"); − Tile tile = layer.Tiles[tileX, tileY]; − − // rotate it 45° − tile.Properties["@Rotation"] = 45; − − // flip it (0 = normal, 1 = horizontal, 2 = vertical) − tile.Properties["@Flip"] = 1; − } − </syntaxhighlight> − − If you're using Tiled: − : '''Note: this only works when editing a <tt>.tmx</tt> file. Tile transforms aren't supported by the <tt>.tbin</tt> plugin. − + + Line 1,104:
Line 942: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + − ===See also===+
move SMAPI info into separate section and expand, rewrite rest of page to focus on Tiled
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:
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]].
# [[Modding:Modder Guide/Get Started|Create a SMAPI mod]].
# See instructions below for map changes.
# 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===
===Using Tiled===
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.
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.
# [[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.
# 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.
You can add custom sprites, tiles, or images to a map. Be sure to [[#Tilesheet order|prefix custom tilesheet IDs with <code>z_</code>]] to avoid shifting the vanilla tilesheet indexes.
You can add custom sprites, tiles, or images to a map. Be sure to [[#Tilesheet order|prefix custom tilesheet IDs with <code>z_</code>]] to avoid shifting the vanilla tilesheet indexes.
# 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''.
# Add custom sprites to the map:
## In the ''Layers'' pane, click the layer you want to edit.
## In the ''Tilesets'' pane, click the tab for your custom spritesheet.
## In the ''Tilesets'' pane, click one tile to select it. To choose multiple, click and drag the cursor.
## Move the cursor to the map, and you'll see an overlay with the tiles you selected.
## Click the map to place those tiles on the selected layer.
===Map properties===
===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.
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===
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.
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:
: <syntaxhighlight lang="C#">
# 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===
===Tiles===
You can edit the tiles for an existing map.
You can edit the tiles for an existing map. See the [http://doc.mapeditor.org Tiled documentation] for more info.
===Tile animation===
===Tile animation===
You can animate tiles to create effects like Gil in his rocking chair (see example at 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.
:# Click the edit button (wrench icon) for the tilesheet in the ''Tilesets'' pane.
:# Select the tile you want to animate in the new view.
:# Select the tile you want to animate in the new view.
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.
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.
:# 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 flip or rotate buttons (see image at right).
:# Click the map to place the flipped/rotated tile.
:# 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==
==Known properties==
:# Change the ''Name'' field to match the original map's tilesheet name.
:# 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.
* 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.