MOTIVE.

The purpose of this tutorial is to assist people who may be interested in modding Supreme Commander FA version 1.5 3599 but have little or no experience. This tutorial begins with the most basic steps including how to set up Windows Vista and Windows 7 for modding, basic modding tools needed, how to trouble shoot your edits to the game, how to work with the game scd folders and many more areas. The final tutorial section consists of how to create and add a new class of upgradeable Metal Extractor to the game

BE AWARE!!!
This tutorials' primary focus is how to create and add an UPGRADEABLE STRUCTURE using the resources that are already available in the game to the Ai so that it will build and upgrade it via the Ai structure upgrade system. If you are building an upgradeable mobile attack unit such as a tank, plane, ship etc you will need to use a different upgrade system called the ENHANCEMENT UPGRADE system. This is the system the Ai Commander's and Sub Commanders use to upgrade.

INTRODUCTION TO THE MODDING BASICS SECTION.

This tutorial is intended to help people that are new to modding Supreme Commander FA. With that purpose in mind the topic sections of this tutorial are written in a manner that the user even if 100% new to modding any kind of game or may have little to no actual computer knowledge follows the instructions provided in each section by the time the user reaches the final section they will be able to use what they have learned to create their own custom upgradeable structure and add it into the game. Every section contains information that is needed to be able to complete the final section of the tutorial. This tutorial takes into consideration that not everybody is at the same skill level. Some people have never modded before and others will be more experienced .

If you are a more experienced modder and already understand all the basics of working in the mod folder, working with scd folders the log window etc you may want to skip over all the basic training steps and go straight to the upgradeable Mass Extractor blue print section of this tutorial.

WHAT THIS TUTORIAL WILL DO. This tutorial will cover in detail adding and trouble shooting a new upgradeable structure in Supreme Commander FA version 1.5 3599. This will include an overview of certain tools used in this type of modding. It goes into step by step detail of how to set up Windows Vista and Windows 7 for modding, the log window for trouble shooting, How to work with scd folders, the Mod folder system and many other pre requirements that are necessary to learn before you will be able to mod this type of unit.

WHAT THIS TUTORIAL WILL NOT DO.

This tutorial will not cover any actual modeling i.e. Blender, Wings or 3dMAX or any heavy detailed Lua scripting. Any scripting shown here can be done by simply following the steps provided. You do not have to know how to write the code itself. The examples provided will show you how to use the existing code already in the game. The user will only be making minor edits to already existing code.

WHAT IS A MOD?

A mod is anything that changes the behavior or look of a game from its original design. If you add just one line of code that changes a units health. Or you add the color green to the user interface panels replacing the original blue that the game shipped with. You have just created a mod. Looking at it from this perspective anyone can mod. What makes the real difference is the level of skill of the individual modder.

TIPS FOR NEW MODDER'S

1. The most important of all. Do not steal another persons work. This is not a reputation you neither need nor want. Ask permission from other modder's before using their work. Sometimes they say yes some times they say no. But no is no and you should respect their wishes.

2. Keep a mod diary. Sketch out your idea's and write down your thoughts. Try to be realistic in the type of mod you want to create. By realistic this means know your own limitations. You may want to do a full conversion mod but have not yet developed even the most basic of mod skills. You are just going to get frustrated and throw in the towel. Start small with the intent of learning more and then maybe someday you really will do that full conversion mod you always wanted to do.

3. Study the code and the folder and file structure in the game itself. The GPG developers left many comments behind in the various files giving explanations and clues to the inner workings of the game.

4. Down load other peoples mods and study them. Look at how they did things that may help you decide how you want to do things. Or things they did that you may want to avoid.

5. If you release a mod do it with a good Read Me file that clearly explains your mods purpose and how and where to install and uninstall it. There are those who actually do read the Read Me so give them some real content and useful information.

6. Try to make your mod as compatible with other mods as possible. Depending on the type of mod you want to make this may not always be possible. If your mod is not compatible with other mods explain that to the end user in your Read Me file.

MOD WORK FOLDER Create a new folder anywhere that suits you and name it what ever you choose to name it for a work area for your mod files. For Vista and Windows 7 users you should not create this folder in your "Programs86" folder. The desktop is a very convenient place. Creating shortcuts from the work folder to the gamedata folder and the Documents\Mygames mods folder will save you some time moving back and forth between folders. If you want to use the log text tool that will be explained further down then a shortcut to the Supreme Commander FA Bin folder is also very useful. The Bin folder is in the Root Directory of your game. You can also create a shortcut from the Bin folder executable and place it in your gamedata folder to start the game. Use a shortcut from the gamedata to get back to your work folder. Create shortcuts in your work folder to your editing tools. Make spare folders and use them as "Tool Boxes" for creating and storing your own templates and back up files.

WHERE TO FIND HELP AND INFORMATION .

There are bits and pieces of information covering just about any and every aspect of scripting and unit modding available in the Mod Developer Support forum at,

http://forums.gaspowered.com/viewforum.php?f=19&sid=72c4d9410735b0eb67c640c1cdc0ca58

The SEARCH FUNCTION there is your friend. The Mod Developer Support forum contains a wealth of information covering every aspect of modding units and script coding for the game but there is no real clear cut one post covers all type of thing such as concerning adding an upgradeable structure although some posts are fairly detailed still they do not cover every aspect. What happens in the support forum is a person runs into a specific problem and posts for help. Once the specific problem is addressed that is usually the end of the thread. You have to search multiple threads to get a broader perspective of the various problems that involve a particular aspect of a modding project.

BE AWARE!!!

The more recent FA information and the older Supreme Commander 1 information is mixed together in the Mod Developer Support at GPG. When searching for information at GPG pay attention to the dates of the post. Much of the older information found at the GPG forum for Supreme Commander 1 carries over to FA and some only carries over in a limited form and some is no longer relevant at all. If you use one of the links provided to a thread at GPG do not take it as this is the only thread and the gospel truth. The GPG links that are provided for you in this tutorial are for providing you with starting points to do your own research.

WINDOWS VISTA AND WINDOWS 7 USERS.

BEFORE WE START....................

If using Vista or Windows 7 due to the nature of the new Windows UAC program for modding\editing purposes you may find it is necessary to install your games to a location other than the Windows Programs 86 directory. There are many on line Windows forums with complaints of programing tools such as code editors or game scenario editors that cannot write to or save changes to other programs that are located inside the Programs 86 folder. The easiest and most common on line solution is to install\reinstall your games on C or some other location outside of the programs 86 folder. Although these areas also have UAC protection it is not as restrictive as in the Programs folders and you can use your editing tools there. As an example, Here is a game path that is installed to C on a Windows 7 Home Premium 64 bit system.

C:\Games\THQ\Supreme Commander - Forged Alliance

Be advised that if you install outside the Programs 86 directory it may not create the THQ\Supreme Commander - Forged Alliance folders for you. Windows 7 will dump all the game folders loose into C drive. You should first create the following folders in C,( or D, F or whatever may be the drive of your choice) Games\THQ\Supreme Commander to be safe. You do not need to create the THQ folder but it is good practice to have a regimented folder structure. When installing the game use the browse function in the installer to navigate to and select the Supreme Commander folder and install the game there. You should also create a separate folder in the THQ directory for the GPGnet Multi Player program that comes with the game.

If you have already installed the game in Programs 86 and want to move it to another location you may find it necessary to uninstall EVERY folder on your computer involving the game. This includes hidden folders and any GPG folders that you may have in your Documents\MyGames. Some people have had problems with the hidden files still linking to Programs 86. This can cause people to still have problems running or editing the game. You may find that you need to remove EVERY GPG file from your computer and then reinstall to your new location. Most programs after you type in the product key code will automatically take you to the next page and show you what directory it is going to install the program in. For example the installer window will show something like, C:\Program Files (x86) (some program name) To change the installation directory there will be a browse button on the installer template. Click it and step by step navigate to your new folder that you created and it will install your program there. Some programs do not automatically show you the install path. Instead the template you see will give you a choice between "NORMAL INSTALL" and "CUSTOM INSTALL". Normal Install will be the default and if you click next it is going to install into Programs 86. Instead click on Custom Install and then you will be able to navigate to the drive\folder of your choice.

SECTION 1. Recommended Information and FreeWare Tool Resources for Beginners

GPG Mod Developer Support Forum

This is a sticky thread index page from the Mod Developer Support Forum that covers vast amounts of quick reference links to threads containing useful information.

http://forums.gaspowered.com/viewtopic.php?t=2318

Unit and Weapons Creation Tutorial

http://forums.gaspowered.com/viewtopic.php?t=12880
Besides the over all useful content found in the GPG Mod Developer Support forum there is an old but still very useful unit tutorial written by one of Supreme Commander 1 and FA's most talented modder's, The tutorial can be found at this link.This tutorial is 40 plus pages long and covers the information fields in the blue prints in detail. The focus of the tutorial is building attack units. Although written for the original Supreme Commander most of the information is still relevant to FA. It also has very useful blank modding templates and important information on how to package your mod should you want to release it for general use.

LUA Help

LUA 5.0 MANUAL. http://www.lua.org/manual/5.0/manual.html

LUA 5.1 MANUAL. http://www.lua.org/manual/5.1/manual.html

Supreme Commander and FA both use Lua 5.0. It is a slightly modified type of Lua by GPG for their own use version of 5.0 but still most of the Lua manual methods are relevant. Supreme Commander 2 is using Lua 5.1 which has some important changes in Lua that you will need to be aware of.

SUPREME COMMANDER LUA DOCUMENTATION.

This can be found on the Supreme Commander Wiki.

http://supcom.wikia.com/wiki/LUADOC_1.5.3599

CRIMSON EDITOR
http://www.pcworld.com/downloads/file/fid,64534/description.html

This is a freeware editor and it is pretty powerful. You can use "Windows Note Pad" for editing but an actual code text editor provides many more options. Syntax highlighting, File searches etc There are more than a few very good free text editors available. This is just one of the more popular editor's.

7zip zip tool.
http://www.7-zip.org/download.html
This is a popular zip tool. All the gamedata SCD folders are zip files. These are Units.scd, LUA.scd etc. If you look in your gamedata folder and you do not see the .scd extension i.e. your folders only say Units, Textures, Lua etc. this is because you have " Hide Extensions For Known File Types" active in your "Folder Options" panel. This is the same panel that we looked at for revealing the hidden folders. Start/ControlPanel/FileOptions. Go there and remove the check from the " Hide Extensions For Known File Types" box click "Apply" and "OK" and now you can see the .scd file extensions. This is a must do because you are going to be editing these extensions when packing and unpacking the scd files.

You can extract an scd without changing the extension but when you repack it you will need to rename the repacked file from mod.zip back to mod.scd. To do this you need to be able to actually see the file extension to rename it. You also need to be sure that you are repacking it in the right zip format. There are more than a few posts at GPG from people having trouble understanding how to pack and unpack the .scd folders. This will be explained in detail in the scd section of this tutorial.

WINMERGE
http://winmerge.org/

A very useful tool for side by side file comparison and it can also edit. As an example somebody has modded the StrikeForce Ai in Platoon Lua and you would like to determine what changes that person has made to the original Ai. You can make two separate blank pages and copy\ paste the original Strike Force in one page and the modded Strike Force in the other page. You can then load them into WinMerge and view them side by side with all the differences highlighted. The above method of making two separate files is used because of the differences in the length of the original files. The original Platoon lua has 2,994 lines of code but the Strike Force Ai is only 57 lines of that code. WinMerge breaks them all up trying to match areas that it thinks match but really do not making it very difficult to read. Strike Force is just one of many Ai's in the Platoon file. For good even line to line comparison it is best to make your own template files containing only the actual code sections you want to compare.

GIMP 2.6
http://gimp-win.sourceforge.net/

Gimp 2.6 DDS plug in http://nifelheim.dyndns.org/~cocidius/dds/

This is for viewing and editing the DDS files in the game. You need to install the Gimp DDS plug in. Not hard just follow the directions and put it in the right folder.

Paint.NET
http://www.tesnexus.com/downloads/file.php?id=11909

Another nice program for using with DDS files. There are two files here. The actual paint net and a plug in for Normal maps. Down load both.

Pastebin
http://www.pastebin.com
If you are having problems and you are asked to post a copy of your log window errors it is good forum etiquette to post and link to pastebin instead of having an extremely long thread post. Post your log at paste bin and paste a link to it in your forum post

GUID Generator
">http://www.somacon.com/p113.php
Each mod that is placed in the Documents\Mygames folder needs a UID number. This is an online tool that will create a UID number for you.

