Creating 2D assets

The game uses images in different parts of the UI. Many of them were created in Photoshop, but you can use any program to make them.

Image size

For icons and recipe images, we usually take a screenshot with our voxel editor, and maybe add some darker outline to it with an illustration program (6px black with 40%-60% opacity). The size for these images is usually 300x300 pixels, but it can vary (make sure they're square).

Here's how you can take a screenshot in Qubicle 1:

  • Open your QB model and don't touch the camera.

  • Go to the top menu, click on Render, then on 'Render Settings...'

  • Set the resolution to 300x300 in the small text boxes at the right and click OK to apply the changes.

  • In the menu bar that's right above the scene area, click on RES. GATE to enable visualizing the resolution gate.

  • Pan your camera so that the model is inside it, trying to make it as big as possible without going out of the frame but leaving some margin so that the image is balanced. For some models you might want to rotate the view a little too.


  • Now go to the Render menu again, click on 'Render As...' and save your image.

  • You might want to edit it in Photoshop or similar to add the border. Mind that the image has the background transparent, if you save it solid the game would show the background white.

Other voxel editors will have different options for taking screenshots.

Dynamic portraits

For dynamic portraits, such as those for hearthlings and pets (which are taken internally by the game), we need to add some info in the entity's JSON file. This is from rabbit.json, inside its "entity_data" section:

  "stonehearth:portrait": {
     "portrait_types": {
        "headshot": {
           "camera": {
              "pos": [
              "look_at": [
              "fov": 45

We add "stonehearth:portrait" : {}. The information inside is used by portrait_renderer_service.lua. Currently the portraits only have "portrait_types" : { "headshot": {} } but you can customize the portrait you want to display in the UI (see portrait_renderer_service.lua and Javascript files that make use of the portrait service, like citizens.js, show_team_workshop.js, unit_frame.js and select_roster.js).

The properties for the headshot are the position of the camera, the look_at, and fov (field of view, how close or far from the camera we are). You can adjust these values if your entity is too small or too big and the portrait doesn't look good in the unit frame.

Generated icons

The game also auto-generates icons for items for the thought bubbles, and caches them in the saved_objects/generated_icons directory. Some of the topics that hearthlings can chat about don't have a 3D representation, they are passed as a 2D static image that already exists (for example, the weather icons).

These icons are often taken for the iconic form of the entities, because it's the item that the hearthlings have interacted with (by carrying it). They are known to show hollow surfaces where the item had material maps applied, though. If you need to adjust the camera for a generated portrait for the thoughts (sometimes it may clip through the item) use these fields instead for your entity data, and adjust the values until you get the desired result:

  "stonehearth:portrait": {
      "portrait_types": {
         "icon": {
            "center": { "x": 0, "y": 0.3, "z": 0.8 },
            "rotation": { "x": 0, "y": 15, "z": 45 },
            "extra_distance": 0.5,
            "fov": 30,
            "animation": "custom.json",
            "animation_time_ms": 42

Since the icons are cached, you might have to clear the generated_icons folder for the portrait to be taken again.

Static portraits

For portraits for the campaign dialogs, we use static images made with our voxel editor, these are not auto-generated. They range in size from 200x200 pixels to 400x400 pixels, most of them being 300x300 pixels. But it's up to your choice. You can also create your own encounter type that uses a custom UI and custom CSS (Less), which can rescale the image if it's too big or small.

UI icons

You will already have these icons if you copy the existing files from the stonehearth mod, but just in case you want to make them from scratch, here are their sizes:

  • The size of buff icons is 46 x 51 pixels.
  • The size of trait icons is 60 x 40 pixels.
  • The size of job perks icons is 74 x 74 pixels.
  • The size of weather icons is 100 x 100 pixels.
  • The size of start menu icons is 74 x 74 pixels (there are some narrower exceptions).

For the crafting workshop's UI, choose one that's similar to your crafter's theme and edit the images. All the images are in .png so it's easy to edit them. Make sure to use an application that supports transparency.

Same for customizing the rest of UI elements from the game.

Style guide

For hand-made 2D icons we have a style guide, if you want to follow Stonehearth's style.