Level files

LDF files - Level Description Files - define every level you play in the game. This article explains how to edit and create them.

File locations

/<leveldir>/single/ contains single-player levels

/<leveldir>/multi/ contains multiplayer levels

/<leveldir>/mbpix/ contains mission briefing and debriefing maps in IFF/ILBM format - these are not covered in this article

/<leveldir>/bg/ contains level selection masks, menu backgrounds etc. in IFF/ILBM format - these are not covered in this article

Editing tools

Level files are plaintext files so they can be edited using a standard text editor. Examples include Windows Notepad, WordPad and Notepad++ (recommended). For Notepad++ users there's a syntax highlighting plugin available.

For hexadecimal-decimal conversion, you can use Windows calculator. Choose “programmer” mode from the menu.

Various specialized tools exist as well:

UA Level Reader by leftylink generates XLS worksheets from level files. Download here. See also Level maps page.

Random Level Generator by AOE_Danny - generates random levels. Contains many options for different levels.

Sector preview images are useful when editing the typ_map section:
Sector images This package has correct sector numbers. The original sets of images, still found somewhere, contain errors.
Sector image charts This package contains one big image per set, with all available sectors in one image.

There are also two sets of high-quality preview images of sky textures available:
Sky screenshots by Doomfrost
Sky screenshots by Bronsteijn24k

windsgn.exe, the official level editor of UA developers, was uploaded to the internet by an user who got it in an auction. See the thread for more information.

Historical tools

Typ_map designer by Allan Glenn - a GUI tool for typ_map section editing. Incomplete, supports model set 1 only.

UA Level Compiler by Allan Glenn - a GUI level editor with more features. Incomplete and buggy, suppports model set 1 only.

Level numbering

The levels are internally recognized by their numbers which range from 1 to 255. (Using number 0 will probably result in problems, but this has not been tested.) The level number must be included in the level file name twice and the name starts with L. Numbers 1…9 must have leading zeros. Examples:

L0101.ldf → level 1
L5252.ldf → level 52
L163163.ldf → level 163

Single player levels are recognized by their numbers as color indices in the level selection mask but this is not covered in this article.

FIXME It has been reported that having more than 127 levels in the multiplayer level directory will cause problems.


Long lists such as complete vehicle and building numbers are not included in this article but faction numbers are always needed:

  • 0 = Neutral, using this as a faction is possible but it does not work like other factions. Most importantly, AI units of other factions will ignore it. It may also have unknown glitches. Functional buildings can't be assigned to faction 0 (see the map dumps section later).
  • 1 = Resistance
  • 2 = Sulgogars
  • 3 = Mykonians
  • 4 = Taerkastens
  • 5 = Black Sect, invisible units (invisibility hard-coded)
  • 6 = Ghorkovs
  • 7 = Drones, has primitive icons (can be changed)
  • Trying anything above 7 will lead into problems.

Coordinate system

There are two different coordinate systems used to define object locations in the level.

Sector-based coordinates are used for big, static objects such as beam gates and tech upgrades. The top left corner inside the borders is (1,1). Modders don't usually have to care about the outer (border) corner as it's outside the playable area. X-coordinate increases from west to east and Y-coordinate from north to south.

Host stations and squads use the more accurate coordinate system which allows placing them almost freely on the map. A sector has a width and height of 1200 units and the top left corner is (0,0). X-coordinate increases from west to east but the north-south axis is Z and it decreases from north to south so the Z value is always negative. Note that the border sectors must be included, i.e. the top left corner inside playable area is (1200, -1200). Y-coordinate is used with host stations to define the height relative to ground and it is negative as well. Also note that X and Z-coordinates should not be divisible by five, especially on sector boundaries, as this can cause problems according to earlier modding guides.

Notes on briefings and names

Mission briefing texts as well as level names are loaded by the language system. The language system is not covered in this article. If a name doesn't exist in the language file, then a name defined in the level file is used.

LDF file structure

The information in level files is divided into sections which are fairly easy to understand.

Headers and comments

