Particle effects

Cubemitters are the particle effects. For convention, stonehearth's particle effect files (which are just JSON!) have names that end with ".cubemitter.json". This way we can tell them apart from effect files that might have the same name. All the existing cubemitters are located inside the stonehearth\data\horde\particles directory.

You can have several cubemitter tracks for the same effect, if you need to (for example, to have both big and small particles playing at the same time, like the effects for the lamps).

The effect file

Example of a cubemitter track from an effect JSON file:

  "cubemitter": {
     "type" : "cubemitter",
     "start_time" : 0,
     "end_time" : 30,
     "cubemitter": "particles/sparks/hit_spark.json",
     "transforms": {
        "x" : 0,
        "y" : 1.25,
        "z" : 0,
        "rx" : 0,
        "ry" : 0,
        "rz" : 0
     }
  }

These are the fields that we can find in a cubemitter track:

Creating cubemitter files

Now for the contents of our cubemitter JSON file. Remember that you can copy an existing one from stonehearth\data\horde\particles to get started (try changing the values one at a time and see how they affect the particles).

Each cubemitter file has these fields:

iconFor all the following fields of the cubemitter file, assume that the possible values for the "kind" property are "CONSTANT" / "CURVE" / "RANDOM_BETWEEN" / "RANDOM_BETWEEN_CURVES" unless specified otherwise. You can check how to define the "values" field for each of them in this table, although for some fields they might be a little different (such as for colors):

Testing particle effects

There's a quick way to iterate over particle effects without having to restart the game every time.

Add "enable_renderer_file_watcher" : true, to your user_settings.json file, at the same level than the "user_id". This will allow you to view the changes in game every time you save the JSON file of the cubemitter (it might take a while to update depending on the life time of the particles).

So we can start a new game, start our effect using debug tools, edit the JSON file, save it and it will update the effect inside the game, no need to reopen it.

How to create particle effects in SHED

At the time this guide was written, SHED won't be able to detect the effects if they're not inside the directories mentioned above. So make sure you're using the same directory structure than in the stonehearth mod (your_mod_namespace/data/horde/particles).

Go to the Effects Editor, and select the 'Cubemitters' tab. You can right-click on an existing cubemitter, click on 'Clone', select your mod as the target mod and provide a replacement text. Once the tree refreshes you should see your cubemitter listed there, if not, you might need to reload SHED.

When you select your cubemitter file, you should see the JSON in the middle and a web editor at the right:

cloning_cubemitter_file

It's easier to edit in the web editor, since it has curve editors and color pickers, then save it with the blue 'SAVE' button at the top so that the JSON file gets modified, and then save the JSON file too to confirm the changes. Or if you prefer, you can edit the JSON file directly.

Here are some workarounds if the web editor isn't working correctly.

You'll see that many of the fields have a + button at the right to add them or expand them, and an x button to remove them.

When you choose "CURVE" or "RANDOM_BETWEEN_CURVES" in a dropdown, you'll first need to add a curve, then you'll be able to edit it in the curve editor. The way it works is:

curve_editor_color_picker

For the colors, there will be color pickers. Click on them and you'll be able to easily choose a different color, as well as transparency (but remember the rules mentioned above about how to set the fields for transparency).