Targetware: Customizing the User Interface

Editing the User Interface Code

You can change how the User Interface (UI) looks simply be repainting the textures, but if you want to change how it works, or if you want to make up an entirely new design of your own, you will need to delve into the UI code file itself. Don't worry, it's not scary; it's a simple text file. Using this documentation, you can create an entirely new User Interface that looks and acts just the way you want.

You already know that the UI lives in the "ui" sub-directory of the Targetware directory. It could actually be any almost any sub-directory, the game will look for whatever file is specified in the "ui = x" line in config.txt. The file that controls the default UI is named, unsurprisingly, "ui.txt". This file can be opened in any text editor and edited freely. Before diving in headfirst, don't forget to make a backup copy of it, just in case.

UI Terminology

The Targetware User Interface has two main "modes": Pre-Load, and In-Game. The Pre-Load interface is what you see first when you start up the game. By default, it presents a full-screen, graphical interface to the player, guiding them through the process of selecting a server for online play, loading a scenario for offline practice, etc. It governs a player's actions right up to the point when a scenario loads, or a player connects to an online server.

The "In-Game" menus take over as soon as the player enters the "Scenario Environment". These menus are mainly text-driven, and typically occupy less screen real estate, so as not to cover up terrain, sky, and aircraft. The In-Game menus let the user select functions that apply specifically to the particular scenario they are taking part in.

The In-Game menus are further broken down into Pre-Flight and In-Flight. Pre-Flight menus are displayed when the user logs onto a server (or loads an offline scenario), and allow the user to select a mission and aircraft, study briefings, check the roster, etc. Once a user selects an aircraft and begins flying, the Pre-Flight menus disappear. Pressing the ESC key will bring up a menu again, this time, the In-Flight menu. The In-Flight menu has options for exiting the plane, checking scenario, team, mission, and unit briefings, as well as a pilot's handbook.

Design Considerations

Before you start designing your new User Interface, ask yourself some basic questions:

• How large a screen am I designing the UI for?
• Will the Pre-Load UI scale to match smaller or larger screens, or will it always display at the size I tell it to?
• Will the In-Game UI scale or not?
• What functions are important to my interface? Do I care about being able to practice offline?

UI File Breakdown: Sections

The User Interface file is made up of several different sections:

• [UI]
• [Error Box]
• [Error Button]
• [Progress Bar]
• [Progress Button]
• [Game]
• [Page x]

The [UI] section establishes the rules for the UI as a whole; it determines whether the UI will scale or not, what the original design size is, what font should be used, how many different screens it will have, etc.

The [Error Box] and [Error Button] sections are valid for the entire UI, and determine the size, color, texture, and positioning of the error window that appears any time an error occurs. For example, if a scenario fails to load, or if your connection to a server is terminated prematurely, the error window will appear with a message describing the error, and the user will click the cancel button to make the window go away.

The [Progress Bar] and [Progress Button] sections are used to setup the small window displayed when the game is doing some time-consuming operation, such as loading a scenario or downloading a mod.

The [Game] section contains everything used by the In-Game UI, including the pre-flight menu, the in-flight menu, briefing displays, roster displays, etc.

Each numbered [Page] section represents a unique, Pre-Load UI screen. Page 1 will always be displayed first, when the user double clicks the Targetware application icon. Subsequent pages can be accessed by the user clicking on buttons.

Widgets: Building Blocks of the UI

The [Game] section and [Page x] sections are further broken down into individual chunks called "Widgets". For example, in the current default Targetware UI, the In-Game menu uses 76 widgets. A widget could be a button, it could be a piece of text giving feedback to the user, it could be a list of available servers, etc.: widgets are the building blocks upon which the UI is built.

The number of widgets used by a Page, or by the Game section, is determined by the "num_widgets = x" line in each Page/Game section. Each widget section is then labeled with "Game Widget x", or "Page z Widget x" where x is the number of the widget within that Game or Page section.

Widget Types

The following types of Widgets are currently supported:

• Panels
• Buttons
• Fields
• Displays
• Text

For detailed information on each widget type, click on the name of the widget in the list above.

Widget Display Priority

Widgets are drawn on the screen in order, from back to front, depending on the widget number they are assigned. The Page itself is drawn first, then each succeeding widget. This means, for example, that higher-numbered widgets can obscure lower-numbered ones, if their positions are set to overlap.

Design Size and Scaling

When you design your UI, you have to tell the game engine what screen size you are designing it for, and how you want it to behave with screens smaller or larger than that size. This code comes at the beginning of the UI code file, in the [UI] section, as follows:

