[Tutorial] Adding mining resources

##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!

19 Likes

And this is my night gone now. Thanks!

1 Like

Hahaha! This is what happens when I get my espresso machine running again!

Let me know how it goes

2 Likes

I’ll be able to get some ancient tree roots that have been left inside the stone :smiley:

1 Like

If you’d like them to drop useable wood, you can spare yourself coding in a new resource and just set the tree_root_vein to drop “stonehearth:resources:wood” in the ‘mine_loot.json’.

Of course, that wouldn’t be as cool as a new wood resource… petrified wood maybe?

The entire “rock” section of code can be omitted as well, unless you want your miners scratching their heads when they randomly mine out some wood!

2 Likes

wow, brilliant stuff @phector2004! even @Geoffers747 could follow this! :smile:

thanks for taking the time to compile this tutorial! :+1:

5 Likes

I’m working on adding some marble for my columns mod and using this tutorial to help me along the way. This point is no longer absolutely true. I’ve got my marble mineable without using a comma at the end. The game engine must handle that all on its own now. There may be some cases where it is still true, but I haven’t come across them yet.

2 Likes

thanks so much for compiling this @phector2004, its really helpful.

1 Like

Got my vein done :smile:
Thanks for this tutorial.

As an aside, I’ve got a theory on how weight works now but I’d love it to be clarified, maybe by @sdee?
I think the total weights of all outcomes are summed and each individual weight is given a chance by weight/weightSum. This would mean not having to worry about how high or low the absolute weights go as its all relative.

3 Likes

That’s the way I read it as well. Which is why when they want a chance for nothing to happen (or for a loot drop to be nothing), they’ll add a weight for null event/item.

2 Likes

Glad to have helped!

That seems about right, I think in my earlier tests setting weights for the vein to 100 for both nothing and the resource yielded a lot of crystal (approx 50% yield). I think its beneficial when adding in custom resources as you aren’t replacing the chance to drop nothing with your new resource.

1 Like

@capotzalco, lovely tutorial! Making sure @albert sees it. :slight_smile:

You absolutely surmise correctly. The weights in loot tables are relative to the total weight of the entire loot table. That way, we can keep adding stuff to the loot table and not have to worry about everything adding up to 100.

You can think of weights as like lottery tickets. The weight you have is the # of tickets you have (or partial tickets.) Your chances of getting drawn depend on the # of tickets in the lottery.

3 Likes

Nice analogy, and a thumbs up from a Mathematician :smiley:

3 Likes

I must renew this

How can i add the selectable stone in the vein to see the tooltip of my_vein
i did all the json work but i cant select a stone in my_vein so where is the reference to the manifest entries like this "terrain:ui:coal_block" : "file(entities/terrain/ui/coal_block)", im searching for hours now but i can`t figure out my problem

my_vein appears, is minable everything is ok but no tooltip

The list of items that can be highlighted in that way is hardcoded into a lua file. Specifically, it’s in stonehearth/services/client/terrain_highlight/terrain_highlight_service.luac. Overriding lua files is possible, but generally not a good idea.

I live in hope that one of the guys from Radiant ( @Albert? @sdee?) will extract the relevant array into a json file so that we can mixinto that instead of living dangerously with overrides.

1 Like

thank you tuhalu.
i don`t like overrides and work around them even if that kills some fine tuning of my mod)
so my_vein must do without it

1 Like

Indeed. Added a feature request for this. Thanks!

4 Likes

@Tuhalu - Just made the change for the next patch. Thanks for bringing this to my attention!

7 Likes

Sweet. I imagine there will be a few mods that are waiting for this to be available :smile:

2 Likes

Thanks albert this will bring my mod to more detail life

1 Like