Extend command line single player launch capabilities #6888

Garanas · 2025-07-17T14:20:48Z

Description of the proposed changes

Fixes various things:

Documents and annotate the majority of the launching a skirmish via the command line interface.
Assign the default value of all lobby options by default.
Add support for /gameoptions argument to define lobby options.
Add support for (a new) /gamebots argument to define AI army configurations.
Add support for (a new) /gamemods argument to define what (sim) mods to load.
Add support for (a new) /runWithTheWind argument to run the simulation as fast as possible.
Fix an issue with the scoreboard for missing the FullShare option.

And introduces a new powershell script as inspired by the script made by @lL1l1. It serves as an example on how to launch a bot session.

Testing done on the proposed changes

It enables a setup such as this:

launch-bot-session-01.mp4

The AI is running, but the AI itself is not functional yet. The procedure is described at:

https://github.com/Garanas/fa-average-joe-ai?tab=readme-ov-file#launch-the-game

Where you can launch the game from Visual Studio Code using command line arguments.

Additional context

I am not aware of this functionality being used anywhere except for the AI tournament functionality of Softles. That setup overrides this file however. The existing launch script uses the autolobby functionality. Therefore I'm not that afraid of backwards compatibility issues.

Checklist

Changes are annotated, including comments where useful
Changes are documented in a changelog snippet according to the guidelines.
Request 2-3 reviewers from the list of reviewers and their areas of knowledge.

Some of these changes are inspired by the work of @HardlySoftly , see also attached his scripts for the automated AI tournaments.

FAF-AI-Autorun-main.zip

The game expects a list of (parsed) mod_info files.

Garanas · 2025-07-17T14:49:12Z

I'm quite certain that this file is barely, if ever used. For example, for campaign maps it still checked for the scenario type campaign instead of campaign_coop.

Therefore the question is - do we even need to support that? And if we do want to, is that part of the scope of this pull request?

Garanas · 2025-07-20T07:28:38Z

@lL1l1 it may be interesting to rename LaunchFAInstances to something like LaunchAutolobby. What are your thoughts about that?

lL1l1 · 2025-07-20T08:41:53Z

I actually made it launch the custom lobby in #6856, so that new name wouldn't fit.

Garanas · 2025-07-20T11:06:30Z

I actually made it launch the custom lobby in #6856, so that new name wouldn't fit.

I see now. What are your thoughts - perhaps we can split it into two PowerShell scripts? There's a giant if-statement at the bottom of the current PowerShell script.

lL1l1 · 2025-07-21T08:22:22Z

I think it would be nice to reuse the other logic that exists in the script, but it could use a little refactor split the 1/0-player scenarios with AI the multiplayer/lobby scenarios more clearly. I would put the 1/0 player scenario closer to the top of the file with an exit statement to terminate the script. The big chunk of multiplayer logic with networking params, window size, teams, divisions/clans, etc. can be placed after that.

I also like the format for your argument list in LaunchBotSession, the base arguments could be moved to the top of the file so that it is easier to understand for someone editing the script for the first time.

Garanas · 2025-08-04T05:48:48Z

These changes will cause a merge conflict with #6873. I was not aware of #6873 when I made this pull request, even though I was appointed to review 😞

Garanas · 2025-08-16T05:13:55Z

@BlackYps What is the plan with this pull request? Because #6873 is merged there's now merge conflicts that I can't fix because they are also semantically incompatible.

BlackYps · 2025-09-04T18:41:41Z

I can't really tell you what your plan should be. I understand that there is a conflict, but can't you build upon the changes of #6873?

Garanas · 2025-09-10T19:31:29Z

@lL1l1 Would you be fine if I undo some of your changes made to SetupBotSession in #6873 in favor of the version in this pull request? The version in this pull request provides more control through the command line.

lL1l1 · 2025-09-11T04:31:26Z

@lL1l1 Would you be fine if I undo some of your changes made to SetupBotSession in #6873 in favor of the version in this pull request? The version in this pull request provides more control through the command line.

Yeah that's fine.

lL1l1 · 2025-07-18T19:58:27Z

lua/SinglePlayerLaunch.lua

+
+--- Generates a table of all set game mods.
+---
+--- Lobby options can be set using the `/gamemods` argument. The format is `/gamemods uid:name uid:name ...`. The name is not used but it is useful to document what mod the UID is supposed to represent. As an example: `/gamemods f27c55b4-v075-55b4-92b6-64398e75e23f:m27ai faf0863e-94a0-b0b0-9ba583e9feb4:rngai`


