I’ve wanted to get into Stonehearth modding for a while, and I’ve probably read every tutorial ever posted on the Discourse. But… modding’s changed a lot - especially in A18 - and I’m not sure what resources are still up to date. Also, I have no clue where to begin. The last time I tried modding [way back in "version" : 1] I made a few Qubicle models, tried to make one a craftable item, ran into a lot of problems, had someone on the Discourse fix my mod, and then gave up.
So I have a few general questions before I begin. Nothing specific yet.
What exactly are mixins/mixintos/overrides? How do you make them and how do they work? I thought I understood them earlier, but they seem to have changed a bit as the modding API has.
Also, how does the manifest work? This has always been the most confusing part for me.
Are there any tutorials/example mods that are up to date?
How does the UI work? I get that it’s formatted HTML with JS controlling the behavior and links to Lua somewhere, but how is it all tied together? (I don’t need to know exactly, but I want to get my head around how Stonehearth works before I dive in.)
The manifest is the first and only thing the game will read inside any folder or .smod file in the mod folder. It is the starting point to everything. There you list everything needed in your mod, the game will read it and now will know where everything is in your mod.
One important section of a manifest (although completely optional) is the “alias” section. There, you create “nicknames” for your most used files. Ex.instead of adding the complete path (like /mymod/path/file.json) to whenever I need that file, I can type an alias in that section and use it like mymod:myalias. You will see in the default stonehearth mod things like stonehearth:tree:oak or stonehearth:food:berry. Those are alias of real files in the mod. It is just to help and make things easier for us modders. It is completely possible to use anything without alias.
Then there is the “mixinto” section. It is actually simple. On the left side there is a file (or alias of a file) that you want to change. On the right side of that line you put the file (or its alias) with the changes you want. The game will add the contents of your file to the original file. In case there is overlaps, it will replace the old values with the new from your file.
In my case creating biomes, one important file for me is the biome index file, it lists all biomes the game has, to show in the biome picker. So I create another file similar to the original, but in it I put a line with my biome. Using the mixinto, my content gets added to the original. But only if my name is different, if I try to add another named temperate, it will replace the one in the original. That’s basically how mixinto works.
Mixins are like templates files. If you need to copy the same thing over multiple files, you can put it all in a “template file”, then when you need its contents, you add it as a mixin, in another file. A good example is with the trees. The game has a file with everything all trees have in common (they all have an axe symbol when you harvest it and the scale of its models are always full scale). Then all the trees files has at the start a line like “mixins”: “stonehearth:mixins:tree” . This is just like a copy and paste. Everything in that mixin ends up in the file you added that line.
Overrides fully replaces one file by another. So if I override the oak file, every time the game calls it (when generating a world or when a player plants it) it will instead call my file, the one that overrides it. One example is a mod adding a winter theme to the game. It should override all the trees with a snow version and that’s it, when the game generates a world, it will be all snow trees.
One good place to start is to download the startermod_basic. And mess with its contents.
While aliases are not strictly necessary, it seems like poor practice to ignore them. There are many good reasons to use them and no good reasons not to.
You don’t have to remember the exact file path every time you need to refer to it in your files.
If you change the file path of a file, then you only need to change the path in the manifest (instead of everywhere it is used).
With an alias, you can test an item with the item dropper in the debugtools mod. It is probably not strictly necessary for a MicroWorld, but it couldn’t hurt there either.
It helps you keep track of all the things in your mod if they are all “visible” in your manifest. If they are only loaded through secondary or tertiary file links, its easy to lose track of them.
You won’t be the only one ever looking at your mod! Using aliases improves readability for everyone, making it easier for others to help with problems or build on your work.
Would anyone be interested in writing like… an Alpha-18 continuously updating “how to mod” guide with me?
Maybe different people covering different sections? Organize it into “Chapters”
Chapter 1 would be a broad introduction into modding similar to what @BrunoSupremo just gave,
Chapter 2 a simple adding in a new entity in-game(probably an item).
Chapter 3 adding in additional recipes to make said entity via an existing crafter,
Chapter 4 adding in additional drops/behaviors to existing things(mining, enemy loot, etc)
Chapter 5 adding in additional classes broadly
Chapter 6 working with crafter classes
Chapter 7 working with combat classes
Chapter 8 adding in commands/new behavior from scratch
Chapter 9 adding in new UI windows
Chapter 10 modifying existing biomes.
Chapter 11 adding in a new biome from scratch
Chapter 12 ???
If anyone would be interested in making a step-by-step video/text guide of this let me know, I have some spare time coming up soon and I really want to help “open the doors” to more people modding. At the moment it just seems like a lot of fragments of information to go off of, but a seriously step-by-step guide made and managed by a collaboration of current modders would probably make people feel a lot more willing to give it a shot.
I already thought about doing a complete explanation on biomes, going line by line, but I lack time. Although there is a lot of material around the discourse where I helped with explanations on specific items of the biome generation. Glueing all together would already make an extensive guide on that topic.
I guess the hardest part (to modding) is the starting knowledge, after understanding the basic mechanics of the manifest, mixintos, etc. it is just a matter of actually starting the mod.
Except if you need to venture into art, UI or .lua files, then there are extra steps to learn.
What are mixins, mixintos and overrides? There is an article about this in the dev blog, but it is quite old now. There is also this, which is also pretty old and may be out of date.
How do the coordinate systems in stonehearth work? I have a tutorial/reference on this.
After all these basics, then we can have links to a bunch of tutorials that expand on that information. For instance, my tutorial on Adding Mining Resources needs knowledge of most of those topics above before you can really understand it comfortably.
I’d like to do an “intro to modding” almost like a prologue to this guide to actually mod stuff. In that intro it’d discuss what you need to get started, what are some basics you need to know etc. It would also go into the pros and cons of different software you can use(modeling/text editors)
Then actual split up “chapter” by “chapter” pieces that go in depth on the subject preferably written by someone who has experience in said area or even multiple people who have experience.
Then you can have the “table of contents” post that has hyperlinks to each section of the entire guide. So like the original author would make a post then make like 16 replies and all the top comments on the page would be reserved to put in these sections.
EDIT: Also the reason I ask multiple people if they want to help make 1 ‘go-to-’ universal guide is because it’d be a lot easier to find 1 Table of Contents of a how-to-all guide of modding and go to the section you want rather than jumping from a lot of different guides here and there putting the pieces together.
Also it saves from an overlap/mutliple people explaining the same subjects and would instead be multiple perspectives/input to cover 1 topic more broadly.
Additionally since there’s a few things that can be done in multiple ways showing 2 ways to accomplish 1 task and saying either way is okay to use would result in less confusion than 2 different sources saying “here’s how you do it”.
Idk, if anyone’s interested in making 1 big guide that would cover all aspects of modding and sort them into a variaty of easy to read sections so people can find what they need let me know.
And similar to what you’re talking about @Tuhalu we could have at the top of the section “Please read sections 4, 5 and 7 before reading this section” or something so they know what topics they should know before attempting to say… make a biome, or an entire event campaign.
I like the idea. We can also make the pinned topic a wiki post, so anyone can edit it and add links to more resources or mark links as outdated if they reference something that has changed recently.
There is the tools part (the first items on Tuhalu’s list) which could explain whatever tools you might want to use depending on what you’re going to mod, and then the modding part which should start with explaining the manifest, etc.
Now that I think, there’s also SHED, which adds another way to do some things, but it’s not finished…
I’m in favor of text tutorials (with pictures when needed), although sometimes they can be quite a wall of text
But they are easier to update than videotutorials.
It’d be nice to make a big text tutorial first and have the video tutorial actually following the text tutorial(even if the person doing it knows what they’re doing) just to show reference material to what they are doing.
Perhaps every… 2 versions of Stonehearth or so it’d need to be updated.
Still a big workload, but it’d be easier to accomplish with a community working towards it.
lol, I could go into the very fundamentals: first we may need to understand what is “modding” better.
Just for fun…
Basically, I’ll call anything that “modifies” some vanilla version of something as a “mod”. the exact meaning of vanilla though, can be vague.
There are various levels of modding, which I categorize by the types of modifications:
Modding 101: in-place modification. This simply modifies some properties of existing parts of “vanilla”, without creating any content independent enough to be considered new. This requires the least amount of knowledge. Sometimes, even without knowledge, you can just change things to test things out and derive the associated relation/behavior.
Modding 201: replacement. This replaces some existing part of “vanilla”. Knowledge of the thing being replaced is required. But knowledge of how the vanilla framework system work to “link up” that thing being replaced is not. E.g. say I know the model file of poyo. I can easily replace it with another model file of same format. BUT: I won’t know exactly how the game engine will know that it has to read the file (iow, I don’t have enough knowledge to add another creature)
Modding 301: addition. Other than just knowledge of the part being replaced, you know the knowledge of how the system/framework links up that part, so you also gained the knowledge to add new things in addition to existing stuff (and link it up propertly so it appears in-game)
Modding master class: engine extension. usually the ultimate level of modding. It was two forms: a mod-in-engine form and a mod-in-mod form:
mod-in-engine. You know enough of the game engine and how it works that you can actually change part of the behavior (which can be intended or unintended by the engine) and possibly extend some functions/framework similar to levels of the developers (e.g. extend engine api).
mod-in-mod. You make use of the vanilla modding framework to build your own modding framework, which allows other people to write “mods” (for your modded framework). Your framework will be responsible for processing and plugging those “mods” into the actual game engine.
Disclaimer: I just made this up in 5 minutes of typing. don’t take it too seriously!
EDIT: One suggested approach for people who wants to start out modding in a simpler manner:
Simple approach to start modding
Make a backup copy of stonehearth.smod in the /mods folder and don’t ever change it.
rename stonehearth.smod (NOT THE BACKUP) to stonehearth.zip
extract all contents into the current folder. It should appear as a “stonehearth” subfolder within the mods folder.
Go in and try viewing and fiddling with whatever you want inside that folder. Just be careful to remember what you did in case the game could not start due to your last changes.
After you figured out what you wanted to change, NOW, learn the proper way of packaging a mod so that it is non-destructive. Basically, a mod is like a set of instructions to apply all the changes that you did over to the contents of “stonehearth” folder.
After you learn and repackage your changes into a proper mod, delete (or move to elsewhere) the changed “stonehearth” folder, and restore “stonehearth.smod” (or the extracted stonehearth folder) to original and run the game to see if it behaves the same.
From here on, since you now know the non-destructive way of modding, you should use the proper modding method.
BUT, sometimes, (lazy) me would still want to change things directly in stonehearth to test/explore stuff quickly without having to put together a new mod to do it.
The advantage of this approach is that we don’t have to learn the mod packaging part until we actually have some mod content we want. Well, at least it seems more approachable to me. For a “proper” approach, would still be good to start knowing mod packaging part before you mod.
I’d be willing to do a video detailing the insides of a mod. Maybe other people can then handle other parts of it.
Maybe you can structure it like this:
Volume 1: Items and the basics.
Episode 1: the tips and tricks of the trade.
Episode 2: A beginners guide to the inner workings of a mod.
Episode 3: Going through the process of adding a new item.
Episode 4: The wondrous world of components, and what you can do with them.
Episode 5: …
…
Volume 2: Classes
Volume 3: …
I’d be willing to do episode 2. I do not feel I know all the tips and tricks to make a good and comprehensive Episode 1. But I’d be willing to do episode 2, touring all the important parts of a mod that you need to know to add an item, (where the item sits, where it is catalogued, where recipes are dealth with), and how to read .json, basically all the things you need to know to not freak out and instead know what you are looking at when you look inside a mod.
No promises for the very near future, there are two exams in the next two weeks I need to pay attention to, but maybe right after that I can find time for it.
