Arbitrary Tilesheet Access
First off, if you are a mod user and not a mod author, you've made a wrong turn. This page isn't for you. Begone, user!
Arbitrary Tilesheet Access allows you to use any texture or image as a tilesheet when making a map. Normally, you are
restricted to only using images that are available in the games Maps folder e.g. Maps/townInterior.png.
With Arbitrary Tilesheet Access, you will now be able to use images from other folders, such as TileSheets/furniture.png
or even modded textures like Mods/UniqueID/whatever.png. The benefit of this is that you do not need to
make copies of these textures and include them with your mod, meaning you maintain compatibility with recolours or
other edits to these textures automatically. Also, if you're using a texture from another mod, you will not need to
redistribute their assets with your map.
In order to allow other tilesheets not present in the Maps folder to be loaded, Arbitrary Tilesheet
Access will bypass SMAPI's restrictions by looking for a specific tilesheet naming convention. It will check that the
file path of your tilesheet's source image starts with the word Content. Then it will ask SMAPI to load the rest of
the file path as an asset name, and if it exists in the content pipeline, it will load. If your tilesheet's image
source does not match this format, SMAPI will load the tilesheet as it normally does, including with the restriction
to the Maps folder. For example, take this snippet from the vanilla game's Town.tmx file:
15 | |
16 | |
17 | |
18 | |
19 | |
The image source of this tilesheet on line 16 is spring_outdoorsTileSheet and it does not look like a file path. It just looks like a single word. Therefore, the game will load Maps/spring_outdoorsTileSheet.png to use as a tilesheet. This is normally what you have to do for your custom maps, too, in order to ensure SMAPI doesn't reject your tilesheet. Now let's take a look at a snippet from a modified BusStop.tmx I made to make use of Arbitrary Tilesheet Access:
924 | |
925 | |
926 | |
927 | |
928 | |
929 | |
As you can see, the image sources for those tilesheets are file paths. They both begin with the word Content, signaling to Arbitrary Tilesheet Access that it should handle the file loading. For the first tilesheet on line 925, the file path after the word "Content" is TileSheets/furniture, which means that the map will load that asset from the vanilla game to use. Any edits that other mods have made to that same asset will then show up in your map.
The second tilesheet shown on line 928 uses an asset from one of my other mods, Button's Extra Books, as an example. In that mod, I used Content Patcher to Load the textures for my item sprites into the asset name Mods/{{ModId}}/Books, hence that is what I need to use for the tilesheet image source (after replacing the {{ModId}} token with the actual unique ID, of course). You can see the result of using these tilesheets in this BusStop edit below:
Note that in the BusStop.tmx code shown above, the first tilesheet does not include a .png file extension while the second one does. Like normal tilesheets, it does not actually matter, and the game will search for the correct asset whether or not the .png is included.
The easiest way to ensure that the image source of your tilesheet image source is correctly formatted is to recreate the required folder structure in your mod folder. Usually, when editing a map, you want the tilesheet to be in the same folder as the map file. When using Arbitrary Tilesheet Access, you can instead create a folder named Content in the same folder as your .tmx file, and then inside that Content folder, create another folder (e.g. TileSheets), and so on until you have the correct folder to place the tilesheet in so that the resulting file path matches the asset name you want to load. An example of this is shown below:
If you use a folder structure like this when adding a new tilesheet in Tiled, the image source will automatically match the required format for Arbitrary Tilesheet Access. You can, of course, simply edit the .tmx file directly in Notepad++ or similar to make sure the image source is correct, if you are so inclined. It is important that you still delete these tilesheets from your mod folder before publishing. This is especially important if you are using an image from another mod, as failing to delete the images from your mod folder would mean you are distributing another mods assets, likely without permission.
It is also important to remember that if you are using an image from another mod, you must set that other mod as a required dependency. Your map will fail to load and cause errors if you use an image from another mod and that mod is not present.
If you encounter any issues with using this mod, please feel free to ping me @spiderbuttons in the Stardew Valley Discord in the #making-mods-general channel. Please do not DM me! Just ping me in the channel.