Difference between revisions of "Creating plugins"

Latest revision as of 14:55, 28 December 2011

Starting with version 016, it is possible to create editor plugins with Lua. These plugins are currently fairly limited in functionality, but will be expanded in the future. Plugins are basically Lua scripts that generate items (much like a levelgen script does), and inserts them in the editor.

It is possible for the plugin to create a menu to get input from the user. There are currently 4 different menu widgets that can be added to a menu:

        CounterMenuItem:new("Angle", 90, 1, 0, 360, "deg.", "Disabled", "Sweep of arc", "Help me!"),          -- Name, value, step, min, max, units, minmsg, text, intvalue, 
        ToggleMenuItem:new("Toggleable", {"First", "Second", "Third"}, 1, false, "Pick one!"), -- Name, choices, selected index, wrap, help
        YesNoMenuItem:new("Hello",2,"Pick one"),                                               -- Name, selected index (1 = no, 2 = yes), help string
        TextEntryMenuItem:new("Text here", "start", "Empty", 20, "Enter your text")               -- Display Value, starting text, empty string, length, help

To create a menu, you must create a function in your script called getArgsMenu(). That should return something like this:

-- Standard plugin method for building a menu to get parameters
function getArgsMenu()
   local menuItem1 = CounterMenuItem:new(...)   -- Note the use of ':', NOT '.'
   local menuItem2 = YesNoMenuItem:new(...)
   local menuItem3 = TextEntryMenuItem:new(...)
 
   return "Menu Title",
      { menuItem1, menuItem2, menuItem3 }
end

The selected menu item values will be supplied to the script in the arg table in the order they were presented on the menu. All values will be strings (which can be tranparently converted to numeric values where appropriate). Items on a ToggleMenuItem will be returned as the value shown on the menu, not the corresponding numeric index.

Also, remember that if the plugin is creating new items, they will be added as if they were coming directly from a level file. That means that all coordinates will be multiplied by the level's gridSize parameter. If your plugin objects are coming out too large, you may want to divide any coordinates by the gridSize, which can be obtained as follows:

local gridsize = levelgen:getGridSize()