Skip to content

docs: Add engine changes reference pages #89

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Skyaero42 merged 3 commits into from
Jul 10, 2026
Merged

docs: Add engine changes reference pages #89

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a4cb554
docs: add engine changes reference pages
Jaredl-Dev Jul 1, 2026
67d4e49
Merge branch 'TheSuperHackers:main' into docs/engine-changes-wiki
Jaredl-Dev Jul 6, 2026
41a722a
docs: document game window transition speed option
Jaredl-Dev Jul 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions SourceCode/EngineChanges/command_line_arguments.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Added and Changed Command Line Arguments

This page documents command-line arguments added or changed in TheSuperHackers engine source compared
with the retail source release. It does not repeat every retail command-line argument.

## Added or Expanded Arguments

| Argument | Value | Availability | Description |
| --- | --- | --- | --- |
| `-headless` | None | Release and debug builds | Runs the game without a window, graphics, input, or audio. Intended for replay simulation and can be combined with `-replay`. Also disables intro and sizzle playback. |
| `-replay` | Replay filename ending in `.rep` | Release and debug builds | Starts replay playback or simulation from the command line. The argument can be repeated, can include wildcards, and must refer to a file in the replay folder or one of its subfolders. It disables intro, sizzle, and shell-map startup and allows another game instance to already be running. |
| `-jobs` | Positive process count | Release and debug builds | Used with `-replay`. Runs replay simulations in separate processes, up to the supplied count at the same time. If omitted, replay simulations run sequentially in the same process. |
| `-noshaders` | None | Release and debug builds | Forces the low-feature GPU path by setting the chipset type used by the renderer. In the retail source this switch was exposed for Zero Hour; the current code exposes it for both Generals and Zero Hour. |
| `-forcefullviewport` | None | Release and debug builds | Forces full viewport mode by setting `ViewportHeightScale` to `1.0`. This supports Control Bar Pro style addons and mirrors the `GenTool/fullviewport.dat` integration. |

Examples:

```text
generals.exe -headless -replay "Last Replay.rep"
generals.exe -headless -replay "*.rep" -jobs 4
generals.exe -forcefullviewport
```

## Changed Retail Arguments

| Argument | Value | Current Behavior |
| --- | --- | --- |
| `-win` | None | Forces windowed startup. It is now parsed before the game window is created. |
| `-fullscreen` | None | Forces fullscreen startup. It is now parsed before the game window is created. |
| `-nologo` | None | Disables the startup logo and is now available in release builds. |
| `-noShellAnim` | None | Disables shell/window animations and is now available in release builds. |
| `-useWaveEditor` | None | Enables the water/wave editor mode and is now available from the non-debug engine-init argument table. |

## CRC Replay Analysis

| Argument | Value | Availability | Description |
| --- | --- | --- | --- |
| `-SaveDebugCRCPerFrame` | Output folder | Builds with `DEBUG_CRC` enabled | Stores CRC debug logging in a separate file for each frame. If the first CRC logging frame is unset, this sets it to `0`. The output folder is deleted and recreated for every started game. |

`-SaveDebugCRCPerFrame` is intended for replay analysis and is commonly used with the existing CRC
debug arguments, for example `-ignoreAsserts -DebugCRCFromFrame 0 -LogObjectCRCs`.
42 changes: 42 additions & 0 deletions SourceCode/EngineChanges/debug_commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
<!-- markdownlint-disable MD033 -->
<!-- Needed to allow for <kbd> tags for keyboard key styling. -->

# Added and Changed Debug Commands

This page lists debug commands whose player-facing availability, default binding, or behavior changed in
TheSuperHackers engine source compared with the EA retail source release. It does not repeat unchanged
debug commands from the [In-Game Debug Commands](ingame_debug_commands) page.

Source-only debug commands with no current default binding are intentionally omitted.

## New Commands

