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. However, Modders with specific wishes are invited to request features from the Development Team.

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 if it were a HTML file; 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

GroupImage()

GroupImage([Image1, Image2, Image3,...]) combines several images, so you can treat them as a single one. Often used together with TranslateImage(Image1, Point(x,y)) to position the images relative to an implied (0,0) co-ordinate.

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) 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.
Additionally, the imported image is 'painted' with the color, that is, the colorvalues in each pixel are multiplied with the given color, so Black, being Color(0,0,0) will render the pixel completely black and white, being Color(1,1,1) won't change it. N In the example below "white" is used instead of a Colorvalue. "White" is a color constant; a hardcoded variable. Note that this does not work on gauges, at least not on GaugeImageRect.
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. Nevertheless, this functions supports using Black as the transparent color. The boolean at the end turns that on (true) or off (false)
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.

RotateImage()

RotateImage(AnImage, number) supposedly rotates an image. The number sets the rotation but it is unknown what unit it takes. Hard to get to work at all.

Functions that return gamedata

GetAmmo()

Returns how much ammo is left. Between 0.0 and 1.0
Example: GetAmmo(Me, OnEveryFrame)

GetCloaking()

Returns a cloaking factor. When calculating a ship's signature, the game multiplies it by this factor. I suppose it might be the one that is defined in the core .igc for every cloak part.
Example: GetCloaking(Me, OnEveryFrame)

GetEndurance()

Ksero thinks this is the countdown of oxygen when flying a life pod. Returns a number between 0.0 and 1.0
Example: GetEndurance(Me, OnEveryFrame)

GetFuel()

How much booster fuel the ship has. Returns current fuel / fuel capacity (ie. Between 0.0f and 1.0f). Updated when event fires
Example: GetFuel(Me, OnEveryFrame)

GetMass()

Returns a Number with the ship's mass. Updated when event fires.
Example: GetMass(Me, OnEveryFrame)

GetModelType()

Returns the ModelData's ModelType flag. Updated every time Event fires. Possible values are for example OT_ship, OT_station, OT_missile. These possible values are not exported.
Example: GetModelType(Me, OnMeChange)

GetModelTypeDesc()

Returns a string describing the ship (defined in core.igc). Updated when event fires
Example: GetModelTypeDesc(Target, OnTargetChange)

GetName()

returns a string with the ship's name (defined in core .igc). Updated when event fires
Example: GetName(Me, OnMeChange)

GetOre()

If the Model is an asteroid, returns how much HE3 is left in it. Updated when event fires
Example: GetOre(Me, OnEveryFrame)

GetPercentEnergy()

How much Energy the ship has, in percent. Updated when event fires
Example: GetPercentEnergy(Me, OnEveryFrame)

GetPercentHitPoints()

Returns the amount of Hull the ship has left, not as a percentage, but as a fraction between 0 and 1. Updated when event fires. Naturally, best used on every frame.
Example: GetPercentHitPoints(Me, OnEveryFrame)

GetPercentShields()

How much Shield the ship has, not as a percentage, but as a fraction between 0 and 1. Updated when event fires. Best used on every screen.
Example: GetPercentShields(Me, OnEveryFrame)

GetRange()

