Post Sun Mar 03, 2019 9:32 am

ISBoxer 2.2.302.2 - Creating Modules

ISBoxer 2 Module development took a step forward with ISBoxer 2.2.302.2. This post will provide some information to help us get started in creating the first ISBoxer 2 Modules.

Before we begin ...
Before taking any steps, first let's cover what a Module is, who might want to create a Module, and of course, what skills and knowledge it may take to create a Module.

To the first point, ISBoxer 1 had no concept of Module at all. This is expected to be a new topic for any ISBoxer user, and there will be many questions. It's okay. :)

An ISBoxer 2 Module is a self-contained unit of features/functionality that someone has programmed, which can then be packaged up and shared with others. World of Warcraft players know what an "Addon" is for World of Warcraft, and this is essentially the same thing -- You can download and install WoW Addons into the game, giving you additional features and settings that are otherwise unavailable. So you in that way can think of a Module as an "ISBoxer 2 Addon", and you can imagine that there will be a variety of Modules created by lots of people, and reasons why someone might want a Module. ISBoxer 2 will provide curated lists of Modules available for you to download.

With that said, making a Module for ISBoxer 2 is not incredibly different from making an Addon for WoW. Most people will not want to (let alone understand how to) write code and therefore will look for Modules that already exist (just as with WoW, most people do not want to write code to create Addons, and frankly do not understand what the hell a Lua is anyway).

