ModularLua 0.5.1 - making Lua easier in Wesnoth

[melinath]

ModularLua 0.5.1 Features

Dialog creation

With Wesnoth's built-in dialog creation, there is a lot of flexibility. However, there's also a lot of boilerplate and room for mistakes, making even simple dialogs a pain and a half to set up. With ModularLua, you simply input a quick lua table representing the dialog, and it does the rest for you.

With Wesnoth:

Code: Select all

local helper = wesnoth.require "lua/helper.lua"
local T = helper.set_wml_tag_metatable {}

dialog = {
    T.tooltip{id="tooltip_large"},
    T.helptip{id="tooltip_large"},
    T.grid{
        T.row{
            T.column{
                horizontal_grow = true,
                T.label{
                    label="shell"
                }
            }
        },
        T.row{
            T.column{
                T.grid{
                    T.row{
                        T.column{
                            T.label{
                                label="egg"
                            }
                        }
                    },
                    T.row{
                        T.column{
                            T.label{
                                label="chicken"
                            }
                        }
                    }
                }
            }
        }
    }
}

wesnoth.show_dialog(dialog)

With ModularLua:

Code: Select all

local dialog = modular.require("dialog")
local d = dialog.create({widget="label", label="shell"}, {{widget="label", label="egg"}, {widget="label", label="chicken"}})
d:display()

Event registration

Registering custom event handlers with Lua in Wesnoth involves overloading the wesnoth.game_events.on_event handler. You have to either overload it every time that you want to register a new event, or you have to have one central overload with a mess of if/then statements checking what the current event is. Again, a lot of boilerplate. ModularLua provides an event registry which maps event names to lists of functions to run for that event, making event handlers simple.

With Wesnoth:

Code: Select all

local game_events = wesnoth.game_events
local old_on_event = game_events.on_event
function game_events.on_event(name)
    if name == "prestart" then
        <do_something>
    elseif name == "turn 3" or name == "turn 5" then
        <do_something_else>
    end
    if old_on_event ~= nil then old_on_event(name) end
end

With ModularLua:

Code: Select all

local events = modular.require("events")
events.register("prestart", function()
    <do_something>
end)

local function something_else()
    <do_something_else>
end
events.register("turn 3", something_else)
events.register("turn 5", something_else)

Pango markup generation

Generating pango markup is one of the more esoteric tasks in LuaWML. It looks like HTML, almost. But there's no way to easily generate the markup. It always has to be hand-crafted. This is mostly a concern when it comes to things which aren't easy to remember, like the bullet entity and text colors. ModularLua provides helper functions which wrap arbitrarily long lists of strings in appropriate markup.

Note: The markup library is geared more towards automatic pango generation. For longer, hard-coded text, you're probably better off just writing it by hand.

With Wesnoth:

Code: Select all

-- Compare to data/lua/wml/objectives.lua
local function color_prefix(r, g, b)
	return string.format('<span foreground="#%02x%02x%02x">', r, g, b)
end

local bullet = "&#8226; "
local win_string = "Victory"
local win_objective = "Kill the beast!"
local turn_counter = 5
local win_objectives = color_prefix(0, 255, 0) .. bullet .. win_objective .. turn_counter .. "</span>" .. "\n"
local objectives = "<big>" .. win_string .. "</big>\n" .. win_objectives

With ModularLua:

Code: Select all

local m = modular.require("markup")
local win_string = "Victory"
local win_objective = "Kill the beast!"
local turn_counter = 5
local win_objectives = m.color(0, 255, 0, m.bullet, win_objective, turn_counter) .. "\n"
local objectives = m.concat(m.big(win_string), "\n", win_objectives)

Scenario-level tag registration

This one's a little more abstract, since there's more than one way to do it - but if you ever tried this, I think you'll appreciate the difference that ModularLua makes. This code will allow [tag_name] as a scenario-level tag, will persist the tag across save/load cycles, and will allow the use of [tag_name] as an action tag to dynamically add new [tag_name] information from inside events.

With ModularLua:

Code: Select all

local events = modular.require("events")
local my_new_tag = events.tag:new("tag_name")

By default, this tag will only store the configuration that was originally passed into it. You can add more behavior by overriding the init method of your new tag.

Overriding init:

Code: Select all

-- This tag will output the "message" attribute of its WML configuration table using wesnoth.message.
local events = modular.require("events")
local wesnoth_message_tag = events.tag:new("wesnoth_message_tag", {
    init = function(cls, cfg)
        local o = cls:get_parent().init(cls, cfg)
        if cfg.message ~= nil then
            wesnoth.message(tostring(cfg.message))
        end
    end
})

And more!

ModularLua cleans your dishes! Feeds your cat! Jumps up and down on your bed for you! Well, not really... but there are a lot of other things it does for you. Read the code to find out what. There is documentation in the code, though it's more complete in some places than in others. Also feel free to catch me on IRC in one of the #wesnoth channels if you have any questions.

Contributing
If you want to contribute, feel free to fork my repository on Github.

Bug reports/Feature Requests
I know that people generally like to put bug reports and feature requests in the forum, but it would be very helpful for me if you post them on Github so that I can keep track of them easier. To put it another way: I'll be less likely to forget!

[Anonymissimus]

As a general comment - why do you set up and use your own repository ? The wesnoth umc repository is basically exactly the same as what you have there.
In case you need time for your real life or whatever someone else could keep your projects alive. And one can learn from the other coders.

(Ah ok, you seem to have non-wesnoth related stuff there, while the umc repo is no general purpose repository. Yet for wesnoth stuff it would make more sense...)

[melinath]

That's a fair question. There's a couple things going on here:

• Github is prettier than the Wesnoth-umc-dev
• Github uses git, which I know how to use, rather than svn, which I know how to check out repositories with.
• Github lets anyone who's interested make an account and fork the repository, rather than requiring that in addition you apply to be able to fork. (Of course the application for umc dev isn't hard core or anything, but it's another step.) So even if I need time in my life, other coders will still be able to carry the project on.
• I find the idea of having a single repository for multiple projects very strange. (Though I am willing to accept that this may be that I am just lacking in experience of one kind or another.)
• My impression is that UMC-dev has a single repository that everyone edits, and that the edits are immediately accepted. I prefer the model of forks and branches which are later merged together.
• Did I mention that github is pretty? I mean, it's gorgeous! Best feature (I think) is the network graphs, which show you all the branches, merges and commits for every user who has forked the repository.
• Also (part of being pretty) it's very user-friendly.

<secret_thoughts>Hmm... you know, it might be nice to have a umc-dev user on github that could fork all projects to make sure that a record of them is maintained.</secret_thoughts>

Edit:: Also, having just made my sourceforge account - it wants to know my job title and "number of employees", which I just find bizarre and unnecessarily complicated.

[melinath]

ModularLua 0.5
I've uploaded v0.5 of ModularLua to the add-on server. Along with various bugfixes, it adds the following new features:

• Added modular.dofile to match modular.require
• Added inspection and debug modules that make it easy to look at lua and wml objects.
• Added a debug shell which, thanks to recent work by Exasperation, can include a working shell history (unlike the shell posted here).

[melinath]

ModularLua 0.5.1

Version 0.5.1 of ModularLua is up on the add-on server. I came back from a hiatus and discovered I was getting some pretty silly errors. These have been corrected, along with some enhancements and improved event documentation. The full changelog is:

0.5.1
=====

* events.register now takes a single event name as its first argument and a
function as its second argument.
* scenario-level tags created with the events framework are now guaranteed to be
processed by the framwork in the same order in which they were registered.
* small bugfixes and typo corrections.
* improved documentation of the events module.