Returns a Number with the range of the ship (presumably the maximum range of the ship's guns). Updated when event fires.
Example: GetRange(Me, OnEveryFrame)

GetRipcordTimeLeft()

Returns the time left before ripping. Make sure the ship is ripcording before calling this.
Example: GetRipcordTimeLeft(Me, OnEveryFrame)

GetSectorName()

Returns a string containing the name of the sector the ship is currently in.
Example: GetSectorName(Me, OnMeChange)

GetSideColor()

Ksero thinks this returns the color of the team that the specified ship/model belongs to
Example: GetSideColor(Me, OnMeChange)

GetSideName()

Ksero thinks this returns the name of the team that the specified ship/model belongs to
Example: GetSideName(Me, OnMeChange)

GetSignature()

Returns the signature of the model / ship
Example: GetSignature(Me, OnEveryFrame)

GetSpeed()

Returns a Number with the ship's speed. Updated when event fires.
Example: GetSpeed(Me, OnEveryFrame)

GetVectorLock()

1 if the ship is flying on a vectorlock. 0 otherwise
Example: GetVectorLock(Me, OnEveryFrame)

IsCloaked()

Returns 1.0 if the ship is cloaking; 0 otherwise
Example: IsCloaked(Me, OnEveryFrame)

IsEjectPod()

Returns 1 if the ship is a lifepod. 0 otherwise
Example: IsEjectPod(Me, OnMeChange)

IsNotNull()

Whether the ModelData refers to a valid ship (ie if it points to a valid model)
Example: IsNotNull(Me, OnMeChange)

IsRipcording()

Returns 1 if the ship is ripcording. 0 otherwise,
Example: IsRipcording(Me, OnEveryFrame)

IsVisible()

Ksero thinks this returns 1 if the player can see the ship (ie it's inside the player's scan range), otherwise 0
Example: IsVisible(Target, OnEveryFrame)

Math Functions

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)

See also font.mdl for predefining font styles and use of nonstandard fonts.

Events

Events determine when and how often your code must run. In order to minimize the use of processing power, it is wise to when possible, choose the event that fires the least often. For instance, there is no need to check your own team color hundreds of times per second.
There are three events to choose from in MDL:

OnMeChange: true whenever the player enters or leaves a sector, or changes ship (gets podded).
Example: GetSideColor(Me, OnMeChange) retrieves the players teamcolor.
OnTargetChange: true whenever a new target is selected.
Example: GetName(Target, OnTargetChange)
OnEveryFrame: true on every frame.
Example: GetFuel(Me, OnEveryFrame) retrieves the players fuel level at every frame.

constants, wrappers and the like

AcceptedOrder: return type: string. Not certain, but I think this is the "Accepted" text that appears when you accept an order
Example:
AutopilotOn: return type: Number. Whether the autopilot is turned on or off
Example:
BoardState: return type: Number. A flag with three states. If the player has his own ship, if he is flying as a turret gunner or if he is an observer of another player.
Example:
ChatRecipient: return type: String. The current chat target
Example:
ChatText: return type: Number. The current chat text (ie the text the player is writing to send to someone)
Example:
ComposeState: return type: Number. Flag. Has different values depending on if the player is writing a chat message, giving a ship an order in F3-mode etc
Example:
CriticalTipText0: return type: String. Current critical messages.
Example:
CriticalTipText1: return type: String. Current critical messages.
Example:
CriticalTipText2: return type: String. Current critical messages.
Example:
CriticalTipText3: return type: String. Current critical messages.
Example:
CurrentVote: return type: String. Contains the current "vote" string. (ie when a vote is proposed, this contains the string with the voting message
Example:
Detected: return type: Number. Whether the player has been detected by enemy scanners or not
Example:
Experience: return type: Number. The player's kill bonus
Example:
GotArtifact: return type: Number. If the player has an artifact?
Example:
GotFlag: return type: Number. If the player has the flag?
Example:
HasVote: return type: Number. I imagine this is 1 when there is a vote, 0 when not
Example:
Kills: return type: Number. The player's fragcount?
Example:
KillsOn: return type: Number. If the game is a DeathMatch game
Example:
Lives: return type: Number. The number of lives of the player?
Example:
LivesOn: return type: Number. Not sure. Whether the game has limited lives?
Example:
Money: return type: Number. How much money the player has got
Example:
QueuedOrder: return type: String. The current queued order
Example:
RadarMode: return type: Number. Flag about the current radar mode (all/default/target/none)
Example:
SectorName: return type: String. Name of current sector
Example:
Signature: return type: Number. The player's signature
Example:
TargetExperience: return type: Number. The targetted ship's kill bonus?
Example:
TargetInRangeFlag: return type: Number. Whether the selected target is in range of player's weapons?
Example:
TipText: return type: String. Non-critical messages like "Reloading chaff...", "Missile lock lost."
Example:

Images

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

Modifying the User Interface