This post is for those who would like to learn to make Modules.
Here's a quick run-down of Module development can involve:
1. ISBoxer 2 Launcher includes a Lua (https://www.lua.org) engine. Lua at this point is a fairly well known programming language, and is used by WoW Addons. Within the Launcher it is possible to create new Task Types (see the other 2.2.302.2 thread) that are implemented in Lua.
2. In the Game Client context, ISBoxer 2 uses LavishScript. This is the same language used internally by ISBoxer for in-game behaviors. As with new Task Types in the Launcher being Lua, in-game Task Types can be created that are implemented in LavishScript. Do note that it is not necessary in all cases for a Module to include any LavishScript, particularly if the needed in-game code is already built-in or otherwise available. However, we will be providing brand new tutorials and guides that cover LavishScript development for ISBoxer 2, as the original LavishScript documentation does not really point you in the right direction (it provides a bit of a technical reference...) So with that said, this particular post will not be covering LavishScript for in-game work, and we will cover that separately later on.
3. JSON (http://json.org) is used for data transfer and storage. ISBoxer 1 used XML, ISBoxer 2 uses JSON. You will be unable to avoid learning what JSON is if you intend to make a Module.
4. JSON Schema (https://json-schema.org/) is used to describe what is allowed/expected by any particular JSON, and is used to automagically set up configuration GUI for Modules, Tasks, and more. ISBoxer 2 recognizes JSON Schema, and so will the development environment for working on ISBoxer 2 Modules.
5. LavishGUI 2 ("LGUI2" for short; https://www.lavishsoft.com/wiki/index.php/LavishGUI_2) is used for custom in-game GUI. ISBoxer 1 created in-game GUI with LGUI2's original predecessor called LavishGUI using XML; "Click Bars" are an example. ISBoxer 2 is using the new hotness LGUI2 which uses -- you guessed it -- JSON instead of XML. Using LGUI2 eliminates a lot of restrictions that exist for ISBoxer 1, including limitations on which Mouse buttons can be used to activate GUI buttons. LGUI2 also includes new features for animating and bringing the GUI to life, new types of GUI controls including circular controls, and so on.
6. Tasks. (see the other 2.2.302.2 thread). A Module may include Task Libraries and Task Types for you, so you are not always expected to accept workarounds as per the demo in the other thread ;)

Let's get on with it then, here's how to have ISBoxer 2 create your first Module for you
First, you'll want to enable "Module Developer mode" in ISBoxer 2's Preferences tab:
Image
Just tick the box.

At the bottom of the Preferences tab there's an icon for Modules, click that now. This tab initially appears to be a blank page, that's because you have no Modules. :) If you've enabled Module Developer mode, there is a + at the top of the window for creating a new Module. Click it now to bring up the Module Creator window which looks like this:
Image

The Module Creator will create a handful of files for you, with names and locations depending on what is entered in this window. The "Display Name" will be what you (or a user) will see the Module listed as. The "Folder Name" should be a valid name for a folder in Windows, as this will be used both for your Module's workspace folder, as well as for your Module's install folder. "Version" does not have specific requirements, but it should be understood that a newer version number/name/string could be determined by a string comparison, such that "B" comes after "A" and "2" comes after "1" ... ... so if you want to label your version "1.0a" that's perfectly fine. "Abbreviation" will be used in filenames and in code, and should therefore (generally) contain only letters and numbers, and start with a letter. If you expand the "Templates" at the bottom, it will list several filenames and internal object names that will be created using the Abbreviation. Once you're satisfied with the names and such here, click the ✔ to have your Module created.

It pops up a message indicating where the Module was created, like so:
Image

Thanks, Module Creator Window!

... and here we are:
Image

Now you have a box that can be ticked to "auto-load" this Module, there's an open folder icon, and an X if you want to delete the Module entirely.

Let's see this Module Configuration stuff
The Module creator sets up some example configuration options for you. Click the Edit Team tab on the left, then find the Modules tab on the bottom

Image

KNOWN ISSUE: The drop-down box on the right does not have a selection by default. This will be improved.

Select your Module in the list on the left (you do not need to tick the box to see this, just select it). With the Module highlighted, the drop-down box on the right now has a "Global" option; select the "Global" option.

And, voila.
Image
Here we have some example Global Settings for your Module, using exactly the same system demonstrated for Tasks in the other 2.2.302.2 thread. It will be possible to configure separate settings per Team, per Character, etc. But, for the moment, what you want to understand is that these options are defined by a JSON Schema in your Module. The settings themselves are stored in JSON, in a format specified by the schema.


So now you've seen that you can create a Module, and you see where options can be set for the Module.

Let's set up a development environment!
The development environment is going to make all the difference when creating ISBoxer 2 Modules. You're going to use a glorified text editor, and hopefully I don't really have to explain this to any programmer. You guys know that already. So let me explain about our reference environment. :)

Visual Studio Code, or "VS Code" is a free and open source environment provided by Microsoft.
Download: https://code.visualstudio.com/download

Many people have already formed their opinions on VS Code, and that's fine, if you have another editor you prefer, we're not stopping you (and those folks may be interested in our official tmLanguage file for LavishScript). But, for the purposes of showing everyone what to do, we're going to use VS Code. I'm using VS Code for ISBoxer 2 Module development myself, and so I do expect to continue to maintain support for VS Code.

So, download and install VS Code. I'll wait here while you do so. It's about a 50mb download, and will require about 200mb of disk space installed. You do not need to select any special options during installation, all of the defaults work fine. You do not need to have the installer launch VS Code when the install is complete; I will show you what to do!

Now you should have VS Code installed, and we're going to assume you don't have it running and haven't even touched it yet. Yay! Back into ISBoxer 2!

Go back to the Preferences tab on the left, and the Modules tab at the bottom, back where you found the Module Creator Window and it now shows your Module with the Open Folder icon, etc. Click the Open Folder icon!
Image

The easiest way to open VS Code to edit your module is right here, the .code-workspace file. Double click the file. Unfortunately Windows is a little dumb and doesn't understand that the .code-workspace file is for VS Code by default, so it will ask what app you want to open the file with. Select Visual Studio Code, and allow it to use this program every time to open .code-workspace files. That gets you here:
Image

The left side shows you a list of the files in the folder, and whichever of those files you've already got open in a tab in VS Code (currently none of them). LEFT CLICK ON THE .ISS FILE! That gets you here:
Image

Take note of the Marketplace popup in the bottom right. By saying Marketplace it sounds like you might have to buy something, but you're not buying anything, you're going to install a free piece that we have provided. Click "Search Marketplace"

Now on the left side, VS Code will list a couple of Extensions you could choose to install to handle "iss" files. CLICK THE LAVISHSCRIPT EXTENSION -- not the Inno Setup one. You can just click Install!
Image

After that's installed, click the Explorer tab on the left (that's the pages/documents icon above the magnifying glass) to go back to the file list, and again click the .iss file. This time the code is turned pretty colors and the "Search Marketplace" notification no longer appears:
Image

