So You Want To Make a Custom Don't Starve (Together) Character

6/6/20 - Hello! Over the last few months I've gotten a number of requests for help on Twitter, but unfortunately I don't play this game at all anymore. I can't help you!

Hello! My name is Corgi, and welcome to my very questionable tutorial! This guide will attempt to show you how to create a custom playable character for the Klei Entertainment games Don't Starve and Don't Starve Together.

Caveat Emptor: I am very new at this myself. The steps I will cover in this guide are probably not the most efficient way to do things. However, as I was learning how to do this on my own, I ran into a lot of difficulties--the existing guides I found were all very old, information was scattered, image links were broken, etc. I may not be a great DS modder, but I am very good at writing guides, and so this is my attempt to make a more up-to-date, easy-to-read tutorial. I hope this will at least form a jumping-off point for anyone else interested in character modding DS/T. The guide itself borrows largely from the original ESC Template Tutorial, expanded upon and more thoroughly explained.

This is a text and image walkthrough, not a video walkthrough. Video walkthroughs are the bane of my existence. I will also be including information for people using a Mac.

So you've played some Don't Starve and maybe you've seen all the cool custom characters people have created and modded into the game! Hey! You wanna do that, too! But where to begin?

The good news is that as game mods go, a custom DS/T character is not too hard to get started. To begin, you will need the following:

This template, by Dleowolf, forms the core of everything we're going to work on. There are three versions of this file: one for Don't Starve and DS: Reign of Giants, one for Don't Starve Together, and one for DS: Shipwrecked. Download the one appropriate to the game mode you wish to play. For this tutorial, I will primarily be focusing on creating a DST character, but most of the information should be applicable to all game modes. You can also find these files on the Steam Workshop (DS/ROG, DST, DSS), but I find downloading the files directly to be more straightforward.

2. The Don't Starve Mod Tools

This tool app is downloadable via Steam. Assuming you own the game(s), you can find it by clicking on Games > Tools, and then installing Don't Starve Mod Tools.

3. An Image Editor

For modding the sprites and other art assets, you will need a capable image editor, such as Photoshop, the GIMP, Paint.NET, or something else of your choice. Personally, I draw all of my art assets in CLIP Studio Paint, and then do minor edits like positioning and resizing in Photoshop. Support for transparency is required, but this is default behavior in all but the most basic editors.

4. A Text Editor

A lot of code is going to be messed with in this guide! You will need a good text editor--not Notepad or TextEdit. For Windows, Notepad++ is commonly recommended. On Mac, I use Atom, which also has a Windows version if you would like to try it. Whatever you use, syntax highlighting will help you immensely. Syntax highlighting is when a program colors words differently based on context. You can see the difference below.

Syntax highlighting is very useful in making sense of the Lua language that DS uses, especially if you aren't familiar with the language. Atom users must install Lua support separately via this package (just search for language-lua within the Atom program's Install section); N++ supports it automatically.

TEX Tools, by Handsome Matt, is a duo of programs used to work with the TEX file format DS uses for its images. We will primarily be using the TEXCreator file in here to convert the modicon file from PNG to TEX. TEXTool can be used to view TEX files.

Mac Users: The above link goes to the original Windows files. I have wrapped them into Wine wrappers and made them available for download. (mirror 1. mirror 2) The wrapping process unfortunately makes them extremely large, around ~400MB unzipped. If you are familiar with Wineskin Winery, you can recreate them on your own: I used the WS9Wine1.9.21 engine and copied the folder acquired by downloading the Windows tools into the wrapper. Mono MUST be installed; Gecko does not need to be. If you cannot get any of the above to work, I'm afraid I cannot help you further, and you will need to use a Windows machine.

The ktools are two command-line tools for Mac, Linux, and Windows: ktech, which converts PNG to TEX and vice-versa, and krane, which converts animation and build files into Spriter projects. If you are comfortable with the command line, you probably don't need me to explain further. Caveat: I ran into an error when I attempted to build ktools with libzip installed, and had to uninstall it to get a functioning build.

5B. (MAC USERS) SEMI-OPTIONAL: Access to a Windows Machine

I know. I don't like it either. However, the process to get the files to compile is very difficult to get going on OSX. If you are comfortable with the command line, you can try using the instructions listed here. Some of the things suggested in that comment are reflected in my fork of the ktools, such as fixing the premake5.lua script. My ultimate goal in using these tools was to enable myself to use the scml and png compilers via the Terminal, which I succeeded in doing through enough trial-and-error that I am not confident I could reproduce the steps for you here. However, it CAN be done.

If all of this is beyond you, you will need access to a Windows machine, or a friend with a Windows machine, in order to run the compilers. A virual machine program such as Parallels or Virtualbox (the latter of which is free) will also work.

