From 6d809ab797fa814ab39b35d784bd2633b7b53fca Mon Sep 17 00:00:00 2001 From: lL1l1 <82986251+lL1l1@users.noreply.github.com> Date: Wed, 2 Sep 2026 05:41:01 -0700 Subject: [PATCH 1/6] Update replay debugging documentation --- docs/development/developmentEnviroment.md | 52 ++++++++++++++++++----- 1 file changed, 42 insertions(+), 10 deletions(-) diff --git a/docs/development/developmentEnviroment.md b/docs/development/developmentEnviroment.md index f405b42998..8842865691 100644 --- a/docs/development/developmentEnviroment.md +++ b/docs/development/developmentEnviroment.md @@ -144,23 +144,55 @@ The arguments are passed along by the debugger. The change to the bash script is ## Running a replay -A hard crash may only show up in a replay. You'll need to use the debugger to investigate. You want to run the replay using the debugger. This requires two steps: match the game version of the replay and acquire the replay itself. +If you want to investigate a bug in a replay, you can run it with the debugger and your own debug code. This requires two steps: +### Acquire the replay: +FAF downloads `.fafreplay` files, but the game only recognizes `.scfareplay` files. +- You can unpack `.fafreplay` into `.scfareplay` by starting the replay from the client and then immediately closing it, resulting in a temporary reply file at `C:/ProgramData/FAForever/cache/temp.scfareplay`. -The game version depends on the game type. Checkout the repository to the correct branch: +- Alternatively, you can download `.fafreplay` from `https://replay.faforever.com/` and unpack it using the [Rust FAF replay parser](https://crates.io/crates/faf-replay-parser) with `fafreplay unpack `. -- `FAF`: `deploy/faf` -- `FAF Beta`: `deploy/fafbeta` -- `FAF Develop`: `deploy/fafdevelop` + - Storing the unpacked replay here allows the in-game replay dialog to see it: `%USERPROFILE%/Documents/My Games/Gas Powered Games/Supreme Commander Forged Alliance/replays/%PROFILE_NAME%` -Unlike the `.fafreplay` files you can get from and view with the faf client, the base game which you will run to test and debug only recognizes the `.scfareplay` extension for replays. To convert a `.fafreplay` to the `.scfareplay` extension you can start the replay with the faf client and immediately close it. The client will have created a temporary version of your replay with the `.scfareplay` format in the cache folder of the client: + `%PROFILE_NAME%` is the in-game profile name. -- `C:/ProgramData/FAForever/cache/temp.scfareplay` +### Matching game data +After you acquire the replay, you need to match the game version to run it. This has two parts: +1. **Matching the Lua repository version.** -Copy that replay to the replays folder of the game: + Simply checkout the repository to the correct branch for the game type: + - `FAF`: `deploy/faf` + - `FAF Beta`: `deploy/fafbeta` + - `FAF Develop`: `deploy/fafdevelop` -- `C:/Users/%USER_NAME%/Documents/My Games/Gas Powered Games/Supreme Commander Forged Alliance/replays/%PROFILE_NAME%` +2. **Matching the game version numbers** -Note that the last path is incomplete: you need replace `%USER_NAME%` with your systems profile name and `%PROFILE_NAME%` with the profile name you use in the game. You can launch the game using the bat files as described earlier. + The game version numbers in the replay file header and in `../fa_path.lua` (a file one directory down from the game exe) must match. + + - The simplest way is to run the replay using the client, and then launching the replay's game exe with the dev init file. In addition to correcting the version number, this downloads the correct version of the patched exe for the replay. + + Example command (uses debugger and immediately launches replay): + ```cmd + "C:\ProgramData\FAForever\replaydata\bin\FADeepProbe.exe" ForgedAlliance.exe /init "init_dev.lua" /EnableDiskWatch /nomovie /showlog /log "dev.log" /RunWithTheWind /replay "C:/ProgramData/FAForever/cache/temp.scfareplay" + ``` + + Make sure to add `init_dev.lua` to the replay directory, or change the path to the init file in the normal game directory. + + - Alternatively you can modify the `fa_path.lua` game version number directly, but this doesn't change the version of binary patches applied to the exe. + +### Running the replay +After you have done the two steps above, you can launch the game with an additional command line argument to launch straight into the replay: + +- `/replay "C:/ProgramData/FAForever/cache/temp.scfareplay"` + +If your game is already open, you can launch the replay using this script that runs from your clipboard (`Ctrl+Shift+V`): +```lua +local replay = "C:/ProgramData/FAForever/cache/temp.scfareplay" +if LaunchReplaySession(replay) then + SetFrontEndData('replay_filename', replay) +else + WARN(string.format('Issue starting replay "%s"', replay)) +end +``` ## Starting a singleplayer session quickly From 0a1bf2297187212a4d0de6b4d6316d746c7f1797 Mon Sep 17 00:00:00 2001 From: lL1l1 <82986251+lL1l1@users.noreply.github.com> Date: Wed, 2 Sep 2026 05:43:21 -0700 Subject: [PATCH 2/6] Copy changes to setup-english.md --- setup/setup-english.md | 59 +++++++++++++++++++++++++++++++++--------- 1 file changed, 47 insertions(+), 12 deletions(-) diff --git a/setup/setup-english.md b/setup/setup-english.md index b2905c75c7..3b4e918ca9 100644 --- a/setup/setup-english.md +++ b/setup/setup-english.md @@ -135,23 +135,58 @@ FADeepProbe.exe /init "init_local_development.lua" /EnableDiskWatch /showlog /lo The arguments are passed along by the debugger. The change to the bash script is similar. When the game crashes the debugger will try and inform you in the log what happened. -Running a replay ----------------- +## Running a replay + +If you want to investigate a bug in a replay, you can run it with the debugger and your own debug code. This requires two steps: +### Acquire the replay: +FAF downloads `.fafreplay` files, but the game only recognizes `.scfareplay` files. +- You can unpack `.fafreplay` into `.scfareplay` by starting the replay from the client and then immediately closing it, resulting in a temporary reply file at `C:/ProgramData/FAForever/cache/temp.scfareplay`. + +- Alternatively, you can download `.fafreplay` from `https://replay.faforever.com/` and unpack it using the [Rust FAF replay parser](https://crates.io/crates/faf-replay-parser) with `fafreplay unpack `. + + - Storing the unpacked replay here allows the in-game replay dialog to see it: `%USERPROFILE%/Documents/My Games/Gas Powered Games/Supreme Commander Forged Alliance/replays/%PROFILE_NAME%` + + `%PROFILE_NAME%` is the in-game profile name. + +### Matching game data +After you acquire the replay, you need to match the game version to run it. This has two parts: +1. **Matching the Lua repository version.** + + Simply checkout the repository to the correct branch for the game type: + - `FAF`: `deploy/faf` + - `FAF Beta`: `deploy/fafbeta` + - `FAF Develop`: `deploy/fafdevelop` -A hard crash may only show up in a replay. You'll need to use the debugger to investigate. You want to run the replay using the debugger. This requires two steps: match the game version of the replay and acquire the replay itself. +2. **Matching the game version numbers** -The game version depends on the game type. Checkout the repository to the correct branch: - - `FAF`: `deploy/faf` - - `FAF Beta`: `deploy/fafbeta` - - `FAF Develop`: `deploy/fafdevelop` + The game version numbers in the replay file header and in `../fa_path.lua` (a file one directory down from the game exe) must match. -Unlike the `.fafreplay` files you can get from and view with the faf client, the base game which you will run to test and debug only recognizes the `.scfareplay` extension for replays. To convert a `.fafreplay` to the `.scfareplay` extension you can start the replay with the faf client and immediately close it. The client will have created a temporary version of your replay with the `.scfareplay` format in the cache folder of the client: - - `C:/ProgramData/FAForever/cache/temp.scfareplay` + - The simplest way is to run the replay using the client, and then launching the replay's game exe with the dev init file. In addition to correcting the version number, this downloads the correct version of the patched exe for the replay. -Copy that replay to the replays folder of the game: - - `C:/Users/%USER_NAME%/Documents/My Games/Gas Powered Games/Supreme Commander Forged Alliance/replays/%PROFILE_NAME%` + Example command (uses debugger and immediately launches replay): + ```cmd + "C:\ProgramData\FAForever\replaydata\bin\FADeepProbe.exe" ForgedAlliance.exe /init "init_dev.lua" /EnableDiskWatch /nomovie /showlog /log "dev.log" /RunWithTheWind /replay "C:/ProgramData/FAForever/cache/temp.scfareplay" + ``` + + Make sure to add `init_dev.lua` to the replay directory, or change the path to the init file in the normal game directory. + + - Alternatively you can modify the `fa_path.lua` game version number directly, but this doesn't change the version of binary patches applied to the exe. + +### Running the replay +After you have done the two steps above, you can launch the game with an additional command line argument to launch straight into the replay: + +- `/replay "C:/ProgramData/FAForever/cache/temp.scfareplay"` + +If your game is already open, you can launch the replay using this script that runs from your clipboard (`Ctrl+Shift+V`): +```lua +local replay = "C:/ProgramData/FAForever/cache/temp.scfareplay" +if LaunchReplaySession(replay) then + SetFrontEndData('replay_filename', replay) +else + WARN(string.format('Issue starting replay "%s"', replay)) +end +``` -Note that the last path is incomplete: you need replace `%USER_NAME%` with your systems profile name and `%PROFILE_NAME%` with the profile name you use in the game. You can launch the game using the bat files as described earlier. Multiple instances ------------------ From d7b7bdecd19b683bcd735a356b78b6cd25ef3b56 Mon Sep 17 00:00:00 2001 From: lL1l1 <82986251+lL1l1@users.noreply.github.com> Date: Wed, 2 Sep 2026 05:44:22 -0700 Subject: [PATCH 3/6] Copy setup-english.md file style --- setup/setup-english.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/setup/setup-english.md b/setup/setup-english.md index 3b4e918ca9..af00adf542 100644 --- a/setup/setup-english.md +++ b/setup/setup-english.md @@ -135,7 +135,8 @@ FADeepProbe.exe /init "init_local_development.lua" /EnableDiskWatch /showlog /lo The arguments are passed along by the debugger. The change to the bash script is similar. When the game crashes the debugger will try and inform you in the log what happened. -## Running a replay +Running a replay +---------------- If you want to investigate a bug in a replay, you can run it with the debugger and your own debug code. This requires two steps: ### Acquire the replay: From c7d42a65facc928166057048c71b2d680be50bd5 Mon Sep 17 00:00:00 2001 From: lL1l1 <82986251+lL1l1@users.noreply.github.com> Date: Wed, 2 Sep 2026 05:51:40 -0700 Subject: [PATCH 4/6] Add instructions on checking out old game versions --- docs/development/developmentEnviroment.md | 4 ++++ setup/setup-english.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/docs/development/developmentEnviroment.md b/docs/development/developmentEnviroment.md index 8842865691..6ba21227ba 100644 --- a/docs/development/developmentEnviroment.md +++ b/docs/development/developmentEnviroment.md @@ -164,6 +164,10 @@ After you acquire the replay, you need to match the game version to run it. This - `FAF Beta`: `deploy/fafbeta` - `FAF Develop`: `deploy/fafdevelop` + For older game versions, you can check out easily by git tag: `git checkout ` + + For example: `git checkout 3834` + 2. **Matching the game version numbers** The game version numbers in the replay file header and in `../fa_path.lua` (a file one directory down from the game exe) must match. diff --git a/setup/setup-english.md b/setup/setup-english.md index af00adf542..64a1a58314 100644 --- a/setup/setup-english.md +++ b/setup/setup-english.md @@ -158,6 +158,10 @@ After you acquire the replay, you need to match the game version to run it. This - `FAF Beta`: `deploy/fafbeta` - `FAF Develop`: `deploy/fafdevelop` + For older game versions, you can check out easily by git tag: `git checkout ` + + For example: `git checkout 3834` + 2. **Matching the game version numbers** The game version numbers in the replay file header and in `../fa_path.lua` (a file one directory down from the game exe) must match. From feb07fbd40ff04a73da16b2acaf08db0e0b82df4 Mon Sep 17 00:00:00 2001 From: lL1l1 <82986251+lL1l1@users.noreply.github.com> Date: Wed, 2 Sep 2026 05:54:15 -0700 Subject: [PATCH 5/6] Use init_local_development.lua instead of init_dev --- docs/development/developmentEnviroment.md | 4 ++-- setup/setup-english.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/development/developmentEnviroment.md b/docs/development/developmentEnviroment.md index 6ba21227ba..8d99c0d106 100644 --- a/docs/development/developmentEnviroment.md +++ b/docs/development/developmentEnviroment.md @@ -176,10 +176,10 @@ After you acquire the replay, you need to match the game version to run it. This Example command (uses debugger and immediately launches replay): ```cmd - "C:\ProgramData\FAForever\replaydata\bin\FADeepProbe.exe" ForgedAlliance.exe /init "init_dev.lua" /EnableDiskWatch /nomovie /showlog /log "dev.log" /RunWithTheWind /replay "C:/ProgramData/FAForever/cache/temp.scfareplay" + "C:\ProgramData\FAForever\replaydata\bin\FADeepProbe.exe" ForgedAlliance.exe /init "init_local_development.lua" /EnableDiskWatch /nomovie /showlog /log "dev.log" /RunWithTheWind /replay "C:/ProgramData/FAForever/cache/temp.scfareplay" ``` - Make sure to add `init_dev.lua` to the replay directory, or change the path to the init file in the normal game directory. + Make sure to add `init_local_development.lua` to the replay directory, or change the path to the init file in the normal game directory. - Alternatively you can modify the `fa_path.lua` game version number directly, but this doesn't change the version of binary patches applied to the exe. diff --git a/setup/setup-english.md b/setup/setup-english.md index 64a1a58314..96f8e4a2c8 100644 --- a/setup/setup-english.md +++ b/setup/setup-english.md @@ -170,10 +170,10 @@ After you acquire the replay, you need to match the game version to run it. This Example command (uses debugger and immediately launches replay): ```cmd - "C:\ProgramData\FAForever\replaydata\bin\FADeepProbe.exe" ForgedAlliance.exe /init "init_dev.lua" /EnableDiskWatch /nomovie /showlog /log "dev.log" /RunWithTheWind /replay "C:/ProgramData/FAForever/cache/temp.scfareplay" + "C:\ProgramData\FAForever\replaydata\bin\FADeepProbe.exe" ForgedAlliance.exe /init "init_local_development.lua" /EnableDiskWatch /nomovie /showlog /log "dev.log" /RunWithTheWind /replay "C:/ProgramData/FAForever/cache/temp.scfareplay" ``` - Make sure to add `init_dev.lua` to the replay directory, or change the path to the init file in the normal game directory. + Make sure to add `init_local_development.lua` to the replay directory, or change the path to the init file in the normal game directory. - Alternatively you can modify the `fa_path.lua` game version number directly, but this doesn't change the version of binary patches applied to the exe. From 534d480048b3f3001b88e2c0b77e8e12d688ce6c Mon Sep 17 00:00:00 2001 From: FAForever Machine User Date: Wed, 2 Sep 2026 12:55:19 +0000 Subject: [PATCH 6/6] Add snippet template --- changelog/snippets/category.7274.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog/snippets/category.7274.md diff --git a/changelog/snippets/category.7274.md b/changelog/snippets/category.7274.md new file mode 100644 index 0000000000..8692e4e3ff --- /dev/null +++ b/changelog/snippets/category.7274.md @@ -0,0 +1 @@ +- Your explanation here... [Don't forget to change the category in the filename] (#7274).