rework interactive mode (add scaling + recommended options) + autodetect HUD mode

Author: nbusseneau

CHANGELOG.md

@@ -7,9 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+-   Add scaling algorithm selector to interactive mode.
+-   Add `[RECOMMENDED]` tags to recommended options in interactive mode (maps to the default CLI options). The recommended option can be selected either by using its number (as usual) or by pressing ENTER (as a shorthand).
+
 ### Changed
 
 -   Improve warning displayed when unable to patch custom resolution in `ProfileX.json` by making it more explicit it can usually be ignored.
+-   Auto-determine default HUD resizing mode when using the CLI: `expand` for for 16:10, 21:9, and 32:9 / `center` for 48:9 and wider.
 
 ## [1.7.4] - 2022-10-14
 

README.md

@@ -282,8 +282,9 @@ Hephaistos supports the following HUD resizing modes: **(Click on items to show
 <details>
 <summary><code>expand</code> (default)</summary>
 
-Expand the HUD horizontally and vertically, i.e. HUD will scale with screen size.
+Expand the HUD horizontally and vertically.
 Static HUD elements will be repositioned to their intended location for the new screen size, e.g. health indicator will be in the bottom left, resource indicator will be in the bottom right.
+This is the default HUD resizing mode used by Hephaistos for 16:10, 21:9, and 32:9, but note that you may want to try out `--hud=center` for 32:9 to see what you prefer.
 
 ![hud_21-9-vanilla](https://user-images.githubusercontent.com/4659919/178168394-99b68f49-b391-4fa9-9f5b-89be99981a91.jpg)
 ![hud_21-9_expand](https://user-images.githubusercontent.com/4659919/178168395-2f730460-a8c8-4d11-8a35-8f3b0c003626.jpg)
@@ -293,15 +294,15 @@ Static HUD elements will be repositioned to their intended location for the new
 <details>
 <summary><code>center</code></summary>
 
-Keep HUD in the center of the screen with the same size as the original HUD, i.e. screen size will change but HUD will not move.
+Keep HUD in the center of the screen with the same size as the original 16:9 HUD.
+Screen size will change but HUD will not move, static HUD elements will remain at their default 16:9 position.
+This is the default HUD resizing mode used by Hephaistos for 48:9 and wider.
 
 ![hud_21-9-vanilla](https://user-images.githubusercontent.com/4659919/178168394-99b68f49-b391-4fa9-9f5b-89be99981a91.jpg)
 ![hud_21-9_center](https://user-images.githubusercontent.com/4659919/178168396-37eb931d-0158-409c-8e8d-702e37fa5435.jpg)
 
 </details>
 
-You might want to use `--hud=center` for 32:9 or wider resolutions.
-
 ### Scaling
 
 Hephaistos supports the following scaling algorithms: **(Click on items to show details)**
@@ -338,8 +339,6 @@ This scaling is not recommended for general usage as it effectively "zooms out"
 
 </details>
 
-Use `--scaling=pixel` if you wish to use pixel-based scaling.
-
 ### Custom resolution
 
 By default, Hephaistos patches a custom resolution in the [`ProfileX.sjson` configuration file](https://www.pcgamingwiki.com/wiki/Hades#Configuration_file.28s.29_location) by updating its `WindowWidth`/`WindowHeight` and `X`/`Y` values.

hephaistos/cli.py

@@ -8,7 +8,7 @@
 
 from hephaistos import backups, config, hashes, helpers, interactive, lua_mod, patchers, sjson_data
 from hephaistos.config import LOGGER
-from hephaistos.helpers import HadesNotFound, HUD, ModImporterRuntimeError, Platform, Scaling
+from hephaistos.helpers import AspectRatio, HadesNotFound, HUD, ModImporterRuntimeError, Platform, Scaling
 
 
 class ParserBase(ArgumentParser):
@@ -105,90 +105,6 @@ def __start(self) -> None:
         # if in interactive mode, loop until user manually closes
         self.__restart() if config.interactive_mode else self.__end()
 
-    def __interactive(self, raw_args: list[str]) -> None:
-        interactive.clear()
-        try:
-            msg = f"""Hi! This interactive wizard will help you to set up Hephaistos.
-Note: while Hephaistos can be used in interactive mode for basic usage, you will need to switch to non-interactive mode for any advanced usage. See the README for more details.
-
-{helpers.check_version()}
-"""
-            print(msg)
-            available_subcommands = {
-                subcommand: helpers.capitalize(self.subcommands[subcommand].description)
-                for subcommand in ['patch', 'restore', 'status']
-            }
-            subcommand = interactive.pick(
-                add_option=interactive.EXIT_OPTION,
-                **available_subcommands,
-            )
-            raw_args.append(subcommand)
-            if subcommand == 'patch':
-                choice = interactive.pick(
-                    common1610="Select from common 16:10 resolutions",
-                    common219="Select from common 21:9 resolutions",
-                    common329="Select from common 32:9 resolutions",
-                    common489="Select from common 48:9 / triple screen resolutions",
-                    manual="Input resolution manually",
-                )
-                if choice == 'common1610':
-                    (width, height) = interactive.pick(
-                        prompt="Select resolution:",
-                        options=[
-                            '1280 x 800',
-                            '1440 x 900',
-                            '1680 x 1050',
-                            '1920 x 1200',
-                            '2560 x 1600',
-                            '3840 x 2400',
-                        ],
-                    ).split(' x ')
-                elif choice == 'common219':
-                    (width, height) = interactive.pick(
-                        prompt="Select resolution:",
-                        options=[
-                            '2560 x 1080',
-                            '3440 x 1440',
-                            '3840 x 1600',
-                            '5120 x 2160',
-                        ],
-                    ).split(' x ')
-                elif choice == 'common329':
-                    (width, height) = interactive.pick(
-                        prompt="Select resolution:",
-                        options=[
-                            '3840 x 1080',
-                            '5120 x 1440',
-                        ],
-                    ).split(' x ')
-                elif choice == 'common489':
-                    (width, height) = interactive.pick(
-                        prompt="Select resolution:",
-                        options=[
-                            '5760 x 1080',
-                            '7680 x 1440',
-                        ],
-                    ).split(' x ')
-                else:
-                    width = interactive.input_number("Width: ")
-                    height = interactive.input_number("Height: ")
-                    print()
-                raw_args.append(width)
-                raw_args.append(height)
-                choice = interactive.pick(
-                    prompt="Select HUD preference (for 32:9, try out both options and see what you prefer!):",
-                    expand="Expand HUD horizontally / vertically (recommended for 21:9 and 16:10)",
-                    center="Keep HUD in the center (recommended for 48:9 / triple screen)",
-                )
-                raw_args.append('--hud')
-                raw_args.append(choice)
-            # repass modified raw_args to parse_args after selection is done
-            return self.parse_args(raw_args)
-        except interactive.InteractiveCancel:
-            self.__restart(prompt_user=False)
-        except interactive.InteractiveExit:
-            self.__end()
-
     def __handle_global_args(self, args: list[str]) -> None:
         # logging verbosity level
         level = ParserBase.VERBOSE_TO_LOG_LEVEL[min(args.verbose, 2)]
@@ -230,6 +146,135 @@ def __configure_hades_dir(self, hades_dir_arg: str) -> None:
             LOGGER.error(msg)
             self.__end(1, prompt_user=config.interactive_mode)
 
+    def __interactive(self, raw_args: list[str]) -> None:
+        interactive.clear()
+        try:
+            msg = f"""Hi! This interactive wizard will help you to set up Hephaistos.
+Note: while Hephaistos can be used in interactive mode for basic usage, you will need to switch to non-interactive mode for any advanced usage. See the README for more details.
+
+{helpers.check_version()}
+"""
+            print(msg)
+            available_subcommands = {
+                subcommand: helpers.capitalize(self.subcommands[subcommand].description)
+                for subcommand in ['patch', 'restore', 'status']
+            }
+            subcommand = interactive.pick(
+                options=available_subcommands,
+                additional_option=interactive.EXIT_OPTION,
+            )
+            raw_args.append(subcommand)
+            if subcommand == 'patch':
+                self.__interactive_patch_handler(raw_args)
+            # repass modified raw_args to parse_args after selection is done
+            return self.parse_args(raw_args)
+        except interactive.InteractiveCancel:
+            self.__restart(prompt_user=False)
+        except interactive.InteractiveExit:
+            self.__end()
+
+    def __interactive_patch_handler(self, raw_args) -> None:
+        options = {
+            AspectRatio._16_10: "Select from common 16:10 resolutions",
+            AspectRatio._21_9: "Select from common 21:9 resolutions",
+            AspectRatio._32_9: "Select from common 32:9 resolutions",
+            AspectRatio._48_9: "Select from common 48:9 resolutions",
+            AspectRatio.manual: "Input resolution manually",
+        }
+        aspect_ratio = interactive.pick(options=options)
+        dispatch = {
+            AspectRatio._16_10: lambda: self.__interactive_pick_resolution([
+                '1280 x 800',
+                '1440 x 900',
+                '1680 x 1050',
+                '1920 x 1200',
+                '2560 x 1600',
+                '3840 x 2400',
+            ]),
+            AspectRatio._21_9: lambda: self.__interactive_pick_resolution([
+                '2560 x 1080',
+                '3440 x 1440',
+                '3840 x 1600',
+                '5120 x 2160',
+            ]),
+            AspectRatio._32_9: lambda: self.__interactive_pick_resolution([
+                '3840 x 1080',
+                '5120 x 1440',
+            ]),
+            AspectRatio._48_9: lambda: self.__interactive_pick_resolution([
+                '5760 x 1080',
+                '7680 x 1440',
+            ]),
+            AspectRatio.manual: self.__interactive_input_resolution,
+        }
+        (width, height) = dispatch[aspect_ratio]()
+        raw_args += [width, height]
+
+        enabled = "enabled"
+        recommended = "recommended"
+        args = {
+            AspectRatio._16_10: {
+                enabled: [Scaling.VERT_PLUS, Scaling.PIXEL_BASED],
+                recommended: Scaling.VERT_PLUS
+            },
+            AspectRatio._21_9: {
+                enabled: [Scaling.HOR_PLUS, Scaling.PIXEL_BASED],
+                recommended: Scaling.HOR_PLUS
+            },
+            AspectRatio._32_9: {
+                enabled: [Scaling.HOR_PLUS, Scaling.PIXEL_BASED],
+                recommended: Scaling.HOR_PLUS
+            },
+            AspectRatio._48_9: {
+                enabled: [Scaling.HOR_PLUS, Scaling.PIXEL_BASED],
+                recommended: Scaling.HOR_PLUS
+            },
+            AspectRatio.manual: {
+                enabled: [Scaling.AUTODETECT, Scaling.PIXEL_BASED],
+                recommended: Scaling.AUTODETECT
+            },
+        }
+        scaling = self.__interactive_pick_scaling(enabled=args[aspect_ratio][enabled], recommended=args[aspect_ratio][recommended])
+        raw_args += ['--scaling', scaling]
+
+        recommended = {
+            AspectRatio._16_10: HUD.EXPAND,
+            AspectRatio._21_9: HUD.EXPAND,
+            AspectRatio._32_9: None,
+            AspectRatio._48_9: HUD.CENTER,
+            AspectRatio.manual: None,
+        }
+        hud = self.__interactive_pick_hud(recommended=recommended[aspect_ratio])
+        raw_args += ['--hud', hud]
+
+        return raw_args
+
+    def __interactive_pick_resolution(self, options: list[str]) -> tuple[int, int]:
+        return interactive.pick(prompt="Select resolution:", options=options).split(' x ')
+
+    def __interactive_input_resolution(self) -> tuple[int, int]:
+        width = interactive.input_number("Width: ")
+        height = interactive.input_number("Height: ")
+        print()
+        return (width, height)
+
+    def __interactive_pick_scaling(self, enabled: list[Scaling], recommended: Scaling=None):
+        options = {
+            Scaling.AUTODETECT: "Hor+ / Vert+ (based on input resolution): keeps experience close to vanilla game.",
+            Scaling.HOR_PLUS: "Hor+: keeps experience close to vanilla game.",
+            Scaling.VERT_PLUS: "Vert+: keeps experience close to vanilla game.",
+            Scaling.PIXEL_BASED: """Pixel-based: effectively "zooms out" the camera.""",
+        }
+        options = {option: description for option, description in options.items() if option in enabled}
+        return interactive.pick(prompt="Select scaling algorithm (see README for more details):", options=options, recommended_option=recommended)
+
+    def __interactive_pick_hud(self, recommended: HUD=None) -> HUD:
+        options = {
+            HUD.EXPAND: "Expand the HUD horizontally and vertically.",
+            HUD.CENTER: "Keep HUD in the center of the screen with the same size as the original 16:9 HUD.",
+        }
+        return interactive.pick(prompt="Select HUD resizing mode (see README for more details):", options=options, recommended_option=recommended)
+
     def __restart(self, prompt_user=True) -> None:
         if prompt_user:
             interactive.any_key("\nPress any key to continue...")
@@ -261,9 +306,9 @@ def __init__(self, **kwargs) -> None:
         self.add_argument('--scaling', default=Scaling.AUTODETECT,
             choices=[Scaling.HOR_PLUS.value, Scaling.VERT_PLUS.value, Scaling.PIXEL_BASED.value],
             help="scaling type (default: 'hor+' for wider aspect ratios / 'vert+' for taller aspect ratios)")
-        self.add_argument('--hud', default=HUD.EXPAND,
+        self.add_argument('--hud', default=HUD.AUTODETECT,
             choices=[HUD.EXPAND.value, HUD.CENTER.value],
-            help="HUD mode (default: 'expand')")
+            help="HUD mode (default: 'expand' for most aspect ratios / 'center' for 48:9 and wider)")
         self.add_argument('--no-custom-resolution', action='store_false', default=True, dest='custom_resolution',
             help="do not patch custom resolution in 'ProfileX.sjson' configuration file (default: patch custom resolution)")
         self.add_argument('-f', '--force', action='store_true',
@@ -272,7 +317,8 @@ def __init__(self, **kwargs) -> None:
     def handler(self, width: int, height: int, scaling: Scaling, hud: HUD, custom_resolution: bool, force: bool, **kwargs) -> None:
         """Compute viewport depending on arguments, then patch all needed files and install Lua mod.
         If using '--force', discard backups, hashes and SJSON data, and uninstall Lua mod."""
-        scaling = helpers.configure_screen_variables(width, height, scaling)
+        scaling, hud = helpers.autodetect(width, height, scaling, hud)
+        helpers.configure_screen_variables(width, height, scaling)
         LOGGER.info(f"Using resolution: {config.resolution.width, config.resolution.height}")
         LOGGER.info(f"Using '--scaling={scaling}': computed patch viewport {config.new_screen.width, config.new_screen.height}")
 
@@ -302,7 +348,7 @@ def handler(self, width: int, height: int, scaling: Scaling, hud: HUD, custom_re
             LOGGER.error(e)
             if config.interactive_mode:
                 LOGGER.error("It looks like the game was updated. Do you wish to discard previous backups and re-patch Hades from its current state?")
-                choice = interactive.pick(options=['Yes', 'No',], add_option=None)
+                choice = interactive.pick(options=['Yes', 'No',], recommended_option='Yes', additional_option=None)
                 if choice == 'Yes':
                     self.handler(width, height, scaling, hud, custom_resolution, force=True)
             else:

hephaistos/helpers.py

@@ -21,12 +21,19 @@
 
 # Type definitions
 IntOrFloat = Union[int, float]
+class AspectRatio(str, Enum):
+    _16_10 = '16:10'
+    _21_9 = '21:9'
+    _32_9 = '32:9'
+    _48_9 = '48:9'
+    manual = 'manual'
 class Scaling(str, Enum):
     AUTODETECT = 'autodetect'
     HOR_PLUS = 'hor+'
     VERT_PLUS = 'vert+'
     PIXEL_BASED = 'pixel'
 class HUD(str, Enum):
+    AUTODETECT = 'autodetect'
     EXPAND = 'expand'
     CENTER = 'center'
 class Platform(str, Enum):
@@ -335,15 +342,27 @@ def run_modimporter(modimporter_file: Path, clean_only: bool=False) -> None:
                     raise e
 
 
-def configure_screen_variables(width: int, height: int, scaling: Scaling) -> Scaling:
-    """Compute virtual viewport size to patch depending on scaling type and given resolution width / height."""
+def autodetect(width: int, height: int, scaling: Scaling, hud: HUD) -> tuple[Scaling, HUD]:
+    """Set default values based on aspect ratios for arguments with autodetection."""
     if scaling == Scaling.AUTODETECT:
-        # use hor+ for aspect ratios wider than default (e.g. 21:9)
+        # use 'hor+' for aspect ratios wider than default (e.g. 21:9)
         if (width / height) >= (config.DEFAULT_SCREEN.width / config.DEFAULT_SCREEN.height):
             scaling = Scaling.HOR_PLUS
-        # use vert+ for aspect ratios taller than default (e.g. 16:10)
+        # use 'vert+' for aspect ratios taller than default (e.g. 16:10)
         else:
             scaling = Scaling.VERT_PLUS
+    if hud == HUD.AUTODETECT:
+        # use 'center' for 48:9 and wider
+        if (width / height) >= (48 / 9):
+            hud = hud.CENTER
+        # use 'expand' for anything else
+        else:
+            hud = hud.EXPAND
+    return (scaling, hud)
+
+
+def configure_screen_variables(width: int, height: int, scaling: Scaling):
+    """Compute virtual viewport size to patch depending on scaling type and given resolution width / height."""
     config.resolution = config.Screen(width, height)
     if scaling == Scaling.HOR_PLUS:
         virtual_width = int(width / height * config.DEFAULT_SCREEN.height)
@@ -358,7 +377,6 @@ def configure_screen_variables(width: int, height: int, scaling: Scaling) -> Sca
     config.scale_factor_X = config.new_screen.width / config.DEFAULT_SCREEN.width
     config.scale_factor_Y = config.new_screen.height / config.DEFAULT_SCREEN.height
     config.scale_factor = max(config.scale_factor_X, config.scale_factor_Y)
-    return scaling
 
 
 def recompute_fixed_value(original_value: IntOrFloat, original_reference_point: IntOrFloat, new_reference_point: IntOrFloat) -> IntOrFloat: