[Tutorial] How to add a custom, craftable item


It is rather easy to add a custom item into the Alpha which will be craftable by the carpenter (as it is the only profession in the game at the moment).

Get prepared:

  • Unzip the “stonehearth.smod”-file
  • Create a .png-file which represents the look of your item in the crafting UI
  • Create a .qb-file which represents your item
  • Create a .qb-file which represents an itemized version of your item

Creating the .qb-files will require a Home-, Master- or Stonehearth-Edition of QC.

Relevant References (where to change / add something):

  • Stonehearth >> Mods >> stonehearth >> entities >> furniture ( :one: )
  • Stonehearth >> Mods >> stonehearth >> entities >> professions >> carpenter >> recipes ( :two: )
  • Stonehearth >> Mods >> stonehearth ( :three: )

:one: - Just take an existing folder (item) and use it as a template. You will need to add the .png and the two .qb-files in this folder. The files named “proxy” are including information for the iconized version of your item. Be sure to replace all the references in the .json-files with your file- and folder-names. In the .json-files you can define how the item will be called once it is placed in the world and what will be the description.

:two: - Create a recipe-file with your item name (again use an existing one as a template). Be sure to adjust the references (file- and folder-names) in the recipe-file. Here you can define the text which will be shown in the Crafting UI, the amount of resources required to craft your item and the duration it will take. You also need to add the name of this file into the “recipes.json”-file which you will find in this folder.

:three: - Open the file called “manifest.json” and add the following two lines (after you have replaced the placeholder with the name / folder of your item):

“placeholder” : “file(entities/furniture/placeholder)”,
“placeholder_proxy” : “file(entities/furniture/placeholder/placeholder_proxy.json)”,

Once done, just zip the stonehearth-folder again and rename it to stonehearth.smod. You should be ready to go now.

A detailed tutorial (15 Min.) can be watched here:

Community Mods List
[Mod] Colors Mod by Chimeforest
Where Can I Find My .json files in my game directory?
Paul's Attempts at Qubicle
Can you add new items?
Stonehearth: Almost 3 years in development
Pandemic's Art and Modding Corner! Bringing Pretty Back since 2017!
Voxel Pirate's Tutorials n' Stuff (Overview)
Taking Questions about Mixintos and Overrides

ah good ol’ 6 am topics. thanks this was helpful.


Oh Voxel you darn scurvy pirate :smile: … this can’t be done with qubicle basic can it? Anyways thx for the tutorail its very handy.


Awesome! This will probably help a lot of potential modders. :smiley:


@DragoKen Unfortunately not with QC in the free version. You will either have to have the Master- or Home-Edition… or just wait for next week and buy the Stonehearth Edition which should be available for $11.


@voxel_pirate u sir are a scholar and a gentleman. i had worked out 2/3 of the things, but could not get my head around the last! than you!


I probably will :smiley: but really tempted to splurge a bit on the $40 one since … yeah more gadgets :grin:


… the feature to export into the .obj-format is for sure very nice :wink:.


Oh wow… I didn’t even see that was possible. Here I come, world!


Thanks for this tutorial, both the Video and the instructions are good, can’t wait to see what people add


@voxel_pirate ok ur gona laugh at this one, ive been scratching my head as to why it was not working, and why when the carpenter crafted the item it would not spawn in the world as an icon.

after tearing my head out for hours, i noticed my qb files are only 1kb in size. they were empty… so in all,
can i ask what your export settings are for your qb files?

edit: scratch that i cant export anything as .qb with master edition of qubicle


This settings work for exporting qb files

@voxel_pirate Nice guide. I had found this out already but failed due to typos :blush:. I tried to add a different category, but game crashed. Did you found out what you need for that?


na still did not work, its not the settings its just not working for me, its stupid. i tryed other models as well.


maybe it is typos. I had those too and wondered why it did not work. Everything has to be exact correctly named.


named? as in the file name?


everything. filename too


i have the model named, i have the file named the same, it should just export as sickle.qb, but it exports so fast and is empty when i open it again.


maybe a dumb question, but have you selected the object in qubicle? It needs to be selected before exporting and at the origin (0,0,0). Some objects have the middle of the object at the origin, some have a corner of the box surrounding the object as (0,0,0)


@moondrixx_01 You can see my export settings in the video. They are similar to Miturion’s but I have “Hollow” unchecked but check “Single Object” (as proposed by Tim from Minddesk). Depending on the size of your item the proxy-qb-file could be rather small (mine is 4 kb), however the full-sized qb-file should be significant larger. Can you upload your qb-files somewhere to check them?

I have had the same issue with items not spawning. I could add the item and see it in the crafting UI. My carpenter also crafted it, but once he was finished the item did not spawn. The problem was that I did not add it in the manifest.json. Be sure that you have it in there with the right links to the folders / files. Also that it is included in the redipes.json.

P.S. In worst case invest the 15 minutes to take a look at the video above. There you should see all steps required.


yep every other step is in place EVERY thing is right cheeked it 5 times over. the exact issue ur describing is happening, i have watched the video twice now, its all right, just the qb files r empty. Dropbox - Error