As with most UA files, semicolon (;) is a comment tag and everything after it will be skipped by the game.

The level usually starts with a header section which contains information about the level, list of changes and names of the authors. As it consists entirely of comments, it doesn't affect gameplay at all.

Notes on included scripts

Most levels include a script (can include more than one) which is loaded when the entering the level. These scripts load more scripts which initialize certain units and buildings. The script engine principles are covered in another article. Check existing levels for reference.

Main level information

This section defines the core parameters of the level.

    set  = 4
    sky  = objects/Nacht2.base
    slot0        = palette/standard.pal
    slot1        = palette/red.pal
    slot2        = palette/blau.pal
    slot3        = palette/gruen.pal
    slot4        = palette/inverse.pal
    slot5        = palette/invdark.pal
    slot6        = palette/sw.pal
    slot7        = palette/invtuerk.pal
    title_default        = MOONLIGHT_CITY
    title_deutsch        = MOONLIGHT_CITY
    title_english        = MOONLIGHT_CITY
	ambiencetrack   = 	5_00_15000

Section keywords

begin_level starts the section
end ends the section

set defines the model set used in the level. Stock sets are numbered with 1…6. (Note: set 46 is an interface set, not a valid model set)
sky defines the sky texture. The textures are stored in /<datadir>/objects/ as BAS files which contain the sky dome model and one or more VBMP bitmaps. Sky preview images are available for modders, see the tools section above.

slot0 … slot7
Every level must contain 8 slots which define certain color palettes. Leave these untouched or copy them from an existing level unless you really know what you're doing.

Titles are normally loaded by the language system. These titles here are only used when a title is not defined in the language file.

ambiencetrack defines the background music track. The first number is the track number (from 2 to 6 in the original game), second is minimum break in milliseconds and third is maximum break in milliseconds.

event_loop defines the tutorial level events and announcer voiceovers (numbered from 1 to 3). The loops are hard-coded and using them in other levels is very rare and not recommended. The audio files can be edited but it's not covered in this article.

movie defines a video file which is played when entering the level. Example: mov:tut1.mpg
win_movie defines a video file which is played when successfully exiting the level via a beam gate.
lose_movie defines a video file which is played when your host station gets destroyed in the level.
Movies are only used in single-player levels.

unit_limit defines the unit limit (maximum number of units)
unit_limit_type defines the unit limit type (0…2)
unit_limit_arg defines the special limit argument which is a percentage value
The unit limit is only used in multiplayer levels. If not defined, the game uses the default limit which is defined in world.ini configuration file and should not usually be changed.
The unit limit types are:
0 = fixed limit which cannot be exceeded.
1 = when exceeded, power stations become less efficient by a percentage value defined in argument
2 = when exceeded, units become more expensive by a percentage value defined in argument

slow_connection = yes is used to indicate that a multiplayer level is playable over slow connection such as dialup. This is largely obsolete nowadays.

Briefing and debriefing maps

These sections define the background maps used in briefing and debriefing.

    name         =  MB_40.IFF
    size_x       = 480
    size_y       = 480
    name         =  DB_40.IFF
    size_x       = 480
    size_y       = 480

Section keywords

begin_mbmap begins a briefing map definition. Only used in single player levels.
begin_dbmap begins a debriefing map definition.
end ends these sections.
name defines the file name. The files are stored in /<leveldir>/mbpix/.
size_x defines the map width in pixels.
size_y defines the map height in pixels. The size parameters are sometimes omitted and FIXME → it's not known when it is allowed.

Beam gates

Beam gates are used to exit the level. They are only used in single player levels. A level can contain multiple beam gates but levels with more than two are rare.

    sec_x        = 5
    sec_y        = 10
    closed_bp    = 5
    opened_bp    = 6
    target_level = 50		; Death Valley
    target_level = 51		; Dark Valley
    keysec_x     = 16
    keysec_y     = 16
    keysec_x     = 10
    keysec_y     = 10

Section keywords

begin_gate starts a beam gate definition.
end ends it.

