Sandbox/GUI/Getting Started

So, it looks like I can't exclude this page/section from the search engine as I had hoped. I wanted to put this in a sandbox so that it wouldn't be published without some proper review. I guess for now

DON'T TRUST ANYTHING YOU READ HERE

This guide is designed to help you get a simple Wesnoth GUI, implemented in lua, up and running while describing the basic building blocks along the way. Some would find creating a GUI in part or in full using WML simpler to follow, and those alternatives are available, but we're using lua.

For example purposes, we'll create a directory in our campaign directory called lua containing a file called gui_tutorial.lua, and add a command in the prestart event for a scenario which will create a right-click menu option to invoke our new GUI. Of course there are other methods, but this one will get us started. After all, we really just want to get something up on the screen ASAP, right?

In our prestart event, we create a simple menu item, which calls lua with one command that calls the function most_basic_gui() which is found in gui_tutorial.lua:

        [set_menu_item]
            id=most_basic_gui
            description="Our first GUI"
            [command]
                [lua]
                    code=<<
                        wesnoth.require("~add-ons/<OUR_CAMPAIGN>/lua/gui_tutorial.lua").most_basic_gui()
                    >>
                [/lua]
            [/command]
        [/set_menu_item]

And create gui_tutorial.lua:

local function most_basic_gui()
        local dialogDefinition = {
                wml.tag.tooltip { id = "tooltip_large" },  -- required
                wml.tag.helptip { id = "helptip_large" },  -- required
                wml.tag.grid {   -- our most basic gui
                        wml.tag.row {  -- must start with a row
                                wml.tag.column {  -- a row needs a column
                                        wml.tag.image {  -- we can put stuff in a column
                                                label = "units/trolls/grunt.png"
                                        }
                                }
                        }
                }
        }
        gui.show_dialog(dialogDefinition)
end
return { most_basic_gui = most_basic_gui}

In the above file, we have