DCS Reference: Labels

DCS's visual model is… quirky. It uses a rather naive system for drawing units that has the unfortunate side-effect of making things harder to see on better hardware. Higher resolutions make units appear as smaller pixels, and fancy post-processing and anti-aliasing make them indistinct against the background. In BMS such tendencies are counteracted, and other visual cues compensated for, through a system of “smart scaling” that actually provides a better simulation of visual perception.

DCS does not have that. Indeed, according to the developers, it cannot possibly have that since that would create problems with radar (and other sensor) detection. The less said about how hilariously broken and backwards this implementation is, the better.

What DCS has instead is the label system. They're the big ugly things that clutter up your view with tons of overlapping text when all you want is an indication of what's out there at a range where a pilot would be able to identify those details. For spotting, you can turn them into just simple dots, but that still isn't a very neat solution. As luck would have it, you can actually get the benefits of that without any (or at least most) of the downsides by creating your own Labels.lua file.

Labels.lua

The Labels.lua file is where DCS sets up how labels appear on-screen. Like kneeboard images, this file can show up in a number of places but only two actually matter:

• In the %USERPROFILE%\Saved Games\DCS\Config\View directory.
• In a Config\View directory stored in a mission (.miz) file.

The first is used to define how labels will appear to you, unless something else is specified elsewhere. If a Labels.lua file exists here, it will override the default label settings used in DCS. The default can also be changed, but there's never any real reason to do so since the userprofile file exists for the exact reason of letting you personalise labels in an easier way without outright modding.

The second is used to define how labels will appear to everyone playing that mission. It will override any personal labels you might have defined in the aforementioned userprofile directory. Of course, on top of this, a mission can also categorically enforce labels to use a specific setting (full, dots, or completely off). This file and its directories can be added using any regular zip manipulation tool since that's exactly what .miz files are.

This page will dissect the Labels.lua file commonly used on the Even Lamer Goon Server, to explain and provide examples of how you can create your own setup. The original file can be found here, and retains the helpful descriptions included in ED's original file.

When editing this file, use something sensible, such as Notepad++ or BBEdit — something that does not try to be clever and interpretative, but rather simply stores exactly what you type and nothing else.

Basic settings

The Labels.lua file opens up with some very basic settings: what should actually show and what should not.

  4. AirOn			 	= true
  5. GroundOn 		 		= true
  6. NavyOn		 	 	= true
  7. WeaponOn 		 		= true
  8. labels_format_version 		= 1 -- labels format vesrion

To turn a specific set of labels on or off, simply change the respective category value to “true” or “false”. Here, everything is left on. A common request is to turn weapons off — simply change line 8 to say WeaponOn = false.

The last line is what it says on the tin: the version of the labels file format. Leave it at 1.

Formatting and string variables

Next follows a lengthy description of string formatting variables and rules, which will help anyone familiar with Lua strings to formulate pretty much everything else in the file.

Variable	What it means	What it does
%N	Object name	Displays the object/unit type (not to be confused with pilot name), eg. “Su-27” or “T-80”
%D	Distance to object	Displays (surprise) the distance to the object, eg. “8.5nm”
%P	Pilot name	Displays the name of the pilot (or callsign for AI pilots — not to be confused with object name), eg. “Tippis” or “Enfield 1-1”
%n	New line	A manual line break (in case you want to have lots of info but short lines)
%%	The ‘%’ symbol	The % sign is usually used to denote other variables so this is used to actually display a % sign.
%x	To display any other ‘x’ symbol	…and the above can be generalised to show any symbol, eg. %& to show an ‘&’ or %= to show an ‘=’.
%C	Extended info	Various weapon system data

The file also enumerates the various alignment options available when you position text relative to the unit: RightBottom, LeftTop, RightTop, LeftCenter, RightCenter, CenterBottom, CenterTop, CenterCenter, and LeftBottom. These work pretty much exactly the same as the alignment options in an MS Office table.

So RightBottom means the text will be right aligned (i.e. expand to the left from the unit) and will sit below the unit (i.e. expand down). CenterTop means the text will be centred (i.e expand to both the left and right) and be on top (i.e. expand up). CenterCenter will put the label exactly on top of the unit and expand in every direction from there — this may seem like an immediately obvious “right” choice, but will actually misalign the unit symbol in most cases.