These define the location of the gate in sectors. See Coordinate System for more information.

These define the opened and closed model (appearance) for the gate. The numbers point to the building scripts. The standard gates are 5 (closed, with intersection), 6 (open, with intersection), 25 (closed, without intersection), 26 (open, without intersection).

target_level defines a level number which is opened after passing through the gate. A beam gate can have more than one target level.

These pairs define the key sectors similarly to the main gate sector. A beam gate can have 16 key sectors at maximum.

mb_status = unknown is used to hide the gate in mission briefing. Using it on beam gates is relatively uncommon. FIXME

Host stations

The host station definitions are usually put after beam gates. Single player and multiplayer levels have some major differences in this section.

A single player level can contain 8 host stations at maximum. The first station is the user host station and the others are controlled by the AI. The AI stations should have budgets, otherwise they may just sit and do nothing.

A multiplayer level can have 4 host station definitions at maximum and the allowed factions are 1 (Resistance), 3 (Mykonians), 4 (Taerkastens) and 6 (Ghorkovs). Only one host per faction is allowed and none of the hosts has budgets.

    owner        = 1
    vehicle      = 56
    pos_x        = 14963
    pos_y        = -330
    pos_z        = -35288
    energy       = 1000000
    reload_const = 165625
    owner        = 2
    vehicle      = 61
    pos_x        = 43613
    pos_y        = -330
    pos_z        = -11757
    energy       = 1000000
    reload_const = 666666
        con_budget      	=       99
        con_delay               =       300
        def_budget      	=       99
        def_delay               =       200
        rec_budget      	=       90
        rec_delay               =       4000
        rob_budget      	=       70
        rob_delay               =       500 
        pow_budget		= 	0
        pow_delay               =       00
        rad_budget 		= 	0
        rad_delay               =       00
        saf_budget 		=	0
        saf_delay               =       00
        cpl_budget      	=      	10
        cpl_delay               =       00

The first example shows a player-controlled host station and the second an AI-controlled host station.

Section keywords

begin_robo starts a host station definition.
end ends it.

owner is the faction to which the station belongs.

vehicle is the vehicle type. Host stations are usually defined in robos.scr (single player), net_robo.scr, inetrobo.scr (multiplayer).

These are the coordinates as explained in the coordinate system part. Note that the height (Y) is relative to the ground below the station, not to a certain fixed or averaged height value. Also note that X and Z coordinates should be non-divisible by 5.

energy defines the energy of the host station. Note that the defined value is 100 times the value that appears in the game, and the value must be divided by 4 to get the energy of each battery. Or: battery energy * 4 * 100 = defined value.

reload_const The reload constant or Drak constant defines the maximum energy recharging rate. FIXME »calculations coming later…«

viewangle is mainly used in multiplayer levels and it defines the direction of the station camera in degrees when the level is loaded. This is usually not used in single-player levels.

mb_status = unknown is used to hide the station in the mission briefing. It's usually put after the budgets but it should work before them as well.

Budgets and delays

Budgets and delays determine the behavior of AI stations. Delay values define the time in milliseconds after which the particular action begins. The budgets are percentage values of time ← FIXME used for each action.

Conquering sectors

Defending itself with units

Reconnaissance with scouts

Attacking enemy host stations

Building power stations

Building radars

Building flak stations

Moving from one place to another

Stoudson bombs

Stoudson bombs, often called “superitems” in comments, are usually defined after the host stations.

	sec_x		= 15
	sec_y		= 11
	inactive_bp	= 35
	active_bp	= 36
	trigger_bp	= 37
	type		= 1
	countdown	= 180000
	keysec_x	= 13    
	keysec_y	= 18
	keysec_x	= 5    
	keysec_y	= 17
	keysec_x	= 18  
	keysec_y	= 13

Section keywords

begin_item starts a Stoudson bomb definition.
end ends it.

These define the location of the bomb in sectors, similar to beam gate.

