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.

Various specialized tools exist as well:

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

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, suppports model set 1 only, and buggy.

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

Sector preview images provided by TerraTools may be useful when editing the typ_map section. These packs contains some errors, however.
New version
Old version, probably more errors

There is also a set of high-quality preview images for sky textures available:
Sky screenshots by Doomfrost

For hexadecimal-decimal conversion there are many online tools available. The new versions of Windows Calculator can convert them, and there is also a stand-alone converter available:
BaseConv (requires .NET Framework 4)

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.

Factions

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

  • 0 = Undefined, using this as a faction is possible but will result in glitches
  • 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.

Notes on briefings and names

Mission briefing texts as well as level names are loaded by language.dll from its resources. Editing them is not covered in this article. If a name doesn't exist in language.dll 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 not covered in this article. Check existing levels for reference.


Main level information

This section defines the core parameters of the level.

begin_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
end

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 packages which contain VBMP bitmaps. Sky preview images are available for modders.

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.

title_default
title_deutsch
title_english
Titles are normally loaded by language.dll from its resources. These titles here are only used when a title is not defined in language.dll.

ambiencetrack defines the background music track. The first number is the track number (from 2 to 6), 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 (max 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 be edited unless you know what you're doing.
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.

begin_mbmap
    name         =  MB_40.IFF
    size_x       = 480
    size_y       = 480
end
begin_dbmap
    name         =  DB_40.IFF
    size_x       = 480
    size_y       = 480
end

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.

begin_gate
    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
end

Section keywords

begin_gate starts a beam gate definition.
end ends it.

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

closed_bp
opened_bp
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.

keysec_x
keysec_y
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.

begin_robo
    owner        = 1
    vehicle      = 56
    pos_x        = 14963
    pos_y        = -330
    pos_z        = -35288
    energy       = 1000000
    reload_const = 165625
end
begin_robo
    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
end

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).

pos_x
pos_y
pos_z
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.

con_budget
con_delay
Conquering sectors

def_budget
def_delay
Defending itself with units

rec_budget
rec_delay
Reconnaissance with scouts

rob_budget
rob_delay
Attacking enemy host stations

pow_budget
pow_delay
Building power stations

rad_budget
rad_delay
Building radars

saf_budget
saf_delay
Building flak stations

cpl_budget
cpl_delay
Moving from one place to another


Stoudson bombs

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

begin_item    
	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
end

Section keywords

begin_item starts a Stoudson bomb definition.
end ends it.

sec_x
sec_y
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 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.

countdown defines the countdown time in milliseconds, however, this is inaccurate.

keysec_x
keysec_y
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 definition.

Notes on type 2 Stoudson bomb

The type 2 Stoudson bomb is internally called “Stoudson Wave” and it's sometimes used (Total Chaos campaign for example) for special effects. (NOTE that the “Stoudson Wave” in Zircon campaign is just a renamed type 1 bomb with different effects!)

It has sound effects and it counts down like standard bombs but it does not have any visual effects and it doesn't destroy anything. FIXME »destruction to be checked, long time since I saw these last time…« 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.

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

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.

pos_x
pos_z
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. Look for existing levels for reference.

Modifications

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

These follow the standard script format which is covered in another article.


New units

Editing this part requires knowledge of the script engine and is not recommended unless you really know what you're doing.

It is possible, although rare, to include new unit (vehicle/weapon/building) data into 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.

Another way is to include custom scripts 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 rare and needs more complex code. Note that user units in single player are often not defined here.

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

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:

begin_gem
    sec_x        = 18
    sec_y        = 16
    building     = 50
    type         = 2                 
        begin_action
        	modify_vehicle 2
			add_energy = 200
        		add_shield = 4         
        	end
    	end_action
end

Example of a multiplayer upgrade:

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

Section keywords - common

begin_gem starts a tech upgrade definition.
end ends it.

sec_x
sec_y
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 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 is probably more useful even though it has numbering errors and some wrong sectors. Editing typ_map needs lots of trial and error.

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 to both upwards and downwards. If you start from 0 and want to make trenchs 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).

begin_maps
; ------------------------------------------ 
;--- 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 ---
; ------------------------ 
end

References

Level guide by TerraTools. (German version with images )

Level guide by O Y ME

Level guide by Tigerhawk71

modding/ldf_file.txt · Last modified: 2013/12/05 16:52 (external edit)
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