178 lines
6.1 KiB
Plaintext
178 lines
6.1 KiB
Plaintext
LuaConfig Minetet Mod
|
|
=====================
|
|
|
|
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);
|
|
|
|
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]])
|
|
|
|
Git Repo: https://github.com/prestidigitator/minetest-mod-luaconfig
|
|
|
|
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 (as registered on forum.minetest.net)
|
|
License: WTFPL
|