From 76121f1c68e788c2e2b557950e3c57f10d520f9a Mon Sep 17 00:00:00 2001 From: RT Date: Fri, 24 Jul 2026 09:13:37 -0500 Subject: [PATCH] BTFrstrm: add autoconfig-file-spec.html (Load File format reference) --- BTFrstrm/autoconfig-file-spec.html | 564 +++++++++++++++++++++++++++++ 1 file changed, 564 insertions(+) create mode 100644 BTFrstrm/autoconfig-file-spec.html diff --git a/BTFrstrm/autoconfig-file-spec.html b/BTFrstrm/autoconfig-file-spec.html new file mode 100644 index 00000000..018ee99b --- /dev/null +++ b/BTFrstrm/autoconfig-file-spec.html @@ -0,0 +1,564 @@ + + + + +Automatic Config File Specification ? Firestorm Console Load File + + + + +

Automatic Config File Format Specification

+
+ Feature: Console Lobby “Load File” button  |  + Commit: c3346561 (branch 5.1.0b-in-progress)  |  + Date: 2026-07-24 +
+ +

1. Overview

+

+The system operates with two separate files: +

+
    +
  1. + options.ini — machine-level one-time configuration, read once at game startup. + Contains the path to the config file. Never changed by the game. +
    2. +
  2. + The config file (path specified in options.ini) — + written by the external application before each match. + Read by the game when the operator clicks Load File in the console lobby. + Not consumed — the game leaves it on disk. Overwrite it to set the next match. +
    3. +
+

+ When Load File is clicked, the game: +

+
    +
  1. Checks that automaticmode=1 and the file path is configured.
    2. +
  2. Checks that the config file exists on disk (GetFileAttributes). If not, does nothing.
    3. +
  3. Reads the file, applies game options, clears all current lobby slots, then fills slots from the file.
    4. +
  4. Leaves the file on disk unchanged.
    5. +
+ +
+ +

2. options.ini Setup (One-Time, Per Machine)

+

Add the following section to the game’s options.ini in the game working directory.

+ +
[automaticmode]
+automaticmode=1
+automaticfile=c:\mw4files\nextmatch.ini
+ + + + + +
KeyTypeDescription
automaticmodeinteger1 = enabled. 0 = disabled; Load File button does nothing.
automaticfilestringFull absolute Windows path to the config file. Max 259 characters. Can be any local drive letter.
+ +
+ Read at startup only. Changing options.ini requires a game restart. + If the [automaticmode] section is absent, or automaticmode=0, or + automaticfile is empty, Load File always does nothing regardless of what config file exists. +
+ +
+ +

3. Config File Format Rules

+

The config file uses standard Windows INI format, parsed by NotationFile::Standard.

+ + +
+ +

4. Section: [mission]

+

Sets all game lobby parameters. This section is optional — omit it to leave game options unchanged and only configure slots.

+ +
[mission]
+MissionName=ScarabStronghold - Attrition
+GameType=2
+Visibility=0
+Weather=0
+TimeOfDay=0
+TimeLimit=7
+Radar=0
+HeatOn=0
+FriendlyFire=0
+SplashDamage=0
+UnlimitedAmmo=1
+WeaponJam=0
+AdvanceMode=0
+ArmorMode=0
+ +

4.1  MissionName — string, max 255 characters

+

+The scenario name, exactly as it appears in the mission list dropdown in the console lobby. +Match is exact string equality, case-sensitive. Trailing/leading spaces are stripped by the parser. +

+
+ If the name is not found in the list for the selected GameType, + mission selection silently fails — the dropdown stays at its previous value. + No error is logged. All other parameters (Visibility, Weather, etc.) are still applied. + The available mission names depend on what scenario files are installed on the machine; + there is no static guaranteed list. +
+ +

4.2  GameType — integer (dropdown index, 0-based)

+
+ This is the position in the game type dropdown, NOT the internal game type ID number. + The dropdown is built dynamically at lobby startup — only game types that have at least + one installed scenario are shown. If a game type has no installed maps it is skipped and all + subsequent indices shift down by one. +
+

For a standard full installation with all game types present, the order is fixed:

+ + + + + + + + + + + + + +
IndexDisplay NameMode
0DestructionFFA
1Team DestructionTeam
2AttritionFFA — default DEFAULT
3Team AttritionTeam
4Capture the FlagFFA
5King of the HillFFA
6Team King of the HillTeam
7Steal the BaconFFA
8Master TrialSpecial
9Siege AssaultSpecial
10+Custom map variantsVaries (if custom content installed)
+

Team vs. FFA is important: it determines whether the Team or Skin field is applied to each slot. See Section 5 for details.

+ +

4.3  Visibility — integer