6. A Rename Utility

We'll be doing a search-and-replace to change a lot of the filenames, so something to automate that process is needed. If you are using Windows, Notepad++ and ReNamer will work. If you are on a Mac, I recommend using NameChanger and Atom together, which I will explain later.

7. (MAC USERS) Spriter

This program is included with the Windows Mod Tools, but us Mac folk have to download it manually. Grab the free version from here.

Got everything? Let's go!

Awesome, you're ready to start! Let's begin by looking at the contents of the file you just downloaded. We'll be looking at the Don't Starve Together set, which differs some from the ones for the other two templates. Unzip the template you grabbed and open up the folder.

We'll go through these one by one. For now, don't delete anything.

anim - This is the folder that will ultimately hold your finished, compiled artwork, the stuff that makes your character yours.

- This is the folder that will ultimately hold your finished, compiled artwork, the stuff that makes your character yours. bigportraits - This folder has two sets of files in DST, with the names esctemplate_none and esctemplate on three different file types each. There is also a "notes" file with some special instructions for making the "_none" files work. DSRoG will only have one set.

- This folder has two sets of files in DST, with the names esctemplate_none and esctemplate on three different file types each. There is also a "notes" file with some special instructions for making the "_none" files work. DSRoG will only have one set. exported - This is where the individual files that make up your character's body go before being compiled. It starts with three folders: esctemplate , esctemplate_cleared , and ghost_esctemplate_build . Respectively, these are your character's body parts; empty versions of the same files, so if your character does not have a tail, you can just copy and paste the "tail" files from cleared into esctemplate ; and the images that make up your character when they are dead in multiplayer, as a ghost. Ghost files do not appear in single-player templates.

- This is where the individual files that make up your character's body go before being compiled. It starts with three folders: , , and . Respectively, these are your character's body parts; empty versions of the same files, so if your character does not have a tail, you can just copy and paste the "tail" files from into ; and the images that make up your character when they are dead in multiplayer, as a ghost. Ghost files do not appear in single-player templates. images - Other miscellanious images that will need to be compiled: avatars, map icons, character selection images, etc.

- Other miscellanious images that will need to be compiled: avatars, map icons, character selection images, etc. modicon - These are the files that make up what your mod's icon will look like on the in-game mod selection screen.

- These are the files that make up what your mod's icon will look like on the in-game mod selection screen. modinfo - This file contains your mod's official name, the version info, compatibility, etc.

- This file contains your mod's official name, the version info, compatibility, etc. modmain - This file is what hooks everything together: it calls your art assets, fetches the script file, it's where the character select screen lines like perks and quotes live.

- This file is what hooks everything together: it calls your art assets, fetches the script file, it's where the character select screen lines like perks and quotes live. scripts - This contains the "prefabs" folder, which determines your stats and other interesting character traits, and the file speech_esctemplate.lua , which contains EVERYTHING your character will say in response to the game world!

That's a lot to look at all at once! Let's start slow, with modinfo.lua.

modinfo.lua

The comments in this file explain it quite well. It dictates the name of your mod on the Steam Workshop, the description of it, the author, and the version number. If you have a thread on the Klei forums for your mod, you can change the variable under "forumthread" as well.

This is very straightforward. The one catch is version number. Each time you update the mod, you must change the version number, no matter how small the change. You will not be able to upload it to the Workshop otherwise. As a working example, here is the section for a character I made.

Renaming

In all likelihood, your character's name is not Esctemplate. To that end we need to go through the template folder and replace every instance of "esctemplate" with the character's name. It does not need to be the full name, as this is just for scripting purposes; if you were making a character named Johnny Joestar, you could just call him "jojo" in the files, and fill out his full name in modmain later.

BE AWARE that lua is a cAsE sEnSiTiVe language: "esctemplate" and "ESCTEMPLATE" are treated as completely different things, and your character's name MUST follow the same convention. With this in mind, follow the below steps to replace the default name.

NOTEPAD++

In Notepad++, press Ctrl + Shift + F or go to Search > Find In Files to open the Find In Files dialogue. Set Directory to the mod folder, and ensure the Match Case box and In all sub-folders box are ticked. Do a Replace in Files for "esctemplate" and "ESCTEMPLATE", respectively. All instances of "esctemplate"/"ESCTEMPLATE" within the files should now contain your character's name. The filenames themselves are unchanged! Open ReNamer, and drag your mod folder onto the bottom window. Click the box that says "Click here to add a rule," click "Replace" on the left, and do the same search and replace that you did above. There are no all-caps ESCTEMPLATES in the file names, so you should only need to do this once. All your files should now be renamed!

ATOM

