Mods/LuaConfig

From Minetest Wiki
Jump to: navigation, search
LuaConfig
Blank.png
A mod
Mod Type Misc
Author Prestidigitator
Latest version 1.0
Forum topic 12040
Source code GitHub
Technical name luaconfig

This mod makes it really, really easy for other mods to load Lua-based configuration settings. It's as simple as adding "luaconfig" to your mod's depends.txt and putting this at the top of your init.lua:

local config = luaconfig.loadConfig();

and then optionally (to make settings globally visible):

mymod = { config = config };

This automatically detects the name and path of your mod and loads settings from "config.lua" in your mod directory and/or "mymod_config.lua" in the world directory, allowing the latter to add to or overwrite the former. No errors will be generated if either or both files are missing.

This mod allows simple Lua variable-based configuration settings that almost guarantee that you don't accidentally set global variables from the config files (you can if you REALLY try, but it's difficult). You'll have access to all variables defined from the config files using logic like:

print(config.message);

Contents

Simple Example

Here's a mod that announces to all when a player joins and leaves, and greets the player directly when he/she joins. Keep in mind that the name "mymod" is just an example, and would actually be replaced by the name of your own mod.

-- mymod/init.lua

local config = luaconfig.loadConfig();

local function prepare(message, player)
   return string.gsub(message, "<player>", player:get_player_name());
end;

minetest.register_on_joinplayer(function(player)
   minetest.chat_send_all(
      prepare(config.joinAnnouncement, player));

   minetest.after(
      3.0,
      function()
         minetest.chat_send_player(player:get_player_name(),
                                   prepare(config.greeting, player));
      end);
end);

minetest.register_on_leaveplayer(function(player)
   minetest.chat_send_all(
      prepare(config.leaveAnnouncement, player));
end);

Here is the mod's (default) config file:

-- mymod/config.lua

joinAnnouncement  = "<player> says hello!"
leaveAnnouncement = "<player> says goodbye!"
greeting          = "Hello <player>, and welcome"

And here's a world-specific config file for world "myworld":

-- myworld/mymod_config.lua

joinAnnouncement  = "<player> saunters in and says 'Howdy!'"
leaveAnnouncement = "<player> tips his hat and says 'Adiós, amigos!'"
greeting          = string.gsub(greeting, "Hello", "Howdy") .. " to myworld!"

Advanced Use/Examples

The luaconfig.loadConfig() function takes two optional parameters, for convenience. The first is the name of your module. It's auto-detected if missing or nil, but passing it in is helpful if you don't call the function right away (e.g. if you reload some settings periodically without restarting the server), as there is no way to auto-detect what mod you are in once you get to callbacks. So you can do:

local MOD_NAME = minetest.get_current_modname();
-- and later, from a callback...
local config = luaconfig.loadConfig(MOD_NAME);

The second optional parameter is an existing table to use instead of creating a new one. This same table is returned by the function, but can be safely ignored. This is useful if you want to set some defaults right from your mod code before loading settings from the config files:

local config = { greeting = "What, you're back?!" };
luaconfig.loadConfig(nil, config);
-- Use config.greeting as usual

If this second parameter is missing or nil, the luaconfig.loadConfig() function looks for a globally visible table named after your module, and a 'config' table inside that. If it finds this, it uses it. Otherwise it creates a new table and returns it. So doing this works just fine:

mymod = {};
mymod.config = {};
mymod.config.greeting = "What, you're back?!";

luaconfig.loadConfig();
-- Use mymod.config.greeting as usual

Of course, if your mod uses a table called 'mymod.config' already, you can just pass in an empty table and/or retrieve it back from the function to avoid conflicts:

local settings = luaconfig.loadConfig(nil, {});
-- or
mymod = { settings = {} };
luaconfig.loadConfig(nil, mymod.settings);

Note that the "config.lua" file in the mod directory is loaded first, and then the "<modName>_config.lua" file from the world directory. The world-specific file can thus access and modify settings made from the mod file, and both can access and modify settings that your mod code makes before calling luaconfig.loadConfig(). For more complicated (table-based) settings, you might want to practice writing the configuration like:

complexSettings = complexSettings or {};
complexSettings.name = "Freeway";
complexSettings.length = 16;
complexSettings.units = "km";

so that it is easy to copy/paste, comment, and override individual settings later from other files (or the mod code), whether or not the tables or individual settings already exist:

complexSettings = complexSettings or {};
-- default complexSettings.name
complexSettings.length = 20;
-- default complexSettings.units

At this time there is NO built-in support for (re-)writing the config files from within the game. This is by design. These config files contain executable Lua code, and it's not usually advisable to auto-generate that. If you really want to you can implement something using, for example, io.open(), file:write(), and some custom serialization (e.g. making use of minetest.serialize() for each table entry). This is left as an exercise for brave and desperate readers.

Mod Information

Require Minetest Version: (probably any; tested in 0.4.12)

Dependencies: (none)

Soft Dependencies: (none)

Craft Recipes: (none)

API: luaconfig.loadConfig([modName, [configTable]])

Change History

Version 1.0

  • Released 2015-05-03
  • First working version.

Copyright and Licensing

All content, including documentation and source code, are original content created by the mod author and are licensed under WTFPL.

Author: Prestidigitator

License: WTFPL

External Links