| Command | Default Binding | Available In | Description |
| --- | --- | --- | --- |
| `DEMO_BEGIN_ADJUST_DEFAULTPITCH` | <kbd>Ctrl</kbd>+<kbd>,</kbd> | Generals and Zero Hour | Starts adjusting the default camera pitch. |
| `DEMO_END_ADJUST_DEFAULTPITCH` | <kbd>Ctrl</kbd>+<kbd>,</kbd> release | Generals and Zero Hour | Stops adjusting the default camera pitch. |

## Newly Available in Generals

These commands existed in the EA Zero Hour retail source, but not in the EA Generals retail source. The current
TheSuperHackers source exposes them for both Generals and Zero Hour.

| Command | Default Binding | Description |
| --- | --- | --- |
| `DEMO_SHOW_AUDIO_LOCATIONS` | <kbd>Shift</kbd>+<kbd>Alt</kbd>+<kbd>A</kbd> | Toggles audio location markers. |
| `DEMO_TOGGLE_SUPPLY_CENTER_PLACEMENT` | <kbd>Shift</kbd>+<kbd>Alt</kbd>+<kbd>Ctrl</kbd>+<kbd>S</kbd> | Toggles supply-center placement logging/debugging. |
| `DEBUG_OBJECT_ID_PERFORMANCE` | <kbd>Shift</kbd>+<kbd>Alt</kbd>+<kbd>Ctrl</kbd>+<kbd>Q</kbd> | Runs ObjectID lookup performance tests. |
| `DEBUG_DRAWABLE_ID_PERFORMANCE` | <kbd>Shift</kbd>+<kbd>Alt</kbd>+<kbd>Ctrl</kbd>+<kbd>A</kbd> | Runs DrawableID lookup performance tests. |
| `DEBUG_SLEEPY_UPDATE_PERFORMANCE` | <kbd>Shift</kbd>+<kbd>Alt</kbd>+<kbd>Ctrl</kbd>+<kbd>W</kbd> | Reports the number of sleepy update modules. |

## Changed Commands

| Command | Default Binding | Changed Behavior |
| --- | --- | --- |
| `DEMO_REMOVE_PREREQ` | <kbd>Alt</kbd>+<kbd>P</kbd> | Retail toggled prerequisite checks for the local player only. The current source toggles the same state for every human player. In multiplayer, every client should apply the same state to avoid mismatches. |
| `DEMO_INSTANT_BUILD` | <kbd>Alt</kbd>+<kbd>F</kbd> | Retail toggled instant production for the local player only. The current source toggles the same state for every human player and ignores the command in multiplayer while any human player has production in progress. |
| `DEMO_FREE_BUILD` | <kbd>Alt</kbd>+<kbd>B</kbd> | Retail had the debug handler, but no default key binding. The current source generates a default binding and toggles zero-cost production for every human player. In multiplayer, every client should apply the same state to avoid mismatches. |
| `DEMO_GIVE_ALL_SCIENCES` | <kbd>Shift</kbd>+<kbd>Alt</kbd>+<kbd>Ctrl</kbd>+<kbd>K</kbd> | Retail granted all grantable sciences to the local player only. The current source grants them to every human player. In multiplayer, every client should run the command to avoid mismatches. |
| `DEMO_INSTANT_QUIT` | <kbd>Alt</kbd>+<kbd>F4</kbd> or window close | Retail Generals closed directly from the window-close path, while retail Zero Hour routed close through this message. The current source routes close/end-session through `DEMO_INSTANT_QUIT` in both games and uses the current game quit flow. |

<!-- markdownlint-restore -->
20 changes: 20 additions & 0 deletions SourceCode/EngineChanges/engine_changes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Added and Changed Engine Features

This section documents front-facing changes in TheSuperHackers engine source compared with the EA retail
source release. It focuses on changes that players, modders, map makers, and tool authors may need to use
or account for, such as configuration settings, command-line arguments, key bindings, debug commands, and
INI fields that were added, changed, or removed.

Backend implementation details are intentionally left out unless they affect how the game is played,
configured, tested, or modded.

## Pages

