Modding MechCommander - ABL's scripting extracted mission files tutorial

Hello dear MechCommanders,
today i would like to add this article about abl scripting missions in MechCommander. First of all i will begin with an overview and introductions in order to explain, how mission files are used by the game and what files are needed to mod them. Mission files are to find in the MechCommander's root game folders where although the *.exe files are. In the original version all mission files are stored in ONE big *.fst file. Although called *.fst library. Mission files that are created with the MC Editor come in two versions. One is the actual *.fst file for the single mission, the other is a *.dpk file, containing the same content but containing the uncompressed *.sol/*.mpk of the related mission for "distribution". So when you use *.fst mission files for sharing, keep in mind that they don't contain any *.sol/*.mpk files. When you would like to play the mission in solo- or multiplayer- modes you need to copy the *.sol/*.mpk file manually into the "DATA\SAVEGAME\*.sol/*.mpk" folders. That although means that *.FST files always come as two files when they are used to be shared to others ( MC_ROOT_FOLDER\*.fst & MC_ROOT_FOLDER\DATA\SAVEGAME\*.sol/*.mpk). A *.fst file can although have both - one *.sol file and one *.mpk file - that would allow to use the mission for singleplayer, as well as multiplayer scenarios. Of course those maps have to be designed in a way that they can be used for both (drop-zones, team drop-zones, artillery crates... ).

Basically a complete mission should contain those files when they are not extracted:

1. MissionName.DPK ---> this file contains ALL mission files needed for modding, but game only can use *.FST files so this is just a file for distribution that is useless for players without a working Mission extractor that puts the *.FST version & the *.sol/*.mpk into their places
2. MissionName.FST &
   MissionName.sol or/and MissionName.mpk ---> those files are needed to implement a *.FST file used by the game

When you work with the original source, you will always face those files when it is about modding missions in MechCommander. The original mission files for MechCommander as well as the customer made missions and the MSZone "Dropship Command" missions are all shared as *.DPK or *.FST packages. The only existing extracted mission source for MechCommander you can find on github (the original code and *.fst files from the basic game) or here on ModDB while downloading my "Extracted Mission Source" for MechCommander Gold - Darkest Hours v4.x.

But when you would like to mod existent *.FST or *.DPK files you have to extract them yourself. There are several tools available for extracting any mission source or certain files out of any *.DPK or *.FST file you want to work with. The tools for modding MechCommander you can find here. In the first place i was used to cMunsta tools for working with Mission files. But there is an exception. For "extracting" mission files i use "Tigress's tools". The Tigress Tools for MCG contain a tool (MCGTools.EXE) with a simple UI that allows to extract any *.FST or *.DPK file. It works brilliantly. But for recompiling them into *.FST/*.DPK files i use cMunsta tools again, cause the way cMunsta build his packing tool is more comfortable to me using MC Shell for the most file creation processes. But anyways - tigress tools use cMunsta functions - so it's basically obsolete what of both you may use. I experienced less issues by leaving most of the Tigress tools unused, cause they may have unintended sideeffects - i simply don't know what else entries those tools change so i prefer to do most of the modding work manually.

A complete extracted mission source looks this way (standard file arrangement):

Mission *.FIT & *.ABL (*.ABL=*.ABI) files

• c** Data\MISSIONS\campaignMissionName.FIT
  ---> this is the head / title file for each mission - it contains data for single player campaign and solomission game modes
• c Data\MISSIONS\MissionName.ABL
  ---> Mission ABL functions - this file contains the used *.ABL code for the mission functions, it contains functions for mission objectives, timers and includes all other "include" files below cause this file is the "ABL-headmaster" file used by the MC game engine while executing / during mission
• c Data\MISSIONS\MissionName.FIT
  ---> Mission.FIT file - i call it MasterMission file cause this planetext file contains all relevant settings for editing mission setup in general. This file defines several technical settings for the mission as well as air support, dropweight, dropzones, mission objectives (only frame settings for objectives - functions for objectives are to be found above (*.ABL file of mission), AI, allied & additional player units, positions on map, used NPC A.I. unit brains (warriorbrains), used BattleMechs & Vehicles and mover groups in inmission battlefield - for modding a mission an understanding of this file is a must - this file is directly related to the missionParamater file (WarriorBrains - containing all listed warriors of Mission.FIT)
• c Data\MISSIONS\MissionName.TXT
  ---> Mission Briefing Text - this file contains the briefing text message that is displayed in the logistics menu before mission launch
• c Data\MISSIONS\MissionName_INIT.ABI
  ---> Initiaion include - entries for objectives, functional buildings, salvage & added player units - this file needs to be synchrone to it's mission's variable include file but the entries are not the same - this file contains more detailed entries for salvage and buildings - the salvage itself is predefined here - what weapon and how many contain an object
• c Data\MISSIONS\MissionName_LOP.ABI
  ---> Lookout point include - predefined lookout points (reach area X - reveal area Y) - often used by modders for additional functions like functions related to new player units/mechwarriors
• c Data\MISSIONS\MissionName_MP.ABI
  ---> Multiplayer include - multiplayer mission functions (can be left untouched for sologaming)
• c Data\MISSIONS\MissionName_STR.ABI
  ---> Structure include - functions of buildings, connections turrets <-> towers <-> powe supply & additional functions
• c Data\MISSIONS\MissionName_VAR.ABI
  ---> Variable include - entires for objectives, functional buildings, salvage & added player units - this file needs to be synchrone to it's mission's initiation include file but the entries are not the same - this file contains only static boolean & eternal integer entries for the mission scenario
• c Data\MISSIONS\WARRIORS\MissionNameParams.fit
  ---> mission brain parameter files for NPC orders, waypaths & behaving/acting, those are the warriors from the warriorlist in the Mission.FIT file above the total count of warriors in this file needs to be equal to "NumWarriors = xx " in the Mission.FIT file and the order must be the same (number ID)
• u** Data\SAVEGAME\MissionName.sol/*.mpk
  ---> Only in *.DPK mission packs! - Start file for solomissions or multiplayer game modes

Mission Terrain files

• c Data\TERRAIN\MissionName.BDG
  ---> Binary file with the buildings location and offsets.
• c Data\TERRAIN\MissionName.DAT
  ---> Binary File. i don´t know what it is. It has some height value a some other value for each Tile
• c Data\TERRAIN\MissionName.ELV
  ---> Binary file with the has the : height, TileID, OverlayID and some extra stuff
• c Data\TERRAIN\MissionName.FIT
  ---> Text file Size of the map and what type of Tiles to look, regular or expansion
• c Data\TERRAIN\MissionName.GMM
  ---> Binary file. This it´s a really complex file. Mostly stuff for Movement on the map and Definition of Zones & "Doors". It´s similar of the one used on MC2 but it has differences Github.com
• c Data\TERRAIN\MissionName.LOG.TGA
  ---> Image file small size for in-mission HUD
• c Data\TERRAIN\MissionName.OBJ
  ---> Binary file with Misc Objects location and offsets.
• c Data\TERRAIN\MissionName.PRE
  ---> Binary file that has the Initial TileIDs / preferences to preload
• c Data\TERRAIN\MissionName.TGA
  ---> Image file for briefings

** = c = file is compressed in *.FST/*.DPK || u = file is uncompressed in *.DPK

For modding the Terrain files in MechCommander i recommend using the in-built MC Editor. In general those terrain files can be although edited with other mapping software - if it may read the files. I have heard that some C&C mod tools can do this job. I myself use only the MechCommander Editor and Extender with their functions in order to...

• edit buildings & infrastructure
• linking buildings (turrets <-> towers <-> generators)
• buildings status (health, side, salvage)
• Creating mission objectives and basic *.ABL code
• Adding new MechWarriors
• Getting coordinates in order to manually add units or salvage
• placing units
• creating XXL images of the entire maps
• some more basic functions

... manually you can not do much with objects on the map cause you don't have any coordinates or references in the source files. For modding missions and functions the terrain files are not needed anyways. You can do most of the modding part just by working on the Mission.fit / *.abl files above. I found out how you can work around maximum unit limits on maps - explained below - it is done via ABL scripting.

Actually i'm trying to find out how to create and use larger maps, than basic editor allows. There are existing some XXL maps that could not be created by the original map editor. So i guess there are other solutions to work on those files i didn't get yet.

To do things like adding more units to a map (45 was the original editor limit) you need to manually change and edit the basic abl codes in the Mission *.FIT & *.ABL files that are listed above. To work around the unit limit you can use the editor for example to place 45 mechs on a map, save that map, then again load the terrain files without mission data, add 45 units again and then save this under another mission name. Now you just need to open the Mission.FIT file in mission folder and the MissionParameter file warriors folder. The warriors, parts, mover groups needs to be updated and written clean into the code. Of course you need to renumber the added units from the 2nd mission file you renamed. So warrior 1 will be warrior 46 then - and part 1 will be part 46 then. The mover cell groups can be added to the end of the file - but you have to keep in mind that each group can only exist once - so Group 1 of the second mission files need to become group 5 when there are 4 groups in the first mission - and so on. By combining the content of units in mission 1 & 2 you just need to edit those two files. Although keep in mind that the game will crash when you place to units too close next to each other or in the same place - so better keep distances between units and dont use the same spaening coordinates twice, otherwise = Access violation. The maximum of enemy units is approximately ~200 by using this workaround. This is although the same way the Editor Extender can add additional mission objectives to a certain mission. All you need to do to create 8 mission objectives is to make objectives 5-8 in the editor first, save the mission, then copy 5-8 over mission objective slots 5-8 - switch back to the original editor, create mission objectives 1-4, saving - and then switch back to extender and update extender mission objective entries. So sad they didn't added this function for units on a map - would making adding units way faster.

For any imagineable other modding procedure in missions you need to manually use *.ABL functions from the pre-defined libraries of the game. You can find the *.ABL libraries here. The code itself contains many clear planetext with descriptions and explanations what makes *.ABL coding a bit more comfortable while Modding MechCommander.

Articles

Beginner's Guide
Player's Guide
MCGold.iso & Downloads (look into the description)
Overview - All MechCommander standalone version (pre-installed game folders)
What is MechCommander?
MechCommander Gold - Darkest Hours Free Fullversion Download (Patch v4.2)
What is Darkest Hours all about?

Downloads

You can find ALL MechCommander Downloads here & here

(c) by RizZen 2020