+ + + + + + + +
ValueDisplay NameDescription
0DefaultSame as Clear DEFAULT
1ClearFull visibility range
2Light FogReduced visibility range
3Heavy FogHeavily reduced visibility range
4Pea Soup FogNear-zero visibility range
+ +

4.4  Weather — integer

+ + + + +
ValueDisplay
0Off DEFAULT
1On (rain or snow depending on map)
+ +

4.5  TimeOfDay — integer

+ + + + +
ValueDisplay
0Day DEFAULT
1Night
+ +

4.6  TimeLimit — integer (actual minutes, not a list index)

+

+ Specify the desired match length in real minutes. + Valid values that appear in the lobby dropdown: +

+

+ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 20, 25, 30 +

+

+ Other integers are accepted and applied to the network parameter but will not match a dropdown item + (the visual display may show the nearest value). +

+

+ Special value -1: use the server’s current default time (7 minutes unless changed separately). +

+

Default if key absent: server current default (equivalent to -1).

+ +

4.7  Radar — integer

+ + + + + + +
ValueDisplayDescription
0NoviceAll mechs visible, no range limit DEFAULT
1NormalStandard radar with range cutoff
2Team OnlyOnly your own team visible on radar
3No RadarRadar completely disabled for all players
+ +

4.8  HeatOn — integer

+ + + + +
ValueDescription
0Off — heat never builds, weapons never overheat DEFAULT
1On — standard heat management enabled
+ +

4.9  FriendlyFire — integer

+ + + + +
ValueDescription
0Off — friendly fire disabled DEFAULT
1On — 100% damage to teammates
+ +

4.10  SplashDamage — integer

+ + + + +
ValueDescription
0Off DEFAULT
1On — area/splash damage from missiles and explosions
+ +

4.11  UnlimitedAmmo — integer

+ + + + +
ValueDescription
0Off — ammo is finite
1On — unlimited ammo DEFAULT (console/arcade)
+ +

4.12  WeaponJam — integer

+ + + + +
ValueDescription
0Off DEFAULT
1On — weapons can randomly jam
+ +

4.13  AdvanceMode — integer

+ + + + +
ValueDescription
0Off DEFAULT
1On
+ +

4.14  ArmorMode — integer

+ + + + +
ValueDescription
0Off DEFAULT
1On
+ +
+ +

5. Sections: [slot0] through [slot15]

+ +

One section per roster slot, numbered starting from zero.

+ +
+ Slots must be contiguous starting from [slot0]. + The parser stops at the first missing slot number. If [slot2] is absent, + [slot3] through [slot15] are never read, even if present in the file. + Do not skip numbers. +
+ +

Maximum: 16 slots (indices 0–15). All slots are cleared before applying file data, so slots not defined in the file will be empty in the lobby after Load File is clicked.

+ +
[slot0]
+Type=1
+PilotName=Alpha One
+Mech=Atlas
+Team=0
+Skin=0
+Decal=3
+ +

5.1  Type — integer, required

+

Determines what occupies this slot. All other fields are ignored when Type=0.

+ + + + + + + + + + + + +
ValueDescription
0Empty — slot skipped, left empty in lobby
1Player slot — a human pilot can connect to this seat
2Bot, difficulty level 1 (easiest)
3Bot, difficulty level 2
4Bot, difficulty level 3
5Bot, difficulty level 4
6Bot, difficulty level 5
7Bot, difficulty level 6
8Bot, difficulty level 7
9Bot, difficulty level 8 (hardest)
+

If Type key is absent, it defaults to 0 (empty) due to zero-initialization.

+ +

5.2  PilotName — string, max 63 characters

+

Only meaningful when Type=1 (player slot). Sets the callsign shown in the lobby pilot editbox. The connecting player can override this after they connect.

+

For bots (Type=2–9), this field is read from the file but ignored by the script.

+

Set to empty value or omit key to leave the name blank: PilotName=

+

Strings longer than 63 characters are silently truncated.

+ +

5.3  Mech — string (chassis name, exact and case-sensitive)

+

Must match exactly one of the chassis names from MechTable.tbl. The lookup is case-sensitive exact string comparison. If the name is not found, the mech dropdown for that slot stays at its previous value. No error is raised.

+ +
+ These are the table key strings, not display labels. + Pay close attention to capitalization, spacing, and special characters (hyphens, Roman numerals). +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Exact Mech= valueNotes
Annihilator
Archer
Arctic Wolfspace between words
Ares
Argus
AssassinIIno spaces; capital I
Atlas
Avatar
Awesome
Battlemaster
BattlemasterIICno spaces
Behemoth
BehemothIIno space; capital I
Black Hawkspace between words
Black Knightspace between words
Black Lannerspace between words
Brigand
Bushwacker
Catapult
Cauldron-Bornhyphen between words
Chimera
Commando
Cougar
Cyclops
Daishi
Deimos
Dragon
Fafnir
Flea
Gladiator
Grizzly
Hauptmann
Hellhound
Hellspawn
Highlander
HollanderIIno space; capital I
Hunchback
Kodiak
Loki
Longbow
Mad Catspace between words
Mad Cat MKIIspace + "MKII" all caps, no period
Masakari
Mauler
Nova Catspace between words
Osiris
Owens
Puma
Raven
Rifleman
Ryoken
Shadow Catspace between words
Solitaire
Sunder
Templar
Thanatos
Thor
Uller
Urbanmech
Uziel
Victor
Vulture
Warhammer
Wolfhound
Zeus
+ +

