Ultroman's Tutorial Collection + Newcomer Intro

[Ultroman 735]

Here's my collection of good threads/posts with great content, either explanations or code snippets. You will also find many other tutorials by following the links in the Forum Subsections paragraph below to the other tutorial collections on the forum.

I keep adding to this list in a text file on my computer anyway, so I might as well keep the list here for everyone to peruse. Klei ppl: It would be awesome if this could be put in a state where it did not get archived, so I can keep updating it. UPDATE: Thanks for the pin, @JoeW!

>> Link to the Newcomer Intro Post <<
The Newcomer Intro Post has a lot of basic information you need to start modding, plus a bunch of great tips, for example about how to debug your mods and how to search the forum effectively. Also contains links to various other resources, some similar to this thread, where you can find even more great information, albeit most of it is older than most of the things in this post, but there is still a lot of great information to find.

If you're making your first player character, start by looking at the first 4-7 links in the "Player Character Stuff" section below AFTER you've been through the newcomer post.

2021 update: It has come to my attention, that the tutorials are slowly being lost to automatic archiving on the forums. Since only pinned posts and those in the "Tutorials and Guides" section seem to stay alive, I'll start converting the scattered posts into actual tutorial threads, starting with the oldest ones. Many of them need a dusting, anyway.

Forum Subsections
DS "Tutorials and Guides" Section
DST "Tutorials and Guides" Section
Link to Recezib's excellent "Guide to getting started with modding for DST (and a bit for DS, as well)" post, similar to the newcomer post, but with MANY more details. I can't guarantee that all the information in there is up-to-date, though, since the post is from December 2014 and links to other posts just as old.
Link to Cheerio's old, but still good, "Guide to getting started with modding for DS" post, again similar to the newcomer post, but with many more details. I can't guarantee that all the information in there is up-to-date, though, since the post is from 2013 and links to other posts just as old.