Black Ops Icon Support mod
[http://supremecommander.filefront.com/file/Global_Icon_Support;99906"> http://supremecommander.filefront.com/file/Global_Icon_Support;99906]
This mod greatly simplifies adding custom DDS placeholder icons to the build menu

SUPREME COMMANDER 1 and FA PATCHES.

BE ADVISED, Personal edits to the original gamedata files such as edited blue prints or added lines of code may cause a patch to crash during installation. Use only a clean installed game for patching.

The above warning also includes any scd mods such as Sorian or Duncane AI scd's Make sure that only the clean original files that the game shipped with are in your gamedata file when trying to patch the game.Most people use the GPGnet site to patch their games. If you log in with a new unpatched FA game and it does not automatically upgrade then that is because you are signed into to the Supreme Commander 1 section. GPGnet itself also has its own patches for the multi player client, chat and for using their own mod vault and you will be prompted to let GPG install their net patches. Let the game patch up with the multi player net patches first. The process is automatic. Click ok for each net patch. All GPGnet searching for updates messages appear in the upper left screen as a thin ticker tape message. After all the net patches are installed look at the bottom of the GPGnet screen and you will see a tool bar. There is an FA icon button there. Click that and it will transfer you to the FA section of the GPGnet site. GPGnet automatically detects where your game is installed.You will see a message that says searching for FA updates after clicking the FA icon button. Again it is all automatic. Just click OK for each FA patch. A problem that can occur with GPGnet is after it loads a large game patch the GPG page will close out and you may not be able to get back in. If you try to sign back into GPG it will say that you are are already logged in. There does not appear to be any control or button that lets actually lets you back into the site or log out. If you run into this problem either unplug your internet connection or restart your computer and then sign back in again and finish updating the game.

If for some reason you can not log into GPG you can down load all of the official GPG patches from this site,

http://supremecommander.filefront.com/file/3596_to_3598_FA_Patch;84474

and install them yourself. Look to the right at related files and you will see links to all the other official GPG release patches for both FA and the original Supreme Commander.

REMEMBER! to install the patches in order. For FA 96 to 98 first then to 99 . If you screw this up and load 99 before 98 and it breaks your game the only fix is to uninstall the game and then reinstall. There is a patch that will update your game from 96 to 99. Check your patches before installing to see what version they upgrade from and what version they upgrade to.

IN GAME LOG WINDOW {AKA The debug Window}

Supreme Commander and FA both have a built in debugger program. The actual debugger itself does not work. But the Log Window does work and you WILL need it. Not you might, You will. It is next to impossible to trouble shoot your changes with out it and no matter how explicit or detailed a tutorial is there are going to be errors made by you. Even if it is just a typo it can\will stop the game and you have to track it down. The log window can make these kinds of mistakes much easier to find.

This link will take you to the step by step instructions written by a GPG employee on how to set up the Log Window.

http://web.archive.org/web/20100402060811/http://forums.gaspowered.com/viewtopic.php?t=1847

It cannot be emphasized enough that this tool is essential for modding this game. When posting for help in the GPG developer forum you are going to be asked to provide a copy of the output of this log so other modder's can read it to find out what you are doing wrong. If you cannot provide it then nobody is going to be very willing to help you. If you are new to modding then setting the log window up for the first time can be a little confusing at first but it is not that hard. Look at it as your first trouble shooting challenge modding this game. If you decide to mod this game you are going to come across trouble shooting challenges that are far more challenging, complicated and frustrating than trying to figure out how to set up the log window.

Setting up the Log Window involves some minor editing of the Supreme Commander Game Preferences file. In Vista and Windows 7 the Game Preferences File is in a hidden folder. The file path to the Games Preference File using Windows 7 is,

C:\Users\Your Computer Name\AppData\Local\Gas Powered Games\Supreme Commander Forged Alliance

The AppData file in Windows 7 is the hidden file. The same file in XP may also hidden. It is there but you can not see it. To view this file go to your desktop. Use Start/Control Panel, In Control Panel select Folder Options. In Folder Options click on the VIEW tab. Right in the very top section of this template you will see two radio buttons. Select

" Show Hidden Files, Folders and drives"

All the hidden folders on your computer can now be seen. They have a ghostly transparent look compared to the normal folders.

BE AWARE!!!!
These files are hidden for your protection. Many are essential files to the Operating System. They are hidden so that they are not accidentally deleted by the user. If you have young children or other people besides yourself using your computer you may want to return these files to hidden status after you are finished with setting up the Log Window. You only need to reveal them to find your game preference file. After that there is no necessary reason to keep them un-hidden. The Game Preference File can be edited with "Windows Note Pad". Any lua or bp file in the Supreme Commander 1 or FA can be edited with Note Pad.

Now that you have your Log Window set up start the game and test to see if the Log Window is set up correctly. Be sure that the game video options are set to Windowed Mode and you have Cheats enabled. When changing to widowed mode sometimes it may be neccesary to shut down and restart the game for the change to properly take effect. The log window will not appear if cheats are disabled. Once the game has loaded and your Commander has his/her feet firmly on the ground press F9. The Log Window should open. Press the X button on the Log Window itself to close it. You will see a main log window view screen. The information output to the screen can be controlled by using the selection boxes at the top of the Log Window screen. You will see Debug, Info, Warning, Error and Custom. The most important options are the first four. Debug and Info produce very long lists of information. You can run the log window with them deselected. Deselecting them only deselects the information view. They are still running and reselecting either or both options at any time in the game will give you the full list from the very moment the game started.

There is a CLEAR button. If you press that then ALL the previously recorded information will be deleted up to the point that you cleared it. The Debug and Info buttons do have their uses but for now with the view to them disabled all you will see are any error and warning messages and these are really the most important messages. They tell you when something is wrong in the game. That is how you trouble shoot your changes. Here is an example of an actual error log.

WARNING: Invalid BuilderGroup named - Time Exempt Extractor UpgradesMetal - in BaseBuilderTemplate: MetalRushMainBalanced
WARNING: Invalid BuilderGroup named - Time Exempt Extractor UpgradesMetal - in BaseBuilderTemplate: MetalRushMainLand
WARNING: Invalid BuilderGroup named - Time Exempt Extractor UpgradesMetal - in BaseBuilderTemplate: MetalRushMainNaval
WARNING: Invalid BuilderGroup named - Time Exempt Extractor UpgradesMetal - in BaseBuilderTemplate: MetalTechMain
WARNING: Invalid BuilderGroup named - Time Exempt Extractor UpgradesMetal - in BaseBuilderTemplate: MetalTurtleMain
WARNING: NUM PROPS = 7867
WARNING: GetResource: Invalid name
WARNING: GetResource: Invalid name
WARNING: GetResource: Invalid name
WARNING: GetResource: Invalid name
WARNING: GetResource: Invalid name

The above warnings were caused by a typo in several base template files. UpgradesMetal was supposed to be Upgrades Metal. This kind of error can take hours to find without using the log window. These warnings show up in orange text. If you have never run the log window before and you see the warnings for Num Props and Get Resource Invalid name warnings do not worry about them. These are bugs that shipped with the game .

You can start the log window before the map actually loads. You can open it in the main lobby screen right after the intro movies. If you are in the next area, the game set up lobby, for some reason it will not open. You can also use a command line switch in your desktop short cut to start the log window automatically. There is a link to a Wiki page listing the command line switches available to add to your short cut just few lines down from here.

To make a permanent copy of the information in the Log Window right click your mouse in the log window using "SELECT ALL" and copy\paste to a note pad text file or your code editor. The log has constant feed coming to it so do not be surprised if you use select all and nothing seems to be actually selected. It is selected. Just use the copy\ paste function.

CREATING A LOG TEXT FILE.

If anything happens before the game actually loads or a crash occurs and you did not see an error in the Log window before it happened there is another logging tool available to you to determine what happened by adding the /log DamnLog.txt line to the end of your desktop shortcut path. An example from a working game shortcut is shown below

"C:\Games\THQ\Supreme Commander - Forged Alliance\bin\ForgedAlliance.exe" /log DamnLog.txt

You can custom name this log to whatever you like. It is commonly nicknamed the DAMN LOG. Once you create it, it will appear in the "BIN" folder of the Supreme Commander FA Root Directory folder. If you have an unexpected crash you can look at this log to find out what happened. A very useful tool for trouble shooting especially unexpected crashes. It records all the same information that you see in the Log Window. If in the game you press the Log Window clear button by accident and you have the Bin folder text log command switch in your shortcut you still have a complete record of the game from the very first file loaded to the last file before the game closed. This log is automatic. As soon as you start the game this log starts recording.

There are numerous shortcut command switch add on's you can use. They can be found at this page on the Supreme Commander Wiki.

http://supcom.wikia.com/wiki/Command_line_switches

IN GAME CONSOLE.

This is a totally separate tool from the LOG WINDOW. This is opened via the ( , ) comma key more commonly known as the tilde (~) key on US keyboards. There are various corresponding European keys that open the console. At the bottom of the linked Wiki Page is a table for the various countries that use a key other than the ~ key. The console is powerful. Care should be exercised when experimenting with it. Console commands can be found here on the Wiki

http://supcom.wikia.com/wiki/Console_commands

BE AWARE!!! of this particular console command

Debug_Crash

It does exactly what it says it does. It crashes the game.

SOME ADVICE BEFORE STARTING TO WORK WITH FOLDERS AND FILES.

Make back up copies of all you original scd's and back up copies of your mod as your work progresses and place them some where other than your hard drive. External hard drives. thumb drives, burn it to a disk. If your hard drive ever fails then you still have copies of your work.

SECTION 2 WORKING WITH SCD FOLDERS AND ADDING AN AI SCD MOD.

For people who are already familiar with packing and unpacking scd folders you may want to skip this section. It is only for the people are unfamiliar with what an scd is or how to repack scd folders.

OVERVIEW OF THIS PART OF THE SCD SECTION
This section is for people that are new to working with .scd folders to get a feel for packing, repacking and renaming folders using the scd extension. The examples will be using the common easy to recognize and find game file names i.e. Units, Textures, Lua, that the game shipped with. You will be working with these .scd folder's in your mod work folder only. DO NOT put anything in your gamedata folder. If this is new to you then it is suggested that you read through this entire .scd section first and then go back and slowly follow everything step by step.

BE AWARE!!!

Do not make ANY edits to or delete the original .scd folders in the gamedata directory. Make copies of the originals and move them to your work folder and do your edits with the copies.You do not have to use capitals when naming your folders. The only reason capitals are being used is to high light important information .

BE AWARE!!!
THIS NEXT SECTION IS JUST FOR PRACTICING PACKING AND UNPACKING SCD's.

USING "WINDOWS NOTE PAD" AS YOUR TEXT EDITOR

You do not need an actual code editor to edit lua or bp text files. You can use " Windows Note Pad" to edit existing or create new lua and bp files. After extracting the contents of the .scd folder open the extracted lua folder and RIGHT CLICK on any lua text file inside. With any lua or bp text file selected, Select the "Open With" option, find Note Pad and select it as your editor of choice. All the lua and bp text file icons will automatically change to "Note Pad" Icons. It is recommended that you should get a code editor and learn how to use it. It will make your life as a Supreme Commander modder much easier. You do not have to be an expert programmer to enjoy the most useful features of a good code editor. Use the help files that come with the editor or find a basic on line tutorial for your editor that will guide you through the user interface and in a few hours you will have more than enough basic knowledge to effectively use your editor program and its most important features. Especially with so many high quality freeware editors available today. But it is of course your choice.

To create a new Lua or bp text file using note pad all you have to do is add the file extensions to your new Note Pad txt file. As Examples,

MyModdedFile.txt to MyModdedFile.lua or MyModdedFile.bp

What is an SCD?

The SCD's in the gamedata directory are a type of combination folder. They are both a zip and a data folder that contain other folders and their files that are essential to the operation of the game. To view the contents of a .scd folder you do not have to extract it. You can use your zip program to view the contents of the folder and browse through it and read what ever you like. Use the "Open Archive" option of your zip program to do this. You do not need to change the .scd extension to extract the contents of the .scd. Create a new work folder inside your mod work folder and place any copied .scd from the gamedata folder inside it and extract it using the "Extract Here" option of your zip program.

When you extract an .scd folder it copies the contents of that folder to your new work folder. If you use your zip program "Open Archives" option to view an .scd that you have just extracted you will see that all the original contents are still there. The folders and files were not removed from the .scd folder. They were copied.

THE ACTUAL PROCESS

Three popular ways to select files and folders are,

BAND BOX, Using the mouse. Hold down the Left Mouse button and drag a box over the desired files, This is the most common method that people know.

SHIFT+CLICK. Select the first file you want to work with using your Left mouse. Then go to a folder or file more than one file away. Hold down the shift key and then Left click the last file in line. This will select every file in between the first file selected and the last file selected. This is very useful if you have several consecutive files in a row you want to select.

CTRL+CLICK. Hold down the Ctrl key and Left click on individual files and they will be added to your selection. This lets you select only the files you want from a mixed group of files. This one is very useful. For example there are folders in the game such as the Units folder or the DDS folders in Textures folder that have hundreds of files in them and you may only want a couple that are separated by many of other files.

Using the lua.scd found in the gamedata folder as our example, make a copy of it and paste that copy in a clean new folder in your mod work folder. Using the "Extract Here" option of your zip program extract the copied .scd. You should now see a common Windows type folder named lua along side the lua.scd. Make another new folder in your work folder and move the lua.scd into it leaving only the extracted lua folder in your work folder. This makes it easier to create a new lua.scd by having just one folder named lua in the same work folder. After extracting the contents of the copied lua.scd folder you can save it some place as a clean back up or delete it. You are done with it. You will need to go to "ControlPanel\Folder Options" and deselect "Hide Extensions For Known File Types". You need to do this before you can proceed to the next step.

BE AWARE!!!
In this next step you only want to select and repack (zip) the practice lua folder that is INSIDE the work folder that you created for extracting the lua.scd. You DO NOT want to select the actual work folder you created for extracting the .scd itself for repacking.

7zip is being used in this section as the example for zipping folders. Using your mouse select the lua folder that you recently extracted. With the lua folder selected now right click and a menu should appear. Select your zip program from the menu and a fly out menu showing the various zip formats available to you should appear. In the 7zip menu there are 6 choices, You want to use the "ADD TO LUA.ZIP" option. In the current version of 7zip version this is the 5th choice or the second from the last choice. Zip the lua folder using that option. After you are done you should now have a zip folder named LUA.ZIP. If you just have a zip folder named LUA and you can not see the .ZIP extension then you still have not properly done the deselecting of "Hide Extensions For Known File Types". After deselecting the check box in "File Options" you also need to click "APPLY" and then "OK" for the changes to actually take effect.

You will need to be able to see the .zip ext to be able to rename the folder.

If you can see the .zip extension then select the zipped lua folder, RIGHT CLICK and select "RENAME" from the menu. Rename LUA.ZIP to LUA.SCD The zip folder icon will revert back to the .scd icon. The lua folder is now repacked as an .scd and ready for use.

If using 7zip with Vista or Windows 7 and right clicking the selected folder does not give you a 7zip menu option then go to the folder where you have 7zip installed. inside the actual 7zip directory there is a file manager icon. Click on that and using the 7zip file manager navigate to your mod folder. Using the 7zip file manager itself select your lua folder and zip it using the file manager control panel. You can also right click the file in the manager after zipping and rename it from zip to scd from there. Then close the manager and use copy\paste to move your new scd to where ever you wish to store or use it

PACKING MORE THAN ONE FOLDER INTO ONE SCD

You can zip more than one edited folder at a time using any of the select folder/file methods that were mentioned in the beginning of this section. This also true if you are using the 7zip file manager method described above. Using the manager in the manager window use shift click or ctrl click as explained above in the file selection methods to select the folders you want to pack. If you want to create an .scd that contains the folders units, texture and lua all in one .scd select all three folders at the same time and follow the same steps for using your zip program. This creates an .scd mod pack and if all the folders and files are in the correct level they will be read by the game. Referring to how the 7zip program does things again, When zipping more than one modded folder instead of naming the finished zip folder LUA.ZIP it will take the name of the folder that you have the edited files in. Using 7zip if your edited folders are inside a new folder that you never renamed the created zip folder will automatically be named NEWFOLDER.ZIP. WinRar or another zip program may give you a different name other than 7z but the steps are the same.

You can rename NEWFOLDER.ZIP to what ever you want but be sure to add the .SCD extension. NOTICE that it is .SCD {a period separates the extension from the folder name}. These periods are hard to see and easily missed so to spell it out it looks like this,

FOLDERNAMEperiodSCD

That is the only period that you use and it MUST be there. Do not put a period after the .scd extension. The game will not read your modded folder if you do. You can use underscores in the file name. For example,

01_mymod_.scd

ADDING A CUSTOM NAME TO YOUR SCD AND PLACING IT IN THE GAMEDATA FOLDER

BE AWARE!!!!! Adding an Ai .scd mod requires a few more steps than just knowing how to pack and unpack an scd.

When you create a new Ai mod and you are ready to add it to the gamedata directory as an .scd you cannot name it lua.scd because lua.scd already exists in that directory. If you try to place your edited lua.scd in the gamedata folder as lua.scd you will get the error message "lua.scd already exists". The FOLDER NAME you give your edited .scd folder does not matter. You can name it lua2.scd if you wish. It is the SCD EXTENSION that is important and that your edited lua folder {or units or textures or any other gamedata .scd file} is in the very first level of your mod .scd folder .You can name it greencheese.scd and the game will still read it as long as the .scd extension is used correctly.

It is repacking the folder that seems to give some people the most problems. The three important things to remember are use the correct zip format, zip the right folder and rename using the right extension. A common error that some people make when they are new is they zip the wrong folder. They make a work folder for extracting, extract the .scd contents to that folder and then when repacking they repack selecting the work folder itself for zipping rather than the actual edited folders inside the work folder. They think that they have to create a new folder to put the edited folders in to repack it. This is incorrect. You do not need to add a folder and then zip. When repacking you need to select the actual edited folder or folders/files and zip it/them.

Keep in mind that when you zip something that the zip program creates the zip folder for you. .Zip is a folder type that places your edited lua folder inside itself. But the game is not programmed to read the .zip extension. It is programmed to read the .scd extension which is again a combination zip and data file type folder. When you rename from .zip to .scd your mymod.scd now becomes the directory folder for your edited folder. Your edited folder has to be in the next level of the folder structure for the game to be able to read it.

The proper file path for the original gamedata lua folder is, { This example game path is not installed in program files 86 so the first part of the file path may be different than yours.}

C:\Games\THQ\Supreme Commander - Forged Alliance\gamedata\ lua.scd\lua

Your scd mod must follow the same path

C:\Games\THQ\Supreme Commander - Forged Alliance\gamedata\ mymod.scd\lua

The above file path must be followed for a game folder or your edited folder to be read, \gamedata\ any.scd\anyfolder <--------- i.e. lua, units texture etc.

If you incorrectly select the work folder that your edited lua is in for repacking instead of the actual edited lua itself then the file path becomes,

C:\Games\THQ\Supreme Commander - Forged Alliance\gamedata\mymod.scd\workfolder\lua

and it will not work in the game because your edited lua folder is in the wrong level of its directory. Your edited lua inside the .scd should have no extensions. It is just lua ( or units or textures) and nothing else.

When you repack folders and files you can use your Open Archive option to check yourself. When viewing the contents of your mymod.scd using the Open Archive option the first file you should see should be lua. If you see New Folder or the name you named your extraction work folder then you have done it wrong. If you have repacked more than one edited file i.e. unit, textures or any other edited folders in the same mymod.scd as your edited lua then when you look inside your new mymod.scd you should see three folders. lua, units, and textures all in the first level.

The game looks for folder's inside the gamedata .scd's named lua, units, textures etc. There are two other .scd folders in the gamedata folder that have a folder in the first level named lua, mohodata.scd and moho.ua.scd. It is advised that you do not edit these two folders until you know more about what you are doing. The lua files in those two folders "HOOK" into the various lua files in the lua.scd.

The game searches for all three lua's and it expects to find them in the correct level of the three .scd folders. If these folders are not where the game expects them to be then the game can not read them. When you add your mymod.scd to the gamedata folder the game finds your edited lua and reads it also but only if it is in the correct directory level. The game will not look for it in the second or third level. This is why you should not edit the actual gamedata folders. If it is just your edited mymod.scd that is being passed over the problem is only in your mod. But if you edited an actual gamedata .scd folder then the game itself is broken. It will not start or if it does it will crash soon after. If you made clean .scd back ups then it is fixable but if you did not make clean back ups you will have to reinstall the game. You can copy and mod any folder or file in the gamedata folder and repack it as a mymod. scd and the game will read it. You do not have to mod the original game files. You can mod a single function in the lowest level of any given .scd folder structure and as long as you follow the proper folder structure and file path in your mymod.scd the game will read it.

Concerning Zip file compression the default settings that come with the 7zip program seems to be good enough.

ADDING A CUSTOM AI SCD TO THE GAME

BE AWARE!!!

Ai mods cannot be turned on or off. This is why they are usually created as scd folders. If you are creating your own Ai scd it is important to remember to remove any other Ai scd mods you may have in the gamedata folder because they can interfere with play testing your own Ai mod.

The method here is using the Sorian Lobby Enhancement Mod. Download the mod from the link provided below. This mod has several other useful features for the user. It is an scd mod. Install it in your gamedata folder with the original .scd's. On the Sorian Mod page you will have to scroll down a little bit to get to the download link. If you would like to mod Ai's you should down load his most recent Ai's also and study them. They are still the best of any available Ai's.

http://forums.gaspowered.com/viewtopic.php?t=33944

Adding an Ai used to involve editing several folders. With the Lobby Enhancement Mod only one is necessary and one is optional. The optional folder is only needed if you want to add tool tips for your Ai. Tool tips describe what your Ai is. Hard Easy Air Land etc.

To add an Ai to the game you create a new folder and name it CustomAis_v2. This is the FOLDER NAME you MUST use because it is the folder name that Sorians Lobby Enhancement Mod is looking for. You can and should custom name the lua text file that goes into the folder. Just make sure you use the (.lua ) text file extension. Below is an example using a working Ai mod,

MetalAI.lua

This folder goes in the Ai folder in the mod.scd\lua The proper path consists of 4 folders and one lua text file.

The full File path is, mod.scd\lua\AI\CustomAis_v2\MetalAI.lua

In the MetalAI.lua example the following tables are added.

AI = {
Name = "Metal AI",
Version = "2.0.0",
AIList = {
{
key = 'metal',
name = "AI: Steel AI",
},
{
key = 'metalrush',#rush
name = "AI: Steel Rush",
},
{
key = 'metalair',
name = "AI: Steel Air",
},
{
key = 'metalwater',
name = "AI: Steel Naval",
},
{
key = 'metalturtle',
name = "AI: Steel Turtle",
},
{
key = 'metaltech',
name = "AI: Steel Tech AI",
},
{
key = 'metaladaptive',
name = "AI: Steel Adaptive",
      },
   },
}

Due to the above lua file these Ai's will now be listed and selectable in the drop down Ai menu in the game set up lobby.

THE CUSTOM TOOL TIPS FOLDER, is named CustomAITooltips and needs to be located in the same folder as the CustomAis_v2 is in.

The full file path is

mod.scd\lua\AI\CustomAITooltips\allmetalTooltips.lua

It contains the following tables,

Tooltips = {
 aitype_metal = {
 title = "AI: Steel",
 description = "It is afraid of you",
 },
 aitype_metalrush = {
 title = "AI: Steel Rush",
 description = "It throws things at you",
 },
 aitype_metalair = {
 title = "AI: Steel Air",
 description = "It drops things on your head",
 },
 aitype_metalwater = {
 title = "AI: Steel Naval",
 description = "It makes you afraid of the water",
 },
 aitype_metalturtle = {
 title = "AI: Steel Turtle",
 description = "It is a snapping turtle",
 },
 aitype_metaladaptive = {
 title = "AI: Steel Adaptive",
 description = "Random choosing of any of the Steel AI's",
    },
 }

The above information from this ai mod scd " HOOKS" into the original lua.scd tooltips.lua that are displayed in the game lobby game set up control panel. Download the Sorian 2.0 Ai, Extract it and in his lua/ai folder you will find the two custom folders listed above. Make a tool box folder in your work folder and copy and paste the two custom folders there for future use. If you want to create an Ai in the future you can use them as your templates. You do not have to write out the tables from scratch. Edit your own information into the tables and place the two custom folders inside your mod.scd\lua\AI and your Ai be will recognized and added by the game. Pay attention to the placement of the { } lua table constructors. Misplacement or one missing will cause errors in the game. Start paying attention from this point forward to how the code is constructed. You will be seeing lots these. { }. These are Lua table constructors.

Section 3 HOOKING FILES AND FUNCTIONS

This section will show you how to use a technique called HOOKING and show an example of a trouble shooting problem concerning the adding of a new class of Mass Extractors to the FA game. Hooking a new function will be needed to fix the problem.

BE AWARE!!!
When working with the Documents\Mygames folder you do not zip your mod folder. Put all your files into a folder and name the folder after whatever your own mod name may be and place it in the mods folder in the C:\Users\Your Computer Name\Documents\My Games\Gas Powered Games\Supreme Commander Forged Alliance\mods\mymod

This is a link to a short tutorial on hooking by a GPG Dev http://forums.gaspowered.com/viewtopic.php?t=1060 The linked tutorial is pre FA but still the methods are relevant.

WHAT IS HOOKING?

Hooking is a method that either adds or overwrites your custom code from an external mod file located in the Documents\Mygames mods folder or a mymods.scd in the gamedata folder to the actual GPG game folders without physically editing those folders. To hook a game folder or file you first create a new folder and name it HOOK. Place the Hook folder inside your mymod folder or your mymod.scd. Any modded lua functions that you want to add to the game are placed inside the Hook folder.

Using the mymod name example, The file path from Documents/Mygames for the Hook folder inside the mod folder would be,mods\mymod \hook\ Any files that mymod hooks into the game will be placed into that folder.

There are two common types of hooking.

Non destructive hooking, This is where your custom mod function or functions are added into a game session without interfering with any original code or others players mods.

Destructive Hooking, This is where your custom lua function or functions actually overwrites a function or functions in the original GPG .scd code cancelling a function or functions of the original scd's and depending on load sequence may interfere with other players mods.

DESTRUCTIVE HOOKING

Destructive Hooking is a method that overwrites a function or functions in the original game.scd's replacing the original function with its own function. Non destructive hooking is the preferred method to preserve mod compatibility. If two or more mods are compatible they can all be active at the same time i.e. two players each with a mymod active in the game can both have their own hook files and not interfere with each other using the non destructive hooking method because nothing is being overwritten in the original GPG .scd folders or in each others mod. But if one mod is using destructive hooking and it happens to be the mod that the game loads last then the other mods and the actual GPG files will be trying to run according to the overwritten changes of the last loaded mod.

This is a case where he who finishes last wins. When the game starts and loads all the game files including mods for that session it reads the original .scd's first and then each mod as it is loaded. The last mod loaded if it has destructive hooking has its overwrites passed into the game and the other files including the original GPG files will be trying to run on that hook function.

With non destructive hook functions everybody's custom functions are added to the game and can be read without interfering with each other or the original GPG files. Instead of overwriting any other existing code the mymod hook files code is literally added into the game. If the original GPG file is 100 code lines and you add or mod a function in that file using non destructive hooking that is 30 code lines long then the game actually reads and passes into the game 130 lines of instructions from that file. Only the mod units that call on the extra 30 lines of code will use that code. There will be actual examples of both styles of hooking using the same function shown in this section.

As an example the original all_metal mod created by a mapper/modder called Stix will be used for hooking. His mod was made for early Supreme Commander 1. This mod permitted the building of mass extractors anywhere on the map. Later patches broke the mod and it would no longer work with patched versions of Supreme Commander 1 or FA.

function AIGetSortedMassLocations(aiBrain, maxNum, tMin, tMax, tRings, tType, position)
local markerList = AIGetMarkerLocations(aiBrain, 'Mass')
local newList = {}
  for k,v in markerList do
 if aiBrain:CanBuildStructureAt( 'ueb1103', v.Position ) then
 table.insert( newList, v )
       end
 end
 return AISortMarkersFromLastPos(aiBrain, newList, maxNum, tMin, tMax, tRings, tType, position)
 end

The reason this mod no longer works in FA is because of this line from the above code.

if aiBrain:CanBuildStructureAt( 'ueb1103', v.Position ) then table.insert( newList, v )

UEB1103 is the UEF factions T1 mass extractor. A later released GPG patch added this new section of code to the original SortMarkers code and it broke the original metal mod. It is common for patches to break mods because patches add new code to the games. The original Supreme Commander used a different code to achieve the same purpose. In this particular case the Log Window does not show any errors because the code is actually working as it is supposed to work. With the updated code and all 4 factions in the game the commanders will be idle when using the original mod.

This kind of trouble shooting involves finding a starting point on your own. The problem is the extractors or something that is related to the extractors. In this case the starting point is the script lua in the extractors unit blue print folder. The script lua is a separate file from the unit bp. It is a lua file that is in the same folder as the unit bp and the dds files. It will be necessary to trace out call by call function by function all the files that are involved with the extractors. In this particular case it is not the extractors code but is something related to the extractors. It is the mass markers code. The code below is the code that is used for sorted mass locations in the unpatched Supreme Commander 1

function AIGetSortedMassLocations(aiBrain, maxNum, tMin, tMax, tRings, platoon, unit)
local markerList = AIGetMarkerLocations(aiBrain, 'Mass')

return AISortMarkersFromLastPos(aiBrain, markerList, maxNum, tMin, tMax, tRings, platoon, unit)
end

The two codes perform the same function in a different manner. The patched in code and the FA code has what is called a "For" loop. for k,v in markerList do This mass marker code is in the aiutilities.lua. To create a fix for the old mod it is necessary to overwrite the new FA code with a destructive hook. This is done by taking the original Supreme Commander 1 code and placing it in the mymod Hook folder. The same rules apply to the mod folder as to an scd. The mod file paths need to imitate the original game file path. A full file path from a mod folder example is provided here.

C:\Users\Your Computer Name\Documents\My Games\Gas Powered Games\Supreme Commander Forged Alliance\mods\mymod\hook\lua\AI\aiutilities.lua

The above example code from the original Supreme Commander will hook in as destructive actually overwriting the sort mass marker code that is in the GPG lua.scd and the mymod hooked edit will be passed into the game.

function AIGetSortedMassLocations(aiBrain, maxNum, tMin, tMax, tRings, platoon, unit)

This is because the above function line in the hook is identical to the original GPG code. Try to picture a function as a name tag. The name is AiGetSortedMassMarkers. An event happens in the game and another function somewhere else calls to AiGetSortedMassMarkers. With no mods in the game the path leads straight to lua.scd into aiutilites. But because the mymod mod files were the last files loaded with the edited function placed in the mymod hook folder aiutilites.lua the mymod hook is the first AiGetSortedMassMarkers the game finds and the game uses this function instead of the original found in the GPG lua.scd

Any other function that calls to

function AIGetSortedMassLocations

in the game including other mods, will now read and use the edited code that is in the mymod hook folder.

NON DESTRUCTIVE HOOKING

To create a non destructive hook you add a unique name to the function, An example would be,

function AIGetSortedMassLocationsmymod(aiBrain, maxNum, tMin, tMax, tRings, platoon, unit)

By adding mymod to the function name a new function is created and this causes the code to be added into the aiutilities code the game will search for. Now when another function calls AIGetSortedMassLocations even though mymod may have been loaded last the game does not find the function it is looking for in Hook folder aiutilities. It passes over the unique name function because it is not the function name that the call is looking for and goes to the original lua scd and finds it there. But if the code calls for a build anywhere extractor then it will use the code that is found in the mymod hook folder.

In what may be a more simple and clear explanation,

identical function name =overwrite

modded function name = added

To make the new added hook function work it is necessary to check every instance in the game that calls this function. In this case two other functions call to aiutilities for sorted mass locations.

Marker Build Conditions

local markerTable = AIUtils.AIGetSortedMassLocations(aiBrain, maxNum,threatMin,threatMax,threatRings,threatType, 
position)

And the strike force ai in Platoon lua

self:Stop() for k,v in AIUtils.AIGetSortedMassLocations

These both need to be changed to

AIUtils.AIGetSortedMassLocationsmymod

The Strike Force Ai in Platoon.lua is a function that is made up of many functions hooked together. You need to copy the entire Strike Force Ai and change the very first call

StrikeForceAI = function(self)

to

StrikeForceAImymod = function(self)

and then locate the function that is in the strikeforce Ai that calls

AIUtils.AIGetSortedMassLocations

and change it to

AIUtils.AIGetSortedMassLocationsmymod

You now have to add all three of these files with their new functions to your hook folder.You need an aiutilities.lua, Platoon.lua and MarkerBuildConditions.lua The file paths from the hook folder have to imitate the actual game file paths to these files.

aiutilities.lua = mods\mymod\hook\lua\AI\aiutilities.lua
Platoon.lua = \mods\mymod\hook\lua\Platoon.lua
MarkerBuildConditions.lua = \gamedata\mymod\lua\editor\MarkerBuildConditions.lua

It is not necessary to copy every function that is included in those files to your mymod hook files.You only need to copy the actual functions that you edited. If the game is looking for another marker function and does not find it in your marker lua then it will go look for another marker lua and see if it can find it there. For example the original GPG Platoon.lua is just short of 3000 lines of code. the strike force ai is about 60 lines out of that 3000. You only need to copy the edited strikeforceAi to your own Platoon.lua hook file. Open the original Platoon.lua, Find the strikeforceAi and copy\paste it into a new text file and name the new text file Platoon.lua. Paste your copied strikeforceAi into the your new Platoon.lua and make your edits. Do the same with the aiutilities.lua and MarkerBuildConditions.lua. Make new folders with the proper names where necessary and add all this to your mymod\hook\lua.

PLAY TESTING YOUR CHANGES IN THE GAME.

SETTING UP A SKIRMISH MODE TEST GAME

In skirmish mode you can start a game with just you in it. This involves selecting the Sand Box victory condition and not selecting any Ai opponents. This is good if you just want to check if your icon place holders are showing up or if your units can actually build a certain unit you have edited or added. If it is a mobile unit you can see if it can actually be built. Will it move? Are there animation problems? Can it fire its weapons? But just because your own commander and units are using the changes you made does not mean for certain that the Ai is going to use those same changes. For this you need to be able to observe the Ai and how it reacts to your changes

SETTING UP A LAN MODE TEST GAME

You can use this mode even if you are not connected to a LAN or the Internet. This mode is very useful for Ai testing becausing a human player does not have to be in the game. You can have all 4 factions in the game at the same time and just sit back and watch how they respond to your changes.

To set up a LAN game,

MAIN LOBBY, select the MULTI PLAYER LAN option, This will take you to the next screen which is the,

LAN/IP CONNECT SCREEN, Select Create. next will be, Game Name, Enter a name for your game. This name will be permanent. Every time you start a LAN mode game you will be able to select that name. Port Leave it in, Auto. Next screen is,

GAME LOBBY SCREEN, Down at the bottom left of the Army set up screen there is a black button that says OBSERVE. Click that and your player slot becomes empty. You are now an observer. All the other game preferences i.e. unit count, mod manager, unit restrictions etc are set up the same as in skirmish mode.

If you are using LAN mode and you do want to be in the game yourself after you have all your preferences set up, to the right of your player name is a column that is named READY There is a square button in that column and you need to press that button to enable the game launch button. Then press launch and the game goes into the start sequence.

USING THE CONSOLE FOR AI TESTING

CHEATS MUST BE ENABLED!
These are a few useful console commands for testing an Ai

All console commands are activated and deactivated following these steps

ai_InstaBuild

Open the Console using the ~ key. The console has a command line.

Click the command line and then type A

This opens a menu with all the commands that start with A.

Scroll down and find, ai_InstaBuild Double click on it and it appears in the console command line.

Press Enter on your keyboard. Build times are removed from the Ai. To turn the ai_InstaBuild off follow the exact same steps.

You may not get a good accurate test if you run the Instabuild command for to long because the Ai starts getting confused after awhile. Buildings and units are popping up faster than it can issue and clear commands. It is useful to jump start the beginning phase of the game.

ui_DebugAltClick.

This only seems to work if a human is actually in the game
Type U into the console command line.
Follow all the same steps used to activate ai_instabuild
With this enabled hold down the ALT key and select any AI unit and you are now in control of that AI.

A separate useful tool is ALT- F2. While holding down the ALT key press F2 and a widow will open that permits you to spawn any unit regardless of faction into the game. When the window opens select a faction, tech level and a unit from the list. The unit will spawn where ever your cursor was when you opened the window. If you have a specific place you want the unit to spawn place your cursor there first and then open the spawn window. Before spawning another unit it is not necessary but it is helpful to deselect the faction and the unit tier that you just used. If you select Aeon T1 then all the Aeon T1 units will be listed. If you now select Cybran T1 then all the Cybran T1 units will be added to the same list. You can select any faction and any tier and they keep beeing added to the list. Eventually the list becomes rather long with all the factions units mixed together.

In the ALT-F2 Mode you can select a faction by double clicking on the faction icon in the Alt-F2 window. You will be able to see that factions ai economy stats and you can select indivudal units. The Ai will still be in control of the units also and it will usually cancel any qued build or move orders that you give a unit. You can usually issue one or two individual orders to a unit before the Ai tries to reassign the unit to another platoon.

Most important though is if you have added a new custom unit to the game and it does not appear in the spawn list then there is problem. Your new unit is not being fully recognized by the game. This can be a Blue Print ID problem.

Try making sure that your mod bp id imitates the original bp id method. 3 letters and 4 numbers For instance mymod extractor bp.= MME1234.

A QUICK LOOK AT SOME INFO OUTPUT FROM THE LOG WINDOW

To be able to see if your hooks are actually being loaded into the game you need to use the Log Window. Here is an actual section from the Log Window start up using the info option. When you select the Info option all the files that the game has loaded are shown. In the line below the tester has an edited aiutilities.lua in their hook file. By watching the the Log Window the tester can see that the game has recognized and loaded their edits

INFO: Hooked /lua/ai/aiutilities.lua with /mods/metal_mod_player_test/hook/lua/ai/aiutilities.lua

This does not guarantee that your edited function is actually working as it should. Determining that the file is actually being loaded is only the first step in testing. Now time needs to be spent observing the game and watching how the Ai acts and responds. Depending on the edit changes it may be immediately obvious such as the addition of a new unit or the changes may be more subtle such as trying to balance the economy in a new Ai. You should also know that part of the observation process is not just watching for your code to work properly but to also make sure that your code is not interfering with another function causing it to not work properly. This is time consuming and only practice and experience can teach you.

Here is some of what you can see happening in the in game log window and what it is telling you. It can be used by the tester as a check list of the various game and mod files that are being loaded. If a file is missing then the tester knows that file is not working properly. More work will be needed to get it loaded into the game

INFO: Active game mods for blueprint loading: \000{

Below is the information from the mod_info.lua. Every non scd mod needs this file, This file informs you that your mod has been read by the game and it is trying to load any .lua and .bp files it has found. If you do not see this when trying to load your mod then it has not been detected by the game and something is wrong. Usually the problem is your mod is in the wrong folder or if you typed it out by hand it has some kind of typo. This file is not dependent upon your mod. Your mod folder can be empty with only the mod_info.lua inside and it should show in the log window as having been read by the game at start up.

INFO: { INFO: author="stix',
INFO: copyright="none',
INFO: description="Test Makes it so you can build mass pumps ANYWHERE, just like the metal maps in Total Annihilation.',
INFO: exclusive=false, 
INFO: hookdir="/hook',
INFO: icon='/textures/ui/common/dialogs/mod-manager/generic-icon_bmp.dds',
INFO: location="/mods/metal_mod_player_test',
INFO: name="Player Only Metal Style Maps',
INFO: selectable=true,
INFO: shadowdir="/shadow',
INFO: ui_only=false, INFO: uid='61546f53-f46c-4d5b-bd0d-ef7e39cbd761',
INFO: url=' ', INFO: version=1
INFO: },

Below is a list of more mod files being loaded into the session. When the game is loading the info option gives you the file path of every hooked file. The game itself also has its own hooks being loaded from mohodata.scd and moho.lua scd. The loaded hooks are not always blocked together. Sometimes they are more spread out.

INFO: Hooked /lua/ai/aiaddbuildertable.lua with /schook/lua/ai/aiaddbuildertable.lua
INFO: Hooked /lua/ai/aiattackutilities.lua with /schook/lua/ai/aiattackutilities.lua
INFO: Hooked /lua/ai/aibehaviors.lua with /schook/lua/ai/aibehaviors.lua
INFO: Hooked /lua/aibrain.lua with /schook/lua/aibrain.lua
INFO: Hooked /lua/sim/factorybuildermanager.lua with /schook/lua/sim/factorybuildermanager.lua
INFO: Hooked /lua/sim/buildermanager.lua with /schook/lua/sim/buildermanager.lua
INFO: Hooked /lua/sim/builder.lua with /schook/lua/sim/builder.lua

The SCHOOK is another type of hook file. This is from the Sorian Ai and it is a hook type that he uses to hook into the sim side functions of the game. The game is divided in to two sections. User side and Sim side. Most basic mods are User side. UI type mods that change the appearance of the lobby area's or the in game hud are sim side mods. This hook is coming from his scd Ai mod.

As a reminder remember when using the mod folder in Documents\MyGames you DO NOT zip your files nor do you need any specific file name. You do need to make a name with no spaces. my mod will not work But you can use mymod or my_mod and the game will read it as long as all the files inside are correct. In that respect it follows the same rules as the scd folder mod. All your folders must be in the right folders and at the right levels imitating the GPG game data file structure.

THE MOD_INFO.LUA

Here are some important things that you need to know about the mod_info.lua.

The game detects the mod_info.lua and this is how your mod gets recognized by the game. You must have this file in your actual mod folder. This means actually inside the mymod folder and it needs to be in the first level of the folder. When you open mymod you should see the mod_info.lua file. It should not be in any other folder in your mod.

It is the mod_info.lua that the game sees and adds your mod to the game. The game itself establishes the file path from the actual game location on your hard drive to the Documents\Mygames. If your mod_info.lua is done right then when you start your game, go to the game set up lobby, select options and then select the mod manager. When the mod manager window opens you should see the description for your mod in the window somewhere. For example the description from the example mod_info will say,

'Test Makes it so you can build mass pumps ANYWHERE, just like the metal maps in Total Annihilation.',

Click on the description and the link lights up and the game will now load your mod files when you actually press the LAUNCH button. This only means that the game sees your mod_info.lua. It DOES NOT mean that all is good and your mod is in good working order. The game has not yet tried to load your actual mod files. It will not do this until you hit the LAUNCH button. If the folders or files have serious errors in them it will not load them or may even cause the game to crash.

Here is a break down of the code that is in this file. There are only few lines and only a couple of those are really important.

name = "Player Only Metal Style Maps"

You can put what ever you want as your name.

version = 1

If you have more than one version of your mod released then when others are playing an on line game they can compare to see if they both are playing with the same release of your mod.

"uid = "61546f53-f46c-4d5b-bd0d-ef7e39cbd761"

The UID is important for mod load order. the actual name is GUID. This an acronym for, Globally Unique Identifiers

Here is link for you to use that has a uid generator.For any mod you make you can use this to get yourself a new UID

http://www.somacon.com/p113.php.

copyright = "none"

Every person has the right to copy right something if they want to.

description = "Test Makes it so you can build mass pumps ANYWHERE, just like the metal maps in Total Annihilation."

Short description of your mod that appears in the game mod manager

author = "stix"

Who created the Mod.

url = ""

If you have your own website for your mod you can enter that here.

exclusive = false
ui_only = false

The last two are generally not used.

SECTION 1a CREATING AN UPGRADEABLE STRUCTURE TUTORIAL

MODDING INTO THE GAME UPGRADEABLE MASS EXTRACTORS

The scd folders that we will be working with are UNITS.scd, LUA.scd and TEXTURES.scd all found in the SupremeCommander-Forged Alliance\ GAMEDATA folder. The fourth directory will be the Mods directory in the Documents\MyGames folder. The file path is,

C:\Users\Your Computer Name\Documents\My Games\Gas Powered Games\Supreme Commander Forged Alliance\Mods

If you have never downloaded any mods from the GPG Vault then you most likely do not have a mods folder in the Mygames folder so you will need to create the folder yourself. When you download a mod from the GPG vault the GPG download program automatically creates the mods folder for you. Using any other source you need to create your own mods folder. It is just a folder. It does not matter if you create it or it is created by GPGnet The same applies to maps also downloaded from the vault. If you have downloaded any maps from the vault you will see a separate maps folder that was created by the GPG downloader. For this tutorial, if you do not already have a mods folder create a new folder and name it mods and place it inside the Supreme Commander Forged Alliance folder of the Mygames folder.

IF YOU ARE USING THE MODS FOLDER IN DOCUMENTS\MYGAMES DO NOT ZIP THE FOLDERS.

There are two methods used to create a mod.

mymod.scd zip and place inside the gamedata directory.

mymod leave files unzipped and place inside the Documents\Mygames\Gas Powered Games\Supreme Commander Forged Alliance\mods folder.

The first method is to make an scd file mod. This is the usual method of making a new Ai mod. Ai mods cannot be turned on or off. This is why they are usually created as scd folders. If you are creating your own Ai .scd it is important to remember to remove any other Ai .scd mods you may have in the gamedata folder such as Sorian or Duncane because they can interfere with testing your own Ai mod. Using the.scd mod method, your mod folders and files need to be zipped, renamed with the proper .scd extension and placed in the gamedata directory. an example file name is, mymod.scd

The second method is to add your unzipped mymod folder to the Documents\Mygames folder. The file path is, \Documents\My Games\Gas Powered Games\Supreme Commander Forged Alliance\mods\mymod

Your mymod folder being the last folder in the path. As long as your mymod is its proper place in the path and your edited folders and files inside are in their proper place the the game will take care of the rest when it starts up.

For the unzipped method take all the files that you have edited and place them in one folder. As in the scd method, All your files and folders must follow the proper file paths that the game uses to find it's own original files and folders. You do not use an extension on your mymod folder but still the lua folder needs to be in the first level to be found by the game.

Name your folder what ever you like and place that folder into the mods folder in the MyGames directory. Make sure that you have included the mod_info.lua.

Make several empty folders in your work file. Make a copy of the Lua, Units and Texture scd's and place them in separate folders in your work folder. Using your zip program extract each one in their separate folder.

The rest of this tutorial will be referring to mostly the Aeon extractors from the units.scd folder. The unit.bp files are,

uab1103 Tech 1

uab1202 Tech 2

uab1302 Tech 3

HOW TO USE THE MERGE BLUEPRINT METHOD

A blue print file is recognized by the .bp extension by the game. The units.scd is not the only place in the game that has blueprints. In the lua scd there are weapons bp, projectiles bp etc. If you are modding a mobile attack unit you will need to be aware of these other .bp files.

There are two methods for modding a blue print file.

Merging

Creating a new unique blue print

MERGING BLUEPRINTS This is explained in detail in the units tutorial that is linked for you to GPG in the SECTION 1. Recommended Information and FreeWare Tool Resources for Beginners but we will take a look at this method here also.

Merging is how Stix created his original all metal mod. Here is an example of a merged type of file. The name of this file is mod_units.bp. Here is the original Stix code.

#aeon,
   UnitBlueprint {
   Merge = true,
   BlueprintId='uab1103' ', # aeon t1 mex
   Physics = {
   BuildRestriction = ' ',
    },
 }

In the original mod only the original three factions from Supreme Commander 1 are represented. The merge blue print code is repeated 8 more times to cover each of the original 3 factions extractors. You do not need to make a separate .bp text file for each extractor. You can add all the units you want to merge as a continuous list all in one text file. As long as each merge template is properly closed there will be no problems. If a table is accidently left open when in the game the Log Window will show an error such as,"ERROR Expected to close at line 30 in mod_units.bp".

Notice these symbols

' ',

after BuildRestrictions = ? This is the lua open string. ' ', Stix was using it to overwrite the build restriction on the Supreme Commander 1 mass extractors. He used this code as a "destructive hook".

In the code example below another destructive hook is added. DragBuild. It does not overwrite an existing function but it adds a function to the categories field in the uab1103 original .bp that affects everybody that is playing the game. To repair the mod it was necessary to change the BuildRestriction = 'RULEUBR_OnMassDeposit', toBuildRestriction = 'RULEUBR_None', The open string method used in the original mod would no longer work in the FA game. It caused an error in the game that showed that something was now required to actually be entered into 'RULEUBR_ string. It is the 'RULEUBR_None' that permits the faction engineers to build on land and not Mass deposits. Adding DragBuild permits the human player to hold down the left mouse button and issue a multiple build queue order. "dragging" the mouse creating a continuous line of build sites for the mass extractors. The Ai does not drag build.

#######
#Aeon 
#######
UnitBlueprint {
Merge = true,
BlueprintId='uab1103', # Aeon T1 Mex
Categories = {
'DRAGBUILD',
}, 
Physics = {
BuildRestriction = 'RULEUBR_None',
   },
}

By using the "merging",technique which is a type of hooking, the parameters of the unit are being changed with out physically editing the original bp. The original bp file now has the new parameters added to the categories and overwriting the rule OnMassDeposit and will be loaded into the game at start up. Remove the mod file from the mod folder and the extractors will revert back to the original behavior that is dictated by the original bp. With the rule set to none the game construction units can now build extractors on land anywhere the human player wishes to build them. But two more problems arise here. With the rule set to none the player's can build on land anywhere but not on mass deposits. It reversed the restriction from build only here to build anywhere but here. The second problem is the Ai is spam building extractors everywhere.

Study the code structure. This a common code structure found in the unit files. These { } are the basic lua table constructors. You will see a lot more { } before this tutorial ends.

The opening bracket is the first bracket after Unit Blueprint = { Here is a break down of how the tables open and close.

Unit Blueprint = {<------- Main table opens
Categories = {,<-------Table 1 opens
'DRAGBUILD',
},<-------Table one closes
Physics = {<-------Table 2 opens
BuildRestriction = 'RULEUBR_None',
},<-------Table 2 closes
}<------Main Table closes

Notice the two inner closing brackets are typed as }, The , is part of the code. Many times when you get an error in the log window that will be the cause. The error will say something like error in bp uab1103- line expected to close at line 25. This means that one of your closing brackets is either in the wrong place or something is missing and it is usually the comma. It is very easy when cut and pasting blocks of code to miss a comma or even a whole final closing bracket. This is where a good code editor is useful.One of the abilities of Crimson Editor is to find where {} ( ) [ ] type symbols open and close. If you have Crimson Editor then click the Search tab on your tool bar. At the bottom of the drop down you will see an entry that says ADVANCED. This opens a fly out menu. In the fly out two of the options will be Pairs Begin Position and Pairs End Position. Using the pairs tool you can now locate the matching symbol for opening or closing a table {} or string ( ) [ ]. Select any of the listed symbols. When it is selected it should have an _ under the symbol. If the _ is not there then you have an open in your code. Another thing that can happen is you select the symbol and you get the _ under it. This still does not tell you if your closing bracket is actually in the right place. To determine the actual position of the matching closing bracket select the first{ and click the Pairs End Position and it will take you to where the matching closing bracket is. Somewhere you have one in the wrong place and it needs to be relocated to the proper place. If you are moving code blocks via cut and paste it is best to do it in small sections at a time. Small sections does not mean number of lines but rather by number of functions. One function can run for several hundred lines of code. Move only that one function and then test it to make sure you did not miss something before moving on to another edit.

A GPG DEV TIP CONCERNING BLUEPRINT LOADING

The GPG developers left many comments in the the various game folders and files explaining the various functions. What they do and how they are intended to work. Here is a major dev tip for merging blue prints. This comment can be found in,

gamedata\mohodata.scd\lua\system\blueprints.lua

There is more than one lua folder in the gamedata folder. This lua folder is located in the mohodata.scd.

Blueprint loading
# 
# During preloading of the map, we run loadBlueprints() from this file. It scans
# the game directories and runs all .bp files it finds.
#
#The .bp files call UnitBlueprint(), PropBlueprint(), etc. to define a blueprint.
#All those functions do is fill in a couple of default fields and store off the 
#table in 'original_blueprints'. 
#
#Once that scan is complete, ModBlueprints() is called. It can arbitrarily mess
#with the data in original_blueprints.
#
#Finally, the engine registers all blueprints in original_blueprints to define the
#"real" blueprints used by the game. A separate copy of these blueprints is made
#available to the sim-side and user-side scripts. 
#
#How mods can affect blueprints 
#
#First, a mod can simply add a new blueprint file that defines a new blueprint.
#
#Second, a mod can contain a blueprint with the same ID as an existing blueprint.
#In this case it will completely override the original blueprint. Note that in
#order to replace an original non-unit blueprint, the mod must set the "BlueprintId"
#field to name the blueprint to be replaced. Otherwise the BlueprintId is defaulted
#off the source file name. (Units don't have this problem because the BlueprintId is
#shortened and doesn't include the original path).
#
#Third, a mod can contain a blueprint with the same ID as an existing blueprint,
#and with the special field "Merge = true". This causes the mod to be merged with,
#rather than replace, the original blueprint.
#
#Finally, a mod can hook the ModBlueprints() function which manipulates the
#blueprints table in arbitrary ways.
#1. create a file /mod/s.../hook/system/Blueprints.lua
#2. override ModBlueprints(all_bps) in that file to manipulate the blueprints
#
#Reloading of changed blueprints
#
#When the disk watcher notices that a .bp file has changed, it calls
#ReloadBlueprint() on it. ReloadBlueprint() repeats the above steps, but with
#original_blueprints containing just the one blueprint.
#
#Changing an existing blueprint is not 100% reliable; some changes will be picked
#up by existing units, some not until a new unit of that type is created, and some
#not at all. Also, if you remove a field from a blueprint and then reload, it will
#default to its old value, not to 0 or its normal default.
#

Most Dev tips are just a few lines long. This dev spent some time writing this because the information is important for modding the game. Attention should be paid to these dev tips when you are looking through the various files and folders. Studying the above tip is very helpful in understanding merging and creating new blue prints which is essential knowledge for unit modding

LOCATING UNITS IN THE UNITS FOLDER

THE UNITS FOLDER

The Units folder contains 679 folders. The folders themselves contain various numbers of files and DDS images. Some of the props bp's only have 2 files in them. The Aeon T1 mass extractor has 12 files including DDS. There are thousands of places to make a mistake. Remember the Log Window is your friend. Edit in small increments and test often.

GPG choose to use an alpha numeric system for the unit id system. This system is not that user friendly considering there are 679 total files with only 3 letters and 4 numbers to identify the units

The 3 original factions have a U as the first letter in the bp name. When they added the Seraphim they used an X. X is intended to mean expansion. All the new buildings and units for all the other factions in the FA expansion also begin with X.

The U for the original factions stands for UNITS. the next letter identifies the faction.
A= Aeon
E= Earth
R= Cybran

R= Cybran? For those who do not know Cybran was not the original intended name for that faction. They were originally intended to be named Recyclers but as the game developed and before it was released the name was changed to Cybran.Every once in a while in the various files you will still come across the original Recyclers name. When you see Recyclers it actually means the Cybrans

When FA came out X was added to the Units folder. The Seraphim faction is XS

The third letter identifies Unit type. Again, using the Aeon and following the Aeon Unit type as they are listed in order in the Units folder it works like this,

UAA=Air

UAB=Buildings

UAC=Civilian Buildings

UAL=Land

UAS=Ships

The mass extractor's are classed as buildings.

If you need to find a specific unit and do not know it's actual bp number there are a couple of files in the lua.scd that can be very helpful. One such file is,

lua/ui/help/unitdescriptions.lua.

It seems to list every unit that is in the game.

Using this file if you are looking for the bp number of the Cybran Tech 1 radar. Going to the units description lua you will find.

['urb3101'] = '<LOC Unit_Description_0216> Radar system with minimal range. Detects and tracks surface and air units.',

Or looking for an expansion unit. The Megalith Crab egg for instance

##Crab Egg Units
['xrl0002'] = '<LOC Unit_Description_0447> Tech 3 amphibious construction, repair, capture and reclamation unit.',
['xrl0003'] = '<LOC Unit_Description_0448> Amphibious assault bot. Capable of attacking land and naval units.',
['xrl0004'] = '<LOC Unit_Description_0449> Mobile AA unit. Armed with flak artillery.',
['xrl0005'] = '<LOC Unit_Description_0450> Slow-moving heavy artillery. Must be stationary to fire.',

Now you have a name to go with the unit bp id number making your search in units easier.

Another good place to look is Platoontemplates lua. The file path is

/lua/platoontemplates.lua

Not to be confused with the Platoontemplates in the lua\AI\Platoontemplate folder. This Platoontemplate lua is in lua.scd\lua\platoontemplates.lua It is right under the the Platoon.lua .

The Platoontemplates.lua in the lua appears to be some kind of master template that has all the platoon templates in one file that all the other templates hook into.It can be useful to make copies of these two files and put them in a tool box folder in your mod work folder for quick reference.

SECTION 2a The UAB1103 AEON T1 MASS EXTRACTOR BLUEPRINT

Extract your units.scd folder and look for UAB1103. This is a big scd. It takes a little time to extract and to repack

Now that the units folder is extracted open the UAB1103 folder and look at the various files contained inside. There are 12 including the DDS files. When creating a custom blue print it will be necessary to rename each and every one of those files with a new name. Take a quick look inside the UAB1103_script.lua. Notice this line.

local AMassCollectionUnit = import('/lua/aeonunits.lua').AMassCollectionUnit

This means that this code calls on another function outside of the script file to do what it needs to do. The file path tells you exactly where that called function is. It is in the lua.scd in the lua folder in the aeonunits.lua text file and the function to look for inside that file is.AMassCollectionUnit.

It is necessary for you to learn how to trace a unit and its functions through the various files. Many units including the extractors call functions across a broad spectrum of files. Miss some obscure file somewhere and your mod will not work. This is another place where a good code editor is useful. Crimson Editor has a find in files search function. High light uab1103,Open the search\find in files in the tool bar and using the browse option on the find in files template select the lua folder. There is another check box on the template that says check in sub folders. Select that and it will search the entire lua folder for any and every mention of uab1103. It finds them in order. It will give you exact file location of where they are located. A new window opens in the editor with all these locations indexed. Double click a line in the new window and it instantly opens that file for you to read. The weak point is if there are to many binary files i.e non text like DDS in a folder it chokes the editor. It can zip through text files but in a folder like Textures or Units that are loaded with images the editor can sometimes crash using Find in Files.

EXPLANATION OF THE FIELDS IN THE UAB1103 BLUEPRINT

The following is a general explanation of the various fields of the uab1103 blue print. More experienced people may want to skip over this part

Open the UAB1103_unit.bp This is the main unit blue print for the Aeon T1 mass extractor bp. It has 203 total lines of code. Notice it is all table constructors{ } Look at the very top, UnitBlueprint {

That is the opening constructor. It's pair mate, } is the very last line of code at line 203. And then there are all the various { } through out the bp. Notice that all the closing constructors for the various bp fields have a comma after the }. Using the very top field as an example,

AI = { # outer table opens
TargetBones = { # inner table opens
'Turret01_B02',
'Turret02_B02',
'Turret03_B02',
   }, # inner table closes
}, # outer table closes

This code tells an Ai attack unit where to aim its weapon when attacking the extractor. Look at the two }, constructors. This is a good example to use because it is a very small code block The first AI = { closes at the last }, The table inside opens with TargetBones = {

and closes at 'Turret03_B02', },

The comma means that there is no more information from this table after that point. Without the comma the table is still open and it will cause an error when you try to run the game. This # symbol is a comment symbol. In Lua 5.0 this symbol can be used to" COMMENT" a line. That means that the game will not read that line. Looking at the dev tip above every line he writes starts with #. If it did not the game would crash because it does not expect to see anything like a dev tip written in the game code. The # can very useful for trouble shooting a block of code that is giving you problems. For example,

#AI = {
#TargetBones = {
#'Turret01_B02',
#'Turret02_B02',
#'Turret03_B02',
   #},
#},

The game will not read this code. It will pass over it. This is also useful for making your own notes and marking positions where you made your own edits in a file. I.E

#edited bp from health 100 to health 150

In Lua 5.1 and above the # now has been assigned a function and it can no longer be used as a comment. Another use of a good editor is you can select large or small blocks of code and comment them out using the editors comment function. Crimson Editor comments out lines of code like this,

#LOG('*AI DEBUG: RETURNING ECONOMY NUMBERS FROM AIBRAIN ', repr(aiBrain))
-- local econ = {}
-- econ.MassTrend = aiBrain:GetEconomyTrend('MASS')
-- econ.EnergyTrend = aiBrain:GetEconomyTrend('ENERGY')

The -- comments out the code

Notice the #LOG('*AI DEBUG: ? You will find these commented lines throughout the game files.

If you open it or uncomment it, LOG('*AI DEBUG: RETURNING ECONOMY NUMBERS FROM AIBRAIN ', repr(aiBrain)) It will print out information to your log window in the game. When you get familiar with these you will start learning to write your own and they are extremely useful for trouble shooting but be careful with them. Loop debugs can spew thousands of entries into the log window in just a few minutes creating excessively long log files.

If you have a code editor that has a find in files function you can tell it to look for LOG('*AI DEBUG: and it will find and show you every debug line in the lua or any other folder. You can use select all in the file window and cut and paste these into a new text file. Put them in your tool box and you have a handy debug library that you can use for adding debugs to your own code edits to help you trouble shoot.

Next Section

Adjacency = 'T1MassExtractorAdjacencyBuffs',

If you have played the game long enough you know that certain units give you bonuses if you build next to them. This calls to the 'T1MassExtractorAdjacencyBuffs', which sets the amount of bonus received. Next section,

Audio = {
ActiveLoop = Sound {
Bank = 'UAB',
Cue = 'UAB1103_Active',
LodCutoff = 'UnitMove_LodCutoff',
},
Destroyed = Sound {
Bank = 'UALDestroy',
Cue = 'UAB_Destroy_Land',
LodCutoff = 'UnitMove_LodCutoff',
},
DoneBeingBuilt = Sound {
Bank = 'UAB',
Cue = 'UAB1103_Activate',
LodCutoff = 'UnitMove_LodCutoff',
},
UISelection = Sound {
Bank = 'Interface',
Cue = 'Aeon_Select_Resource',
LodCutoff = 'UnitMove_LodCutoff',
    },
},

The sounds the unit makes in the game. This calls to the sound folder. It is in the root Supreme Commander folder.

Next section,

Categories = {
'PRODUCTSC1',
'SELECTABLE',
'BUILTBYTIER1ENGINEER',
'BUILTBYTIER2ENGINEER',
'BUILTBYTIER3ENGINEER',
'BUILTBYCOMMANDER',
'AEON',
'STRUCTURE',
'ECONOMIC',
'TECH1',
'MASSPRODUCTION',
'MASSEXTRACTION',
'SIZE4',
'VISIBLETORECON',
'RECLAIMABLE',
'SHOWQUEUE',
'SORTECONOMY',
},

This is an important section. You can add or remove from it. Remember to add your custom category as all capitals inside this lua symbol ' ', just like all the rest of them are written in the categories field. This is how you get an engineer or factory to build or not build a unit. If you remove the 'BUILTBYTIER3ENGINEER', when you start the game and look at the T3 engineer you will see that the Aeon T1 extractor is no longer in the T3 build menu.

Next section

Defense = {
AirThreatLevel = 0,
ArmorType = 'Structure',
EconomyThreatLevel = 1000,
Health = 800,
MaxHealth = 800,
RegenRate = 0,
SubThreatLevel = 0,
SurfaceThreatLevel = 0,
},

In this section you can create a God mode indestructible extractor. You can change armor types, health etc. If you add a number to the RegenRate = 0, it will heal itself. The higher the number the faster it heals. Surface threat MAYBE the threat rings the game uses to determine how dangerous a target.If an Ai attack unit comes in range it picks up how big of a threat the in range enemy unit is.

Next section

Description = '<LOC uab1103_desc>Mass Extractor',

Add your unique unit name to this to have it show in the game.

Next section

Display = {
Abilities = {
'<LOC ability_upgradable>Upgradeable',

Determines if the unit can upgrade. Remove this ability and it will stay at the same tech level forever.

Next section

AnimationActivate = '/units/UAB1103/UAB1103_apump.sca',
AnimationUpgrade = '/units/UAB1103/UAB1103_aupgrade.sca',
Mesh = 
IconFadeInZoom = 130,
LODs = {
{
LODCutoff = 120,
Scrolling = true,
ShaderName = 'Aeon',
},
{
AlbedoName = 'uab1103_lod1_albedo.dds',
LODCutoff = 215,

ShaderName = 'Aeon',
SpecularName = 'uab1103_lod1_specteam.dds',
    },
  },
},
PlaceholderMeshName = 'UXB0017',
SpawnRandomRotation = true,
Tarmacs = 
{
Albedo = 'Tarmacs/Tar6x_aeon_01_albedo',
DeathLifetime = 300,
FadeOut = 150,
Length = 6.4,
Normal = 'Tarmacs/Tar6x_aeon_01_normals',
Orientations = {
0,
90,
180,
270,
},
RemoveWhenDead = false,
Width = 6.4,
   },
},
UniformScale = 0.15,
},

This calls on the DDS files in the first level of this blue print. The LOD file is Level of Detail. There are two of these files. They change the amount of Model Polygons when viewing the model from far way and up close. Less detail when zoomed out and more detail when zoomed in close. You can change these settings but it may cause you lag problems if you change the more detailed settings to show at a farther distance. The albedo DDS affect the shadows that units cast in the game. If you have never noticed the shadows before then start the the game and zoom in on an extractor and you will see a very detailed shadow with its animation timed to the animation of the model itself. As the unit moves the shadow moves with it.

AnimationActivate = '/units/UAB1103/UAB1103_apump.sca',
AnimationUpgrade = '/units/UAB1103/UAB1103_aupgrade.sca',

These two are model files.

Next section

Economy = {
BuildCostEnergy = 360,
BuildCostMass = 36,
BuildRate = 10,
BuildTime = 60,
BuildableCategory = {
'uab1202',
},

MaintenanceConsumptionPerSecondEnergy = 2,
ProductionPerSecondMass = 2,
RebuildBonusIds = {
'uab1103',
'uab1202',
'uab1302',
   },
},

You change this section to make the unit more expensive to build or cheaper. You change the time it takes to build etc.

BuildableCategory = {
'uab1202',
},

This is an important line. This designates the next unit the T1 extractor will upgrade to. Without this tag and the proper unit designated the structure will not upgrade

Next section

General = {
Category = 'Economy',
Classification = 'RULEUC_Resource',
CommandCaps = {
RULEUCC_Attack = false,
RULEUCC_CallTransport = false,
RULEUCC_Capture = false,
RULEUCC_Guard = false,
RULEUCC_Move = false,
RULEUCC_Nuke = false,
RULEUCC_Patrol = false,
RULEUCC_Pause = true,
RULEUCC_Reclaim = false,
RULEUCC_Repair = false,
RULEUCC_RetaliateToggle = false,
RULEUCC_Stop = false,
RULEUCC_Transport = false,
},

All the rules that apply to the extractor. If you wanted to you could add or remove some of these rules and you could actually mod a combination extractor nuke launcher or an extractor that repairs other units in its vicinity.

Next section

FactionName = 'Aeon',
Icon = 'land',
SelectionPriority = 5,
TechLevel = 'RULEUTL_Basic',
ToggleCaps = {
RULEUTC_ProductionToggle = true,
},
UnitWeight = 1,
UpgradesTo = 'uab1202',
},

In this section is a table that is essential to an upgradeable structure. UpgradesTo = 'uab1202',

If you were adding a new faction this is would be part of what you would need to edit. lets call them the Militants. You change FactionName = 'Aeon', to FactionName = 'Militants', Above in the categories section you change 'AEON', to 'MILITANTS', . It would look like,

Categories = {
'PRODUCTSC1',
'SELECTABLE',
'BUILTBYTIER1ENGINEER',
'BUILTBYTIER2ENGINEER',
'BUILTBYTIER3ENGINEER',
'BUILTBYCOMMANDER',
'MILITANTS',

Next section

Interface = {
HelpText = '<LOC uab1103_help>Mass Extractor',
},
LifeBarHeight = 0.075,
LifeBarOffset = 0.35,
LifeBarSize = 0.9,
Physics = {
BankingSlope = 0,
BuildOnLayerCaps = {
LAYER_Air = false,
LAYER_Land = true,
LAYER_Orbit = false,
LAYER_Seabed = true,
LAYER_Sub = false,
LAYER_Water = false,
},
BuildRestriction = 'RULEUBR_OnMassDeposit',<---------- Build Restriction
DragCoefficient = 0.2,
FlattenSkirt = true,
MaxSteerForce = 0,
MeshExtentsX = 1, 
MeshExtentsY = 0.55,
MeshExtentsZ = 1,
MinSpeedPercent = 0,
MotionType = 'RULEUMT_None',
SkirtOffsetX = -0.5,
SkirtOffsetZ = -0.5,
SkirtSizeX = 2,
SkirtSizeZ = 2,

TurnRate = 0,
},

Much of this is model information but you can see here the, BuildRestriction = 'RULEUBR_OnMassDeposit', And we will be editing this line HelpText = '<LOC uab1103_help>Mass Extractor',

The few lines left are all mostly model information.

SECTION 4a CREATING A UNIQUE BLUEPRINT

THE FOLLOWING STEPS WILL CHANGE THE UAB1103 TO A UNIQUE UAB1107

When all the edits are finished this Mass Extractor will be able to be built anywhere on the map

Starting with the actual unit bp folder Id. from the units.scd rename UAB1103 to UAB1107

Open the folder and rename all 12 files inside from UAB1103_xxxxxxxx to UAB1107_xxxxxxxxx

Remember that for a full mod this same process must be done for the other 11 extractors.

Open the newly named UAB1107_script.Lua and change,

UAB1103 = Class(AMassCollectionUnit) { <-----------HERE FROM UAB1103 = Class TO UAB1107 = Class
OnStartBuild = function(self, unitBeingBuilt, order)
AMassCollectionUnit.OnStartBuild(self, unitBeingBuilt, order)
if not self.AnimationManipulator then return end
self.AnimationManipulator:SetRate(0)
self.AnimationManipulator:Destroy()
self.AnimationManipulator = nil
end,
#
PlayActiveAnimation = function(self)
AMassCollectionUnit.PlayActiveAnimation(self)
if not self.AnimationManipulator then
self.AnimationManipulator = CreateAnimator(self)
self.Trash:Add(self.AnimationManipulator)
end
self.AnimationManipulator:PlayAnim(self:GetBlueprint().Display.AnimationActivate, true)
end,
#
OnProductionPaused = function(self)
AMassCollectionUnit.OnProductionPaused(self)
if not self.AnimationManipulator then return end
self.AnimationManipulator:SetRate(0)
end,
#
OnProductionUnpaused = function(self)
AMassCollectionUnit.OnProductionUnpaused(self)
if not self.AnimationManipulator then return end
self.AnimationManipulator:SetRate(1)
end,
}
TypeClass = UAB1103<----------- AND HERE FROM TypeClass = UAB1103 TO TypeClass = UAB1107

BE AWARE!!!! In this particular script these were the only two places that the old unit id was used. Your bp script for your modded structure may be different. The id number may also be used somewhere inside the script itself. Be sure to read the actual script and make sure that you have changed every use of the old unit id number to your new custom unit id number or your mod will not work.

Open the newly named UAB1107_unit.bp itself. It is not necessary to change the sound files unless you have a unique sound folder that you have created for your unit. Be advised that the game sound files are created by a program called XACT. Using another program may cause problems.

In the Categories section of the bp add a unique name for your new unit. The example name for this tutorial will be 'DEEPCORE',

Categories = {
'PRODUCTSC1',
'SELECTABLE',
'BUILTBYTIER1ENGINEER',
'BUILTBYTIER2ENGINEER',
'BUILTBYTIER3ENGINEER',
'BUILTBYCOMMANDER',
'AEON',
'STRUCTURE',
'DEEPCORE',<--------------------ADD YOUR UNIQUE UNIT NAME
'ECONOMIC',
'TECH1',
'MASSPRODUCTION',
'MASSEXTRACTION',
'SIZE4',
'VISIBLETORECON',
'RECLAIMABLE',
'SHOWQUEUE',
'SORTECONOMY',
},

You will need a unique name to set up the Ai to recognize and build your new unit. If you do not set up the Ai and give it some information to find your unit then in the game the player will be able to build your new unit, upgrade it and anything else you coded it to do but the Ai will not because it does not even know that you added a new unit.

Next go down to the Description = ' line and change it to reflect your unit changes,Using the Deep Core example,

Description = '<LOC uab1107_desc> Deep Core Mass Extractor',

The next step is go to the animations line,

Change

AnimationActivate = '/units/UAB1103/UAB1103_apump.sca',
AnimationUpgrade = '/units/UAB1103/UAB1103_aupgrade.sca',

to

AnimationActivate = '/mods/metal_mod_player_test/units/UAB1107/UAB1107_apump.sca',
AnimationUpgrade = '/mods/metal_mod_player_test/units/UAB1107/UAB1107_aupgrade.sca',

BE AWARE The animation file path above is only if you are using the Documents\Mygames folder. If you are creating an .scd mod the file path will be,

AnimationActivate = '/units/UAB1107/UAB1107_apump.sca',
AnimationUpgrade = '/units/UAB1107/UAB1107_aupgrade.sca'

Next is the Albedo section. Change them to reflect your unit id.

AlbedoName = 'uab1107_lod1_albedo.dds',
LODCutoff = 215,
ShaderName = 'Aeon',
SpecularName = 'uab1107_lod1_specteam.dds',
},

The Albedos files do not seem to share the same conflicts that can occur with the animation files.

Next is the Economy section.

Economy = {
BuildCostEnergy = 360,
BuildCostMass = 36,
BuildRate = 10,
BuildTime = 60,
BuildableCategory = {
'uab1203', <--------------- change this line to the id of your next level unit that you want your unit to upgrade to.
},

The original Aeon T2 mex is UAB1202. If you wish to actually build and test the custom extractor from this tutorial you will need to have a custom T2 extractor to upgrade to. Create a T2 Aeon Extractor named UAB1203 and follow all the same conversion steps that are being done to the uab1103. The original Aeon T2 extractor and all the other factions are also governed by the RULEUBR_OnMassDeposit. The build anywhere custom extractor cannot upgrade to the original extractor unit nor can an original 1103 upgrade to a modded 1203. Oil and water. You can not mix the two classes of extractors.

Next is,

Interface = {
HelpText = '<LOC uab1304_help> T3 Deep Core Extractor',

Edit the interface to show the unique name and information that will show up in your game. Remember that the text boxes for unit info in the game are very small.

Next is

LAYER_Land = true,
LAYER_Orbit = false,
LAYER_Seabed = true,
LAYER_Sub = false,
LAYER_Water = false,
},
BuildRestriction = 'RULEUBR_OnMassDeposit',<--------------------Change'RULEUBR_OnMassDeposit to 'RULEUBR_NONE
DragCoefficient = 0.2,
FlattenSkirt = true,

THE AEON T2 EXTRACTOR. IF YOU WISH TO ACTUALLY BUILD AND TEST THIS CUSTOM UNIT YOURSELF You will need to edit the Aeon Tech2 bp, You have to designate the buildable catagory that you want your T2 extractor to upgrade to which is a T3 extractor,

BuildableCategory = {
'uab1304',
},

uab1304 is a custom T3 extractor id.

And here

UpgradesFrom = 'uab1107',
UpgradesTo = 'uab1304',

to upgrade from T1 to T2 you need identify the unit that it will be upgrading from. For the unit to upgrade to T3 you need to identify what the T2 will upgrade to

For Aeon T3 bp

T3 is the final level so you do not need to add the buildable category. But you do need to add the Upgrades from category

UnitWeight = 1,
UpgradesFrom = 'uab1203',
},

If you are modding a unit that starts at T1 and upgrades all the way to a T4 experimental unit. Then in your T3 you would have to identify the buildable category and you would have the "upgrades from" and the "upgrades to". depends on how many times you want your particular unit to upgrade as to how you set up your bp.

Do not forget to change the RULEUBR_ to read none for both the T2 and T3 custom extractors

The next step is to add the custom extractor into the Ai so it knows to build and upgrade the structure when you have Ai commanders in your game

SECTION 5a ADDING YOUR NEW STRUCTURE TO THE AI,

ADDING YOUR STRUCTURE TO THE AI PLATOON AND UPGRADE LUA'S

BE AWARE!!!
This section is about adding a STRUCTURE to the Ai so that it will build and upgrade it via the structure upgrade system. If you are building a mobile attack unit such as a tank, plane, ship etc you need to use a different upgrade system called the ENHANCEMENT UPGRADE system. This is the system the Commander and Sub Commanders use to upgrade.

Listed below are all the files that you will need to add your new structure to if you want the Ai to build it with a code example using the Deep Core extractors used in the new blueprint creation section.

FILE PATH = \gamedata\lua.scd\lua\Platoontemplates.lua

This is not the Platoontemplates found in the lua\Ai folder. This Platoontemplates.lua is in the first level of the lua file in lua.scd

Add your new unit to the Platoontemplates.lua. This is for the Aeon faction T1 again.

T1DeepCoreUpgrade={
"T1DeepCoreUpgradeMetal",
"UnitUpgradeAI",
{ "uab1107", 1, 1, "support", "None" }
},

The Platoontemplates.lua. is divided into factions and then faction units by category. engineer,etc. This is to keep things structured and organized for humans to find there away around. It is always a good idea to comment your edits not just for your own use but so others can see what and where you made changes. For your custom unit find the correct faction or factions and add your new unit into the Platoontemplates.lua. Remember that you need to add a platoon for each new tech level id that your unit will be upgrading to.

If you put Platoontemplates.lua. into mymod\hook\lua\Platoontemplates.lua. it will work. Just remember to make a unique unit id for your custom unit.The reason for this is if you try to use both the original Aeon extractor name and id number,

T1MassExtractorUpgrade={
"T1MassExtractorUpgrade",

"UnitUpgradeAI",

{ "uab1103", 1, 1, "support", "None" }
},

The game will give you a Warning Duplicate Platoon Template Detected. message in the log window. Change either the letters, MMB1103 or the numbers,UAB1107, or both,MMB1107. It is the information that is contained inside the bp that designates who or what builds a structure or unit.

NEXT FOLDER

FILE PATH = \gamedata\lua.scd\lua\AI\PlatoonTemplates\StructurePlatoonTemplates.lua

In this file add,

PlatoonTemplate {
Name = 'T1DeepCoreUpgradeMetal',
Plan = 'UnitUpgradeAI',
GlobalSquads = {
{ categories.TECH1 * categories.DEEPCORE * categories.MASS, 1, 1, 'support', 'none' }
   },
}

For your own mod you will have to use the correct Platoontemplate in the correct folder. Air, Engineer, Land, Sea or Structure. Notice here the use of the unique name category added to the bp category list to set up the Ai. This separates the custom unit from the original extractors

{ categories.TECH1 * categories.DEEPCORE * categories.MASS, 1, 1, 'support', 'none' }

NEXT FOLDER

FILE PATH =\gamedata\lua.scd\lua\upgradetemplates.lua This file contains all the code for the game to identify all the upgradeable units.

# Deep Core extractors
{ 'uab1107', 'uab1203'},
{ 'uab1203', 'uab1304'},

Notice you have to add the upgrade sequence, 1107 to 1203 1203 to1304.

If you want to add a factory here is an example of the Aeon Land Factory code.

# land factory
{ 'uab0101', 'uab0201'},
{ 'uab0201', 'uab0301'},

NEXT FOLDER

FILE PATH =\gamedata\lua.scd\BuildingTemplates.lua

{
'T1DeepCore',
'uab1107',
},

Another categorized list the game searches looking for things the Ai can build. Find your category and add your structure there.

NEXT FOLDER

FILE PATH=\gamedata\lua.scd\lua\basetemplates.lua

This is a file the Ai uses to build base's. It is very very long and contains all the templates for the main base, expansion bases, defensive points etc. You will see a list of buildable units and then a list of co ordinates like this.

{ -30, -29, 0 },
{ -30, -27, 0 },
{ -30, -25, 0 },
{ -30, -23, 0 },

These co ordinate lists are long and at the end of each co ordinate list another template starts.

The best way to do it is to start at the very top, Add your structure, select a structure that is already there and use FIND NEXT. You need to work your way all the way to the bottom adding an entry to each faction that you want to build your unit.

The entry is a just a simple string.

'T2Resource',
'T2DeepCore',
'T3MassExtraction',

The co ordinates are random. It is not { -30, -29, 0 }, = build factory here. It is { -30, -29, 0 }, = build something here from the list if build requirements permit. This will cause the Ai to search various functions per unit in the list to see what it can build.

Next Folder

File Path = \gamedata\lua.scd\lua\ai\AIEconomyUpgradeBuilders.lua

This template tells the Ai when and under what conditions it can upgrade your structure. Using the extractor example copy an already existing extractor template and edit it to apply to your structure.

BuilderGroup {
BuilderGroupName = 'Time Exempt Deep Core Upgrades Metal', 

   BuildersType = 'PlatoonFormBuilder', 

   Builder { 

       BuilderName = 'T1 Deep Core Upgrade Timeless SingleMetal', 

       PlatoonTemplate = 'T1DeepCoreUpgradeMetal', 

       InstanceCount = 1, 

       Priority = 200, 

       BuilderConditions = { 

           { IBC, 'BrainNotLowPowerMode', {} }, 

           { EBC, 'GreaterThanEconIncome',  { 2.0, 10}}, 

           { EBC, 'GreaterThanEconEfficiencyOverTime', { 0.5, 1.2 }}, 

           { UCBC, 'HaveLessThanUnitsInCategoryBeingBuilt', { 1, 'DEEPCORE TECH2', 'MASS', } }, 

       }, 

       FormRadius = 10000, 

       BuilderType = 'Any', 

   },

Next Folder

File Path = \gamedata\lua.scd\lua\ai\AIBaseTemplates.lua

The next step is to add the new structure to the AiBaseTemplates identifying it as an upgradeable structure and what function or functions to call to upgrade the structure.

Using the RushMainAir Template as our example,

# Extractors
       'Time Exempt Extractor Upgrades Metal',
       'Time Exempt Deep Core Upgrades Metal',

BuilderGroupName = Time Exempt Extractor Upgrades is the original game upgrade template for the extractors. This example uses two modified upgrade templates. This string calls to,

BuilderGroupName = 'Time Exempt Deep Core Upgrades Metal',

When the game finds your BuilderGroupName= tag and the conditions are correct then the Ai will upgrade your structure in the game.

This is the end of all the folders you need to make entries to for the Ai to know that your new structure now exists and is upgradeable. Now you need to tell the Ai who builds it, when, and where.

ADDING YOUR STRUCTURE TO THE AI BUILDER TEMPLATES

NEXT FOLDER

FILE PATH =\gamedata\lua.scd\lua\AI\AIBuilders\AIEconomicBuilders.lua

Creating a custom builder template is easy. You can change this line to what ever you want. From BuilderName = 'T1ResourceEngineer 2000 Exp - Naval Metal', to BuilderName = 'T1MyStructureSpecialEngineer 2000 Exp - Naval Metal',

If you change, PlatoonTemplate = 'CommanderBuilder', to PlatoonTemplate = 'CommanderBuilderMetal', Then you will have to go into /lua/ai/EngineerPlatoonTemplates.lua and create a new platoon template by that name.

BE AWARE!!! Do not edit BuildersType = 'EngineerBuilder',
BuildersType cannot be customized with out some serious custom code being added to the various buildmanagers lua's. There are only three builder types recognized by the game,

EngineerBuilder
PlatoonFormBuilder
FactoryBuilder

If you try to custom name them you will recieve errors in the game. The BuildersType are used by the different platoon managers in the Sim folder and those managers are looking for a specific name. What can be confusing is the T1 Engineers use the EngineerBuilder Ai which is totally separate from the BuildersType = EngineerBuilder, You can customize the Engineer Builder Ai to any name you like as long as you remember to add your own custom platoon templates and have the custom named Ai in the Platoon.lua.

It is in the Categories section of the unit bp that the engineer units that can build the new unit are chosen. In the original UAB1103 Bp Aeon T1 mass extractor categories the following units are designated as the builders of the new structure,

'BUILTBYTIER1ENGINEER',
'BUILTBYTIER2ENGINEER',
'BUILTBYTIER3ENGINEER',
'BUILTBYCOMMANDER',

Remove any one of these and that engineer unit will not be able to build the new structure.

This ENABLES these units to build your structure but it does not ASSIGN these units to build it. If you do not actually assign the engineers and the commanders to build your structure then they will not build it. This is what the different files in lua\AIBuilders do. Everything is assigned by platoons. The Ai is constantly forming and disbanding various platoons and assigning orders that are relevant to that platoon. If it is a mobile attack force platoon then it is assigning attack orders. If it is an engineer platoon then it is assigning build orders. Platoons are not static. The Ai does not build three engineers and assign them to a build defenses platoon and that is where they stay for the whole game. The Ai is told how many of a certain unit it is allowed to build and under what conditions it is allowed to build them. Here is the code from the RushMainAir.lua base template that tells the Ai how many engineers it can have in the game at one time.

BaseSettings = {
EngineerCount = {
Tech1 = 15,
Tech2 = 10,
Tech3 = 10,
SCU = 1,
},

This limits the pool of builders the Ai has to work with. 3 Tech 1 engineers may be assigned to one platoon to build three mass extractors. After the three extractors are built the Ai then disbands the platoon and re assigns them to different platoons. One may go build a factory the second go build a Point Defense and third may be assigned to a reclaim platoon. The game is constantly searching the builder lua's looking for something to build. Your structure needs to be in one of the builder templates for it to find.

In this code example the commander is told to build the new structure as soon as the game starts.

Builder {
BuilderName = 'CDR Initial Land Rush Metal',<------This builder name is customized by adding Metal to the original name
PlatoonAddBehaviors = { 'CommanderBehaviorSorian', },
PlatoonTemplate = 'CommanderBuilderMetal',<--------Notice this example uses a custom platoon template
Priority = 1000,
BuilderConditions = {
{ IBC, 'NotPreBuilt', {}},
},
InstantCheck = true,
BuilderType = 'Any',
PlatoonAddFunctions = { {SAI, 'BuildOnce'}, },<----- The SAI insures that this build template will only be used one time and not called again
BuilderData = {
Construction = {
BuildStructures = {
'T1EnergyProduction',
'T1EnergyProduction',
'T1LandFactory',
'T1DeepCore',<------The New structure is added to the commanders build orders
'T1DeepCore',
'T1DeepCore',
'T1EnergyProduction',
'T1LandFactory',
'T1EnergyProduction',
'T1EnergyProduction',
'T1AirFactory',
'T1GroundDefense',
'T1AADefense',
       }
     }
  }
},

If the Ai is going to use the Rush Land Ai against you then the very first thing the Commander builds when it is spawned into the game is 'T1EnergyProduction', and then Commander works his/her way down the Build list. Notice this line,

PlatoonTemplate = 'CommanderBuilderMetal',

That is the first platoon the Commander is assigned to. When the Commanders finish this build list then they are re assigned to another platoon. Each Ai i.e. Rush Naval, Rush Air Rush Land has its own initial start template. If you want the Commander to build your structure right away then you need to add it to the list of each Ai build template found here.

If you want the engineers to build your structure then you do it like this.

Builder {
BuilderName = 'T1ResourceEngineer 2000 Exp - Naval Metal',
PlatoonTemplate = 'EngineerBuilderMetal',
Priority = 850,
InstanceCount = 1,
BuilderConditions = {
{ UCBC, 'HaveLessThanUnitsWithCategory', { 10, 'MASSEXTRACTION TECH1'} },
{ UCBC, 'HaveLessThanUnitsWithCategory', { 5, 'DEEPCORE TECH1'} },
{ UCBC, 'HaveLessThanUnitsWithCategory', { 3, 'DEEPCORE TECH2'} },
{ UCBC, 'EngineerLessAtLocation', { 'LocationType', 3, 'ENGINEER TECH2, ENGINEER TECH3' }},
{ MABC, 'CanBuildOnMassLessThanDistance', { 'LocationType', 2000, 1000, 1, 0, 'AntiSurface', 1 }},
{ EBC, 'MassToFactoryRatioBaseCheck', { 'LocationType' } },
{ UCBC, 'HaveLessThanUnitsWithCategory', { 30, 'MASSEXTRACTION'} },
{ IBC, 'BrainNotLowPowerMode', {} },
},
BuilderType = 'Any',
BuilderData = {
#NeedGuard = true,
DesiresAssist = false,
Construction = {
BuildStructures = {
'T1DeepCore',
'T1DeepCore',
        }
      }
   }
},

Earlier you saw the basetemplates.lua with all the Ai build co ordinates listed and it was mentioned that they were random. The Ai needs to search various functions to find what units it is allowed to build under current game conditions. Here is an example of some of the various Ai control functions.

BuilderConditions = {
{ UCBC, 'HaveLessThanUnitsWithCategory', { 10, 'MASSEXTRACTION TECH1'} },

{ UCBC, 'HaveLessThanUnitsWithCategory', { 5, 'DEEPCORE TECH1'} },

{ UCBC, 'HaveLessThanUnitsWithCategory', { 3, 'DEEPCORE TECH2'} },

{ UCBC, 'EngineerLessAtLocation', { 'LocationType', 3, 'ENGINEER TECH2, ENGINEER TECH3' }},

{ MABC, 'CanBuildOnMassLessThanDistance', { 'LocationType', 2000, 1000, 1, 0, 'AntiSurface', 1 }},

{ EBC, 'MassToFactoryRatioBaseCheck', { 'LocationType' } },

{ UCBC, 'HaveLessThanUnitsWithCategory', { 30, 'MASSEXTRACTION'} },

{ IBC, 'BrainNotLowPowerMode', {} },

},

This is how the Ai is controlled and balanced.

{ UCBC, 'HaveLessThanUnitsWithCategory', { 10, 'MASSEXTRACTION TECH1'} },

If there are less than 10 original mass extractors it can build the extractors IF

{ UCBC, 'HaveLessThanUnitsWithCategory', { 5, 'DEEPCORE TECH1'} },

There have to be less than 5 of the custom extractors already built if there less than 5 and less than 10 originals then it can build IF

{ UCBC, 'HaveLessThanUnitsWithCategory', { 3, 'DEEPCORE TECH2'} },

There are less than 3 of custom extractors all ready upgraded to tech 2 and on it goes down the list. Each requirement must be satisfied before it can build another extractor. If even 1 requirement comes back false the Ai will look for something else to build.

You can create as many of these different platoons as you want using different build requirements. Early game you may want most of your T1 engineers building your structure so you make a couple of templates with very liberal requirements and as the game progresses You want the Ai to build less and less your structure and more of something else so you make more restrictive build requirements. What needs to be remembered here is that you can not use the same BuilderName twice. Each template must have a unique builder name. For example,

BuilderName = 'T1ResourceEngineer 2000 Exp - Naval Metal',

If you want to add another T1 group,

BuilderName = 'T1ResourceEngineer 2000 Special Exp - Naval Metal',

And then add what ever build requirements you choose to add. You can assign the same Ai to the T1 engineers as many times as you want.Going through the various builder files it can be seen the most common engineer Ai is the EngineerBuilder Ai. T2 and T3 have their own T2EngineerBuilder and T3EngineerBuilder Templates.

These lines also help you control the Ai.

Priority = 850,

Level of how important this build really is. If you change it to 100 then even if the build requirements are met and there is another build template with higher priority the Ai will select the higher priority template first.

InstanceCount = 1,

How many platoons can exist at one time in the game with orders to build your structure. If there is already 1 platoon that has been assigned this task then it will not create another platoon. It will look for something else to build.

Balancing an Ai is extremely time consuming and there are many more of these build conditions involving not just the engineers but also involving other units and structures that all tie in together.

If you want the other tech level engineers to build your structure of course you have to make all the same edits as you do to the Commander and the T1 engineers.

Here is an example from \gamedata\lua.scd\lua\AI\AIBuilders\ AIFactoryConstructionBuilders.lua for getting an engineer to build a factory

Builder {
BuilderName = 'T1 Land Factory Builder - MetalInitial',
PlatoonTemplate = 'EngineerBuilderMetal',
Priority = 1000,
BuilderConditions = {
{ IBC, 'BrainNotLowPowerMode', {} },
{ UCBC, 'FactoryCapCheck', { 'LocationType', 'Land' } },
{ EBC, 'MassToFactoryRatioBaseCheck', { 'LocationType' } },
},
BuilderType = 'Any',
BuilderData = {
Construction = {
Location = 'LocationType',
BuildStructures = {
'T1LandFactory',
'T1LandFactory',
        },
      }
    }
  },
}

If you are adding a mobile unit it works the same as with a structure. You have to tell the appropriate factory what you want it to to build. Here is a land factory example for telling it to build a tank.

# Priority of tanks at tech 2 
# Won't build if economy is hurting
Builder {
BuilderName = 'T1 Light Tank - Tech 2',
PlatoonTemplate = 'T1LandDFTank',
Priority = 500,
BuilderConditions = {
{ UCBC, 'FactoryLessAtLocation', { 'LocationType', 1, 'FACTORY LAND TECH3' }},
{ IBC, 'BrainNotLowPowerMode', {} },

{ EBC, 'GreaterThanEconEfficiencyOverTime', { 0.6, 1.05 }},
},
BuilderType = 'Land',
},

You can mod this to add your mobile unit into the game. Notice the Dev comments concerning how he set up the build conditions.

ADDING CUSTOM ICONS TO YOUR GAME.

Down load the Black Ops Global Icon support mod from this link, With out it the method explained here will not work.

http://supremecommander.filefront.com/file/Global_Icon_Support;99906

Put the Black Ops Global Icon support mod in your Documents\Mygames mod folder. When you start your game go to the mod manager screen and activate it.

You will need to extract the TEXTURES.SCD This is a very large folder and it will a little time for it to extract.

Using your image editor of choice customize a DDS image for your new unit.

After you have edited your icon create a new folder and name it textures.

You will have to create several more folders inside this one to establish the correct file path. The correct file path is,

\textures\ui\common\icons\units

A total of 5 folders. Place your customized DDS images in the units folder and put the Textures folder in your mymod folder. If you are using an scd pack it with your other mod files and place it in the gamedata folder or if you are using the Documents\Mygames mods folder then place it inside your unzipped mymod folder.

REMEMBER!!!! If you are using an scd with a lua, units and texture folder you do not put them inside the lua. select all three folders and zip them together into one scd. Use your open archive option on the scd and you should see three folders, lua, units and textures.

The same applies to the mods folder method except you do not zip it.

If you have done this correctly then when you start your game with the Black Ops Icon mod active your custom image should show in the unit build menu.