[Tutorial] Creating a "handslot-equippable-item" from scratch


Malacath
 Share

Recommended Posts

Preface:
This whole tutorial will lead you through the process of creating a "handslot-equippable-item", not including the creation of artwork. That means we will convert an inventoryimage, create a "ground"-animation and create a swappable build, that is when the player holds it in his hand. Why would you want to do this instead of the usual build-renaming of existing animations? Well, this here is a thousand times more flexible and easier to troubleshoot because, honestly, everyone can make mistakes when using other peoples files as a basis. It also feels a lot less "hackish" than renaming the builds and the endproduct will be completely yours.
Also please keep in mind that when making your own mod you should always refrain from using generic names like I do in this tutorial. So do not use "myitem"!
Currently the full tutorial works sadly only for Windows user as the *.tex/animation compiler Klei provides is not yet ported to Mac or Linux. For the relevant parts (I will mark these) you will have to push the mod to a Windows user and have them convert it.



0 Prerequisites
To successfuly finish this tutorial you will need:
-the "Don't Starve Mod Tools" which you can download from Steam

This is where you find a skillfully hidden dropdown menu to select "Tools" in Steam. Disregard the german  : P

post-245716-0-32928000-1384196602_thumb.


-image assets you want to use for your item

assets.zip

image courtesy to soul, please don't use these assets in your own mod if you intend to release it to the public, thank you ^^


-some patience
-maybe a drink (coffee or tea would be good)
-alternatevly some good music
-preferably a bit of knowledge about "Don't Starve" modding



1 Setting up our mod
Let me assume that you already have your artwork in the form of an inventoryimage of size 64x64 pixels, an image you intend to use for the "ground"-animation and an image you intend to use for the swappable build all in the *.png format.
With those we aim for the following folder structure in our mod-folder

mymod        exported        |->        myitem                |->        ground_myitem                        |->        ground_myitem.png                        swap_myitem                        |->        swap_myitem                                |->        swap_myitem.png        images        |->        inventoryimages                |->        myitem.png        scripts        |->        prefabs                |->        myitem.lua        modmain.lua

You can in fact use more than one image to create your animations and get as complex as you want with your folder structure, but let us keep it basic while still maintaining a certain level of structure for the sake of this tutorial. If you ever work on something more complicated keep in mind that a good structure can be crucuial to a good workflow.
We will also want to set up our two necessary scripts "modmain.lua" and "myitem.lua". The first of these is easy to do

PrefabFiles = {    "myitem",}

If you already have other prefabs registered for your mod then you have to expand the table "PrefabFiles", you should neither create a new one nor override your old one. "myitem.lua" will be a totally generic "handslot-equippable-item" without any use for now. We can go back later and make it a tool, a weapon, a staff... anything you want to do with it basically.

local assets={    Asset("ANIM", "anim/myitem.zip"),    Asset("ANIM", "anim/swap_myitem.zip"),    Asset("ATLAS", "images/inventoryimages/myitem.xml"),    Asset("IMAGE", "images/inventoryimages/myitem.tex"),}prefabs = {}local function fn()    local function OnEquip(inst, owner)        owner.AnimState:OverrideSymbol("swap_object", "swap_myitem", "swap_myitem")        owner.AnimState:Show("ARM_carry")        owner.AnimState:Hide("ARM_normal")    end    local function OnUnequip(inst, owner)        owner.AnimState:Hide("ARM_carry")        owner.AnimState:Show("ARM_normal")    end    local inst = CreateEntity()    local trans = inst.entity:AddTransform()    local anim = inst.entity:AddAnimState()    local sound = inst.entity:AddSoundEmitter()    MakeInventoryPhysics(inst)        anim:SetBank("myitem")    anim:SetBuild("myitem")    anim:PlayAnimation("idle")    inst:AddComponent("inspectable")        inst:AddComponent("inventoryitem")    inst.components.inventoryitem.imagename = "myitem"    inst.components.inventoryitem.atlasname = "images/inventoryimages/myitem.xml"        inst:AddComponent("equippable")    inst.components.equippable:SetOnEquip( OnEquip )    inst.components.equippable:SetOnUnequip( OnUnequip )    return instendreturn  Prefab("common/inventory/myitem", fn, assets, prefabs)