- [Options.ini](options_ini): player-facing options stored in `Options.ini`.
- [Added/Changed Command Line Arguments](command_line_arguments): launch arguments added or changed by the engine.
- [Key Bindings](key_bindings): non-debug key bindings added or changed by the engine.
- [Debug Commands](debug_commands): in-game debug commands added or changed by the engine.
- [GameData.ini](gamedata_ini): mod-facing `GameData.ini` settings.
- [GameAudio.ini](gameaudio_ini): mod-facing `GameAudio.ini` settings.
- [InGameUI.ini](ingameui_ini): mod-facing `InGameUI.ini` overlay and styling settings.
- [Object Module Fields](module_fields): object module fields added for INI authors.
13 changes: 13 additions & 0 deletions SourceCode/EngineChanges/gameaudio_ini.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# GameAudio.ini

This page lists mod-facing `GameAudio.ini` settings added in TheSuperHackers engine source compared
with the retail source release.

Boolean values use `Yes` or `No`. Percentage values use the existing INI percentage syntax, such as
`75%` or `100%`.

| Name | Accepted Values | Default | Description |
| --- | --- | --- | --- |
| `Use3DSoundRangeVolumeFade` | `Yes` or `No` | `Yes` | Enables volume fading for 3D sounds as they approach maximum range, avoiding abrupt cutoff at the edge of the sound range. |
| `3DSoundRangeVolumeFadeExponent` | Real number | `4.0` | Controls the non-linear 3D sound range fade curve. Higher values make volume fall off more sharply near maximum range. |
| `DefaultMoneyTransactionVolume` | Percentage | `100%` in Generals, `0%` in Zero Hour | Sets the default money deposit and withdraw sound volume used when `Options.ini` does not contain `MoneyTransactionVolume`. |
16 changes: 16 additions & 0 deletions SourceCode/EngineChanges/gamedata_ini.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# GameData.ini

This page lists mod-facing `GameData.ini` settings added in TheSuperHackers engine source compared
with the retail source release.

Boolean values use `Yes` or `No`.

| Name | Accepted Values | Default | Description |
| --- | --- | --- | --- |
| `ViewportHeightScale` | Real number, usually `0.0` through `1.0` | `0.8` | Scales the tactical viewport height. `0.8` preserves the original control bar area; `1.0` makes the tactical view use the full screen height so custom control bars can overlay it. |
| `AllowMoneyPerMinuteForPlayer` | `Yes` or `No` | `No` | Allows regular player control bars to show money per minute when `Options.ini` has `ShowMoneyPerMinute=yes`. Observer control bars can show money per minute regardless of this setting. |

@Skyaero42 Skyaero42 Jul 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this enabled? I thought this change was revered as it was deemed controversial.

@Jaredl-Dev Jaredl-Dev Jul 2, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you're talking about AllowMoneyPerMinuteForPlayer, I believe it's disabled by default in GameData.ini. Unless a mod or patch enables it in GameData.ini, the corresponding setting in Options.ini will have no effect.

| `ObjectPlacementOpacity` | Real number, usually `0.0` through `1.0` | `0.45` | Controls the opacity of the build-placement preview object. |
| `ObjectPlacementShadows` | `Yes` or `No` | `Yes` | Enables shadows on build-placement preview objects. If disabled, increasing `ObjectPlacementOpacity` can help preserve preview contrast. |

`ViewportHeightScale` is also forced to `1.0` by `-forcefullviewport` and by the `GenTool/fullviewport.dat`
compatibility check.
62 changes: 62 additions & 0 deletions SourceCode/EngineChanges/ingameui_ini.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# InGameUI.ini

This page lists mod-facing `InGameUI.ini` overlay styling settings added in TheSuperHackers engine
source compared with the retail source release.

These settings style overlays that are enabled or disabled by the matching `Options.ini` font-size entries.
Positions use `X:<number> Y:<number>`. Colors use `R:<0-255> G:<0-255> B:<0-255> [A:<0-255>]`;
alpha is optional and defaults to `255`.

