This is a guide on how to remove existing and add your own templates. You can read up about the feature in general here. Throughout this guide we'll be building our own templates that we can cycle through. We'll do this by creating a UI mod. You can then upload the mod to the vault. Make sure to have read the vault rules before you do that.
We assume you are familiar with a code editor. We also assume that you are familiar with structured text, specifically with the syntax of a Lua table. For those unfamiliar, we recommend you to use Visual Studio Code as your code editor. It has built in syntax highlighting for Lua. The remainder of this guide assumes you use Visual Studio Code.
We'll build the UI mod from scratch. We do not assume you know how this procedure works. We'll do our best to explain what we need in this guide. For more information we recommend these articles written by Balthazar.
If you have questions at any point you are welcome to ask them on the official FAForever Discord. Once you've given yourself the modder role you can see the #modding-general
channel. We'll be there to help you if you get stuck on this guide.
We'll start by navigating to the mods folder. By default, the FAForever client tells the game to read mods from:
C:/ProgramData/FAForever/user/My Games/Gas Powered Games/Supreme Commander Forged Alliance/mods
You can check and confirm the location by launching the FAForever client. Then navigate to the bar menu (top left corner) and open the settings. Click on the Forged Alliance Forever
tab and there you'll find the location the game searches for mods:
Create a new folder in the mods folder. For this guide we'll call that folder guide-cbt-example
. It is better when there are no spaces in the name of the folder. Once created, go inside the folder. Your path should be:
C:/ProgramData/FAForever/user/My Games/Gas Powered Games/Supreme Commander Forged Alliance/mods/guide-cbt-example
In that folder, create a new file called mod_info.lua
. Open the file using your code editor. Paste the following content into the file:
name = "<your-mod-name>"
uid = "<your-mod-name>-<your-mod-version>"
version = 1
description = "<your-mod-description>"
author = "<your-user-name>"
icon = "/mods/<your-mod-folder-name/<your-icon-name>"
selectable = true
enabled = true
exclusive = false
ui_only = true
requires = {}
requiresNames = {}
conflicts = {}
before = {}
after = {}
Everything between <>
is up to you to decide. For this guide we'll go with the following:
name = "Context based templates - an example"
uid = "ctb-example-01"
version = 1
description = "An example on how to customize the context based templates"
author = "Jip"
icon = "/mods/guide-cbt-example/icon.png"
selectable = true
enabled = true
exclusive = false
ui_only = true
requires = {}
requiresNames = {}
conflicts = {}
before = {}
after = {}
Note that at this point the file icon.png
does not exist. It can be any picture, preferable 100x100 in resolution. Anything larger is not necessary. Take note of the syntax, strings (pieces of text) start and end with "
. Don't forget to save the file once you're done .
At this point we have a basic, skeleton UI mod that should show up in-game. To test this, start the game using the client and check the in-game mods manager. If it shows then you're good and you can continue the guide.
A mod 'hooks' the game by appending the files of your mod to the files of the game. This allows you to change and rewrite definitions in the original file. The file that we want to hook is the following file:
/lua/ui/game/hotkeys/context-based-templates-data.lua
That path is a relative path that points to this file on the repository of the game. We'll skip the details on how the relative path is constructed, it is too involved for the purpose of this guide. What matters to us is how we tell the game that we want to hook the file.
The first step is to add /hooks
to the start of the relative path. As a result the relative path looks like this:
/hook/lua/ui/game/hotkeys/context-based-templates-data.lua
The second step is to create a similar folder structure in our mod and then create a file with the same name. Our mod is located at:
C:/ProgramData/FAForever/user/My Games/Gas Powered Games/Supreme Commander Forged Alliance/mods/guide-cbt-example
We therefore create additional folders and then create the files to match the relative path. To match the folder structure we'll have the following path:
C:/ProgramData/FAForever/user/My Games/Gas Powered Games/Supreme Commander Forged Alliance/mods/guide-cbt-example/hook/lua/ui/game/hotkeys/context-based-templates-data.lua
And from the perspective of the mods folder:
/mods/guide-cbt-example/hook/lua/ui/game/hotkeys/context-based-templates-data.lua
Open the lua file context-based-templates-data.lua
and add the following:
WARN("It works!")
Start the game through the client. Enable your mod through the in-game mods manager. Launch the game. Once the game has launched you can open the debug log. It is usually bound to F9. If it doesn't work then you can search for it in the keybindings menu:
Once open you'll see a console-like log. Select the ACU that you spawned with and hit the cycle templates hotkey at least once. The files are now loaded and our mod should be hooked into it.