Do not forget that all instances of "myitem" in these two scripts as well as all following appearances of it have to be replaced by whatever name you choose for your item.
Starting your game now will cause an error because the assets specified at the top are missing. Why? Of course because we did not create them yet. But we will fix that next.



2 Creating the inventoryimage
If you put your "myitem.png" file where I told you... then you are basically done. If you want to test it you will want to comment out lines 3-4 and 29-31 in "myitem.lua". Thus the file should look like this:

local assets={    --Asset("ANIM", "anim/myitem.zip"),    --Asset("ANIM", "anim/swap_myitem.zip"),    Asset("ATLAS", "images/inventoryimages/myitem.xml"),    Asset("IMAGE", "images/inventoryimages/myitem.tex"),}prefabs = {}local function fn()    local function OnEquip(inst, owner)        owner.AnimState:OverrideSymbol("swap_object", "swap_myitem", "swap_myitem")        owner.AnimState:Show("ARM_carry")        owner.AnimState:Hide("ARM_normal")    end    local function OnUnequip(inst, owner)        owner.AnimState:Hide("ARM_carry")        owner.AnimState:Show("ARM_normal")    end    local inst = CreateEntity()    local trans = inst.entity:AddTransform()    local anim = inst.entity:AddAnimState()    local sound = inst.entity:AddSoundEmitter()    MakeInventoryPhysics(inst)        --anim:SetBank("myitem")    --anim:SetBuild("myitem")    --anim:PlayAnimation("idle")    inst:AddComponent("inspectable")        inst:AddComponent("inventoryitem")    inst.components.inventoryitem.imagename = "myitem"    inst.components.inventoryitem.atlasname = "images/inventoryimages/myitem.xml"        inst:AddComponent("equippable")    inst.components.equippable:SetOnEquip( OnEquip )    inst.components.equippable:SetOnUnequip( OnUnequip )    return instendreturn  Prefab("common/inventory/myitem", fn, assets, prefabs)

Start the game and you should see a "cmd" window pop up. It will say some stuff and close itself and run "Don't Starve". Activate your mod, load/create a save, open the console and while having the cursor close to the player type

DebugSpawn("myitem")

and hit enter. Hit the spacebar to pick up your item (since it will be invisible you cannot use the mouse) and see the new inventoryimage in all its tiny glory. If you need you can close the log which overlays the screen by pressing "Ctrl"+"L"

post-245716-0-72582900-1383746064.png


If you are on Linux or Mac you can use simplex's program to convert your image to the "*.tex" format, for which you can find a thread here. Put the converted "myitem.tex" into "mymod/images/inventoryimages/" and create a simple text file next to it, change its name to "myitem.xml" and write the following content inside it

<Atlas>    <Texture filename="myitem.tex" />    <Elements>        <Element name="myitem.tex" u1="0" u2="1" v1="0" v2="1" />    </Elements></Atlas>

Note that you need to change the filetype here and I actually don't know if this functionality is hidden by default in Mac or Linux like it stupidly enough is in Windows, but I trust you know what you're doing.

Alternatevly you can give the mod to someone who has Windows and ask them to start the game once while it's enabled and give it back to you.



3 Creating the "ground"-animation
Now comes the stuff that makes this approach worthwhile. Start up "Spriter" via the "Mod Tools" through Steam or if you have it installed seperately you can use that as well (i.e. when you are on Mac or Linux). Choose "File"-"New Project" or "Ctrl-N" and navigate to your mods folder. Choose to create a new project in "mymod/exported/myitem/ground_myitem"

post-245716-0-44747800-1383746043_thumb.

The first thing you will want to do is change names. In the lower right corner you can see "entity_000" and "NewAnimation". Rename "entity_000" to "myitem", this will be the name of our bank (which is important while coding) Now rename "NewAnimation" to "idle", this will be... well... the name of our animation.

post-245716-0-13039300-1383746050_thumb.

You can add more animations by clicking the third button from the left above the name of the bank. But for this tutorial it will not be necessary. Now you need to add the image by "drag-and-dropping" the image in the top right corner of the window into the grey area in the middle. You can adjust its position simply by "drag-and-dropping" it again within that area. The cross can see in that area is the origin of your animation. That means that in "Don't Starve" this will be the point where your item makes contact with the ground and where the shadows and the collisions centers are (if you add those of course). So adjust the position of the image accordingly. Save that file as "myitem.scml", without the ".scml" this will be the name of our build.
Now get back to your prefabs file. Uncomment lines 3 and 29-31 if you commented them out earlier. When you run the game now you will see the "cmd" window again.