## Network Latency

| Name | Default | Description |
| --- | --- | --- |
| `NetworkLatencyFont` | `Tahoma` | Font used by the multiplayer network latency overlay. |
| `NetworkLatencyBold` | `Yes` | Enables bold text for the network latency overlay. |
| `NetworkLatencyPosition` | `X:3 Y:-1` | Overlay position. `X:3 Y:-1` uses the shared HUD anchor and draws inline with the other top HUD counters. |
| `NetworkLatencyColor` | `R:173 G:216 B:255 A:255` | Main text color. |
| `NetworkLatencyDropColor` | `R:0 G:0 B:0 A:255` | Drop-shadow color. |

## Render FPS

| Name | Default | Description |
| --- | --- | --- |
| `RenderFpsFont` | `Tahoma` | Font used by the render FPS overlay. |
| `RenderFpsBold` | `Yes` | Enables bold text for the render FPS overlay. |
| `RenderFpsPosition` | `X:3 Y:-1` | Overlay position. `X:3 Y:-1` uses the shared HUD anchor and draws inline with the other top HUD counters. |
| `RenderFpsColor` | `R:255 G:255 B:0 A:255` | Current render FPS text color. |
| `RenderFpsLimitColor` | `R:119 G:119 B:119 A:255` | FPS limit text color. |
| `RenderFpsDropColor` | `R:0 G:0 B:0 A:255` | Drop-shadow color. |
| `RenderFpsRefreshMs` | `1000` | Milliseconds between render FPS text refreshes. `0` updates every frame. |

## System Time

| Name | Default | Description |
| --- | --- | --- |
| `SystemTimeFont` | `Tahoma` | Font used by the local system time overlay. |
| `SystemTimeBold` | `Yes` | Enables bold text for the system time overlay. |
| `SystemTimePosition` | `X:3 Y:-1` | Overlay position. `X:3 Y:-1` uses the shared HUD anchor and draws inline with the other top HUD counters. |
| `SystemTimeColor` | `R:255 G:255 B:255 A:255` | Main text color. |
| `SystemTimeDropColor` | `R:0 G:0 B:0 A:255` | Drop-shadow color. |

## Game Time

| Name | Default | Description |
| --- | --- | --- |
| `GameTimeFont` | `Tahoma` | Font used by the game timer overlay. |
| `GameTimeBold` | `Yes` | Enables bold text for the game timer overlay. |
| `GameTimePosition` | `X:3 Y:-1` | Overlay position. The `X` coordinate is applied from the right edge of the screen. |
| `GameTimeColor` | `R:255 G:255 B:255 A:255` | Main timer text color. |
| `GameTimeDropColor` | `R:0 G:0 B:0 A:255` | Drop-shadow color. |

## Player Info List

| Name | Default | Description |
| --- | --- | --- |
| `PlayerInfoListFont` | `Tahoma` | Font used by the observer player information list. |
| `PlayerInfoListBold` | `Yes` | Enables bold text for the player information list. |
| `PlayerInfoListPosition` | `X:0.0 Y:0.5` | Normalized screen position. `X` and `Y` are multiplied by the current display width and height. |
| `PlayerInfoListLabelColor` | `R:125 G:124 B:122 A:255` | Label text color. |
| `PlayerInfoListValueColor` | `R:253 G:251 B:251 A:255` | Value text color. Player names still use player colors. |
| `PlayerInfoListDropColor` | `R:0 G:0 B:0 A:255` | Drop-shadow color. |
| `PlayerInfoListBackgroundAlpha` | `170` | Background rectangle alpha, from `0` to `255`. |
38 changes: 38 additions & 0 deletions SourceCode/EngineChanges/key_bindings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
<!-- markdownlint-disable MD033 -->
<!-- Needed to allow for <kbd> tags for keyboard key styling. -->

# Key Bindings

This page lists non-debug key bindings added or changed in TheSuperHackers engine source. Debug-only
bindings are intentionally omitted because debug commands are documented on the
[In-Game Debug Commands](ingame_debug_commands) page.