General Stuff
Modinfo Guide
Modicons
Explanation of events and event parameters (by Serpens)
Custom events
Exporting music
Original Music Mod tutorial (Here's a post where some person helps another person who is having trouble with this tutorial)
Check if world has caves
Saving and loading data for a prefab
Make prefab a light source
AoE Damage / Explosion
Guide to differences between DS and DST modding and converting mods between the games

Player Character Stuff
Big Book On Character Creation - (full guide to creating a character mod for DST, written by user C_Thun)
Extended Character Template
Extended Character Template Fixes
Extended Character Template "Remaster" (an updated guide to the Extended Character Template; I have not tried this one)
Guide for character modding on Mac
Making Custom Skins for Modded Characters
Reskinning and Animation Guide (full guide to making a mod that reskins a monster; great source for anything with textures; redirects to a Steam Community post)
Custom Character Sounds
Player starting items
Making basic perks (most of them are for DS only; 40+ different ones; haven't tested them, personally, but they seem legit)
Making buffs (simple buff framework with examples incl. movement speed, max-health increase and damage modifier)
Using the sanityaura component
Affecting sanity in a dynamic way, using a custom sanity rate function and e.g. listeners
Auras (can be added to any entity; the example is written for custom entities, but can be changed to be added to non-custom entities)
Sanity gain or drain when around another character or certain entities (the example is a character prefab, but it can be changed to any prefab / tags you want)
Custom Sleeping Stats For A Character
Character transformation / beast-form
Levelling system

Crafting and Food Stuff
Making a recipe character-specific. Also duplicating crafting recipes, plus other stuff
How Cookpot Recipes Work
Fun With Food (shows several different ways of changing the way food works, also character-specific changes)

Item Stuff
Make it so no one else can pick up a custom item (like Thor's hammer)
Make an armor have 100% damage absorption against certain mobs
Life-steal
Creating HANDS item from scratch
[Template/Tutorial] Custom crafting tab and items
How to make Drying Racks

Edited May 26 by Ultroman
added links to forum subsections and rezecib's excellent newcomer post

[Yakuzashi 146]

'You are a good man. Thank you.'

[Ultroman 735]

>>  The Newcomer Intro Post  <<

Welcome to the world of Don't Starve modding!

There are a bunch of things you should do, in order to make your life easier going into this.

• Get yourself a nice text editor. I use Notepad++ and can highly recommend it. Make sure to set the "Language" to "Lua" while you're coding in Lua (the language we use for modding). That'll help you greatly in many ways. The "Find in files" function is also useful, for finding examples of code usage in the game files (CTRL-SHIFT-F in Notepad++, and make sure the filter is either *.* or the extension of the files you want to search in, e.g. *.lua, and also make sure to set Match Case etc. to what you want). Sublime is another great text editor. There are many!
• Take a Lua crash course. Here's a quick text-based crash course for already experienced coders and here are two crash courses in video-form, the first (12 min) basically goes through the Lua Manual while the second (15 min) does its own thing. It WILL save you LOADS of time and frustration to learn Lua first. I'm not kidding. Do this for yourself. You need to know how the syntax and the peculiar table/object model work to form everything from a light, to a list of strings, to a full player object. There is very little help from the language itself, so things like searching through a list is something you have to make yourself or find from a code resource.
  You might be asking how to do tutorials in Lua when you haven't even set up a mod yet. You can use this Online Lua Interpreter to play around.
• Look in the FAQ for general information.
• You'll find the game code scripts in:
  • DS: steamapps\common\dont_starve\data\scripts
    You'll find the new/changed data files for each DLC in: steamapps\common\dont_starve\data\DLC000#
  • DST: steamapps\common\Don't Starve Together\data\databundles\scripts.zip
    Unpack that somewhere far away from your game folder.
• Game code file structure:
  • In the "prefabs" folder you'll find all the entities in the game (players, items, creatures, bosses etc.). Some prefab files hold more than one prefab, like spider.lua and cavespiders.lua which have several creature prefabs in them, and e.g. the amulet.lua and hats.lua which have several item prefabs in them.
  • Everything in the game is made up of components, e.g. health, combat, growable, etc., which are in a separate folder called "components".
  • In the "stategraphs" folder you can find so-called stategraphs for all entities that need one. A stategraph is a collection of states an entity can be in and the actions they can perform. The stategraph also handles a lot of the waiting for, and switching of, animations, etc., based on the actions performed.
  • Then there's the "brains" folder. Living creatures have brains (AI) which choose and trigger actions for them.
  • The UI-stuff is mostly found in the "widgets" folder.
• Look at the amazing collection of modding tips and tutorials you can find in the "Tutorials and Guides" subsections (DS and DST) each of which is a subsection to the respective modding forums (DS and DST). Both have some overlap between DS and DST. There are some for working with items, images and animations. Of course, there is also the list I've compiled in the first post in this thread.
• Learn the basics of the files involved in the mods, by studying a couple of popular mods. I have a post here explaining the contents of modinfo.lua with a link to a simple example-mod.
• Some information about mod icons.
• To see how working mods are made, download a few mods, and look at their code. I can recommend this one for a simple TUNING-variable tweak, and CactusArmor.zip for a simple armor (although it is a DST mod, I think the code should work for both DS and DST, except the api_version in modinfo.lua).
• Look at the tutorials I've listed in the first post of this thread. Even if you don't understand everything that's going on, it should still help you understand bit by bit how things are done. There are many moving parts, so don't expect to just push out a mod on your first day...at least not a bug-free one
• When you're completely baffled by something, try to find an existing mod that does something very similar to what you're doing. You can usually figure out what they're doing or it'll give you some new insight to help you progress.
• Last but not least, when you have finished reading the sections below, continue on with this excellent more in-depth newcomer post written by rezecib, a modding veteran.

 

Searching the forum

"I know how to search a #%&€ forum!" Yeah, but this one is special. When using the search bar at the top, it defaults to searching all the forums, not just the modding forums, so you'll get search results for all Klei's games and all the forums they have, not just the modding forums. These are the two easiest ways I've found to search for modding threads. One (normal forum search) allows you to search exclusively for threads for one of the games, and is probably the most easily accessible, while the other method (advanced search) allows you to search for threads for both games (DS and DST) at the same time OR exclusively one of the games.

Normal modding forum search, when searching exclusively for DS or DST, but NOT BOTH:

• Make sure you go to the right forum
  [Don't Starve Together] Mods and Tools
  or
  [Don't Starve] Mods and Tools
• Click the search-bar at the top of the page
• Click the button that appears to the left of it and choose "This forum"
• Then type in your search at the top, and press Enter or the magnifying glass

Advanced modding forum search, when you don't care whether the thread is for DS or DST:

• Click the search-bar at the top of the page
• Type in any search term and press enter or click the spyglass.
• On the next page, click on "More search options" underneath the search term bar.
• Select "Topics" on the left
• In the "Forums" dropdown below, scroll downwards and select BOTH
  [Don't Starve Together] Mods and Tools
  and
  [Don't Starve] Mods and Tools
  from the list.
  The content is kind of muddled together between the games, despite the mods trying their best to keep them separate, but much of the code can be used for either game. Just be aware that there are differences between the two games, and that you might sometimes need to make slight changes or even take a completely different approach for certain functionality between the games. If you want to be at least almost sure not to have this problem, only select the forum for the game you are modding for.
• Then type in your search at the top, and press Enter or the magnifying glass

 

Debugging

In order to see the full error log, which has more information than the game has room on the screen to show you, and also shows what might have lead to the error, you need to look at the game logs.

For DS there's only one log. It's called "log.txt" and it's right here:

<SystemDriveLetter>:\Users\<UserName>\Documents\Klei\DoNotStarve

For DST, there are two "types" of logs.

If your game crashed while playing, the error is most likely found in your server_log.txt file(s). If your server has caves in it, there will be a server_log.txt for both the regular server "shard" and the caves server "shard". You can find those files here:

<SystemDriveLetter>:\Users\<UserName>\Documents\Klei\DoNotStarveTogether\Cluster_#
(# = 1-5; this is the placement of your server on the list of servers in-game)

In that folder, you will find a "Master" folder and perhaps also a "Caves" folder. Both should have a server_log.txt in them.

There is also a client_log.txt. If the game dies in the main menu or while loading the game or on the character select screen, in which case there might not be any server_log.txt files, you can still find the client_log.txt file here:

<SystemDriveLetter>:\Users\<UserName>\Documents\Klei\DoNotStarveTogether

These files are crucial for us to help you, when you're asking how to fix a crash. Attach those files to your crash post, by dragging and dropping them onto the reply you are about to submit, and if you suspect that it's your mod causing it, also post a zip of your mod.

You can also use those files to your advantage when debugging your mod. If something in your mod is not working, or even if it is crashing during play, you can give yourself lots of hints and information about what code is actually being executed and which parts are not. You do this by using print-statements, like shown below. These print-statements show up in the client_log.txt, which you can even look at while the game is playing (Notepad++ should automatically ask you to reload the file if you come back to it after it has been changed, but not always!!).

-- Simple print just to show if a function was called.
print("MyFunction was called")

-- Printing numbers
print("Current sanity value: "..inst.components.sanity.current)

-- Printing booleans. To print booleans (true/false) you MUST wrap the boolean in a tostring() call,
-- to tell LUA to convert it to a string.
-- Example 1:
print("My value is higher than 100: "..tostring(myvalue > 100))

-- Example 2:
local isMyFeatureOn = true
print("Feature is on: "..tostring(isMyFeatureOn))

You can really use print-statements to great advantage. If you're unsure why your mod isn't working, just slap in print-statements in all the functions and have them print out "<function name> was called", and follow the trail in the log and your code side-by-side. Add in some extra print-statements to make sure your variables are set to what you expect, and I can almost guarantee you, that you will find out what is going wrong.

 

Posting A Topic

If you need help, post a topic in the appropriate modding section of the forum. Note that there is one for DS and one for DST. Please include the relevant code (Lua file) and an error log if you have an error (see above how to find the logs).

Try to keep your post on topic and don't ask too many things at once. It's better to start two, three or four topics, if you want help with two, three or four different things, but you should generally try to focus on fixing only a few things at a time.

Also, keep in mind that the people reading your post have zero knowledge of what you're doing, what you have working, what the context of the problem is, your file structure, how much you actually know what you're doing or anything at all, unless you inform them of it.

Remember that when you're new, the problem is often not what you think it is, but probably something "next to" what you think is the problem, so making sure that people know exactly what you're trying to achieve (the functionality you want to have in the end) and the context in which you're trying to achieve it (is the code for DS or DST? Is it in a bee or in the player?). And be specific. Ex: if you want a healing aura, what do you mean by that? Should the player be healed by being around some things or should things around the player be healed? Which things? What have you tried already?

And remember, stay positive

Edited May 26 by Ultroman
added links to forum subsections and rezecib's excellent newcomer post

[Hornete 8366]

Wooo, Congrats on the pin!

@Ultroman
 

I think you should add this to the post, 

[Ultroman 735]

10 minutes ago, Hornete said:

I think you should add this to the post, 

Ooh, good one! And new

[ry3bread 4]

Thanks again!

This fella’s a hero.

[Mick Satana 1]

Thanks for listing these topics. It's really easy to follow.

 

ps, this link is broken.

On 3/10/2020 at 4:56 AM, Ultroman said:

Character item modding, special objects or features.

[Ultroman 735]

18 hours ago, Mick Satana said:

Thanks for listing these topics. It's really easy to follow.

 

ps, this link is broken.

Thank you for the heads-up. Sadly, that post seems to have been deleted. I'm happy this list helped you

[Merio. 2]

Thank you for this.

[SinancoTheBest 3550]

Are there any specific tutorials for music mods?

[Ultroman 735]

On 9/10/2020 at 3:00 PM, SinancoTheBest said:

Are there any specific tutorials for music mods?

There is an official one, but it's quite old now.

Here's a relevant search.

Here's the original Music Mod tutorial.

Here's a post where some person helps another person who is having trouble with that tutorial.

[Ultroman 735]

ignore this

Edited January 28 by Ultroman

[Ultroman 735]

On 7/14/2020 at 4:05 PM, Mick Satana said:

Thanks for listing these topics. It's really easy to follow.

 

ps, this link is broken.

That post has been replaced by this much more complete tutorial which includes exporting files to edit, converting them into separate images to edit using KTools and Spriter (I recommend that method, unless you really only need to do minor reskinning, as the author also says, but you'll probably want to get to know Spriter and KTools, anyway.

[Muskar 8]

On 3/10/2020 at 1:42 AM, Ultroman said:

Normal modding forum search, when searching exclusively for DS or DST, but NOT BOTH:

• Make sure you go to the right forum
  [Don't Starve Together] Mods and Tools
  or
  [Don't Starve] Mods and Tools
• Click the search-bar at the top of the page
• Click the button that appears to the left of it and choose "This forum"
• Then type in your search at the top, and press Enter or the magnifying glass

 

Doesn't seem to work for me. I get the following result in both Chrome and Firefox - no button appears:

What am I doing wrong?

Also, perhaps in the Debugging section you could add a small section about writing out tables in runtime via a table serializer like serpent or others - noting licenses are worth keeping an eye on etc. I've only tried serpent but it helps greatly with the followings options:

 

local serpent = require "util/serpent" --put serpent.lua and license in "util" folder in the mod
--...
print(serpent.block(table, {metatostring=false, maxlevel=3, maxnum=50, nocode=true})) -- don't set maxlevel very high when metatostring is off, otherwise you'll likely run out of memory

 

 

[Ultroman 735]

4 hours ago, Muskar said:

Doesn't seem to work for me. I get the following result in both Chrome and Firefox - no button appears:

What am I doing wrong?

It appears they've changed the script since I wrote that. Now you have to perform a search and press "More search options" to get to the list of forum sections. Fixed! Thanks for letting me know.

 

4 hours ago, Muskar said:

Also, perhaps in the Debugging section you could add a small section about writing out tables in runtime via a table serializer like serpent or others - noting licenses are worth keeping an eye on etc. I've only tried serpent but it helps greatly with the followings options:

 

local serpent = require "util/serpent" --put serpent.lua and license in "util" folder in the mod
--...
print(serpent.block(table, {metatostring=false, maxlevel=3, maxnum=50, nocode=true})) -- don't set maxlevel very high when metatostring is off, otherwise you'll likely run out of memory

 

 

I would love to, but I simply do not have the time right now. Also, I have never used any of those libraries. Never had the need. You seem like a bright fellow. I would urge you to write up a small tutorial / guide thread about using these, to help others and perhaps serve as a log of understandings for yourself in the future.

Edited March 2 by Ultroman

[Hornete 8366]

@Ultroman Mind adding these guides/tutorials to the main post ? 
 

Spoiler

 

 

 

 

[Ultroman 735]

2 hours ago, Hornete said:

@Ultroman Mind adding these guides/tutorials to the main post ? 

Wow, thanks! That is a lot. I'll add them later, when I've figured out how to categorize them all.

Edited May 27 by Ultroman