post-245716-0-20086700-1383746076_thumb.

This time it will say something about exporting animations and atlasing files, nothing we really care about though. Load a save and spawn the item like you did before (part 2) and it should now be visible. Take a few minutes to admire the beauty of your creation and then go on.
If you are on Linux or Mac there is currently no way of compiling the animation yourself. You will have to give the mod to a Windows user and have them run the game once and give the mod back to you.



4 Creating the swappable build
This part is very close to the last one, but you will have to look out for a few things. Create a new project in "Spriter" in the "mymod/exported/myitem/swap_myitem". Raname "entity_000" to "swap_myitem" and be careful about the name of the animation. We do not have a free choice here, in order to create a swappable build we need to name it "BUILD". Drag and drop the image into the grey area again.

post-245716-0-79860500-1383746056_thumb.

For swappable builds we do not much care for the size, rotation or position of the image, instead you need to move the pivot, that is the red circle in the top left of the bounding box of the image we just dropped into the workspace. When you come close to it it will grow and you can drag and drop it. Wherever you put that pivot will be where the players fist grabbing the item will be. So you will want to move it to the handle of your item, for my example I have to move it a bit lower because the image is very small so that the fist could almost completely cover it. Now right-click on the pivot and choose "Overwrite default pivot". Save the file as "swap_myitem.scml". Note that the window popping up to save your file is very problematic for this task. You will need to write exactly "swap_myitem.scml" as the filename, if you skip the ".scml" part you will jump into the folder with the same name. Now uncomment line 4 in your prefabs file.

post-245716-0-36473900-1383746088_thumb.


Start the game, watch the white text rush by, load a save, spawn the item and equip it. Lo and behold you have created your own "handslot-equippable-item" and it did not even take that long.
If you are on Linux or Mac there is currently no way of compiling the animation yourself. You will have to give the mod to a Windows user and have them run the game once and give the mod back to you.



5 Polishing and finishing up
The best part of this is how easy it is to polish your artwork now. You can simply edit your images in your favourite image editor and the "Mod Tools" will compile the animations/inventoryimage again. You can also tweak the animation files and have them compiled in the next startup of the game.

 

 

 

Spriter Example: Equippable Item

This is the finished product created by Cheerio using the assets uploaded with this post.

 

 

 

Confused? Curious? Feel free to post your questions here and pray that you will get a good answer  ^^

I might expand this tutorial at a later point in time, depending on what questions come up and if people want it. But for now I hope this will help, enjoy your cold coffee  : P

Edited by Malacath
  • Like 22
Link to comment
Share on other sites

@Malacath

Great tutorial! I just didn't get the "colour" parameter for the sample prefab's "fn". It receives TheSim as its parameter (though I don't think that's ever used, since TheSim is a globla variable; usually the fn() is defined as taking no arguments).

*cough* *cough* what are you talking about *cough*

No, srsly, thanks for pointing that out. It was the last (I hope) leftover of the code for the staffs. Since I never used the argument I simply didn't really care. They usually get the colour to specify the animations that are being used.

  • Like 1
Link to comment
Share on other sites

*cough* *cough* what are you talking about *cough*

No, srsly, thanks for pointing that out. It was the last (I hope) leftover of the code for the staffs. Since I never used the argument I simply didn't really care. They usually get the colour to specify the animations that are being used.

There's a small problem i noticed (this may be just me messing up and not a problem in your guide) but, whenever you try to run the game as you said to to test the mod, it doesn't work because of the lack the .tex and .xml files for your item, and it doesn't really say how or where to get these files

 

Note - Even in the finished example, the wand.lua calls for wand.xml and wand.tex, so when i run it it brings up an error because all that's there is wand.png

Edited by Blazingice26
Link to comment
Share on other sites

xml files are text files.  Open up one of the other textures xml file to see what needs inside the one for your wand.tex.   To generate your wand.tex  (which a texture, not text) you need to convert your png image.  simplex has a tool published to do this called ktech.  It should be in the forum downloads

