A Neophyte Tackles the FG Extension - XML and Lua, Why?
by
, May 12th, 2016 at 04:39 (7506 Views)
Most, if not all programs, when stripped down to their very essence do one thing, manipulate data. That’s all Fantasy Grounds does: whether you are constructing a character sheet or rolling a d20 to determine surprise, FG is using your input, the data you supplied, in some predetermined process. FG uses two “languages” to provide extensibility. What do the two languages, XML and Lua bring to this table? XML is a standardized methodology of providing easy access to data. Lua is a methodology to manipulate the data, access it and do something to or with it.
Detour: Computer programs can obtain data in a variety of ways. Your car has numerous little sensors. Microcomputers in your car monitor the sensors, collecting input to ensure a variety of outcomes, like peak performance or a safer environment. Other computer programs collect data directly from humans. A person types on a keyboard, uses a mouse or speaks into a microphone, all of which are handled by a Graphical User Interface (GUI).
Fantasy Grounds has a GUI. It collects data from us and code behind the scenes manipulates that data.
Fantasy Grounds uses XML in at least two distinct ways. One, as we saw last time, is to store data that we enter in XML files on the hard drive. Another way FG employs XML is to specify the look and feel of the GUI. The specifications are data wrapped in tags, whether it be for a pop up dialog, an on-screen button or a player character icon.
Fantasy Grounds uses Lua to manipulate data. When you double click a die, enter text in a field or in the chat box, Lua, behind the scenes manipulates that data. Lua saves it, sends it to another part of the GUI, or it does something else to or with it.
FG’s extensibility allows us to write our own specifications for windows and controls plus we can write our own Lua routines to use those controls to launch special attacks, inflict different types of effects or simply provide different and interesting interactions with players.
Let’s look at a couple of specifications in the XML and Scripting Reference document.
First, one of the Elements, the buttoncontol. Items on the GUI respond to events, like drag and drop, mouse clicks and typing text. The code that services an event is typically called a handler. The buttoncontrol’s event handlers are listed on the upper right portion of the page. Intermixed with the handlers are other supported functions, all of these comprise the element’s “Interface“. onButtonPressed and onValueChanged are examples of handlers. getValue and setValue are examples of other supported functionality. The list is a set of links to their explanations.
In the box just under the name of the element, are the associations with other elements. The first, “Inherits” means that this element, the buttoncontrol, in addition to its own functionality also inherits all the functionality of another element, in this case the windowcontrol. The “Context” can be thought of as the base or most generic specification from which this element is derived. In FG, all the other elements, except the script element, are at their very core a windowinstance.
Under the box containing the Inherits and Context information is a description of what the element does, what it is for, how one might use it. And then below that are all the XML fields, the attributes and properties available for the element.
Now let’s take a look at one of the Packages: Debug. One immediately observes, the missing Inherits/Context box and no properties/attributes definitions. There are some interface functions at our disposal. In the Debug package description “built in” functionality is mentioned. This means that the functionality is exposed for our use but it is not modifiable, it comes to us “As Is”. The descriptions of the two interface functions, chat and console state that they allow us to send text to the chat window or to the console window.
If you recall, last time I said I was going to look inside the CoreRPG ruleset for the variable names and see if those names were the same as the tags in the db.xml file. I was able to convince myself that it is true, they are the same names. I am going to use Debug's console function in some Lua script to prove it.
Detour: How did I find the variables within the core ruleset scripts? I didn’t. Having worked through the tutorials that I mentioned in a previous blog post, plus by dissecting a couple of published FG extensions, I surmised that all user input data is stored in an object called “DB“. The XML and Scripting Reference document also states that the DB package object is used to store user input. Given this information, what is there left to do? I must access the names of the variables in the DB package and write those out to the console.
This post is already pretty lengthy. The implementation of the Lua script to dump all those names to the console is going to take a blog post in itself, so that is where we’ll pick up…
Until next time keep on role playing.