Getting started with modding

[Jeroen De Dauw]

I'm a dev with some experience (github com/JeroenDeDauw) and would like to start doing some modding. I've looked through this forums a bit, checked the GitHub FAF project and looked at some mods. A few years ago I created a little mod. Now I'm looking for help to get up and running in more professional manner without hitting my head against a wall for a few days. Questions:

* Is there a decent general guid for starting with writing mods that I should obviously check?
* I'm not a LUA dev. What development tools are recommended? In particular, I want a good IDE and a test runner. The main features I'd want in the IDE are basic navigation (including going to definition), autocompletion/browsing and live detection of obvious errors (ie cp errors or calling a method on a type that does not have it).
* How do I establish a quick feedback cycle? Writing a pile of code, starting FA, starting a game, and hitting some buttons is even worse than your typical UI driven debugging.
* Is there a recommended way to manage a mod. Things such as collecting bugs reports and contributions, keeping release notes, creating releases and publishing those. It's my impression that in general these things are simply not done, and the code of most mods is not even in VCS. Are there mods for which this is done more professionaly, at which I can look as example?
* Related to the previous point: if I want to contribute to an existing mod, how do I go about it?

[Aurion]

* Is there a decent general guid for starting with writing mods that I should obviously check?

There are some on the original forums I think. Don't have time to find them now, but I mostly look at the source from the mods in the mod vault. Although I'm not very active or experienced as FA modder.

* I'm not a LUA dev. What development tools are recommended? In particular, I want a good IDE and a test runner. The main features I'd want in the IDE are basic navigation (including going to definition), autocompletion/browsing and live detection of obvious errors (ie cp errors or calling a method on a type that does not have it).

I'm afraid it's hard to find a LUA IDE with autocompletion as well as navigation. Afaik most modders just use some code editors.

* How do I establish a quick feedback cycle? Writing a pile of code, starting FA, starting a game, and hitting some buttons is even worse than your typical UI driven debugging.

Someone else needs to help you with that I'm afraid. I think it's possible to start FA with commandline commands (and specific parameters) to start a game faster than manually setting up a game, but haven't seen how.

* Is there a recommended way to manage a mod. Things such as collecting bugs reports and contributions, keeping release notes, creating releases and publishing those. It's my impression that in general these things are simply not done, and the code of most mods is not even in VCS. Are there mods for which this is done more professionaly, at which I can look as example?
* Related to the previous point: if I want to contribute to an existing mod, how do I go about it?

Only way to somehow contribute to mods without VCS is to contact the mod author to ask for permission and edit the source. Nothing will stop you from just throwing your mod folders on Github and start your thread here to look for contributors, though. Which is what I'd recommend to do.

[The Mak]

Aurion pretty much hit all the points. Best way to learn is open up an existing mod and see how things are done, and with the game being this age there is a good chance that what you want to accomplish may have already been done. Going through the files of the featured mods is a great way to find a range of possibilities and functions.

The old GPG Forums is the basic repository of this knowledge. Unfortunately it is a bit unreliable in being available.

You may want to also review the old wiki, specifically the section labeled Supreme Commander internals. Here is a lisitng of functions from the last official version of FA (3599).

[Resin_Smoker]

Take a look at DMS... In a nutshell its a modders toolbox of functions made to simplify modding while adding additional features into the game. Beyond that, start small, till you've worked your way though most of the FA and FAF scripting. Please be aware however that many of the older mods spray have minor issues running with FAF. Simply put FAF rewrites a large part of the base lua and most of these modes were created before FAF came into being. Hence if your running an older mod stick with patch 3599!

P.S I've been modding FA since its Beta and know most anything you'd want to attempt and how it can be done. (There are a few limitations to the engine btw)

Resin

[nine2]

Disclaimer 1: I am a noob myself.
Disclaimer 2: I'm doing this from memory so the exact keywords are incorrect.

Starting guide. There are lots of tidbits floating around on different forums with examples but normally just find a mod that does something similar and look at it's code. Critically, the FA code is overridden by the FAF code which is overridden by your mod.

IDE - no way. No go to definition or test runner. Think notepad. I use visual studio because it's just a nice text editor. You can get plugins that understand lua (syntax highlighting) but I don't use them. Basically all you need is something that can find text across many files at once quickly. I have the FA and FAF codebases unzipped and windows-search-indexed so that I can search quickly. When I'm trying to find references of a function I just use windows search to find them. It's really really shit but it works quickly. Some functions are defined in C++ and are not findable or editable.

Feedback cycle. This way I can actually help.

a) use cheats enabled. Use the AI_INSTABUILD command to instantly build land factories and units (zero construction time). Bind this command to a keyboard shortcut. Much faster than going through the cheat UI (alt F2) to generate units. You can build a fac, upgrade it t3, and get your first brick out in 2 seconds.

b) know that ctrl-F10 will restart a skirmish game or replay