The provided extension is now providing basic highlighting and related features for editing ISBoxer 2 Modules. Nice work, you're ready to edit stuff!

You've got several .JSON files that can be modified, an .iss (LavishScript, actually .iss stands for Inner Space Script) file, and a .lua file. VS Code already includes highlighting for these other files.

Let's look at a .JSON file!
Selecting ANY of the .json files will do basically the same thing, it's going to show you the JSON :)
Image

All of the .json files contain a JSON "object". A JSON object is surrounded by {} and is basically just a set of named values. Values can be null (i.e. "a nothing"), text, numbers, true/false (boolean), another object, or an array (a list of un-named values). So in the above screenshot we have a "description" value that is set to the text "Configuration for Demo Module", a "type" value that is set to "object", and so on. Taken alone, these values are individually meaningless and are just entries in the file. All that really matters is who wants to access these values -- which values something will be looking for in this, and what it expects them to contain. isboxer2Module.json will give you a good simple look at that concept:

Image

This file can be used to look up some things about your Module, such as filenames for different pieces. According to this file we have a "configuration" object that has a "schemaFilename" field set to "DEMO.schema.json". So DEMO.schema.json is our Module's file used for the configuration schema. Likewise the filename for lavishgui2 is listed as "DEMO.lgui2Package.json", and so on. So this isboxer2Module.json is simply describing your Module, filled in with the values from the Module Creator window. If you wanted to change the Display Name for your Module, you could do so in this file by changing the "display_name" entry.

At the top of the file there's a value called "$schema". This is a special keyword recognized by JSON editors in order to understand what exactly should be found within the data, and what is valid or invalid. This provides additional editing capabilities for VS Code and other editors as you make changes to the file. Within the "author" block, the file lists 4 blank entries -- name, email, bitcoin, paypal. However, the schema for an isboxer2Module.json file provides for more values, including a "patreon" value. On the line that says ...
Code:
"paypal": ""

... add a comma at the end (after the empty quotes), and add a double-quote character. So it will look something like ... "paypal": "", "

As soon as you press the double quote, VS Code pops up "patreon" as a suggestion. Press TAB, and it will add "patreon" for you -- this is magic that VS Code is doing based on the Schema we have provided for this type of file! Now it says ...
"paypal": "", "patreon"
... this is not yet valid, as every entry in an object needs a value to go with the name ("patreon"), so add a : and empty quotes.

Now you've got a blank patreon entry after the blank paypal entry:
Image

Nice work! That did literally nothing, but now you should have an idea of where the editor is getting some of its functionality from. You can even follow the Schema link to see the actual Schema for the file.

That's all well and good Lax but I want more!
I know I know, we're getting there!

Next let's talk about the lmacPackage.json files. LMAC is short for LavishMachine, which you don't really need to know but LMAC is what implements Task Libraries and Tasks. The .launcher.lmacPackage.json file defines Task Libraries and Tasks for the ISBoxer 2 Launcher context, and the .client.lmacPackage.json file defines them for the Game Client context. The exact same options demonstrated in the Tasks tab are available right here in the lmacPackage.json files. This means that the Task Libraries and Tasks we set up via the GUI could also be set up here in JSON instead. In fact, you can open up the ISBoxer 2 folder under Documents and find myClientLMACPackage.json and myLauncherLMACPackage.json which contain the actual JSON produced using the GUI, and you can paste things straight from there into the Module files.

Image

Now as long as this Module is enabled, we don't even need the Task we created in the GUI. Neat!

There's still more!
Yep, there's more to get to. We've only covered Tasks and have not even touched on creating any in-game GUI (using LGUI2), how to create a type of Task either in the Launcher (using Lua) or for the Game Client (using LavishScript), how to write JSON Schema to set up custom options in your Module Configuration, etc!

But, first things first! Here's your first Module, and your first ability to tinker with ISBoxer 2. We will build more from there!