• Adding custom flags to user_settings.json
• How to log from your code

Adding custom flags to user_settings.json

We can add custom config variables to the user_settings.json file for our mod in Lua scripts, regardless of whether we add an option in the UI to change them from within the game or not.

They will appear inside a key from the "mods" section of the user_settings file (the key will be the namespace of our mod).

We can add them programmatically if we need to save the value, but if it's for debugging purposes we can simply write the value manually in the user settings to enable/disable the flag.

  -- Saving the 'max_quantity' property in user settings with a value of 5
  radiant.util.set_config('max_quantity', 5)

To retrieve the value from our code, we'd do:

  local max_qty = radiant.util.get_config('max_quantity', 1)

The value will be read from the mod that the scripts belongs to. If the game can't find the config string, the default value will be returned (the second parameter that we pass, normally a number, string or boolean).

If we need to set or get a config value of a different mod from within our mod, we can use these instead:

  radiant.util.set_global_config('mods.other_mod.config_variable', 'custom_value')
  local auto_loot_enabled = radiant.util.get_global_config('mods.stonehearth.auto_loot', false)

For doing this from a Javascript file, take a look at stonehearth/ui/shell/settings/settings.js:

  _updateGameplayTabPage: function() {
     var self = this;
     radiant.call('radiant:get_config', 'mods.stonehearth')
        .done(function (response) {
           var stonehearthOptions = response['mods.stonehearth'] || {};
           if (stonehearthOptions) {
              self.set('showHearthlingPaths', stonehearthOptions.show_hearthling_paths);
              // More code...
           }
        })
  }

How to log from your code

There are several ways to print text in the stonehearth.log file from our mod's Lua files.

First, at the top of your Lua file, create a logger and give it a unique tag:

  local log = radiant.log.create_logger('tag_name')

To write to the log inside your Lua functions, invoke methods on the logger:

  log:info('hello world')

We have multiple levels of logging. Here they are:

  ALWAYS = 0,
  ERROR = 1,
  WARNING = 3,
  INFO = 5,
  DEBUG = 7,
  DETAIL = 8,
  SPAM = 9

All of these have a corresponding method on the logger:

  log:detail('really fine grained logging information')
  log:error('OMG CRAZY IMPORTANT ERROR!')

You probably figured most of that out on your own. Here's the secret sauce.

To actually show stuff in your log, add a logging block to your user_settings.json (at the same level than your user_id):

  "logging" : {
     "show_console" : true,
     "mods" : {
        "your_mod_namespace" : {
           "log_level" : 1,
           "tag_name" : 5
        }
     }
  },

The show_console flag will pop up a window showing the stonehearth.log at run time when your start the game.

Then we have a "mods" section, listing the different mods by namespace. Inside it we have the different log tags, and optionally a log_level flag, which is the default logging level to apply across the whole mod. For each tag we can define the log level that we want to use.

The idea is if your mod has several different logical features, you initialize a separate logger for each of them, with different tags. Then when you're debugging feature A vs. feature B, you can adjust the logging level in your user settings so your log isn't spammed with information that you don't care about.

Examples:

This will log ONLY log:error('...') entries from loggers created with the tag "feature_a":

  "mods" : {
     "your_mod_namespace" : {
        "feature_a" : 1
     }
  }

This will log all log entries from loggers created with the "feature_b" tag:

  "mods" : {
     "your_mod_namespace" : {
        "feature_b" : 9
     }
  }

And of course this works:

  "mods" : {
     "your_mod_namespace" : {
        "feature_a" : 1
        "feature_b" : 9
     }
  }

For quickly printing text to the stonehearth.log that you know you will remove before shipping your mod, you can also use the print() function:

  print('debugging stuff')
  printf('debugging variables %d and %s', num_times, my_string)

These debug texts from the print() function will be shown preceded by a 'DEBUG' tag in the stonehearth.log, so you should be able to locate them quickly.