The following keywords define the model (appearance) of the bomb in inactive, active and exploded state. The numbers are decimal and point to building scripts.
inactive_bp Standard models: 35 for Stoudson bomb, 68 for the Parasite
active_bp Standard models: 36 (bomb), 69 (Parasite)
trigger_bp Standard models: 37 (bomb), 70 (Parasite)

type is the bomb type which is usually 1. Type 2 bombs work to an extent but do not have much effect on the game and may have glitches. See below.

countdown defines the countdown time in milliseconds. However, the correct conversion factor is 1024, not 1000. So if you want to set the countdown to 1 minute, the correct value is 60 x 1024 = 61440. This is probably an intentional choice made by the developers and it was discussed in this forum thread.

These pairs define the locations of the trigger sectors, just like beam gate key sectors. You can include 16 keysectors at maximum. Note that the key sector models don't have separate model definitions.

Notes on type 2 Stoudson bomb

The type 2 Stoudson bomb is internally called “Stoudson Wave” and it's sometimes used by modders as a gimmick. (Note: The “Stoudson Wave” in the Zircon campaign is just a renamed type 1 bomb with different effects!)

It counts down and plays its announcer lines like standard bombs but it does not have any visual effects and it does not destroy anything or affect the sector ownership. Since it is not used in the original levels it may have unknown glitches.

Predefined squads

Predefined unit squads are usually put after the Stoudson bombs. A level can have 96 squads at maximum.

    owner        = 6
    vehicle      = 28
    num  = 4
    pos_x        = 4367
    pos_z        = -12467
    mb_status	 = unknown

Section keywords

begin_squad starts defining a squad.
end ends it.

owner sets the faction that owns the squad.
vehicle defines the vehicle type which the squad consists of.
num defines the number of units in the squad. A squad can have 32 units at maximum.

useable is used for AI squads and it defines that the AI can use the squad, i.e. send it somewhere. Note that it doesn't have a value and that the word really is useable, not “usable”. If it is not defined the squad will stay on place.

These define the location of the squad, see Coordinate System. Note that the numbers should be non-divisible by 5.

mb_status = unknown hides the squad in mission briefing.

Unit modifications

The unit (“prototype”) modifications section contains script snippets that modify certain vehicles, weapons and sometimes buildings FIXME »buildings are rare?«. Putting them into multiplayer levels is rare.

Included scripts

The section usually starts with an included script that loads more scripts to initialize certain vehicles, resetting all previous changes. An example is shown below, but look for existing levels for reference. Script engine principles are covered in another article.

include data:scripts/startup2.scr


modify_vehicle 	56
    shield       = 40
modify_weapon 121
    start_speed     =       0
         force                   =       20000
maxrot                  =       6   		

These follow the standard script format which is covered in other articles. For example, see the vehicle scripts article.

New units

It is possible, although rare, to include new unit (vehicle/weapon/building) data in a level file. This has been tested for multiplayer levels but it might work with single player levels as well. The entries follow standard script format which is documented elsewhere. For example, see the vehicle scripts article. Understanding the script engine principles is important.

Another way is to put the unit data into a new script file and include it somewhere in the level file.

Unit enabling

Units that can be used on the level are usually defined next. Enabling can also be set in modifications but it is less common and requires more commands.

FIXME Note: When this section is used for a faction, it will reset the enabling data of that faction. For this reason, the player's units are usually not defined here in single player.

begin_enable 3
    vehicle = 64
    vehicle = 65
    vehicle = 66
    vehicle = 67
    building = 13

Section keywords

begin_enable starts an enabling section. The number tells the faction for which to enable. Note that there's no equality sign after the keyword.
end ends the section.

vehicle enables a vehicle
building enables a building

Tech upgrades

Tech upgrades, internally called “gems”, are usually defined after enabling. Single-player and multiplayer upgrades have significant differences.

Example of a single-player upgrade:

    sec_x        = 18
    sec_y        = 16
    building     = 50
    type         = 2                 
        	modify_vehicle 2
			add_energy = 200
        		add_shield = 4         