Maybe the mod name can be used to pick a different version of the same mod if the exact uid is unavailable?

lL1l1 · 2025-07-18T20:02:37Z

engine/User.lua

+---@class UISinglePlayerSessionConfiguration
+---@field scenarioInfo UILobbyScenarioInfo
+---@field scenarioMods ModInfo[]
+---@field teamInfo table


This type is like PlayerData[] except a stripped down version without the multiplayer-related data. Maybe something like EnginePlayerData should be created.

lL1l1 · 2025-07-21T07:44:57Z

changelog/snippets/other.6888.md

@@ -0,0 +1,3 @@
+- (#6888) Make it more convenient to launch a (bot) session through the command line
+
+With these changes we shorten the workflow to test (sim) mods and in particular AI mods. There is an example PowerShell script file in the `scripts` folder to help you get started.


Suggested change

With these changes we shorten the workflow to test (sim) mods and in particular AI mods. There is an example PowerShell script file in the `scripts` folder to help you get started.

With these changes we shorten the workflow to test (sim) mods and in particular AI mods. There is an example PowerShell script file in the `scripts` folder to help you get started.

lL1l1 · 2025-07-21T07:48:43Z

scripts/LaunchBotSession.ps1

+    # "/seed", "1",
+
+    # Enable cheats
+    "/cheats",


Does this work? I don't see this string in lua or the decompilation.

Garanas added 12 commits July 16, 2025 19:50

Add annotations

d73afd3

Remove logging

ab6c36b

Add annotations

c981143

Dynamically compute default options

10e8871

Annotate and adjust location of utility functions

cfec787

Add annotations

3e4263d

Add utility function to support the /gameptions argument

3a29fbb

Add utility function to get mods from command line

0d69d75

Fix incorrect type of mod

37407d2

The game expects a list of (parsed) mod_info files.

Add support for mod selection via arguments for bot session

c78b03d

Add annotations

254d799

Add support for bot assignment

25244c4

Garanas marked this pull request as ready for review July 17, 2025 14:47

Garanas changed the title ~~Extend single player launch capabilities~~ Extend command line launch capabilities Jul 17, 2025

Garanas changed the title ~~Extend command line launch capabilities~~ Extend command line single player launch capabilities Jul 19, 2025

Garanas added 4 commits July 20, 2025 09:10

Fix not being able to default all game options

1abb863

Add command line to run the game as fast as possible

cb6e11c

Make game speed adjustable by default

97f24f5

Add license and introduction comments

341ce5b

Add a changelog snippet

1a19dca

Garanas added the area: tooling label Jul 20, 2025

Garanas added this to the Development Iteration III of 2025 milestone Jul 20, 2025

BlackYps removed this from the Development Iteration III of 2025 milestone Aug 15, 2025

Add support for custom armies

13d2a65

lL1l1 reviewed Oct 16, 2025

View reviewed changes

		@@ -0,0 +1,3 @@
		- (#6888) Make it more convenient to launch a (bot) session through the command line

		With these changes we shorten the workflow to test (sim) mods and in particular AI mods. There is an example PowerShell script file in the `scripts` folder to help you get started.

Extend command line single player launch capabilities #6888

Are you sure you want to change the base?

Extend command line single player launch capabilities #6888

Uh oh!

Conversation

Garanas commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of the proposed changes

Testing done on the proposed changes

Additional context

Checklist

Uh oh!

Garanas commented Jul 17, 2025

Uh oh!

Garanas commented Jul 20, 2025

Uh oh!

lL1l1 commented Jul 20, 2025

Uh oh!

Garanas commented Jul 20, 2025

Uh oh!

lL1l1 commented Jul 21, 2025

Uh oh!

Garanas commented Aug 4, 2025

Uh oh!

Garanas commented Aug 16, 2025

Uh oh!

BlackYps commented Sep 4, 2025

Uh oh!

Garanas commented Sep 10, 2025

Uh oh!

lL1l1 commented Sep 11, 2025

Uh oh!

lL1l1 Jul 18, 2025

Choose a reason for hiding this comment

Uh oh!

lL1l1 Jul 18, 2025

Choose a reason for hiding this comment

Uh oh!

lL1l1 Jul 21, 2025

Choose a reason for hiding this comment

Uh oh!

lL1l1 Jul 21, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Garanas commented Jul 17, 2025 •

edited

Loading