##Part 1: The randomly mined resource:
###Step 1: Start off by creating a resource.
A good starting-point tutorial for adding new items can be found here:
For this tutorial’s sake, here’s an example resource, ‘/my_mod/entities/resources/MY_RESOURCE/MY_RESOURCE.json’ :
{
"mixins": "stonehearth:mixins:item_properties",
"type": "entity",
"components": {
"item": {
"category": "resources",
"stacks": 40
},
"stonehearth:material" : {
"tags" : "gold ore resource"
},
"model_variants": {
"default": {
"models": [
"file(MY_RESOURCE.qb)"
]
}
},
"unit_info": {
"name": "MY RESOURCE",
"description": "DESCRIPTION OF MY RESOURCE.",
"icon" : "file(MY_RESOURCE.png)"
}
},
"entity_data" : {
"stonehearth:net_worth" : {
"value_in_gold" : 20,
"rarity" : "common",
"shop_info" : {
"buyable" : true,
"sellable" : true,
"shopkeeper_level" : 1,
"shopkeeper_type" : "caravan"
}
}
}
}
Replace ‘MY_RESOURCE’ with your resource name. You can play around with the ‘value_in_gold’ value and the ‘tags’ tags to your heart’s content. Make sure you have a valid .qb and .png to represent this entity and you’ll want to add it to your mod’s manifest. (See bottom of this post if confused!)
###Step 2: Mixin’ in your resource with a ‘mixinto’
Create a new folder and .json for your mining mixin, e.g. ‘/my_mod/mixins/mine_loot.json’
This will be merged onto the mining loot table, adding your resource as a drop option when mining rock. Here’s a code example to work from:
{
"rock" : {
"items" : [
{"uri" : "file(/entities/resources/MY_RESOURCE/MY_RESOURCE.json)", "weight" : 0.025 },
]
}
}
N.B. You absolutely need to have the comma after the curly bracket in this file. The way mixins work is by adding your code before the original code.
The weight value will affect how commonly your resource will be dug up. 0.025 is the value found for gold - quite rare. You can find other values in your ‘/mods/stonehearth/services/server/mining/mining_loot_table.json’, the file we’ll be mixing in to.
You can also replace “rock” with any type of mineable block:
"grass"
"dirt"
"rock"
"coal"
"*_ore" (iron / silver / copper / tin / gold)
The weight value will likely need to be raised a lot for other block types (in the 10-100 range).
###Step 3: The manifest
If you don’t have one already, create ‘manifest.json’ in your mod’s main folder. All that’s required here are two lines of code, an alias for your resource and a mixinto for your loot table - add these where appropriate in your manifest.
Here’s an example, ‘no frills’ manifest:
{
"info" : {
"name" : "MY_MOD",
"version" : 1
},
"aliases" : {
"resources:MY_RESOURCE" : "file(entities/resources/MY_RESOURCE/MY_RESOURCE.json)"
},
"mixintos" : {
"/stonehearth/services/server/mining/mining_loot_tables.json" : "file(mixins/mine_loot.json)"
}
}
Make sure that you don’t put your mixinto code under “aliases” but rather into “mixintos” if you have other stuff in your manifest.
###Step 4: Mine away!
Hope this works out for you. It’s an easy enough mod.
##Part 2: The veiny route
So let’s say you’d like to give the player the occasional ‘jackpot’ of your resource. Or you’d like your resource to be exceptionally rare unless the player lucks out and spawns near / finds a vein of it.
Veins are slightly more complicated to code. The vein itself is a game ‘scenario’, appearing randomly underground within rock. It’ll require some scouting to discover veins peeking out from the cliffside as these are invisible until seen by a hearthling! (I spent 1 hour scouting maps, thinking my code was broken and trying to debug it because of this…)
Before you begin, you’ll need a resource to drop. See Part I for more info.
###Step 1: Creating the vein
Create a new vein scenario, ‘/my_mod/scenarios/static/terrain/MY_RESOURCE_vein.json’
This will be the data file that describes your vein:
{
"mixins" : "/stonehearth/scenarios/static/terrain/ore_vein/ore_vein.json",
"name" : "MY_RESOURCE_vein",
"kind" : "MY_RESOURCE",
"weight" : 40,
"data" : {
"vein_radius" : 1,
"mother_lode_radius_min" : 2,
"mother_lode_radius_max" : 3
}
}
You can play around with the weight and data values. It’s a good idea to set the weight very high when testing - I had mine at 400 - to make sure nearly every vein will contain your resource until you’re satisfied with it.
Here’s a list of other data parameters you can edit through this file:
"num_veins_min" : 2,
"num_veins_max" : 4,
"vein_length_min" : 44,
"vein_length_max" : 72,
"vein_radius" : 2,
"mother_lode_radius_min" : 3,
"mother_lode_radius_max" : 5
These are the default values from the ore_vein.json. I haven’t experimented with them at all, though.
###Step 2: The Scenario Index
Remember mixintos? You’re going to have to create another mixin to add this to the index of scenarios the game will run.
Here’s an example file, ‘/my_mod/mixins/scenario_index.json’:
{
"static" : {
"scenarios" : [
"/MY_MOD/scenarios/static/terrain/MY_RESOURCE_vein.json",
]
}
}
###Step 3: Creating your resource’s world blocks
Looking back at step 1, there was a resource ‘kind’ that you specified in the vein scenario. This is the type of block that the vein will be made of. Let’s have a look at how to make that block by mixing it into stonehearth’s terrain_blocks.json.
‘/my_mod/mixins/terrain_blocks.json’
{
"block_types" : {
"MY_RESOURCE" : { "tag" : 480, "color" : "#ff1337", "kind" : "MY_RESOURCE" }
}
}
Here, the tag value should be different from the values in the original file (‘/stonehearth/data/terrain/terrain_blocks.json’). Color can be changed with a hex colour code. You can google ‘color picker’ to find a few online that’ll give you these codes.
###Step 4: Modifying the Loot Tables
I’m assuming you’d like to get your resource out of these veins - this requires adding a new section to the game’s mining loot table. If you haven’t looked at part one, create a new .json file, otherwise modify ‘/my_mod/mixins/mine_loot.json’:
{
"MY_RESOURCE" : {
"num_rolls" : 1,
"items" : [
{ "uri" : "", "weight" : 100 },
{ "uri" : "MY_MOD:resources:MY_RESOURCE", "weight" : 20 }
]
},
"rock" : {
"items" : [
{"uri" : "MY_MOD:resources:MY_RESOURCE", "weight" : 0.025 },
]
}
}
Creating this file / adding the ‘MY_RESOURCE’ bit to your previous .json will specify the outcome of mining your new world blocks.
You can change the value of ‘num_rolls’ but I don’t know how that affects the outcome. What’s important here is the weight values. The first one (“uri” : “”, “weight” : 100) specifies how often nothing will drop when you mine a block, while the second one (**…**MY_RESOURCE", “weight” : 20) specifies how often your resource will drop when the block is mined. Typically, these are 100:25 for most ores.
###Step 5: Finalising the manifest
Taking the ‘no frills’ manifest example from above, you will need to add in the mixintos to incorporate your files into stonehearth’s vein files. There are only two mixinto lines to be added:
{
"info" : {
"name" : "MY_MOD",
"version" : 1
},
"aliases" : {
"resources:MY_RESOURCE" : "file(entities/resources/MY_RESOURCE/MY_RESOURCE.json)"
},
"mixintos" : {
"/stonehearth/services/server/mining/mining_loot_tables.json" : "file(mixins/mine_loot.json)",
"/stonehearth/scenarios/scenario_index.json" : "file(mixins/scenario_index.json)",
"/stonehearth/data/terrain/terrain_blocks.json" : "file(mixins/terrain_blocks.json)"
}
}
Don’t forget the commas between entries! You can check your .jsons through JSONLint ( www.jsonlint.com ) to check that they’re valid.
###Step 5: Testing
Assuming you’ve set the weight of your veins to be quite high (as discussed in Step 1), you should see them in the cliffside when you start a new game and explore. Hopefully the drop rate is to your liking as well, at which point you’re ready to set the vein weight back to something reasonable.
Happy modding!
