- Custom Character Tutorial -

Thanks to the custom character system added in version 1.1.0, creating characters for Desktoptale became much easier, no programming required! This wall of text might seem a little intimidating at first, but you'll get there if you follow the steps carefully.
All you need is an image editing application (Paint.NET or the new MS Paint with transparency support is enough) as well as a text editor.

Many new customization options were added in 1.6.0, but using them is strictly optional - see step 5 for details. While the character definition file template is still minimal on purpose, the Clover example below has been updated to make use of all the new features.

If you want to use an existing custom character that you obtained elsewhere, you don't need to do any of this! Just place the character folder into the Custom folder, located inside the Content folder next to Desktoptale.exe - there is a file named "PUT YOUR CUSTOM CHARACTERS HERE" in the right spot to help you find it.

If you prefer to learn from an example, you can download a recreation of Clover using the custom character system here.

Step 1: Preparing your sprites

First, you'll need to download (or draw) a spritesheet of a character to add. At the very least, your spritesheet should contain idle and walking animations for each of the 4 directions (up, down, left and right). If you only have one side sprite instead of seperate left/right ones, don't worry! We'll deal with this in the next step. Note that some games (such as the original Undertale) often don't have dedicated idle sprites as they just use the first frame from the walk cycle - that's fine too! Just continue for now.

Step 2: Editing your sprites

Next, you'll need to cut up the spritesheet into individual files for each state (idle, walking, running) and direction (up, down, left and right). Skip any states and directions you don't have sprites for.

For animations with only one frame (e.g. idle stance), just paste each direction into its own file. Though recommended, they don't need to be the exact same pixel size as Desktoptale will always try to correct for differences.

For animations with multiple frames (e.g. walk cycles), you first need to find a size in pixels that is large enough to fit each single frame. Then, create a new image per direction, set its height to the frame height you just measured (for that direction) and set the width to the frame width multiplied by the frame count of the animation. For example, if you measured a size of 20x32 pixels and the walk cycle is 4 frames, the new image must be 80x32 pixels (these values are what I measured for Clover from the custom character example above). Finally, paste each frame of the animation next to each other into the new file (left to right). To align them correctly, it helps to draw colored rectangles the size of a frame (as many as there are frames in the animation) on a seperate layer to show where the frames should go and use them as a guide.

Step 3: Creating your character definition file

Next, download this template file or modify the Clover.yaml file from the example character above. It's just a plain text file, so you can open it with any text editor you like. Notepad works just fine, but tools like Visual Studio Code or Notepad++ have integrated syntax highlighting that makes working with YAML files a little more comfortable.

The first two lines contain the name of your character and the name of the category it will be sorted into in the character selection list. These can contain spaces, but special characters might cause issues. Enclosing the name or the category in quotes ("like this") can help if it doesn't work. After that, the 3 possible states a character can be in (idle, walking and running) are configured separately for each direction.

The "Sprite" property sets the relative file path to the files you made in step 2, this means that if you place them right next to the YAML file, you can just use the file name itself, which is what I recommend. Re-using the same sprite file across multiple states is allowed.

"FrameRate" sets the frame rate of the animation in frames per second (decimals allowed, seperated by a "."), "FrameCount" determines how many frames the animation contains and "StartFrame" allows starting the first loop of the animation at the specified frame index (starts from 0, so the second frame actually has a frame index of 1).

If you only have one set of side-facing sprites instead of seperate left/right ones, remove the "Right" section of each state in the definition file. This tells Desktoptale to automatically generate one internally by copying the "Left" section and flipping it. For this to work, you need to make sure that the side sprites are left-facing. If they aren't, please flip them manually in your image editing application of choice.

If you don't have seperate running sprites, remove the entire "Run" state from the definition file. This automatically generates one from the "Walk" state that plays its animations at 2x speed.

Step 4: Putting it all together

Almost done! Locate the custom character folder ("Custom" inside "Content" next to Desktoptale.exe) and make a new folder inside (not strictly required but recommended). Next, copy your character definition file and your sprites to this folder (if you followed my advice to put just the file names of the sprites into the definition file). Now, start Desktoptale (close it if you had it open before). Your character should now appear in the character selection list!

Step 5: The cherry on top (optional)

Starting from version 1.6.0, it is possible to set a custom animation to be played while C is held, mimicking the functionality of the Clover dance in custom characters. An animation that plays whenever the character is being dragged around with the mouse can be added as well. Both of these features make use of their own sections in the character definition file, titled "Action" for the former and "Drag" for the latter. Their structure is identical to the Idle, Run and Walk sections, but while both support separate sprites for all orientations, it is also possible to only specify a Down sprite, causing it to be used as a fallback - please refer to the Clover example for details. Additionally, by adding "Loop: false" to the definition of an orientation, the animation will only be played once each time it is triggered instead of continuously playing on loop.

Finally, both walking and running speeds of your character can be overridden by adding the WalkSpeed and RunSpeed parameters to the top of your character definition file. These values are specified in pixels per second at a scale of 1x - at higher scale settings, the speed defined here will be multiplied by the scale factor. If only WalkSpeed is defined, the running speed is automatically set to double its value. To make your character unable to move at all (like Flowey), set both to 0.

Troubleshooting

If you get an error message when opening Desktoptale, that means that there is some error inside your character definition file. I set up a few more or less helpful error messages for a few common problems, but if you're really lost, please contact me on Twitter (@ToadsworthLP) or Discord (toastworth).

If you get an error message when selecting your character from the character list, the program can't find at least one of the sprites specified in the character definition file. The error message contains the full path of where it expected to find the file - the most likely cause for this is a typo in either the file name itself or in a "Sprite" property in the character definition file.