GameCollector.Common
4.2.3.2
See the version list below for details.
dotnet add package GameCollector.Common --version 4.2.3.2
NuGet\Install-Package GameCollector.Common -Version 4.2.3.2
<PackageReference Include="GameCollector.Common" Version="4.2.3.2" />
paket add GameCollector.Common --version 4.2.3.2
#r "nuget: GameCollector.Common, 4.2.3.2"
// Install GameCollector.Common as a Cake Addin #addin nuget:?package=GameCollector.Common&version=4.2.3.2 // Install GameCollector.Common as a Cake Tool #tool nuget:?package=GameCollector.Common&version=4.2.3.2
GameCollector
a fork of GameFinder
.NET library for finding games. GameCollector expands on upstream GameFinder (which is primarily designed to support modding tools), by adding additional supported store launchers, emulators, and data sources, and includes additional information about each game (sufficient for a multi-store game launcher such as GLC). This fork is indebted to erri120's hard work, but as he is reticent to expand the scope of GameFinder, GameCollector continues with a different philosophy.
The following launchers and emulators are supported:
handler | package |
---|---|
Amazon Games | |
Arc | |
Bethesda.net | |
Big Fish Game Manager | |
Blizzard Battle.net | |
Dolphin Emulator | |
EA app | |
Epic Games Store | |
Game Jolt Client | |
GOG Galaxy | |
Humble App | |
Indiegala IGClient | |
itch | |
Legacy Games Launcher | |
Multiple Arcade Machine Emulator (MAME) | |
Oculus | |
Origin | |
Paradox Launcher | |
Plarium Play | |
Riot Client | |
RobotCache Client | |
Rockstar Games Launcher | |
Steam | |
Ubisoft Connect | |
Wargaming.net Game Center | |
Xbox Game Pass |
If you are interested in understanding how GameCollector/GameFinder finds these games, check the upstream wiki for more information (descriptions of the added handlers should eventually be added to a wiki here).
Additionally, the following Linux tools are supported:
handler | package |
---|---|
Wine |
Example and Binaries
The example project uses every available store handler and can be used as a reference. You can go to Releases to download Windows builds of GameCollector.exe, or the GitHub Actions Page and click on one of the latest CI workflow runs to download pre-release binaries for this project.
GameCollector Issues
- Known issues: See GameCollector issues here or upstream GameFinder issues here. Please do not submit bugs/requests for GameCollector on GameFinder's GitHub.
- DLCs/clones: When an entry is detected as a DLC addon (or a clone in the MAME handler), the
string? GameData.BaseGame
field is set to the ID of the main game (or sometimes the string "False" when the relationship can't be determined). To hide DLCs from the consumer application, useFindAllGames(Settings)
wherebool Settings.BaseOnly = true
, or do not use entries wherestring? GameData.BaseGame != null
. - Owned not-installed games: Some handlers can find owned not-installed games. To support this feature for Steam games, see note below. To hide not-installed games, use
FindAllGames(Settings)
wherebool Settings.InstalledOnly = true
, or do not use entries wherebool GameData.IsInstalled == false
. - Unowned games: A few handlers can find all entries in the launcher database. To show only owned games, use
FindAllGames(Settings)
wherebool Settings.OwnedOnly = true
, or do not use entries wherebool GameData.IsOwned == false
. - Non-game items: Some handlers can find non-game (e.g., applications) items. To show only games, use
FindAllGames(Settings)
wherebool Settings.GamesOnly = true
, or parse the item'sList<string> GameData.Genres
for the appropriate string values.
Dolphin/MAME
These handlers both require you pass an AbsolutePath to the emulator executable when instantiating the handler class, e.g., new MAMEHandler(fileSystem, mamePath)
.
Oculus
If the Oculus service is running (as it does even when the program is not open), the database is usually locked and connot be read. The handler attempts to stop the service, but this only works if the consumer application is running as administrator.
Differences from Upstream
GameCollector adds a FindClient()
function to get the path to a given store client's executable.
The TGame implementations of GameCollector's handlers inherit a generic GameData record. Unfortunately, no handler populates all of the fields, and many only provide a few:
enum Handler
string GameId
string GameName
AbsolutePath GamePath
AbsolutePath? SavePath
AbsolutePath Launch
string LaunchArgs
string LaunchUrl
AbsolutePath Icon
AbsolutePath Uninstall
string UninstallArgs
string UninstallUrl
DateTime? InstallDate
DateTime? LastRunDate
uint NumRuns
TimeSpan? RunTime
bool IsInstalled
bool IsOwned
bool IsHidden
List<Problem>? Problems
List<string>? Tags
ushort? MyRating
string? BaseGame
Dictionary<string, List<string>>? Metadata
The Metadata dictionary may include (depending on available information): "ReleaseDate", "Description", "Developers", "Publishers", "Genres", "ImageUrl", etc.
Supported Emulators
This is a new category of handler for GameCollector. They are Windows-only for now.
- Dolphin
- MAME
New Supported Launchers
The following 17 handlers have been added for GameCollector. They are all Windows-only for now:
- Amazon Games
- Arc
- Big Fish Game Manager
- Blizzard Battle.net
- Game Jolt
- Humble App
- Indiegala IGClient
- itch
- Legacy Games Launcher
- Oculus
- Paradox Launcher
- Plarium Play
- Riot Client
- RobotCache Client
- Rockstar Games Launcher
- Ubisoft Connect
- Wargaming.net Game Center
Usage
Like GameFinder, all store handlers inherit from AHandler<TGame, TId>
and implement FindAllGames()
which returns IEnumerable<OneOf<TGame, ErrorMessage>>
. The OneOf
struct is a F# style union and is guaranteed to only contain one of the following: a TGame
or an ErrorMessage
. I recommended checking out the OneOf library, if you want to learn more.
Some important things to remember:
- All store handler methods are pure, meaning they do not change the internal state of the store handler because they don't have any. This also means that the results are not cached and you shouldn't call the same method multiple times. It's up to the library consumer to cache the results somewhere.
- GameIds are store dependent. Each store handler has their own type of id and figuring out the right id for your game might require some testing. You can find useful resources in this README for some store handlers.
Basic Usage
var results = handler.FindAllGames();
foreach (var result in results)
{
// using the switch method
result.Switch(game =>
{
Console.WriteLine($"Found {game}");
}, error =>
{
Console.WriteLine(error);
});
// using the provided extension functions
if (result.TryGetGame(out var game))
{
Console.WriteLine($"Found {game}");
} else
{
Console.WriteLine(result.AsError());
}
}
Finding a single game
If you're working on an application that only needs to find 1 game, then you can use the FindOneGameById
method instead. IMPORTANT NOTE: the results are not cached. If you call this method multiple, the store handler will do the same thing multiple times, which is search for every game installed. Do not call this method if you need to find multiple games.
var game = handler.FindOneGameById(someId, out var errors);
// I highly recommend logging errors regardless of whether or not the game was found.
foreach (var error in errors)
{
Console.WriteLine(error);
}
if (game is null)
{
Console.WriteLine("Unable to find game");
} else
{
Console.WriteLine($"Found {game}");
}
Finding multiple games
If you need to find multiple games at once, you can use the FindAllGamesById
method instead. This returns an IReadOnlyDictionary<TId, TGame>
which you can use to lookup games by id. IMPORTANT NOTE: the results are not cached. You have to do that yourself.
var games = handler.FindAllGamesById(out var errors);
// I highly recommend always logging errors.
foreach (var error in errors)
{
Console.WriteLine(error);
}
if (games.TryGetValue(someId, out var game))
{
Console.WriteLine($"Found {game}");
} else
{
Console.WriteLine($"Unable to find game with the id {someId}");
}
Upstream Supported Launchers
The following handlers come from upstream GameFinder:
Steam
Steam is supported natively on Windows and Linux. Use SteamDB to find the ID of a game.
Usage (cross-platform):
var handler = new SteamHandler(FileSystem.Shared, OperatingSystem.IsWindows() ? WindowsRegistry.Shared : null);
GameCollector adds the ability to check a Steam profile for owned not-installed games. A specific Steam ID may be specified, though it will automatically attempt to find one. However, this feature requires that an API key be activated and specified, and the user profile set to public.
GOG Galaxy
GOG Galaxy is supported natively on Windows, and with Wine on Linux. Use the GOG Database to find the ID of a game.
Usage (native on Windows):
var handler = new GOGHandler(WindowsRegistry.Shared, FileSystem.Shared);
Usage (Wine on Linux):
See Wine for more information.
// requires a valid prefix
var wineFileSystem = winePrefix.CreateOverlayFileSystem(FileSystem.Shared);
var wineRegistry = winePrefix.CreateRegistry(FileSystem.Shared);
var handler = new GOGHandler(wineRegistry, wineFileSystem);
GameCollector adds finding all GOG games in the launcher's database, whether installed, owned not-installed, or unowned.
Epic Games Store
The Epic Games Store is supported natively on Windows, and with Wine on Linux. Use the Epic Games Store Database to find the ID of a game (WIP).
Usage (native on Windows):
var handler = new EGSHandler(WindowsRegistry.Shared, FileSystem.Shared);
Usage (Wine on Linux):
See Wine for more information.
// requires a valid prefix
var wineFileSystem = winePrefix.CreateOverlayFileSystem(FileSystem.Shared);
var wineRegistry = winePrefix.CreateRegistry(FileSystem.Shared);
var handler = new EGSHandler(wineRegistry, wineFileSystem);
GameCollector adds finding owned not-installed EGS games.
Origin
Origin is supported natively on Windows, and with Wine on Linux. Note: EA is deprecating Origin and will replace it with EA app.
Usage (native on Windows):
var handler = new OriginHandler(FileSystem.Shared);
Usage (Wine on Linux):
See Wine for more information.
// requires a valid prefix
var wineFileSystem = winePrefix.CreateOverlayFileSystem(FileSystem.Shared);
var handler = new OriginHandler(wineFileSystem);
EA app
The EA app is the replacement for Origin on Windows: See EA is deprecating Origin. This is by far the most complicated Store Handler. You should read the upstream wiki entry. This implementation decrypts the encrypted file created by the EA app. You should be aware that the key used to encrypt the file is derived from hardware information. If the user changes their hardware, the decryption process might fail because they key has changed.
The EA app is only supported on Windows.
Usage:
var handler = new EADesktopHandler(FileSystem.Shared, new HardwareInfoProvider());
Xbox Game Pass
This package used to be deprecated, but support was re-added in GameFinder 3.0.0. Xbox Game Pass used to install games inside a SYSTEM
protected folder, making modding not feasible for the average user. You can read more about this here.
Xbox Game Pass is only supported on Windows.
Usage:
var handler = new XboxHandler(FileSystem.Shared);
Bethesda.net
As of May 11, 2022, the Bethesda.net launcher is no longer in use. The upstream package GameFinder.StoreHandlers.BethNet has been deprecated and marked as legacy.
Wine
Wine is a compatibility layer capable of running Windows applications on Linux. Wine uses prefixes to create and store virtual C:
drives. A user can install and run Windows program inside these prefixes, and applications running inside the prefixes likely won't even notice they are not actually running on Windows.
Since GameCollector/GameFinder is all about finding games, it also has to be able to find games inside Wine prefixes to provide good Linux support. The package NexusMods.Paths
from NexusMods.App provides a file system abstraction IFileSystem
which enables path re-mappings:
AWinePrefix prefix = //...
// creates a new IFileSystem, with path mappings into the wine prefix
IFileSystem wineFileSystem = prefix.CreateOverlayFileSystem(FileSystem.Shared);
// this wineFileSystem can be used instead of FileSystem.Shared:
var handler = new OriginHandler(wineFileSystem);
// you can also create a new IRegistry:
IRegistry wineRegistry = prefix.CreateRegistry(FileSystem.Shared);
// and use both:
var handler = new EGSHandler(wineRegistry, wineFileSystem);
Default Prefix Manager
GameCollector.Wine
implements a IWinePrefixManager
for finding Wine prefixes.
Usage:
var prefixManager = new DefaultWinePrefixManager(FileSystem.Shared);
foreach (var result in prefixManager.FindPrefixes())
{
result.Switch(prefix =>
{
Console.WriteLine($"Found wine prefix at {prefix.ConfigurationDirectory}");
}, error =>
{
Console.WriteLine(error.Value);
});
}
Bottles
GameCollector.Wine
implements a IWinePrefixManager
for finding Wine prefixes managed by Bottles.
Usage:
var prefixManager = new BottlesWinePrefixManager(FileSystem.Shared);
foreach (var result in prefixManager.FindPrefixes())
{
result.Switch(prefix =>
{
Console.WriteLine($"Found wine prefix at {prefix.ConfigurationDirectory}");
}, error =>
{
Console.WriteLine(error.Value);
});
}
Proton
Valve's Proton is a compatibility tool for Steam and is mostly based on Wine. The Wine prefixes managed by Proton are in the compatdata
directory of the steam library where the game itself is installed. Since the path is relative to the game itself and requires the app id, erri120 decided to put this functionality in the Steam store handler:
SteamGame? steamGame = steamHandler.FindOneGameById(1237970, out var errors);
if (steamGame is null) return;
ProtonWinePrefix protonPrefix = steamGame.GetProtonPrefix();
var protonPrefixDirectory = protonPrefix.ProtonDirectory;
if (protonDirectory != default && fileSystem.DirectoryExists(protonDirectory))
{
Console.WriteLine($"Proton prefix is at {protonDirectory}");
}
Trimming
Self-contained deployments and executables can be trimmed starting with .NET 6. This feature is only available to applications that are published self-contained.
Trimmable:
GameCollector.Common
GameCollector.RegistryUtils
GameCollector.Wine
GameCollector.StoreHandlers.Steam
GameCollector.StoreHandlers.GOG
GameCollector.StoreHandlers.EGS
GameCollector.StoreHandlers.Origin
NOT Trimmable:
GameCollector.StoreHandlers.EADesktop
: This package referencesSystem.Management
, which is not trimmable due to COM interop issues. See dotnet/runtime#78038, dotnet/runtime#75176 and dotnet/runtime#61960 for more details.
I recommend looking at the project file of the example project, if you run into warnings or errors with trimming.
Contributing
See CONTRIBUTING for more information.
License
See LICENSE for more information.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net8.0
- NexusMods.Paths (>= 0.9.5)
- System.ServiceProcess.ServiceController (>= 8.0.0)
NuGet packages (6)
Showing the top 5 NuGet packages that depend on GameCollector.Common:
Package | Downloads |
---|---|
GameCollector.StoreHandlers.Legacy
Library for finding games installed with Legacy Games Launcher. |
|
GameCollector.StoreHandlers.Oculus
Library for finding games installed with Oculus. |
|
GameCollector.StoreHandlers.Plarium
Library for finding games installed with Plarium Play. |
|
GameCollector.StoreHandlers.Paradox
Library for finding games owned and installed with Paradox Launcher. |
|
GameCollector.StoreHandlers.IGClient
Library for finding games owned and installed with the Indiegala Client. |
GitHub repositories
This package is not used by any popular GitHub repositories.