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.
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.
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.
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.
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.
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.
This program is included with the Windows Mod Tools, but us Mac folk have to download it manually. Grab the free version from here.
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.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.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.images - 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.modinfo - 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.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.luaThe 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.
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.
All done? Nice.
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."
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.
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.
/scriptsspeech_esctemplate.luaThis 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.)
/prefabThe /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.luaHere 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!
/bigportraitsHead 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.
/imagesYour /images folder contains miscellanious art assets the game uses; namely map icons and saveslot portraits. DST also features nameplate files and avatars.
modicon.texThe 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.
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.
/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.
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.
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)