Writing LoTRO Lua Plugins for Noobs

[fade2gray]

I created a simple popup context menu, invoked by a chat command, using an example from the Helm's Deep Lua API Documentation.

contextMenu=Turbine.UI.ContextMenu();

menuItems=contextMenu:GetItems();
menuItems:Add(Turbine.UI.MenuItem("Option 1"));
menuItems:Add(Turbine.UI.MenuItem("Option 2"));

local i;

for i=1,menuItems:GetCount() do
    local menuItem=menuItems:Get(i);

    function menuItem.Click(sender,args)
        Turbine.Shell.WriteLine("You have selected "..sender:GetText()..".");
    end
end

contextMenu:ShowMenu();

What I would like to do is detect when the menu closes without a menu option being selected. I assume this can be achieved with the use of a callback and/or update function, but I just can't figure how to do it.

Any advice please?

P.S. "Garan has exceeded their stored private messages quota and cannot accept further messages until they clear some space."

[Thurallor]

I don't believe you can.

However, there is a replacement for the built-in ContextMenu, made by DToX, available at lotrointerface. He provides the standard callback mechanisms IIRC, but since you'll have the source code, you can add your own.

[Garan]

What I would like to do is detect when the menu closes without a menu option being selected. I assume this can be achieved with the use of a callback and/or update function, but I just can't figure how to do it.

Any advice please?

P.S. "Garan has exceeded their stored private messages quota and cannot accept further messages until they clear some space."

I believe Thurallor is correct that this can not be done with the build-in context menu.

