Table of Contents

Working with game library

Introduction

Game database API allows you to access and modify game library and its objects (including platforms and emulators). Database API can be accessed via PlayniteAPI.Database property, which provides IDatabaseAPI interface.

Handling Games

Getting Games

To get list of all games in library use Database property from IPlayniteAPI and Games collection.

foreach (var game in PlayniteApi.Database.Games)
{
    // Do stuff with a game
}

// Get a game with known Id
var game = PlayniteApi.Database.Games[SomeGuidId];

Adding New Game

To add a new game create new instance of Game class and call Add method from Games collection.

var newGame = new Game("New Game");
PlayniteApi.Database.Games.Add(newGame);

Changing Game Data

Changing properties on a Game object doesn't automatically update the game in Playnite's database and changes are lost with application restart. To make permanent changes game object must be updated in database manually using Update method from Games collection.

var game = PlayniteApi.Database.Games[SomeId];
game.Name = "Changed Name";
PlayniteApi.Database.Games.Update(game);

Removing Games

To remove game from database use Remove method from Games collection.

PlayniteApi.Database.Games.Remove(SomeId);

Bulk updates

Every collection change operation (update, add, remove) generates an event that is sent to all plugins and other parts of Playnite. Therefore it's highly recommend to bulk as much changes as possible together. You can use buffer updates which collect all changes and only generate single event once you commit/end update operation.

using (PlayniteApi.Database.BufferedUpdate())
{
    // Any collection changes here don't generate any events
}
// Single event is sent here for all changes made in previous using block

Handling reference fields

Some fields are only stored as references in Game object and can't be directly updated. For example Series field is a reference via SeriesId property, you can't directly assign new value to Series property (it can be only used to obtain referenced series object).

Updating references

Every reference field has it's own collection accessible in Database API object. For example all series can be accessed via Series collection.

If you want to change name of the series then you will need to do it by updating series item from Series collection. The change will be automatically propagated to all games using that series. All field collections are implemented via IItemCollection meaning that the update is done via the same process like updating general game information via Update method on the specific collection.

Adding references

To assign completely new series to a game:

  • Add new series into Series database collection.
  • Assign ID of newly added series to the game via SeriesId property.
  • Call Update on Games collection to update new SeriesId in database.

Some fields allow you to assign more items to a game. For example you can assign multiple tags to a game. In that case you need to assign List of IDs to TagIds property.

Handling data changes

Collections from IDatabaseAPI provide ItemCollectionChanged and ItemUpdated events which you can use to react to data changes in the game library.

PlayniteApi.Database.Games.ItemCollectionChanged += (_, args) =>
{
    PlayniteApi.Dialogs.ShowMessage(args.AddedItems.Count + " items added into the library.");
};

If you want to specifically execute code after game library update (automatic one on startup or manual one from main menu), use OnLibraryUpdated plugin event. OnLibraryUpdated is called after all library plugins finish with their game library updates.

Handling Files

All game related image files are stored in game database itself, with only reference Id being used on the game object itself (with exception of BackgroundImage, which allows use of WEB URL as well). Following examples show how to handle game images using database API.

Exporting Game Cover

Game cover images are referenced in CoverImage property. To save a file first get the file record by calling GetFullFilePath method. GetFullFilePath returns full path to a file on the disk drive.

var game = PlayniteApi.Database.Games[SomeId];
var coverPath = PlayniteApi.Database.GetFullFilePath(game.CoverImage);

Changing Cover Image

Changing cover image involves several steps. First remove original image by calling RemoveFile method. Then add new image file to a database using AddFile. And lastly assign Id of new image to a game.

Following example changes cover image of first game in database:

var game = PlayniteApi.Database.Games[SomeId];
PlayniteApi.Database.RemoveFile(game.CoverImage);
game.CoverImage = PlayniteApi.Database.AddFile(@"c:\file.png", game.Id);
PlayniteApi.Database.Games.Update(game);
Edit this page