Link to comment
Share on other sites

xml files are text files.  Open up one of the other textures xml file to see what needs inside the one for your wand.tex.   To generate your wand.tex  (which a texture, not text) you need to convert your png image.  simplex has a tool published to do this called ktech.  It should be in the forum downloads

Thanks, i couldn't find a good xml converter and i didn't really have an idea of what a xml file actually was, thanks for pointing me in the right direction

Link to comment
Share on other sites

To clear this up, the crucial part here is, that this tutorial is for people who fulfill one of the two conditions:

1) They work on Windows

2) They know someone who works on Windows

Ass soon as the Tools are ported this is no longer the case and anyone can follow it.

So if you are on Windows you need to download the "Don't Starve Mod Tools" from Steam which automize the steps you are missing. In that regard this tutorial is complete because the DSMT are mentioned as a requirement for the tutorial.

Link to comment
Share on other sites

Edit -- Re-added 

So, i followed all the steps and substituted all the stuff and made the xml and tex files, but whenever  i try to run the mod don't starve just crashes, can someone look at this for me and make sure everythings in order?

(note "friendstaff" is the prefab name) WilsonsFriendWand(Mediafire) (are we allowed to use mediafire links here? it won't let me attach the .rar file to the attachments) I need this fixed as soon as possible because its a bit hard to make a mod without being able to test whether it works or not :/

Edited by Blazingice26
Link to comment
Share on other sites

Edit -- Im gonna move this over to my thread so it doesn't clog up yours

Well, if it's related to this tutorial I would actually prefer if you keep it here (additionally to your own thread if you want it there) so in the event that others have a similiar problem they will get the answer here.

Link to comment
Share on other sites

Well, if it's related to this tutorial I would actually prefer if you keep it here (additionally to your own thread if you want it there) so in the event that others have a similiar problem they will get the answer here.

I think it may bthe .xml files, i can't find a good converter for png -> .xml so i had to convert the png into a .doc and rename it to .xml, since i figured they were pretty much the same file, but feel free to test it and see if its working for you and its just something on my side, although i do think you should include something for converting png to .tex and .xml since the script you give for the "myitem.lua" directly calls for both myitem.tex and myitem.xml and won't work without both in good order.

Edited by Blazingice26
Link to comment
Share on other sites

I think it may bthe .xml files, i can't find a good converter for png -> .xml so i had to convert the png into a .doc and rename it to .xml, since i figured they were pretty much the same file, but feel free to test it and see if its working for you and its just something on my side, although i do think you should include something for converting png to .tex and .xml since the script you give for the "myitem.lua" directly calls for both myitem.tex and myitem.xml and won't work without both in good order.

First off, seronis already told you that *.xml is not an image format, it's a text file. Every image in the *.tex format has an *.xml file besides it that looks like this

<Atlas>    <Texture filename="myitem.tex" />    <Elements>        <Element name="myitem.tex" u1="0" u2="1" v1="0" v2="1" />    </Elements></Atlas>

Where "myitem.tex" is in the same folder as "myitem.xml"

So if you are on Windows you have to download "Don't Starve Mod Tools" from Steam which will automatically create these files if you put the "myitem.png" in the right position, that is the "images" folder in your modfolder.

If you are on Linux or Mac you will have to use ktech to convert the *.png file to a *.tex file and write the *.xml yourself according to the template above.

 

All of this is mentioned in the tutorial except for the template. I will edit it hough so it contains a basic guide for how to do it.

 

So getting back to specifically you: Are you on Windows or not?

Edited by Malacath
Link to comment
Share on other sites

First off, seronis already told you that *.xml is not an image format, it's a text file. Every image in the *.tex format has an *.xml file besides it that looks like this

<Atlas>    <Texture filename="myitem.tex" />    <Elements>        <Element name="myitem.tex" u1="0" u2="1" v1="0" v2="1" />    </Elements></Atlas>

Where "myitem.tex" is in the same folder as "myitem.xml"

So if you are on Windows you have to download "Don't Starve Mod Tools" from Steam which will automatically create these files if you put the "myitem.png" in the right position, that is the "images" folder in your modfolder.

If you are on Linux or Mac you will have to use ktech to convert the *.png file to a *.tex file and write the *.xml yourself according to the template above.

 

All of this is mentioned in the tutorial except for the template. I will edit it hough so it contains a basic guide for how to do it.

 

So getting back to specifically you: Are you on Windows or not?

Windows, 8 Specifically 

Link to comment
Share on other sites

Perfect, I uploaded the OP with a screenshot where you can find the dropdownmenu to "Tools" on Steam. This is where you can find the "Don't Starve Mod Tools" which should make the tutorial work again  ; )