The command names are the names used by `CommandMap.ini` unless the entry is marked as default-only.

## CommandMap.ini Bindings

| Command | Default Binding | Usable In | Description |
| --- | --- | --- | --- |
| `INCREASE_MAX_RENDER_FPS` | <kbd>Ctrl</kbd>+<kbd>Numpad +</kbd> | Everywhere | Increases the max render FPS preset. |
| `DECREASE_MAX_RENDER_FPS` | <kbd>Ctrl</kbd>+<kbd>Numpad -</kbd> | Everywhere | Decreases the max render FPS preset. |
| `INCREASE_LOGIC_TIME_SCALE` | <kbd>Shift</kbd>+<kbd>Ctrl</kbd>+<kbd>Numpad +</kbd> | Everywhere | Increases the logic time scale FPS, reducing slow motion. Ignored in network games. |
| `DECREASE_LOGIC_TIME_SCALE` | <kbd>Shift</kbd>+<kbd>Ctrl</kbd>+<kbd>Numpad -</kbd> | Everywhere | Decreases the logic time scale FPS, slowing the simulation. Ignored in network games. |
| `TOGGLE_PLAYER_OBSERVER` | <kbd>M</kbd> | Observer | Toggles observer view between all players and the player currently being looked at. Requires `PlayerObserverEnabled=yes`. |
| `TOGGLE_FAST_FORWARD_REPLAY` | <kbd>F</kbd> | Game | Toggles replay fast-forward. The current default map assigns this key even though the command existed in retail. |
| `TOGGLE_PAUSE` | <kbd>P</kbd> | Observer | Toggles pause in non-multiplayer games. |
| `TOGGLE_PAUSE_ALT` | <kbd>Shift</kbd>+<kbd>P</kbd> | Everywhere | Alternate pause binding that can be used while playing. |
| `STEP_FRAME` | <kbd>O</kbd> | Observer | Advances one frame and pauses again in non-multiplayer games. |
| `STEP_FRAME_ALT` | <kbd>Shift</kbd>+<kbd>O</kbd> | Everywhere | Alternate frame-step binding that can be used while playing. |
| `SELECT_NEXT_IDLE_WORKER` | <kbd>Ctrl</kbd>+<kbd>I</kbd> | Game | Selects the next idle worker for the observed or local player. |

## Default-Only Controls

These controls are generated by the current default meta map, but do not currently have exposed
`CommandMap.ini` command names.

| Default Binding | Usable In | Description |
| --- | --- | --- |
| <kbd>Ctrl</kbd>+<kbd>Numpad 4</kbd> | Game | Rotates the camera left in a fixed increment. |
| <kbd>Ctrl</kbd>+<kbd>Numpad 6</kbd> | Game | Rotates the camera right in a fixed increment. |

<!-- markdownlint-restore -->
23 changes: 23 additions & 0 deletions SourceCode/EngineChanges/module_fields.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Object Module Fields

This page lists mod-facing object module fields added in TheSuperHackers engine source compared with
the retail source release. Existing retail fields are not repeated.

Boolean values use `Yes` or `No`.

## CrateCollide

Available in Generals and Zero Hour.

| Field | Accepted Values | Default | Description |
| --- | --- | --- | --- |
| `AllowMultiPickup` | `Yes` or `No` | Build-dependent | Allows multiple objects to pick up the same crate on the same frame. The default is enabled in retail-compatible or preserved-multi-crate-pickup builds, and disabled otherwise. |

## CreateObjectDie

The `CreateObjectDie` module exists in both Generals and Zero Hour. The added field below is available
only in Zero Hour.

| Field | Accepted Values | Default | Description |
| --- | --- | --- | --- |
| `TransferSelection` | `Yes` or `No` | `No` | If the dying object was selected and the module creates a replacement object, selects the replacement object. This is useful for objects such as the Sneak Attack tunnel. |
Loading
Loading