In Atom, open any file from the template folder. Press Cmd + Shift + F to open the Find In Project dialogue. (see above) Make sure the "Aa" on the right is blue, which enables case-sensitivity. Do a Replace All for "esctemplate" and "ESCTEMPLATE", respectively. All instances of "esctemplate"/"ESCTEMPLATE" within the files should now contain your character's name. The filenames themselves are unchanged! Open NameChanger, then switch to Finder and browse to the template folder. Do a name-match search for "esctemplate" and limit it only to the template folder. A list of all files with "esctemplate" in the name should appear. Select all of these files and drag them to NameChanger's window. Type "esctemplate" into the "Original Text" box and your character's name into the "New Text" one. Again, keep it all lower-case. Hit Rename. All your files should now be renamed!

All done? Nice.

Uploading to Workshop

Now is a good time to test your mod to make sure the core of it works, before you start going in and really messing with things. To do this, we're going to open up the Mod Tool you installed via Steam earlier.

To open it, simply double-click on it. If you are on Windows, doing this will bring up a small box asking you what exactly you want to open. Leave it on "Play Don't Starve Mod Tools" and click "Play." If you are on Mac, it will open this immediately.

You are now at a very simple program that has one purpose: uploading your mod to the Steam Workshop. You can pick which core game to upload to, and add or delete mods. Choose the appropriate target workshop, and then click "Add."

For Update Data : choose your template folder.

: choose your template folder. For Preview Image : Basically any placeholder image file will do while you're working on the mod; you can make a fancier one later, if you wish.

: Basically any placeholder image file will do while you're working on the mod; you can make a fancier one later, if you wish. For Update Details: This is the name and description of your mod. It does not need to match the information in your modinfo.lua file.

The "Upload redundant files" and "tags" don't need be to touched for now.

Once you've got all of this in order, click Publish! The program will do its thing, and you will get a notice that your mod is now on the workshop. Depending on your default settings, it may be visible or hidden; you can change this by going to the workshop page and changing it manually.

While you're there, go ahead and subscribe to your mod too, so you can test it out! Cool! Activating mods in DS/T is fairly straightforward and will not be covered here. Basically what we are looking for, once you've activated the mod, is that it a) shows up in the game and b) does not crash the game. If all was done correctly, it should start without a hitch, and you will probably have a little dog character, or an invisible character. If it errors out, google is your friend. I'm afraid I can't cover lua coding or basic programming concepts in this guide.

Best Practices: It's a very good idea, once you have a known working build, to back it up. This way, if you break the mod while working on it and don't know what you did to fix it, you have a known good version to fall back on.

Customization

If all is well, go ahead and close the game and the mod tool, and we'll get to work customizing your character. Open modmain.lua .

modmain.lua

Do note that all instances of "esctemplate" in this image should be your character's name.

Within this file, you can change your character's title, name, perks/traits, and quote. You can also change the gender; despite what the template says, your options are MALE (he/him), FEMALE (she/her), ROBOT (it), NEUTRAL (singular they/them), or PLURAL (plural they/them). That should be all you need to do in this folder. Open the "scripts" folder in your template folder.

/scripts

speech_esctemplate.lua

This is what your character says in the game! The default file is the one that comes with the core game. If you have the DLC, you may want to consider using the script file that comes with that instead. It should be on your computer, or you can just download this one.

If you open that sucker up, you will find that it has something in the neighborhood of 1000 individual lines. You don't have to change every single one if you don't want to, but if you've got three days to kill, go for it. (Be very careful about the contents! If there is a missing comma at the end of any dialogue line, the game will immediately crash! It should tell you which line in the file it crashes at, but better to avoid them at all.)

/prefab

The /prefab folder within /scripts is basically all of the cool mechanical parts of your character. This is generally where you will put custom perks; for example, our JoJo character might have a perk that lets him regenerate health. The code for that would go in here. Custom perks are beyond the scope of this guide, but google and the Klei forums are very helpful for specific questions.

The DST folder will have an additional file, esctemplate_none.lua . In most cases you won't need to touch this. The primary file here is esctemplate.lua.

/prefab/esctemplate.lua

Here you can define custom starting items (like Willow's lighter), set stats, adjust damage and hunger multipliers, and change speeds. You can also pick which voice to use for your character. Default ones are:

wilson willow wolfgang wendy wx78 wickerbottom woodie maxwell wathgrithr webber

Note: When adding custom code to this file, ensure that you put it BEFORE the final end in the file. This end signifies the end of the whole file, and putting it after that will crash the mod.

That's the bulk of the coding, apart from any custom perks you want to add. You may want to re-upload your file (don't forget to change the version number in modinfo.lua ) and test that it all still works. Onto art!

/bigportraits

Head over into your /bigportraits folder.