Example of a multiplayer upgrade:

    nw_vproto_num        = 15_28_0_0
    nw_bproto_num        = 0
    sec_x        = 5
    sec_y        = 6
    building     = 50
    type         = 3

Section keywords - common

begin_gem starts a tech upgrade definition.
end ends it.

These define the location in sectors, see Coordinate System.

building defines the upgrade center building model. The number points to building scripts.

type defines the upgrade “type” aka the voiceover which is played when the upgrade is captured. Voiceover types are:
0 = universal/generic (mostly multiplayer)
1 = weapon upgrade (mostly single player)
2 = armor upgrade (mostly single player)
3 = new vehicle
4 = new building
5 = radar upgrade (mostly single player)
6 = combined vehicle and building (mostly multiplayer)

mb_status = unknown can be used to hide the upgrade in mission briefing (single player).

Vehicle/building lists - multiplayer

Multiplayer upgrade should often give different units depending on the faction that captures it. This is achieved with two types of lists:

nw_vproto_num is a list of four vehicle numbers.
nw_bproto_num is a similar list of building numbers.

The first number goes for Resistance (1), second for Ghorkovs (6), third for Mykonians (3) and fourth for Taerkastens (4). FIXME »double check…«

If there is no vehicle/building for the particular faction, zero should be used. If there are no vehicles/buildings for any faction the list can be replaced with a zero.

Action section - single player

Single player upgrades can implement more complex modifications. They do not give anything to AI factions.

begin_action starts the action section.
end_action ends it.

The action section contains script snippets that modify certain units. You can put any valid script data here but note that only those parameters that are stored in user.txt file are preserved when loading another level.

The script format is documented elsewhere but the special keywords that are often used with and only with tech upgrades are given here. See the examples and existing levels for information on how to write proper “actions”.

modify_vehicle X
modify_weapon X
modify_building X
These start an action.
end ends it.

enable = X enables the unit for faction X (vehicles, buildings)
add_energy changes the energy of the unit by given value. Note that the real energy is 1/100th of the defined value. (vehicle energy, weapon power)
add_shield changes the armor of the vehicle by the given value. Note that here the defined value is the real value.
add_shot_time changes the AI reload time by given value in milliseconds (weapons)
add_shot_time_user changes the player reload time of a weapon by given value (weapons)
add_radar changes the radar range of the unit by given value. (vehicles)
FIXME → add all special keywords if there are more

Map dumps

The map dump section is the last part of the level. The dumps contain the level terrain, buildings and ownership assignment per sector. See the example at the end of this paragraph for correct format.

begin_maps starts the map dump section.
end ends it after all dumps are defined.

typ_map starts the typ_map section which contains terrain textures and static buildings.
own_map starts the ownership map which contains ownership information of each sector.
hgt_map starts the height map which defines the height of every sector.
blg_map starts the building map section which contains functional buildings.

After each keyword there are two decimal numbers which define the size (x, y) of the map in sectors. As you might guess every dump must have the same size. The border sectors are included in the size (see typ_map section for more information).

The actual map dumps are in hexadecimal format. Ownership map can only contain values 00…07 so the numbers are the same as decimal but in other sections you have to do conversions. Note that in other sections the valid numbers are 00…FF (0…255), and numbers 00…0F (0…15) always have leading zeros.

typ_map - terrain and static buildings

Typ_map section defines the static buildings and terrain structures per sector. The numbers point to sector models that are defined in SET.SDF files. You can use these files as a reference but the sector image pack (see tools section above) is probably more useful. Editing typ_map often needs lots of trial and error. Debugging can be difficult - if a non-existent sector number is put into typ_map, the game will crash and not provide any useful information about the reason.

The boundary areas are often covered with the energy wall sectors. (See existing levels for correct values.) This doesn't have to be the case, but using other sector types doesn't still allow you to go outside the level - the real, invisible border is hard-coded.

own_map - ownership assignment

The ownership map is simple - the numbers are just faction numbers and define the owner of every sector.

The border zone is often assigned to faction 0 but this is not always the case. Assigning it to another faction may affect its energy absorption.

hgt_map - height information