I have cleared some space in my PM in-box (thanks for letting me know that it was full, I hadn't noticed)

[fade2gray]

Thanks for replies guys and sorry for the late response.

I wasn't able to find a solution to my query, but I did manage to find a workaround using a different approach.

@Thuralor:

Regarding DTox's alternate ContextMenu, I see that it's imported with SequenceBars but not actually employed? As it is, I had been attempting, yet again, to hack SB to my own ends and will post my modification in the appropriate thread.

[Thurallor]

Thanks for replies guys and sorry for the late response.

I wasn't able to find a solution to my query, but I did manage to find a workaround using a different approach.

@Thuralor:

Regarding DTox's alternate ContextMenu, I see that it's imported with SequenceBars but not actually employed? As it is, I had been attempting, yet again, to hack SB to my own ends and will post my modification in the appropriate thread.

It is used, but only if you choose Russian for the language option.

The only reason I'm using it (and the reason DToX made it) was to be able to use a different font. The normal Trajan Pro font doesn't have Cyrillic characters in it.

Edit: Starting in version 3.46, DToX's ContextMenu is now used for all languages in SequenceBars. This is because I wanted to include UI elements that can't normally appear in the menus (in this case, sliders).

[Thurallor]

I played around with ListBox and TreeView today. Different comparison functions are required by ListBox:Sort() and TreeView:SetSortMethod().

• For ListBox, the function should accept two list items and return true or false depending on whether the first is "greater than" the second.
• For TreeView, the function should accept two tree nodes and return -1, 0, or 1 depending on whether the first is "less than", "equal to", or "greater than" the second.

[Garan]

Tools of the Trade

For a couple of years now, I have been considering writing a section about the tools that I use for writing Lua plugins. I have put it off because my development tools for Lua plugins are fairly simple, a text editor and a picture editor. No IDE, or Integrated Development Environment, is needed - in fact an IDE can actually complicate the process for many simple plugins to the point that it deters potential developers. That said, I would like to discuss some of the options available for editing both the text files and images for anyone who is not familiar with some of the quirks.

First, let's talk about text editors. Many of you will already be aware that text can come in several flavors, particularly when handling special characters and accents. The Lua interpreter that the Lotro client uses can read text files in two formats, ASCII and UTF-8 without BOM. What does that mean in plain English?

ASCII is the American Standard Code for Information Interchange and represents all of the regular characters used in the English language without accents. In order to specify accented or other special characters you have to use an 'escape sequence' - that is, you use a sequence of a special character followed by numeric codes to represent the special character. For instance, to represent the accented 'é' (a very common letter in French), you would use the escape sequence /195/169 where the '/' character is the escape and the codes 195 and 169 specify the character code. This is OK if you are writing files that predominantly contain English with a few accented or special characters filled in, but what about string table files for French, German or Russian (where the entire alphabet is different)? Well, for those we need a file format that can handle the special characters as typed characters - enter UTF-8 without BOM.

UTF-8 is the Unicode Transformation Format 8-bit specification. BOM refers to Byte Order Mark which normally would indicate
the 'endianness' of a code and is simply a marker in the first couple of byes of the file but in UTF-8 it isn't really
relevant so the code parser is expecting no BOM character, thus UTF-8 without BOM. Using this format, you can simply type the
accent characters if your keyboard supports them, or copy/paste them or (as I usually do) use the Alt+character codes to type
them. For instance, to type a 'é' character, you can hold the Alt key and press the numbers 0233 on your numeric keypad and
you will get a 'é' character (neat, huh?). Many editors also support virtual keyboards where you can get a pop-up window
showing the accent/special characters and select them with your mouse. Just remember to set the encoding to UTF-8 without
BOM before saving your file (the method to do this differs by editor but it is usually an option from the editor menu). Note, the UTF mode supported by standard Windows Notepad is UTF-8 with BOM and will cause an error when read by the client.

So, what editor to use. Well, if you are mostly dealing with English and don't mind using escape sequences for the occasional accent/special character, just use Notepad or any other editor that can save as ASCII. That is by far the simplest answer. To edit using UTF-8 without BOM, I have personally used Notepad++ which is available for free for non-commercial use. Most recently, I have been experimenting with VSCode which is a fairly simple but powerful editor. Lunarwater has written an extension to VSCode that provides context sensitive help for the Turbine API. This is worth noting because the documentation for the API is kind of thin and any help that can indicate when you are using the correct methods and properties of the API classes helps. He has also included support for a number of the undocumented features like SetStretchMode and Rotate (two of my all-time favourite Turbine Window methods). To use the VSCode editor, you can download it from https://code.visualstudio.com/download
To use the Lua and Turbine extensions, open VSCode, click the Gear icon at the bottom left, select 'Extensions' from the menu (or type Ctrl+Shift+X). In the search box at the top, type Lua. Select the 'Lua Language Server coded by Lua' and click Install. Then type 'lotro' in the search box. Select the 'Lord of the Rings Online API' and click Install. You now have context sensitive help for the Lua language as well as the Turbine API for LotRO.

There are many other editors, many of them part of IDEs and if you are already familiar with one like Eclipse, it may be worth using it for familiarity's sake, but I prefer to avoid the overhead inherent in full blown IDEs when editing Lua projects. Then again, if you are already familiar with an IDE, this particular chapter probably isn't really for you

On to image editing. The client only allows us to load two types of images, JPG (Joint Photographic experts Group) and TGA (Targa). JPG files are great for handling compression and making small files, but JPG is a 'lossy' compression, meaning that the image will be slightly different once saved as a JPG in order to enhance the compression and make the resulting file smaller. Normally this is not a big issue and .jpg files are great for large images like maps where exact pixel correctness is less important than getting as many maps into as small a footprint as possible. The biggest difference with tga files is that tga is lossless (thus larger files) but supports the alpha channel - what is an alpha channel, you ask? Well, ever see an overhead projector where slides can be shown on top of other slides, and they show through each other? Well, the alpha channel allows for transparency or even partial transparency of the image so that when over laid it will show parts of the underlying image. This is really handy for UI elements that want to superimpose an irregularly shaped image over a background image. It is also handy if you want to blend an image with a background color to create a variably colored UI element (like the wear state components in the item wear mannequin which change from green to yellow to red to black as an item wears). As an example, .tga files are typically used in MoorMap for Overlays since the Overlay will usually want to show the background map and only overwrite the portions that indicate a special location or instructions or a path, etc.

So, how do you get a jpg or tga file? By far, the simplest method to create/edit a jpg file is the Windows Paint program built into Windows (or whatever editor is built into your chosen OS). This will allow you to create and save images, edit screenshots captured from the client, etc. and save them as jpg files. Unfortunately, Paint does not support the tga format. So, I usually recommend a free application called Paint.Net. Paint.Net has been around for years, has lots of extensions and plugins available if you are into that (I use one for blur effects) and most importantly supports a couple of really useful features, notably jpg and tga formats, transparency and Layers. What's a Layer? Simply put, layers allow you to work on an image in multiple overlapping layers which when combined create a finished product. Why is that important? Because when replacing part of the UI or creating an Overlay for MoorMap, it is easiest to work over a copy of the original. I will take a screenshot, open it in Paint.Net, change the resolution (if necessary), and then add a layer and do my work on the new layer with the original as the background. That way I know that what I am working on will line up exactly where I want it to in the client. Then, I can either flatten the layers to create a new image with my work on top of the default image, or more likely, remove the background layer and have just my work. Once I have the desired image, I save it as a tga file and the transparent portions will display the default client UI or whatever else is behind them when they are displayed.

And that covers not only which applications I use for working on plugins, but some of the reasons why I have chosen those particular applications. As I noted, there are many programs that can be used to write plugins. For simplicity I have focused on those that are either part of the Windows operating system or are free to use for non-commercial purposes.

[egarthur]

I haven't used Paint.Net, but I use GiMP (Gnu Image Manipulation Program), which is also free, and also happens to be open source. It supports both .jpg and .tga, of course. GiMP has a fairly steep learning curve, but once you get into it, it's very powerful. The basic concepts to grasp are layers and the alpha channel -- once you are acclimated to those concepts, the rest comes much easier. There are obscure features of GiMP that I've barely touched on, such as some of the more complex transforms and filters. Although it seems powerful, I haven't really learned the ins and outs of the "paths" concept yet (to my embarassment). GiMP is supposedly scriptable, too, including a Python-ic extension, but that's another aspect I haven't explored much. (Maybe someone should write a Lua extension to GiMP, eh?)

Outside of LOTRO plugin development, GiMP can also be used for file formats not typically associated with still images, such as PDFs and some video formats. When importing a video file, each frame becomes a separate layer, so that's not easy to deal with, but with a short video, and simple manipulations, sometimes it can do things that are not as easily done with a video editor.

In any case, everyone should try different tools and use what works best. For very simple tasks, sometimes I don't bother with GiMP, and just use the Paint (not Paint.Net) that comes with Windows. But mostly it's GiMP.