It's pretty much what it says on the tin. Big portraits! These appear in character select. Draw or edit these images as you wish; size and style are up to you. DST has an extra image. For now, don't worry about the .tex and .xml files. We'll update those later. For those interested in mimicking the game's style, here is a good tutorial by Fidooop.

/images

Your /images folder contains miscellanious art assets the game uses; namely map icons and saveslot portraits. DST also features nameplate files and avatars.

modicon.tex

The modicon.tex file is unique in that it must be compiled by a specific program. Create the icon you would like, name it modicon.png , and then run it through TEXCreator, discussed above. You must set the texture type to 2D, and check both the "Generate Mimaps" and "Pre-multiply Alpha" boxes. Convert the file and drop the .xml and .tex files into your folder.

Compiling the Art

With /bigportraits and /images done, now is a good time to test your mod again. This time we need to make sure your game recompiles the artwork from the .pngs we've been using to the game-readable .tex/.xml files.

If you are working on Windows, the game should automatically recompile them when you boot the game, as long as you have the Mod Tools installed. I had difficulty getting this to work. Fortunately, you can run this manually.

autocompiler.exe is most easily found by right-clicking on the Mod Tools listing in Steam, clicking Properties, going to the Local Files tab, and clicking Browse Local Files. I highly recommend making a shortcut to this folder on your desktop. You will probably be referring back to it often. Within this folder, there is a folder called /mod_tools . autocompiler.exe , png.exe , and scml.exe can be found here. Autocompiler runs both png and scml automatically, but you can run either individually if desired. There is also a helper tool available here, but I have not tested it.

autocompiler works as a stand-alone program, but png and scml must be run on the command line. You can do this by opening the command prompt with Windows+R and typing cmd into the window. Drag png/scml into the prompt, hit space, drag the .png or .scml file you want to convert into the prompt, hit space, and finally drag the template folder into the prompt. Hit enter, and it should begin to export, putting the files where they need to go automatically.

IF YOU ARE MODDING DST, go back into /bigportraits and /images .

You must edit the /bigportraits/esctemplate_none.xml and /images/esctemplate_none_oval.xml , or the game will crash. Open these files (Notepad++ or Atom will work).

In /bigportraits/esctemplate_none.xml , change the Element to [character]_none_oval.tex .

In /images/esctemplate_none_oval.xml , change the Element to [character].tex .

Once your art has been compiled, you can now upload the mod and test it again. If it crashes, make a note of the error, or check your log file (located in Documents) to find the error.

When all this looks good, we can get to the last and trickiest part: editing the character sprite.

Editing the Sprite

With your Mod Tools, you will have also downloaded a program called Spriter. This is accessible in Windows within the /mod_tools folder, and if you are on Mac you should have already downloaded it.

Spriter is a program that will let you preview how the sprites you create for your character look when put together. Do not change or save anything within Spriter. For our purposes, it is STRICTLY to be used to preview the sprite. Spriter's file type is .scml .

If you go to your /exported folder, you will see some subfolders, within which are a lot of folders with names like "leg" and "face." Don't Starve's sprite animation works a lot like traditional frame-by-frame animation, which means it needs an individual file for every possible thing your character can do. That's a lot of files, and this section will take you some time to complete.

The best way to start is to just open a file in your art program of choice and just draw over it. I cannot advise you much on this part, as I have no idea how your charater will look. For the most part, mimicking the template files will get you through it. Be prepared to make a lot of small changes to get things looking just right. Do not change the dimensions of any of the files unless you absolutely know what you are doing.

When you want to check what your sprite looks like, open Spriter and open the esctemplate.scml file in the folder you've been working on. The scml file draws directly from the art within the folder it's in, and it will reflect any changes you've made to the files within.

When you are done editing the sprite, you'll want to recompile the mod. If your game doesn't do this automatically, you can do it manually; see the section above about running png.exe / scml.exe . The scml files will output to the /anim folder as a .zip . You'll want to reupload and test the mod often to make sure the actual character looks the way you want, and that nothing crashes.

Loose Ends

That's just about the bulk of it. Don't forget to back up your known working versions often while you're editing the character. When you are done, and if you would like to share your character on the Workshop, you can remove some of your extra work files. The /exported folder can be completely deleted, as well as all .png folders. You can also delete the notes.txt files. Everything else should stay where it is. You can also add tags to your final upload in Mod Tools, so people can search for it better.

I wrote this whole thing in a single day and I've probably missed something or made a mistake somewhere. If you see something you KNOW is an error, please let me know so I can correct it. I can be reached on Twitter (@heycorgi). If this guide helped you, maybe buy me a coffee. Otherwise, I hope this is helpful for others interested in getting into this game, and have fun modding!

—Corgi (v1.0.1, 6/6/20)