Custom Assets Guide - Megasploot/Dungeondraft GitHub Wiki
1. Preparing an asset pack folder
Extract the example template zip file to a location of your choice. You can locate the .zip either from the Package Custom Assets window button called 'Example Template' or in the install folder of Dungeondraft. Once extracted, you can rename that folder to anything you prefer.
Inside the folder are files and sub-folders that Dungeondraft need to import every kind of asset. The example tries to provide one sample of each type of asset. Use these as references on how to author your own asset. For your own pack, you need an identical structure. You can opt to copy the structure found here or create your own.
You can skip to Packaging the pack to test the example as is. Otherwise, proceed to add a few test assets yourself for the pack.
2. Authoring custom assets
There are two primary types of files to author. The PNG are your raw art files that will be used to display drawings inside the /textures folder. The rest are JSON text files located inside the /data folder. The purpose of each JSON text file is designated by its file extension (e.g. dungeondraft_wall informs Dungeondraft where the wall file and what the default color are).
It is important to keep the PNG files in their respective folders, as Dungeondraft depends on these folders to determine what they will be used for. Subfolders inside these folders are allowed, but really only necessary for the /objects folder to help organize a large library of objects.
The PNGs are authored at 256 ppi resolution natively. That means that Dungeondraft treats 256 pixels you draw as one grid unit across.
Objects
Objects are just PNG files. Once placed into /textures/objects/ or its subfolders, they will start showing up in Dungeondraft's library at the end of the list.
To help organize it, you can add Tags and Tagsets. Open /data/default.dungeondraft_tags in a text editor like Notepad++. You will see a JSON-like format for a section called Tags and a section called Sets. A Tag forms a collection of objects, and a Set is a collection of Tags. Imagine Tags as descriptors of objects, and Sets as groups of Tags. These Tags can be same as existing ones in default Dungeondraft tags. These tags and sets will be merged with the default ones. You will need to revert to the Default tags under the Tags Browser if you have overwritten the default tags.
To make, custom colorable objects, draw the colorable area in a generally reddish tone. Then inside the tags file, add the reference to the object under "Colorable" tag.
Terrain
Terrain are seamless PNG files. Ideally they are 2048 x 2048 in size, but the most important feature is that they tile seamlessly. The terrain system has a hidden mechanic that reads the alpha channel of the PNG as a way to blend together different terrain based on depth. If you simply want normal blending, leave the alpha channel alone. Otherwise, read the next section. Place them in /textures/terrain/.
Terrain blend with each other based on the depth described in the alpha channel. The brighter the alpha, the taller in elevation that section of the terrain. In real-world analogy, if you draw snow on top of cracked earth, it should fill in the cracks first, because cracks are lower. Likewise, the cracked earth terrain in Dungeondraft has darker alpha for the cracks than the rest of the image. Therefore, when a user draws another terrain over the cracked earth texture, it will fill the cracks before filling the rest of the terrain.
Materials
Materials are seamless PNG files. They require an additional border PNG, which is used to encircle each material. You should name the material and its borders materialname_tile.png and materialname_border.png respectively. Place them in /textures/materials/. Ideally, the border textures have at least a 1 pixel transparent gap at the top and bottom of the texture. The top of the border is the outer edge, while the bottom of the border will overlap the material.
Tilesets
A Tileset is a black-and-white PNG texture that contains square tiles that can be placed as floor shapes. They come in 3 flavors:
- Simple
- Smart
- Smart Double
The location of the texture file determines which type of Tileset it is.
Simple
Simple tilesets randomly picks tiles. These are 1024 x 1024 textures that contain 4 x 4 tiles (16 total). They are randomly placed on the grid.
Smart
Smart tilesets pick random tiles unless the user creates a corridor. These are 1024 x 2048 textures that contain 4 x 8 tiles (32 total). The top half functions identically to the simple tileset. The bottom half of the texture are single-wide corridors that are used when a user draws narrow corridors. These must be laid out in the exact same pattern as the example. Dungeondraft will properly place t-junctions, dead ends, and corners based on the layout.
Smart Double
Smart double tilesets are exactly the same as the Smart tileset except that the texture size is 2048 x 2048 containing 8 x 8 tiles (64 total). It's a smart tileset where the author can provide more variety if they desire.
Tilesets can be custom colored. In that case, the artist would create a colored PNG instead of black-and-white. The reddish colors are what Dungeondraft uses as the cue to replace.
To complete a tileset, you need to add the meta file for the tileset. These are located in the /data/tilesets/ folder with the extension .dungeondraft_tileset. There are 3 examples corresponding to each of the 3 flavors of tilesets for you to copy. Follow the same format, but replace the fields with your own.
Path is the location of the tileset image file.
Name is the displayed name.
Type is either 'normal' or 'custom_color' based on the image type.
Color is the default color for the tileset.
Patterns
Patterns use seamlessly tiling textures that usually represent flooring of some kind. There are 2 types of patterns, normal and colorable. Patterns most closely resemble how flooring works in other types of dungeon mapping tools, and can be used when your flooring cannot be cut into square tiles. Place the normal patterns in /textures/patterns/normal/ folder and it is good to go. The colorable patterns need to have fully red areas to recolor and be placed in /textures/patterns/colorable/.
Walls
Walls are black-and-white long textures that tile seamelessly left-to-right. They can be placed with the Wall tool but also can automatically wrap any Floor Shapes. Line-of-sight blockers will be automatically generated in the middle of your texture when a user creates a wall, so it is important to align where the wall should cut off lighting.
Walls also require an end texture that is placed at the end of a wall. You need to give it the same name as your wall but with '_end.png' in the end (eg sample_wall.png and sample_wall_end.png). The height of the texture should be the same height you chose for your wall.
Every wall needs an accompanying meta file inside the /data/walls/ folder. Copy the sample_wall.dungeondraft_wall file and change sample_wall to the name of your wall. Then edit with a text editor, the path and color to correspond to your texture file and default color respectively.
Paths
Paths are long PNGs. Make sure the image loops/tiles left to right. It is ideal to have at least a 1 pixel transparent gap at the top and bottom of the image to prevent float-point artifacts. Place them in /textures/paths/.
Portals
Portals are doors, windows, or anything else that can connect two areas together. They must be exactly 256 pixels wide PNGs. Center the portal image. You do not need additional data for portals to work. Place them in /textures/portals/.
Lights
Lights are grayscale PNG textures of square size. The white portion of the image will let light through. Place any light textures in /textures/lights/. No additional editing needed.
3. Packaging the pack
Before you package your assets, you may want to create a preview image of the pack. It will be displayed in the Asset selection window. This is a 256 x 320 pixel PNG file located in base folder. It must be named preview.png.
You will want to delete any of the sample assets and data if you have not yet done so.
To bundle your custom assets, go to the dropdown menu inside Dungeondraft and select Package Custom Assets. It will pop open a new window (which may have led you to this guide). Click Browse for the Base Folder field and navigate to your pack folder. You will want to highlight the folder from the outside of the folder rather than inside, then click Select Folder.
Fill in the appropriate fields like the Name, Author, and Version. These fields are displayed to future users. Click Package to create the .dungeondraft_pack file. If you have already set a custom assets directory, it will place the pack there. Otherwise, it will default to the current user's My Documents folder.
4. Testing your assets
Once you've created your pack, you can immediately test it by creating a new map and clicking on 💎Edit Asset Pack Selection. Your new pack should appear in the list. Check the checkbox for your pack, hit Accept, and create the new map. Now you can test your pack and address any issues.
In order to refresh the contents of a pack, you will need to quit Dungeondraft and delete the .dungeondraft_pack file. Dungeondraft reads any packs into the memory, so you won't be able to modify existing packs without closing it first.
Please make sure to test all elements from your pack, test their functionality, and test saving them to a map.
5. Distributing the pack
Upload the .dungeondraft_pack to the website or server of your choice and share the link. That's it. I suggest www.cartographyassets.com.
If a user uses the pack to create a map, others who try to open the map will be warned that they have to download this pack in order to open the map safely.
Updating the pack
If you update your pack, you need to be cognizant of backwards compatibility. If your new pack only adds new assets or change their appearances, you can just delete your old pack and repackage it. Dungeondraft will treat the new version as the same pack as the previous one. Changing the version number does not affect compatibility.
However, if you know that your new pack removes old assets, change their names, or in anyway corrupts maps that were created from the previous version, you need to make sure Dungeondraft treats this as a different pack. You do this by going into the pack base folder and deleting the pack.json file before packaging it again.