The height map defines the terrain height of every sector. It is pretty simple but note that the “base height” or “sea level” is often about 127 - this allows easy adjustments both upwards and downwards. If you start from 0 and want to make trenches you have to raise all other sectors.

blg_map - functional buildings

The building map contains functional buildings such as flaks and power stations. It has usually relatively few objects but there are some quirks that should be taken into account.

First: The numbers in the map are hexadecimal but they point to building scripts which are always decimal.

Second: blg_map overrides typ_map.

Third: Special building definitions (beam gates, Stoudson bombs, tech upgrades) override blg_map and do not need a number in blg_map. However, a number is often put into blg_map for clarity.

Fourth: 00 is not a valid owner for a blg_map building. If the sector owner is 00 the blg_map part for that sector will be ignored. Neutral power stations are usually assigned to faction 07 (Drones).

; ------------------------------------------ 
;--- machine generated map dumps, go away ---
; ------------------------------------------ 
    typ_map =
        10 10
        f8 fc fc fc fc fc fc fc fc f9 
        ff af ad 2a af ba ba 11 ae fd 
        ff b3 b1 2b b4 b8 ab 22 bc fd 
        ff 97 19 1f 08 1b 28 83 05 fd 
        ff 09 87 1c 06 02 31 84 07 fd 
        ff b3 ba b9 b6 86 84 85 08 fd 
        ff b3 0c a6 b6 87 86 c9 09 fd 
        ff b3 ca 0d 0c 13 ba ba ab fd 
        ff ac b7 b7 b1 1e ac ab 1c fd 
        fb fe fe fe fe fe fe fe fe fa 
    own_map =
        10 10
        01 01 01 01 01 01 01 01 01 01 
        01 06 06 06 06 06 06 06 06 01 
        01 06 06 06 06 00 00 01 01 01 
        01 06 06 06 06 00 01 01 01 01 
        01 06 06 06 06 01 06 01 01 01 
        01 06 06 06 06 01 01 01 01 01 
        01 00 00 00 06 06 06 06 06 01 
        01 00 00 00 06 06 06 06 06 01 
        01 00 00 00 06 06 06 06 06 01 
        01 01 01 01 01 01 01 01 01 01 
    hgt_map = 
        10 10
        7f 7f 7f 7f 7f 7f 7f 7f 7f 7f 
        7f 7f 7f 7f 7f 7f 7f 7f 7f 7f 
        7f 7f 7f 7f 7f 7f 7f 7f 7f 7f 
        7f 7f 7f 7f 7f 7f 80 7f 7f 7f 
        7f 7f 7f 7f 7f 7f 7f 7f 7f 7f 
        7f 7f 7f 7f 7f 7f 7f 7f 7f 7f 
        7f 7f 7f 7f 7f 7f 7f 7f 7f 7f 
        7f 7f 7f 7f 7f 7f 7f 7f 7f 7f 
        7f 7f 7f 7f 7f 7f 7f 7f 7e 7e 
        7f 7f 7f 7f 7f 7f 7f 7f 7e 7e 
    blg_map = 
        10 10
        00 00 00 00 00 00 00 00 00 00 
        00 00 00 00 00 00 00 00 00 00 
        00 00 00 00 00 00 00 00 00 00 
        00 00 00 00 00 00 00 00 00 00 
        00 00 00 00 00 00 00 00 00 00 
        00 00 00 00 00 00 00 00 00 00 
        00 00 00 00 00 00 00 3f 00 00 
        00 00 05 00 00 00 00 00 00 00 
        00 00 00 00 00 00 00 00 00 00 
        00 00 00 00 00 00 00 00 00 00 
; ------------------------ 
;--- map dumps end here ---
; ------------------------ 


Level guide by TerraTools. (German version with images )

Level guide by O Y ME

Level guide by Tigerhawk71

modding/ldf_file.txt · Last modified: 2020/03/31 15:30 by Ormu
Back to top
CC Attribution-Noncommercial-Share Alike 4.0 International
chimeric.de = chi`s home Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0