5.4  Team — integer

+

+ Only applied in team game modes (game types marked “Team” in Section 4.2 table). + IGNORED in FFA modes. +

+ + + + + + + + + + +
ValueTeamDefault Color
0Team 1Blue
1Team 2Red
2Team 3Yellow
3Team 4Green
4Team 5Purple
5Team 6Light Blue
6Team 7Orange
7Team 8Charcoal
+ +

5.5  Skin — integer (FFA camo, dropdown index 0-based)

+

+ Only applied in FFA game modes. + IGNORED in team modes. +

+ + + + + + + + + + + +
ValueCamo Color/Pattern
0Blue
1Red
2Yellow
3Green
4Purple
5Light Blue
6Orange
7Charcoal
8–15Additional camo patterns
+ +

5.6  Decal — integer (faction emblem, 0–63)

+

+ Applied in both team and FFA modes. + Valid range: 0–63. All values in range are accepted. Common values: +

+ + + + + + + + + + + + + + + + + + + + + + + +
ValueFaction
0None
2Davion
3Steiner
4Kurita
5Liao
6Marik
9ComStar
10Star League
11Wolf Clan
12Jade Falcon
16Ghost Bear
20Hell Horses
21Coyote
22Blood Spirit
24Ice Hellion
27Goliath Scorpion
46BKG
47FSA
48331st
49DDC
50VGL
+ +
+ +

6. Complete Example File

+ +
[mission]
+MissionName=ScarabStronghold - Attrition
+GameType=2
+Visibility=0
+Weather=0
+TimeOfDay=0
+TimeLimit=7
+Radar=0
+HeatOn=0
+FriendlyFire=0
+SplashDamage=0
+UnlimitedAmmo=1
+WeaponJam=0
+AdvanceMode=0
+ArmorMode=0
+
+[slot0]
+Type=1
+PilotName=Blackjack
+Mech=Atlas
+Team=0
+Skin=0
+Decal=3
+
+[slot1]
+Type=1
+PilotName=Viper
+Mech=Mad Cat
+Team=0
+Skin=1
+Decal=4
+
+[slot2]
+Type=2
+PilotName=
+Mech=Thor
+Team=1
+Skin=1
+Decal=4
+
+[slot3]
+Type=2
+PilotName=
+Mech=Warhammer
+Team=1
+Skin=1
+Decal=4
+ +
+ +

7. Known Constraints and Caveats

+ +
    +
  1. + Slots must be numbered contiguously from [slot0]. + The parser uses a loop that breaks on the first missing section. Defining [slot0] + and [slot2] without [slot1] means only slot 0 is processed. +
    2. +
  2. + All current slots are cleared before file slots are applied. + Any slot not defined in the file (or defined with Type=0) will be empty in the lobby. +
    3. +
  3. + Team vs. FFA assignment uses the lobby’s state at the moment Load File is clicked, + not the GameType written in the file. + The game type change from [mission] is processed asynchronously (next frame). + If you are changing game mode, click Load File a second time to correctly apply team/skin assignments, + or pre-configure the lobby to the correct game type before writing the config file. +
    4. +
  4. + MissionName and Mech matches are case-sensitive. + atlas will not match Atlas. +
    5. +
  5. + The file is never deleted by the game. + Write it before the match, overwrite it before the next match. No locking is performed. +
    6. +
  6. + options.ini is read only at game startup. + Changing the automaticfile path or enabling/disabling the feature requires a restart. + The config file itself is re-read fresh on every Load File button click. +
    7. +
  7. + Buffer limits: PilotName ≤ 63 chars (truncated silently); + MissionName ≤ 255 chars; + automaticfile path ≤ 259 chars (MAX_PATH − 1). +
    8. +
  8. + Mech names are sourced from MechTable.tbl. + If the game installation has custom mechs added or some mechs removed, the valid name list + changes accordingly. The table above reflects the standard Firestorm build. +
    9. +
+ +
+

+ Generated from source: MW4Shell.cpp — CTCL_LoadAutoFile, + CTCL_GetAutoSlotName/Mech/Int  |  + ConLobby.script — o_load_file handler  |  + Commit c3346561  |  2026-07-24 +

+ + +