Is there anyway to get it for the standalone version? or can you only get it on steam if you have don't starve? (on steam)

Link to comment
Share on other sites

Is there anyway to get it for the standalone version? or can you only get it on steam if you have don't starve? (on steam)

Oh my god, that's a good question. You can definately install Steam and download the Tools for free, if I'm not mistaken you can even download Don't Starve from Steam if you have the standalone, no promises though.

 

@Cheerio If Blazingice26 has the standalone version and the Mod Tools from Steam will they interplay or will it only work with the Steam version?

Link to comment
Share on other sites

  • Developer

Basically everytime the game starts it looks for the tools so you could download them and then put them in the parent folder of the game and it should work.  The name of the game folder isn't important but the name of the mod tools folder is really important.  Your folders should look like this:

 

/my_programs

    /dont_starve

    /Don't Starve Mod Tools

  • Like 3
Link to comment
Share on other sites

Basically everytime the game starts it looks for the tools so you could download them and then put them in the parent folder of the game and it should work.  The name of the game folder isn't important but the name of the mod tools folder is really important.  Your folders should look like this:

 

/my_programs

    /dont_starve

    /Don't Starve Mod Tools

How can i get the dont starve mod tools without having don't starve on steam? the mod tools aren't on the list of tools i can download If i have to have steam then thats no problem, i can just earn some money raking up the ridiculous amount of leaves on front of our house and buy a key off the humble shop Until then, if someone can use the tools to make the files in the assets folder xml then that would be great since i wont be doing my own art until the coding is complete

 

Sorry i haven't been answering, i've been up all night working on stuff all weekend and completely crashed today

Edited by Blazingice26
Link to comment
Share on other sites

  • Developer

How can i get the dont starve mod tools without having don't starve on steam? the mod tools aren't on the list of tools i can download If i have to have steam then thats no problem, i can just earn some money raking up the ridiculous amount of leaves on front of our house and buy a key off the humble shop Until then, if someone can use the tools to make the files in the assets folder xml then that would be great since i wont be doing my own art until the coding is complete

 

Sorry i haven't been answering, i've been up all night working on stuff all weekend and completely crashed today

Try this link:

 

https://github.com/kleientertainment/ds_mod_tools_win32

Link to comment
Share on other sites

Ok, so I was working on this new weapon mod. I felt the weapon needed to be bigger so I set

up a topic asking how to do that. I was directed here, and I followed the tutorial, but the weapon

is now invisible, swap, ground animation, inventory icon and all. Any idea what's wrong with it?

You're supposed to put the image "swap_logclub.png" into another subfolder called "swap_logclub" as well, this way you create the symbol.

Then you completely skipped the part of naming all things inside Spriter correctly. "entity_000" should be "swap_logclub" and "NewAnimation" is supposed to be named "BUILD". Read the guide again for more information.

Next you didn't change the code to swap the right build. Neither did you change the build and bank of your animations for the object.

So really, read the guide and do the things written there, otherwise it can't work  : P

Link to comment
Share on other sites

Ah, ok. And about not renaming the entities, well, I guess I forgot to on the 15th consecutive try to get it working.

But ok, thanks.

 

EDIT: I did that, and checked, and the animation zips were there, but it was still all invisible in-game.

I checked and the atlas images all had the proper sprite, but everything is still invisible. I can't find anything

in the scripting which would cause everything to be invisible either.

Edited by Soopakoopa
Link to comment
Share on other sites

Ah, ok. And about not renaming the entities, well, I guess I forgot to on the 15th consecutive try to get it working.

But ok, thanks.

 

EDIT: I did that, and checked, and the animation zips were there, but it was still all invisible in-game.

I checked and the atlas images all had the proper sprite, but everything is still invisible. I can't find anything

in the scripting which would cause everything to be invisible either.

Upload the mod again.

Link to comment
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
 Share