We have told the game that our UI design is based around an 800 pixel wide, 600 pixel tall screen size. We have also told it that we want the User Interface to scale (either stretch or shrink) to fit larger and smaller screens, when in the Pre-Load phase. If, for example, a player had set Targetware to run at 1280x960 resolution, the Main Menu and other portions of the Pre-Load UI would scale by 160%, in order to fill the entire screen. If we had set "stretch_main = 0", the UI would only be drawn using 62% of the screen real estate, at 1:1, with the surrounding area being drawn in black. For the In-Game UI, we have chosen not to scale it. This means that people running in higher resolution will be able to see more text on the screen than people running at or under the default 800x600 design size. If we wanted everyone to have the same amount of text, and big letters, we could change to "stretch_game = 1".

Size and Positioning Factors

In order to give designers maximum flexibility in sizing and positioning the various elements of the UI, there are three possible "types" of position and size numbers that can be used. For each element, the size and position is specified with the "size = x,y" and "position = x,y" lines, as in this example:

Here were are positioning the panel in the upper left corner of the screen (0,0), and specifying a size of "800" by "370". What the "800" and "370" means depends on the "type" of size we specify. The following size/position types are available:

To specify a position type, use this pattern: "pos_type = x, y". To specify a size type, use the "size_type = x, y" line. Yes, you can mix size or position types, x axis versus y axis. If no position type is specified, the game engine will default to type 0 for both x and y. If no size type is specified, it defaults to type 1 for both width and height. What this means in our example above is that the "800" and "370" both refer to actual pixels. Here's an example that uses the percentage type of size and position:

Here, we want the game to position our scenario info text display so that it's left edge starts one-fifth of the way over from the left side of the screen, and 1/20th of the way down from the top. For size, it will fill 60% of the width of the screen, and 80% of the height of the screen, no matter how large the screen is. Since this is part of the In-Game UI, it's not going to scale, so using fixed pixels here would result in a display taking up less and less of the total screen area available to it, the higher the resolution of the user. The percentage type of position and sizing is very useful when you want to fill a certain chunk of the screen, and you don't know what the actual pixel width of the screen will be because you aren't scaling.

Positioning Hint: Positive numbers on the "pos = x,y" line mean "start drawing the object x pixels from left edge of screen, and y pixels from top of screen. That you already know. But you can also make the game draw from the lower, right corner by using negative numbers in the position line.

Color and Transparency

Color is assigned on a per-widget basis. Depending on the widget, you can specify a background color, a label color (if there is text associated with the widget), a highlight (mouse over) color, and a disabled color. Color is specified using RGB colors (0-255), plus an alpha transparency factor. For example, a panel using "color = 255, 255, 255, 255" would be fully opaque and white, while a button using "color = 255, 0, 0, 127" would be red, and half-transparent. For transparency, 0 is fully transparent, 255 is fully opaque. Color does affect objects with textures! If you are texturing an object, you will most likely want to use full white (255,255,255) as your background color.

Using Textures

While it is more than possible to make a full UI using nothing more than panels, displays, and buttons with plain color backgrounds, the effective use of graphic textures can make your UI unique, and more attractive. Textures can be in either TGA (targa) or JPG format, and must use power of 2 dimensions, such as 128x128, 128x256, 128x512, 256x256, 512x512, 1024x1024, etc. Textures can be added to widgets using the following code:

The color line insures that our object will be colored exactly as it is in the texture, with no transparency effects. The "texture = " line tells the engine to look for the graphics file "pg2.tga" in the same directory as the UI code file itself. The two "texcoord" lines tell the game what part of the specified file you want to display on the widget. The UI uses the UV coordinate system, with 0,0 corresponding to the upper left corner of the graphic, and 1,1 corresponding to the lower right corner. The first texture coordinate is the upper left coordinate, the second is the lower right coordinate.

Calculating UV Coordinates

To calculate the UV coordinates for your widget, you need to know the pixel coordinates of the upper left and lower right corners of the graphic, and the total width and height of the graphic in pixels. To find the UV coordinates, divide the pixel position by the total width or height of the image. For best results, we recommend that you extend the division out to 5 decimal places when calculating UV coords for the UI. Let's look at an example:

This is a graphic representation of the code example above, which draws a portion of the left side of the Pre-Load UI. This is pg2.tga, shown at half size for illustrative purposes. The top left pixel coordinates of the sidebar are 0,187; since the image is 1024 pixels by 1024 pixels, the x part of the UV coordinate is "0", and the y part is "0.18262" (187 / 1024). THe bottom left pixel coordinates are 110, 600; this results in UV coords of 0.10742, 0.58593.