Font definition

The font_properties variable sets up 5 things, in order, in a regular comma-separated Lua array:

1. The file name of the font to be used (change this with due caution and dread)
2. Font size (in pixels)
3. X-axis (horizontal) shadow offset
4. Y-axis (vertical) shadow offset
5. Blur type

The blur type can be one of 3 values:

0. No shadow
1. A 3×3 pixel blur
2. A 5×5 pixel blur

The blur will be applied around the text (rather than actually blur the text itself) and can be particularly effective in changing how large (or small) just the single dot of a label will appear. For instance:

 43. font_properties =  {"DejaVuLGCSans.ttf", 13, 0, 0, 2}

The Even Lamer server setup uses the default font, at 13px size, with the shadow placed right behind the text (no offset) but with a 5-pixel blur to make it bloat a bit.

Shadow and blur variations

The differences between having shadow and blue is illustrated below. To distinguish the three more clearly, the base text label is in red, the shadow portion of the label is in green, and the blur effect is in yellow. Note that the blur effect also muddles the shadow underneath it.

In practice, blur is generally set in grey or in a similar colour, but perhaps darker shade, to the label itself, whereas the shadow is set in some shade of grey.

Symbol definitions

The symbol definitions is where the first bit of magic happens. This is where you set up exactly what character (because it is all character based) you want the unit to be marked with. While you can conceivably enter any unicode character, the actual end result is obviously limited by what is provided by the font.

If you want emoji aircraft, you need to change to a font that has emoji characters, and then take responsibility for all the breakage that will ensue.

 45. local aircraft_symbol_near  =  "˄" --U+02C4
 46. local aircraft_symbol_far   =  "˄" --U+02C4
 47. 
 48. local ground_symbol_near    = "ˉ"  --U+02C9
 49. local ground_symbol_far     = "ˉ"  --U+02C9
 50.
 51. local navy_symbol_near      = "˜"  --U+02DC
 52. local navy_symbol_far       = "˜"  --U+02DC
 53. 
 54. local weapon_symbol_near    = "*"  --U+02C8
 55. local weapon_symbol_far     = "ˈ"  --U+02C8
 56. 
 57. local function dot_symbol(blending, opacity)
 58.    return {"˙","CenterBottom", blending or 1.0 , opacity  or 0.1} --U+02D9
 59. end

Each unit category gets a “near” and a “far” symbol — exactly what qualifies as near and far is defined later on and can vary with each class. This lets you set up differently apparent symbols for different ranges, which is particularly handy if you do not want to provide any more on-screen information than the symbol itself.

The “--U+ [etc]” at the end of each line is a Lua comment (denoted by the double minus) that explains which Unicode character is actually being used (denoted by the U+ hexadecimal code). This is not necessary — indeed, being a comment, it's outright ignored by DCS — but is obviously a helpful memory aid if you want to explain or recreate the same look elsewhere.

The last couple of lines define how the “dot symbol” a default character that you can fall back on if nothing else is suitable. It follows standar Lua function definition syntax: if you provide (optionally) two values, it returns an pre-defined array describing what this default dot should look like.

The array itself is the interesting bit. It consists of: a character to be used (just like with the ones defined for different units), a text alignment for that character, a default bending value, and a default opacity value. We'll get to those…

Distance conversions

Metric	Imperial	Nautical		Metric	Imperial	Nautical
305m	1,000'	0.16nm		9,260m	30,381'	5nm
1km	3,281'	0.54nm		10km	32,808'	5.4nm
1,524m	5,000'	0.82nm		15,240m	50,000'	8.23nm
1,852m	6,076'	1nm		18,520m	60,761'	10nm
2.5km	8,202'	1.35nm		20km	65,617'	10.8nm
3,048m	10,000'	1.65nm		27,780m	91,142'	15nm
3,658m	12,000'	1.97nm		30km	98,425'	16.2nm
4,630m	15,190'	2.5nm		30,480m	100,000'	16.46nm
5km	16,404'	2.7nm		37,040m	121,522'	20nm