Modifying the User Interface

Stub This article is incomplete This is an article about a topic that should be covered in more detail by the FreeAllegiance Wiki, but is lacking in content. You can help by improving it!

introduction

Allegiance's User Interface can be modified to an extensive degree. Several Mods have been made, and more are in progress of being developed.

Allegiance User Interfaces are determined by three sources

• the game engine calls and interprets the text-mdl files, and some image-mdl files.
• the text-mdl files contain formatting, behaviour and placement instructions for the images and text.
• Images can be in the form of image-mdls, which are basically bitmaps wrapped in some code, or PNG files (and many more formats).

The Game Engine

Understandably, not much can be altered here.

MDL

This is where modders spend most of their time. MDL is unfortunately both very limited as a language, and very particular about its grammar. To understand what it does, it's helpful to think of an MDL-file as a relatively easy way to feed the game engine layout instructions.

An mdl-file can't do anything on its own; it merely contains a variable that the game engine wants. A Modder gets to decide what that variable contains, but only up to a point.

Common MDL Functions

Some instructions get used more than others. It makes sense to discuss some of those here. For a complete reference of the MDL language, see Ksero's MDL Language Documentation.

Functions that return Image Objects

ImportImage()

ImportImage("imagebmp", boolean) imports an imagebmp.mdl file from the Artwork folder to the current textmdl. This is a bitmap 'wrapped' in a MDL-header. Note that the file extension is left out in this call. This file must be in the Artwork folder. It's not certain what the boolean operator does.
Example: ImportImage("softgaugebmp", true)

ImportImage3D()

ImportImage("image_mdl_bmp", Color(R,G,B),boolean) does largely the same as plain ImportImage, only with the addition of a Colorvalue. The imported image is 'painted' with this color. In the example below "white" is used instead of a Colorvalue. "White" is a color constant; a hardcoded variable.
Example: ImportImage3D("softteamcolorbmp", white, true)

ImportImageFromFile()

ImportImageFromFile("folder/folder/imagefile.png", boolean) imports images in many formats, .png being a favorite for many reasons, not the least of which is good support for 8-bit alpha channels. Since the alpha channel determines the opacity of a given pixel, creating a smooth transition between a given image and your ship's surroundings is easy, provided the image in question has an alpha channel. Unlike older Allegiance artwork, transparency is not achieved through using a black background and have transparent bits fade to black. You create your image with transparency and a transparent background. You import it and the engine does the rest.
Example: ImportImageFromFile("mods/CortUI/media/cortui_fp1_target_shield_gauge.png", true)

StringImage()

StringImage(Justification Constant, width, FontObject, ColorObject, "String") creates an image containing a string. The function thakes 5 arguments: A Justification Constant, a number representing the width of the image in pixels, a Font object that specifies the intended font, weight and size in points(must be smaller than 36pt) and a Color object. Last but not least, the string itself. Should be either in the form of a typed out string in double quotation marks, or a String object.
Example: StringImage(JustifyCenter, 160, medVerdana, Color(1, 0, 0), SectorName) SectorName here being a predefined string object.

Miscellaneous functions

Color()

Color(R,G,B) creates a Color Object. This object is later used to assign a specific Color to another object; for instance in ImportImage3D("ImageNamebmp", Color(1,1,1), true). The arguments are decimals between 0 and 1. To convert from hexadecimal color code #c6c6c6, split it up in the separate Red, Green and Blue hex-values C6, convert to decimals 198 and divide by 256 to get 0.77; so #c6c6c6 corresponds to
Example: Color(0.77,0.77,0.77).

ColorA()

ColorA(R,G,B,A), like its sister function Color() creates a color object. It takes the same arguments as Color(), and handles an extra argument representing an alpha value between 0 and 1 to regulate Opacity. The alpha channel has no effect on StringImages.
Example: ColorA(0.12,0.7,0.8,0.75).

Win32Font()

Win32Font("Font Name", Size Points, Bold-boolean, stretch number) Creates a font for in-game use. The chosen font should be in the default Windows Font pack. If the intended font is not on the user's computer, the default font will be used. Font Size can not be greater than 36 (this limitation may come from the way StringImage() works).
Example: Win32Font("Arial Black", 36, true, 0)

Events

OnEveryFrame

Fires on every frame.

OnMeChange

Fires whenever the player enters or leaves a sector, or changes ship (gets podded).

OnTargetChange

Fires whenever a new target is selected.

Images

Creating or altering images is not difficult, given some experience with a decent graphics program.