Internals

This page will try to explain how CortUI is implemented. As such, it should be only relevant to those working on CortUI. If you just want to use it for Allegiance, you shouldn't have to read it.

MDL files

CortUI and the HUDs are a modification of various MDL text files of Allegiance. Therefore, understanding the language used is very essential. Ksero's MDL documentation is compulsory reading. The language documentation explains the syntax and the reference is very useful during development, because it lists the parameters to all the functions and what they do.

The rest of this page assumes you have read and understood the introduction and have the reference ready for lookup.

It is very important that you understand that MDL is more of a functional/descriptive language. It is quite unlike the imperative programming langauges you might know. It is not possible in MDL to say "do this, then do that". You merely construct a ruleset on how the Allegiance client is supposed to build up the UI. There is no way to actually store data over time and there is no way to tell it how to behave that hasn't been prepared by the developers.

The dialogs variable

The core of the modification can be found in the dialog.mdl file. It defines one variable, called dialogs, which defines the whole in-game UI.

It defines a list of pairs. Each pair represents one pane that will appear on the UI at certain times. Each pair consists of the following elements:

Name	Type	Description
image	a variable defined above	the image to display
side	one of the Side* constants	defines to which point the coordinates are given relative to
off point	an XY-coordinate pair	the coordinates of the pane when it is not shown (used for animation)
on point	an XY-coordinate pair	the coordinates of the pane when it is shown
transition time	float	the transition time from off point to on point or the back when the pane is shown/hidden
console mode	integer / bitfield	the context in which to show the pane
undetectable	boolean	whether clicks on the pane are detected and handled

Some more documentation can be found in the modified dialog.mdl. In particular, it contains a list of all the Side* constants and the meaning of the bits used in the console mode bitfield.

CortUI consists of a modification of this dialogs list and various changes of the pane definitions, which in turn depend on the values set in cortui_settings.mdl.

The installer

The installer has been created using the excellent ​Nullsoft Scriptable Install System, a free and open-source installer creator. The definition files are all in the repository, the only external part required to build the installer is the ​!FindProc plug-in, which is also in the repository.

When running the installer, it goes through the following steps:

1. Giving a basic introduction and allowing the user to choose the components to install.
2. Making sure Allegiance is not currently running.
3. Presenting the user with the customization dialog.
4. Determining where Allegiance is installed using the registry key.
5. Letting the user confirm the detection was successful.
6. Preparing the uninstaller.
7. Creating a backup of the files it is going to overwrite in %Alleg%\artwork\mods\CortUI\Backup <date>.
8. Installing all the CortUI-specific files to %Alleg%\artwork\mods\CortUI\. Overwriting all the modified files in %Alleg%\artwork\.
9. Writing the basic cortui_settings.mdl to %Alleg%. Opening it and modifying the values to those chosen by the user in step 3.
10. Finishing the installation and suggesting to read the release notes.

The cortui_settings.mdl is the only file the installer is ever going to edit. All other files are either copied or not, depending on the choices the user has made in the customization dialog. All HUDs are always installed, even if the user doesn't select them. That way, they can still be switched later on through changes in the cortui_settings.mdl.

The uninstaller does not actually revert anything. It just deletes files specific to CortUI and replaces files with special 'stock' versions included in the uninstaller. This is somewhat unstable, e.g. if the stock files change in between CortUI releases, and should eventually be looked into.

GlassHUD Internals Documentation

GlassHUD's artwork (as in: its image files) is found in the folder Artwork/Mods?/CortUI/media/GlassHUD. However, that's not all there is to it. Due to a technical reason, Bunnywabbit had to create a good deal of so-called 'wrapper' files. These have no other function than to sit in the artwork folder and reference a particular image file. The wrapper files for GlassHUD have carry the prefix 'gh_' in their filenames.

The technical reason mentioned above is, that GlassHUD utilizes a lot of images that are given the team color by the game program. The function that achieves this, ImportImage3D, only works for mdl files in the artwork folder. It does not take .png files or file paths. Therefore, the only way to use this function is to create a png file, then create a wrapper mdl file pointing to that png, and then have ImportImage3D call that wrapper mdl file. Bunnywabbit isn't happy about this either.