c) you can use command line args to speed things up.
- specify /map XYZ then it will launch with that map and skip the lobby which is much faster. However you cant enable cheats this way, so have another shortcut without it. I have tried to edit the game to allow cheats from command line but haven't managed to.
- specify /windowed so that it doesnt launch full screen and you can easily see the log window (F9 to display)
- specify /init XYZ.lua to provide custom mod launching script to enable your mod (as FAF itself does)
- specify /enablediskwatch so that FA automatically reloads your changes on the fly (you don't have to restart)

d) You can get instant feedback with a little bit of setup. Create a mod containing "script A" - a loop that executes every second. All it does is import a file of yours - "script B". Now create script B file and edit it with your IDE. Whenever you save changes to it, the loop in A will reimport B. Combined with the /enablediskwatch command line arg, B will get re-executed immediately. So now you have a file that you can edit and every time you save it, it will get executed instantly and results logged to the log window. You actually need a copy of this setup for UI-land and a copy for SIM-land. You can enhance script A so that it wont crash when B contains an error, giving you a chance to fix it and try again.

So to put all that together, once you are setup you can launch a game with a few clicks, turn on AI instabuild with a keystroke, get whatever units you need for your test in a few seconds, then modify your B script in your IDE and hit save and it will instantly run.

Topics to get your head around:
You need to understand difference between sim and ui mods, and what a desync really is. Once you get why a desync happens you intuitively understand what is possible with a sim and ui mod. It's all got to do with how the engine doesn't send your opponent actual sim state but just the commands issued.
You need to understand hooking and mod load order and how merging works.
You need to know about LOG and repr()
You need to know how FA files are structured (its a zip with certain folders inside)

If you want, I can provide those scripts I mentioned and the actual command line args I use. I also have a excel spreadsheet I made that contains all of the functions available ... kind of like luadoc but with heaps more in it that weren't mentioned. I built the spreadsheet by repr'ing all of the modules.

Long answer because this all took me an age to work out and if someone had of just told me that would have been great. I even applied for wiki access at some point to document stuff ... but it took so long I lost momentum.

[nine2]

What sort of mods are you making? UI or sim? New units? Ui enhancements?

[Jeroen De Dauw]

Hey all - thanks so much for the helpfull pointers.

I've just gotten my IRC client hooked up to the chat, which is one step closer to getting things set up as I want. (No way in hell that I'm going to dev on Windows.)

What sort of mods are you making? UI or sim? New units? Ui enhancements?

If I can make the hotkeys better, then I'd like to have a poke at that. And since there are over 9000 crappy shield mods out there, I need to make my own to rule them all.



All in all, I do not really have any plans yet. I first want to see what is possible, and what subset of that can be done in a reasonable amount of time by me.

[Jeroen De Dauw]

Take a look at DMS... In a nutshell its a modders toolbox of functions made to simplify modding while adding additional features into the game.

DMS? What is this? Can you link?

[Jeroen De Dauw]

Disclaimer 1: I am a noob myself.
Disclaimer 2: I'm doing this from memory so the exact keywords are incorrect.

Thank you for the info!

Starting guide. There are lots of tidbits floating around on different forums with examples but normally just find a mod that does something similar and look at it's code. Critically, the FA code is overridden by the FAF code which is overridden by your mod.

IDE - no way. No go to definition or test runner. Think notepad. I use visual studio because it's just a nice text editor. You can get plugins that understand lua (syntax highlighting) but I don't use them. Basically all you need is something that can find text across many files at once quickly.

I installed the lua plugin into my IntelliJ IDE. (Cannot link it due to derp forum restrictions.) This has things such as go to definition. I've yet to see how well this works for the FAF codebase.

Feedback cycle. ...

I'd like to do this on my Linux box, which means booting the game is not an option. (Well, I guess I could go the VM route, though that is a lot of hassle I rather avoid.)

One question I have now that has not been answered as far as I can see is to what extend the code one typically touches with mods can be executed (and thus tested) without running the game itself. And to what extend this code depends on Windows.

[nine2]

I think you need to understand how the code all gets merged up.

FA code is merged with FAF which is merged with your mod. Depending on how each merge is done, sometimes lua files are replaced completely. Sometimes they are concatenated. Sometimes the behaviour of a single function is defined across multiple files.

So what code ACTUALLY gets executed is a bit hard to work out.

Which is why your go to definition thing is a trap - it will go to *a* definition but really it can't know which is the right one and even the concept of there being a right "one" is an illusion. So your feature is definitely useful but I doubt it replaces what I have to do - which is open all versions of the file simultaneously to work out what is overriding what.

I don't know the answer to your last question, but I find it very likely that huge parts of the codebase would not work without running the game. I think everyone just runs the game.

If I can make the hotkeys better, then I'd like to have a poke at that.

i'm interested in that as well, what did you have in mind?