Advanced Installer Documentation & Tasks

[Sewer56]

This PR provides the documentation and task breakdown for the behind the scene details for

• Advanced installer backend #610

These are provided as a series of ADRs; which detail the context, decision drivers, requirements and implementation details for each of the sub-tasks that require to be done to complete the aforementioned issue.

The provided tasks are (mostly) dependency free and can be done in parallel; thus are up for grabs.
Text for all of the individual sub-tasks (which will be posted as separate issues upon merge), is available below.

Feedback would be appreciated.

---

Issue 1: Implement Base Advanced Installer Design

Approx Time: 2 Days.

Implement the base Advanced Installer design described here.

Checklist

• Auto-Invoke AdvancedInstaller if every other installer is no-op (does nothing).

• AdvancedInstaller must work in the absence of suggestion data (in case it is incomplete).

• AdvancedInstaller returns appropriate error if the user attempts to map a path which is already mapped. (This can be an exception, just include extra context data, e.g. target path, which can later be displayed in UI).

• AdvancedInstaller does not give error when mapping an entire folder whereby an item inside this folder has already been mapped. (i.e. If you map file, then folder, do not throw double mapping error)

• AdvancedInstaller emits correct IEnumerable<AModFile> operations.

• Tests cover all aforementioned cases.

---

Issue 2a: Implement Basic Advanced Installer Suggestions

Approx Time: 2-3 hours.

Implement the base Advanced Installer suggestion algorithm described here. This task does not include the filtering further logic.

Prerequisites:

None. This code can be created and tested before Issue 1.

Checklist

• IGame exposes ISuggestionFolder.
• Games are updated to expose ISuggestionFolder.

---

Issue 2b: Improve Advanced Installer Suggestions

Approx Time: 2-3 hours.

Implement the filtering logic in Advanced Installer Suggestion Algorithm.

Prerequisites:

Issue 2a.

Checklist

Method signature should look something like (string filePath, bool isFolder, ISuggestionFolder[] existing).

• Implement Directory Filter Algorithm
• Implement File Filter Algorithm

---

Issue 3: Implement Advanced Installer Persistence Mechanism (UI & Backend)

Approx Time: 2-3 days.
Note: Backlogged. Decided this to merge with UI task to add persistence.

Documented here: Installer Persistence.

Prerequisites

Doesn't matter, it's backlogged. Stuff will be done by then.

---

Issue 4: Migrate Remaining Games to use InstallFolderTarget

Backlog issue, can be done any time.

Approx Time: 1 day.

Some installers still use more legacy mechanisms for installation, rather than the newer InstallFolderTarget of GameCapabilities. In order to leverage the suggestions system for AdvancedInstaller, we should migrate these games to use InstallFolderTarget where possible.

Prerequisites

None

[Al12rs]

The purpose of the Suggested locations area is not to suggest possible locations but rather list *All * the available locations.
"Suggested locations" is just a user facing name for it.

So the objective here isn't to help the user choose, but rather to offer all the locations they might want/need to install the files to.

Intelligent sorting of the options based on potential knowledge is outside the scope for now.

Concretely, the locations are the GameFolderTypes that the Game extension uses + InstallFolderTarget locations that the game defined.

Game folder should always be suggested, if Appdata and Mygames exist for that game install, they should be suggested as well, even if the game does not declare any InstallFolderTarget for them.

[Sewer56]

Game folder should always be suggested, if Appdata and Mygames exist for that game install, they should be suggested as well, even if the game does not declare any InstallFolderTarget for them.

I agree, however the designs don't currently accomodate this, so feedback from Design ( @captainsandypants ) is requested.

The current designs assume the only output folder is game directory.

e.g. From a style perspective, are we supposed to make separate bordered regions for other types of output paths?

[Al12rs]

You just add the entry here:

For example for starfield you would add MyGames/Starfield as another target location.
For Baldur's Gate 3 you would have Appdata/Larian and the Game folder.

So you might need some short name or description of the Target paths from the Games.

You would add another expandable section here for MyGames, under the SkyrimSpecialEdition section.

This case was discussed during the design meetings for this, so design is aware

[Sewer56]

Alright, that works.

Edit: ADR was updated accordingly to make it more explicit, with regards to initial population of directories; and that filtering is considered an iterative improvement.

[Al12rs]

InstallFolderTarget was meant to be used by the Generic Folder installer to recognize folders.
If we unify the two things, we could have games that define InstallFolderTargets that are not actually recognizable.

So either we separate the two concepts with one that just wraps the other adding the information necessary for the Generic Installer to recognize the files, or we keep it a single thing but with a clear way for the Generic installer to know which InstallFolderTarget it should actually use (so perhaps two different methods on IGame returning the two different lists?)

[Sewer56]

I'm not sure that I quite understand the description here.

The initial set of 'suggested folders' (w/o suggestion algorithm) should consist of:

• All GamePath entries.
• All deploy-able folders not in GamePath (specified via InstallFolderTarget).

Are you suggesting that we might run into a situation where we might want to recommend subfolder(s) to the users which we may not necessarily want the Generic Installer to deploy to?

e.g.

Mod
├─ texture.dds

Where texture.dds should go to a folder like {Game}/Data/Textures, but {Game}/Data/Textures is not considered a folder under which the Generic Installer might try deploying to?

That doesn't happen often, but I'm happy to add an interative task to export the needed properties as an interface (trait), and expose another getter from IGame which provides custom suggestions that are not used as part of the deployment step. [And update the documentation accordingly]

[Sewer56]

Updated the OP to reflect latest commit.

[Al12rs]

The deployment steps are already shared between all mods, mod installation has no baring on it. Installer just returns a list of source/target mappings and everything else is handled by common code.

[Al12rs]

Suggestion is misnomer, you should think of these as all possible install locations.

InstallFolderTarget would actually be a good name for it, but it is already used for the GenericFolderMatch installer.
I would actually suggest to rename the version for the GenericFolderMatch installer to something more specific, like RecognizableFolderDescriptor or something along those lines.

Instead of suggestions I would call them something like:
ModDestinationDescriptor