diff --git a/doc/changelog.md b/doc/changelog.md index 04b903ce4..a1dee4fc4 100644 --- a/doc/changelog.md +++ b/doc/changelog.md @@ -18,19 +18,19 @@ #### 5.3.0 * **Breaking Changes**: - * Playnite will no longer load plugins that reference non-SDK Playnite assemblies. See [this page](tutorials/plugins/plugins.md#referencing-playnite-assemblies) for more information. + * Playnite will no longer load plugins that reference non-SDK Playnite assemblies. See [this page](tutorials/extensions/plugins.md#referencing-playnite-assemblies) for more information. * Playnite will no longer install extensions and themes that don't have proper version specified. The version string must a valid [.NET version string](https://docs.microsoft.com/en-us/dotnet/api/system.version)! * **Now obsolete**: * These changes do not break compatibility in current version (mentioned methods are still available in SDK), but they will be made breaking in future major Playnite updates. - * Added `Id` to extension and theme [manifests](tutorials/extensionsManifest.md). This field is currently not mandatory for existing extensions (Playnite 8 will load installed extensions without an ID, but will not install new ones without an ID), but should be provided for better extension installation and update support. Toolbox will not pack new extensions unless `Id` is present. - * The way custom menu items are implemented (for main menu and game menu) has been completely changed (the old system still works temporarily). See [related documentation page](tutorials/menus.md) for more information. + * Added `Id` to extension and theme [manifests](tutorials/extensions/extensionsManifest.md). This field is currently not mandatory for existing extensions (Playnite 8 will load installed extensions without an ID, but will not install new ones without an ID), but should be provided for better extension installation and update support. Toolbox will not pack new extensions unless `Id` is present. + * The way custom menu items are implemented (for main menu and game menu) has been completely changed (the old system still works temporarily). See [related documentation page](tutorials/extensions/menus.md) for more information. * [NavigationChanged](xref:Playnite.SDK.IWebView) from IWebView is now obsolete, use new `LoadingChanged` instead. * New * Metadata plugins can now provide `Features`, `AgeRating`, `Series`, `Region` and `Platform` data. - * Extensions can now provide [custom menu items](tutorials/menus.md) for game menus, including nested entries. + * Extensions can now provide [custom menu items](tutorials/extensions/menus.md) for game menus, including nested entries. * Most useful Playnite settings are now exposed in [IPlayniteSettingsAPI](xref:Playnite.SDK.IPlayniteSettingsAPI). * [ActivateGlobalProgress](xref:Playnite.SDK.IDialogsFactory) method to show blocking progress dialog. * [LoadingChanged](xref:Playnite.SDK.IWebView) event for WebViews. @@ -44,11 +44,11 @@ * [Toolbox](tutorials/toolbox.md) utility has been reworked and accepts different arguments then previously. * New - * Library plugins can now support extra [capabilities](tutorials/plugins/libraryPlugins.md#capabilities). + * Library plugins can now support extra [capabilities](tutorials/extensions/libraryPlugins.md#capabilities). * Added [ImportGame](xref:Playnite.SDK.IGameDatabase.ImportGame(Playnite.SDK.Models.GameInfo)) methods to more easily add new games to the library. * Added [OpenPluginSettings](xref:Playnite.SDK.IMainViewAPI.OpenPluginSettings(System.Guid)) method to open view with extension settings (also accessible via `OpenSettingsView` method inherited from `Plugin` class). * Added [StartGame](xref:Playnite.SDK.IPlayniteAPI.StartGame(System.Guid)). - * Added [UriHandler](xref:Playnite.SDK.IPlayniteAPI.UriHandler) for registering of custom [URI method actions](tutorials/plugins/uriSupport.md). + * Added [UriHandler](xref:Playnite.SDK.IPlayniteAPI.UriHandler) for registering of custom [URI method actions](tutorials/extensions/uriSupport.md). * Added option settings when creating offscreen web view (currently only option to disable JavaScript execution). * Added `OnGameSelected`, `OnApplicationStopped` and `OnLibraryUpdated` events. * Added `Features` game field and appropriate support for it in metadata plugins. @@ -58,7 +58,7 @@ #### 5.1.0 * New - * Added support for creating metadata providers via [plugins](tutorials/plugins/metadataPlugins.md). + * Added support for creating metadata providers via [plugins](tutorials/extensions/metadataPlugins.md). * [ChooseImageFile](xref:Playnite.SDK.IDialogsFactory) method for dialogs API. **Only available in Desktop mode.** * [ChooseItemWithSearch](xref:Playnite.SDK.IDialogsFactory) method for dialogs API. **Only available in Desktop mode.** @@ -87,14 +87,14 @@ * **Breaking Changes**: * In order to unify terminology used in Playnite's UI and that in SDK, some classes and class members were renamed. - * Extensions (both plugins and scripts) have to provide [extension manifest](tutorials/extensionsManifest.md) otherwise they won't be loaded. + * Extensions (both plugins and scripts) have to provide [extension manifest](tutorials/extensions/extensionsManifest.md) otherwise they won't be loaded. * Various information about extension (author, version etc.) must be now stored in manifest file. * Both plugins and scripts have to be stored in the same folder called `Extensions` (rather then in separate `Plugins` or `Scripts` folders). * Signature for default C# plugins has changed and they now have to implement `IGenericPlugin` interface to be loaded. * New Plugin types. There are now two types of plugins that can be implemented: * Generic Plugin: Same as the old plugins. - * [Library Plugin](tutorials/plugins/libraryPlugins.md): Used to add new library providers responsible for automatic game import from various sources. + * [Library Plugin](tutorials/extensions/libraryPlugins.md): Used to add new library providers responsible for automatic game import from various sources. * All existing supported library importers (Steam, GOG etc.) are now distributed as [library plugins](https://github.com/JosefNemec/Playnite/tree/master/source/Plugins). * New APIs: @@ -115,5 +115,5 @@ #### 1.1.0 * **Breaking Change**: Scripts and Plugins must be place in subfolders rather then directly inside of `Scripts` or `Plugins` folders. -* New: `OnGameStarting` event that will execute before game is started. See [events](tutorials/scripts/scriptingEvents.md) for use from scripts. +* New: `OnGameStarting` event that will execute before game is started. See [events](tutorials/extensions/events.md) for use from scripts. * New: [ShowErrorMessage](xref:Playnite.SDK.IDialogsFactory.ShowErrorMessage(System.String,System.String)) method in `IDialogsFactory` \ No newline at end of file diff --git a/doc/tutorials/extensions/dataDirectory.md b/doc/tutorials/extensions/dataDirectory.md new file mode 100644 index 000000000..b6eed3a47 --- /dev/null +++ b/doc/tutorials/extensions/dataDirectory.md @@ -0,0 +1,16 @@ +Script data directory +===================== + +Extensions should store any generated data in a designated extension data directory instead of its installation directory, because installation directory gets purged during extension installation or update. + +Scripts +--------------------- + +To get script data directory, use `CurrentExtensionDataPath` global variable. + +To get installation directory of currently running script, use `CurrentExtensionInstallPath` global variable. + +Plugins +--------------------- + +To get the directory, call [GetPluginUserDataPath](xref:Playnite.SDK.Plugins.Plugin.GetPluginUserDataPath) method. The method returns full path designated to to a specific plugin. The same directory is used to store plugin [settings](pluginSettings.md). \ No newline at end of file diff --git a/doc/tutorials/scripts/scriptingEvents.md b/doc/tutorials/extensions/events.md similarity index 69% rename from doc/tutorials/scripts/scriptingEvents.md rename to doc/tutorials/extensions/events.md index e07cb233f..3e6e25913 100644 --- a/doc/tutorials/scripts/scriptingEvents.md +++ b/doc/tutorials/extensions/events.md @@ -4,12 +4,12 @@ Reacting to events Basics --------------------- -Playnite's API allows script to react to various events like when game is started or installed. +Playnite's API allows extensions to react to various events like when game is started or installed. Available Events --------------------- -|PowerShell Name | Python Name | Event | Passed Arguments | +|PowerShell Name / Plugin name | Python Name | Event | Passed Arguments | | - | - | - | - | | OnGameStarting | on_game_starting | Before game is started. | [Game](xref:Playnite.SDK.Models.Game) | | OnGameStarted | on_game_started | Game started running. | [Game](xref:Playnite.SDK.Models.Game) | @@ -21,6 +21,16 @@ Available Events | OnApplicationStopped | on_application_stopped | Playnite is shutting down. | None | | OnLibraryUpdated | on_library_updated | Library was updated. | None | + +Scripts +--------------------- + + + +Plugins +--------------------- + + Example - Handling start/stop events --------------------- @@ -30,6 +40,14 @@ To have a code executed on selected event define function with specific name in Following example writes name of currently playing game into a text file. +# [C#](#tab/csharp) +```csharp +public override void OnGameStarted(Game game) +{ + logger.Info($"Game started: {game.Name}"); +} +``` + # [PowerShell](#tab/tabpowershell) ```powershell function global:OnGameStarted() @@ -54,40 +72,16 @@ def on_game_started(game): This example writes name of game that stopped running and the time game was running for into a text file. -# [PowerShell](#tab/tabpowershell) -```powershell -function global:OnGameStopped() +# [C#](#tab/csharp) +```csharp +public override void OnGameStopped(Game game, double elapsedSeconds) { - param( - $game, - $elapsedSeconds - ) - - "$($game.Name) was running for $elapsedSeconds seconds" | Out-File "StoppedGame.txt" + logger.Info($"{game.Name} was running for {elapsedSeconds} seconds"); } ``` -# [IronPython](#tab/tabpython) -```python -def on_game_stopped(game, elapsed_seconds): - with open("StoppedGame.txt", "w") as text_file: - text_file.write("{0} was running for {1} seconds".format(game.Name, elapsed_seconds)) -``` -*** - -### Full File Examples - # [PowerShell](#tab/tabpowershell) ```powershell -function global:OnGameStarted() -{ - param( - $game - ) - - $game.Name | Out-File "RunningGame.txt" -} - function global:OnGameStopped() { param( @@ -101,12 +95,7 @@ function global:OnGameStopped() # [IronPython](#tab/tabpython) ```python -def on_game_started(game): - with open("RunningGame.txt", "w") as text_file: - text_file.write(game.Name) - def on_game_stopped(game, elapsed_seconds): with open("StoppedGame.txt", "w") as text_file: text_file.write("{0} was running for {1} seconds".format(game.Name, elapsed_seconds)) ``` -*** \ No newline at end of file diff --git a/doc/tutorials/expandingVariables.md b/doc/tutorials/extensions/expandingVariables.md similarity index 100% rename from doc/tutorials/expandingVariables.md rename to doc/tutorials/extensions/expandingVariables.md diff --git a/doc/tutorials/extensionsManifest.md b/doc/tutorials/extensions/extensionsManifest.md similarity index 100% rename from doc/tutorials/extensionsManifest.md rename to doc/tutorials/extensions/extensionsManifest.md diff --git a/doc/tutorials/plugins/genericPlugins.md b/doc/tutorials/extensions/genericPlugins.md similarity index 100% rename from doc/tutorials/plugins/genericPlugins.md rename to doc/tutorials/extensions/genericPlugins.md diff --git a/doc/tutorials/extensions/intro.md b/doc/tutorials/extensions/intro.md new file mode 100644 index 000000000..054100477 --- /dev/null +++ b/doc/tutorials/extensions/intro.md @@ -0,0 +1,71 @@ +# Introduction to Playnite extensions + +Basics +--------------------- + +Playnite can be extended via extensions implemented via scripts and plugins: + +- Scripts: [PowerShell](https://docs.microsoft.com/en-us/powershell/) and [IronPython](http://ironpython.net/) scripts are supported. +- Plugins: Any .NET Framework compatible language can be used (`C#`, `VB.NET`, `F#` and others). + +Extensions fall under several categories of extended functionality that are available based on selected implementation: + +| Extension | Scripts | Plugins | +| -- | :--: | :--: | +| Executable menu entry | • | • | +| Reacting to game events | • | • | +| Library importer | | • | +| Metadata provider | | • | + +- `Executable menu entry` - adds new executable menu entry under main menu's `Scripts` sub sections. +- `Reacting to game events` - executes code when various game events occurs, like when game is started or stopped for example. +- `Library importer` - provides automatic import of games from various sources. For example all currently supported external clients (Steam, GOG, Origin etc.) [are implemented](https://github.com/JosefNemec/Playnite/tree/master/source/Plugins) via this extension type. +- `Metadata provider` - provides metadata for games in Playnite. Our default metadata provider, IGDB.com, is also [implemented as a metadata plugin](https://github.com/JosefNemec/Playnite/tree/master/source/Plugins/IGDBMetadata). + +Creating Extensions +--------------------- + +It's highly recommended to use [Toolbox](../toolbox.md) utility to create new extensions. It will generate base directory structure and all files needed for you. + +### 1. Directory structure and location + +First create new extension folder inside of Playnite's `Extensions` directory. Location of `Extensions` directory differs based on Playnite's installation type: + +- Portable version: `Extensions` folder directly inside of Playnite's installation location. +- Installed version: `%AppData%\Playnite\Extensions` folder. + +> [!WARNING] +> Automatic installations and updates via `.pext` and `.pthm` files always replace the extension/theme directory completely. Meaning that any files that are not part of the installation package will be lost during installation process! It is highly recommended to store generated files in a separate extensions data folder. See [Data directories](dataDirectory.md) page to learn more about extension directories. + +### 2. Manifest file + +Every extension must provide valid [manifest file](extensionsManifest.md) in order to be recognized and loaded by Playnite. Manifest is YAML formatted file called `extension.yaml` that must be stored inside of extension directory. + +Resulting folder structure should look something like this: +``` +├──Install directory or %AppData%\Playnite +│ └── Extensions +│ └── PluginFolder +│ ├── extension.yaml +│ └── scriptFileName.py or pluginFileName.dll +``` + +See manifest file [documentation page](extensionsManifest.md) for more information about manifest contents. + +### 3. Implementing extension + +For scripts see [scripting introduction page](scripting.md). + +For plugins see [plugins introduction page](plugins.md). + +Loading extensions +--------------------- + +Extensions are loaded automatically by Playnite at every startup (unless extension is disabled via settings menu). Script can be reloaded at runtime via `Tools -> Reload Scripts` menu. Plugins can't be reloaded at runtime. + +Distribution +--------------------- + +Use [Toolbox](../toolbox.md#packing-extensions) utility to package an extension or a theme and distribute `.pext` or `.pthm` file to users. + +The best place to share extensions is official Playnite forum, specifically [extension database](https://playnite.link/forum/forum-3.html) sub-forum. \ No newline at end of file diff --git a/doc/tutorials/scripts/scriptingDatabase.md b/doc/tutorials/extensions/library.md similarity index 79% rename from doc/tutorials/scripts/scriptingDatabase.md rename to doc/tutorials/extensions/library.md index 99ac2a7fb..bfe9a518d 100644 --- a/doc/tutorials/scripts/scriptingDatabase.md +++ b/doc/tutorials/extensions/library.md @@ -1,4 +1,4 @@ -Working with Game Database +Working with game library ===================== Introduction @@ -12,19 +12,30 @@ Handling Games To get list of all games in library use [Database](xref:Playnite.SDK.IPlayniteAPI.Database) property from `IPlayniteAPI` and [Games](xref:Playnite.SDK.IGameDatabase.Games) collection. +# [C#](#tab/csharp) +```csharp +foreach (var game in PlayniteApi.Database.Games) +{ + // Do stuff with a game +} + +// Get a game with known Id +var game = $PlayniteApi.Database.Games[SomeGuidId]; +``` + # [PowerShell](#tab/tabpowershell) ```powershell # Get all games $games = $PlayniteApi.Database.Games -# Get game with known Id -$game = $PlayniteApi.Database.Games[SomeGuidId] +# Get a game with known Id +$game = $PlayniteApi.Database.Games[$SomeGuidId] ``` # [IronPython](#tab/tabpython) ```python # Get all games games = PlayniteApi.Database.Games -# Get game with known Id +# Get a game with known Id game = PlayniteApi.Database.Games[SomeGuidId] ``` *** @@ -33,6 +44,12 @@ game = PlayniteApi.Database.Games[SomeGuidId] To add a new game create new instance of [Game](xref:Playnite.SDK.Models.Game) class and call `Add` method from [Games](xref:Playnite.SDK.IGameDatabase.Games) collection. +# [C#](#tab/csharp) +```csharp +var newGame = new Game("New Game"); +PlayniteApi.Database.Games.Add(newGame); +``` + # [PowerShell](#tab/tabpowershell) ```powershell $newGame = New-Object "Playnite.SDK.Models.Game" @@ -52,9 +69,16 @@ PlayniteApi.Database.Games.Add(new_game) 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](xref:Playnite.SDK.IGameDatabase.Games) collection. +# [C#](#tab/csharp) +```csharp +var game = PlayniteApi.Database.Games[SomeId]; +game.Name = "Changed Name"; +PlayniteApi.Database.Games.Update(game); +``` + # [PowerShell](#tab/tabpowershell) ```powershell -$game = $PlayniteApi.Database.Games[SomeId] +$game = $PlayniteApi.Database.Games[$SomeId] $game.Name = "Changed Name" $PlayniteApi.Database.Games.Update($game) ``` @@ -71,16 +95,19 @@ PlayniteApi.Database.Games.Update(game) To remove game from database use `Remove` method from [Games](xref:Playnite.SDK.IGameDatabase.Games) collection. +# [C#](#tab/csharp) +```csharp +PlayniteApi.Database.Games.Remove(SomeId); +``` + # [PowerShell](#tab/tabpowershell) ```powershell -$game = $PlayniteApi.Database.Games[SomeId] -$PlayniteApi.Database.Games.Remove($game.Id) +$PlayniteApi.Database.Games.Remove($SomeId) ``` # [IronPython](#tab/tabpython) ```python -game = PlayniteApi.Database.Games[SomeId] -PlayniteApi.Database.Games.Remove(game.Id) +PlayniteApi.Database.Games.Remove(SomeId) ``` *** @@ -114,9 +141,15 @@ All game related image files are stored in game database itself, with only refer Game cover images are referenced in [CoverImage](xref:Playnite.SDK.Models.Game.CoverImage) property. To save a file first get the file record by calling [GetFullFilePath](xref:Playnite.SDK.IGameDatabaseAPI.GetFullFilePath(System.String)) method. `GetFullFilePath` returns full path to a file on the disk drive. +# [C#](#tab/csharp) +```csharp +var game = PlayniteApi.Database.Games[SomeId]; +var coverPath = PlayniteApi.Database.GetFullFilePath(game.CoverImage); +``` + # [PowerShell](#tab/tabpowershell) ```powershell -$game = $PlayniteApi.Database.Games[SomeId] +$game = $PlayniteApi.Database.Games[$SomeId] $coverPath = $PlayniteApi.Database.GetFullFilePath($game.CoverImage) ``` @@ -133,6 +166,14 @@ Changing cover image involves several steps. First remove original image by call Following example changes cover image of first game in database: +# [C#](#tab/csharp) +```csharp +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); +``` + # [PowerShell](#tab/tabpowershell) ```powershell $game = $PlayniteApi.Database.Games[SomeId] diff --git a/doc/tutorials/plugins/libraryPlugins.md b/doc/tutorials/extensions/libraryPlugins.md similarity index 100% rename from doc/tutorials/plugins/libraryPlugins.md rename to doc/tutorials/extensions/libraryPlugins.md diff --git a/doc/tutorials/logging.md b/doc/tutorials/extensions/logging.md similarity index 59% rename from doc/tutorials/logging.md rename to doc/tutorials/extensions/logging.md index 62ff94a69..1ff574352 100644 --- a/doc/tutorials/logging.md +++ b/doc/tutorials/extensions/logging.md @@ -4,31 +4,30 @@ Writing to Log Files Scripts --------------------- -To write message into Playnite's log files use `__logger` variable which profiles [ILogger](xref:Playnite.SDK.ILogger) interface. You can log messages with different severities `Error`, `Info`, `Debug` and `Warning`. +To write message into Playnite's log files use `__logger` variable which profiles [ILogger](xref:Playnite.SDK.ILogger) interface. + +Plugins +--------------------- + +Use static `GetLogger` method from [LogManager](xref:Playnite.SDK.LogManager) class, to create logger instance. + +Examples +--------------------- + +# [C#](#tab/csharp) +```csharp +var logger = LogManager.GetLogger(); +logger.Info("This is message with Info severity"); +``` # [PowerShell](#tab/tabpowershell) ```powershell $__logger.Info("This is message with Info severity") -$__logger.Error("This is message with Error severity") -$__logger.Debug("This is message with Debug severity") -$__logger.Warn("This is message with Warning severity") ``` # [IronPython](#tab/tabpython) ```python __logger.Info('This is message with Info severity') -__logger.Error('This is message with Error severity') -__logger.Debug('This is message with Debug severity') -__logger.Warn('This is message with Warning severity') ``` *** -Plugins ---------------------- - -Use static `GetLogger` method from [LogManager](xref:Playnite.SDK.LogManager) class, to create logger instance. - -```csharp -var logger = LogManager.GetLogger(); -logger.Info("This is message with Info severity"); -``` \ No newline at end of file diff --git a/doc/tutorials/menus.md b/doc/tutorials/extensions/menus.md similarity index 100% rename from doc/tutorials/menus.md rename to doc/tutorials/extensions/menus.md diff --git a/doc/tutorials/plugins/metadataPlugins.md b/doc/tutorials/extensions/metadataPlugins.md similarity index 100% rename from doc/tutorials/plugins/metadataPlugins.md rename to doc/tutorials/extensions/metadataPlugins.md diff --git a/doc/tutorials/plugins/pluginSettings.md b/doc/tutorials/extensions/pluginSettings.md similarity index 100% rename from doc/tutorials/plugins/pluginSettings.md rename to doc/tutorials/extensions/pluginSettings.md diff --git a/doc/tutorials/plugins/plugins.md b/doc/tutorials/extensions/plugins.md similarity index 90% rename from doc/tutorials/plugins/plugins.md rename to doc/tutorials/extensions/plugins.md index 387bd444e..dc0b4f8fa 100644 --- a/doc/tutorials/plugins/plugins.md +++ b/doc/tutorials/extensions/plugins.md @@ -6,14 +6,12 @@ Basics Plugins can be written in any .NET Framework compatible languages, this includes C#, VB.NET, F# and others, targeting .NET Framework 4.6. -Plugins use the same Playnite API as [scripts](../scripts/scripting.md). All available interfaces and classes are exactly the same as is their use. For those reasons this plugin documentation mainly focuses on how to compile plugins and other differences compared to scripting. For specific API use cases see [scripts](../scripts/scripting.md) documentation sections. - Plugin types --------------------- There are currently two types of plugins: -- `Generic plugins` Generic plugins offer same extensibility as scripts. You can add new entries to main menu or react to various [game events](../scripts/scriptingEvents.md). +- `Generic plugins` Generic plugins offer same extensibility as scripts. You can add new entries to main menu or react to various [game events](events.md). - `Library plugins`: Add ability to import games automatically as well as methods for metadata download for those games. diff --git a/doc/tutorials/scripts/scripting.md b/doc/tutorials/extensions/scripting.md similarity index 100% rename from doc/tutorials/scripts/scripting.md rename to doc/tutorials/extensions/scripting.md diff --git a/doc/tutorials/scripts/scriptingUI.md b/doc/tutorials/extensions/ui.md similarity index 50% rename from doc/tutorials/scripts/scriptingUI.md rename to doc/tutorials/extensions/ui.md index 4c1a529fa..988797938 100644 --- a/doc/tutorials/scripts/scriptingUI.md +++ b/doc/tutorials/extensions/ui.md @@ -1,11 +1,16 @@ Interacting with Playnite's UI ===================== -### Getting List of Selected Games +Getting list of selected games +--------------------- To get list of currently selected games use `MainView` from `PlayniteApi` variable. `MainView` provides [IMainViewAPI](xref:Playnite.SDK.IMainViewAPI) interface with [SelectedGames](xref:Playnite.SDK.IMainViewAPI.SelectedGames) property returning list of all selected games. -Following example exports names of selected games to a file: +# [C#](#tab/csharp) +```csharp +var gameCount = PlayniteApi.MainView.SelectedGames.Count; +PlayniteApi.Dialogs.ShowMessage($"Selected {gameCount} games"); +``` # [PowerShell](#tab/tabpowershell) ```powershell @@ -18,4 +23,25 @@ with open("SelectedGames.txt", "w") as text_file: for game in PlayniteApi.MainView.SelectedGames: text_file.write("%s\n" % game.Name) ``` +*** + +Dialogs +--------------------- + +[IDialogsFactory](xref:Playnite.SDK.IDialogsFactory) API can be used to show various dialogs. + +# [C#](#tab/csharp) +```csharp +PlayniteApi.Dialogs.ShowMessage("Hello world!"); +``` + +# [PowerShell](#tab/tabpowershell) +```powershell +$PlayniteApi.Dialogs.ShowMessage("Hello world!") +``` + +# [IronPython](#tab/tabpython) +```python +PlayniteApi.Dialogs.ShowMessage('Hello world!') +``` *** \ No newline at end of file diff --git a/doc/tutorials/plugins/uriSupport.md b/doc/tutorials/extensions/uriSupport.md similarity index 65% rename from doc/tutorials/plugins/uriSupport.md rename to doc/tutorials/extensions/uriSupport.md index 6a2839f93..61db22e72 100644 --- a/doc/tutorials/plugins/uriSupport.md +++ b/doc/tutorials/extensions/uriSupport.md @@ -4,7 +4,7 @@ Playnite URI support Introduction --------------------- -Plugins can register custom methods to be executed when specific `playnite://` URI is opened. This can be done using `RegisterSource` method from [UriHandler](xref:Playnite.SDK.IPlayniteAPI.UriHandler) API. +Plugins (scripts are not supported) can register custom methods to be executed when specific `playnite://` URI is opened. This can be done using `RegisterSource` method from [UriHandler](xref:Playnite.SDK.IPlayniteAPI.UriHandler) API. Example --------------------- diff --git a/doc/tutorials/windows.md b/doc/tutorials/extensions/windows.md similarity index 100% rename from doc/tutorials/windows.md rename to doc/tutorials/extensions/windows.md diff --git a/doc/tutorials/intro.md b/doc/tutorials/intro.md index 4334cb7a7..5723317e7 100644 --- a/doc/tutorials/intro.md +++ b/doc/tutorials/intro.md @@ -35,11 +35,11 @@ First create new extension folder inside of Playnite's `Extensions` directory. L - Installed version: `%AppData%\Playnite\Extensions` folder. > [!WARNING] -> Automatic installations and updates via `.pext` and `.pthm` files always replace the extension/theme directory completely. Meaning that any files that are not part of the installation package will be lost during installation process! It is highly recommended to store generated files in a separate extensions data folder. See pages for [scripts](scripts/dataDirectory.md) and [plugins](plugins/dataDirectory.md) to learn more about extension data folders. +> Automatic installations and updates via `.pext` and `.pthm` files always replace the extension/theme directory completely. Meaning that any files that are not part of the installation package will be lost during installation process! It is highly recommended to store generated files in a separate extensions data folder. See [Data directories](extensions/dataDirectory.md) page to learn more about extension data folders. ### 2. Manifest file -Every extension must provide valid [manifest file](extensionsManifest.md) in order to be recognized and loaded by Playnite. Manifest is YAML formatted file called `extension.yaml` that must be stored inside of extension directory. +Every extension must provide valid [manifest file](extensions/extensionsManifest.md) in order to be recognized and loaded by Playnite. Manifest is YAML formatted file called `extension.yaml` that must be stored inside of extension directory. Resulting folder structure should look something like this: ``` @@ -50,13 +50,13 @@ Resulting folder structure should look something like this: │ └── scriptFileName.py or pluginFileName.dll ``` -See manifest file [documentation page](extensionsManifest.md) for more information about manifest contents. +See manifest file [documentation page](extensions/extensionsManifest.md) for more information about manifest contents. ### 3. Implementing extension -For scripts see [scripting introduction page](scripts/scripting.md). +For scripts see [scripting introduction page](extensions/scripting.md). -For plugins see [plugins introduction page](plugins/plugins.md). +For plugins see [plugins introduction page](extensions/plugins.md). Loading extensions --------------------- diff --git a/doc/tutorials/plugins/dataDirectory.md b/doc/tutorials/plugins/dataDirectory.md deleted file mode 100644 index e15becc79..000000000 --- a/doc/tutorials/plugins/dataDirectory.md +++ /dev/null @@ -1,9 +0,0 @@ -Plugin data directory -===================== - -Introduction ---------------------- - -Plugins should store any generated data in a designated extension data directory instead of its installation directory, because installation directory gets purged during plugin installation and update. - -To get the directory, call [GetPluginUserDataPath](xref:Playnite.SDK.Plugins.Plugin.GetPluginUserDataPath) method. The method returns full path designated to to a specific plugin. The same directory is used to store plugin [settings](pluginSettings.md). \ No newline at end of file diff --git a/doc/tutorials/scripts/dataDirectory.md b/doc/tutorials/scripts/dataDirectory.md deleted file mode 100644 index 0fddbb95c..000000000 --- a/doc/tutorials/scripts/dataDirectory.md +++ /dev/null @@ -1,11 +0,0 @@ -Script data directory -===================== - -Introduction ---------------------- - -Scripts should store any generated data in a designated extension data directory instead of its installation directory, because installation directory gets purged during plugin installation and update. - -To get script data directory, use `CurrentExtensionDataPath` global variable. - -To get installation directory of currently running script, use `CurrentExtensionInstallPath` global variable. \ No newline at end of file diff --git a/doc/tutorials/toc.yml b/doc/tutorials/toc.yml index a04d50ebc..f2e5cd5e2 100644 --- a/doc/tutorials/toc.yml +++ b/doc/tutorials/toc.yml @@ -1,51 +1,38 @@ - name: Introduction href: intro.md -- name: Toolbox utility - href: toolbox.md - -- name: Scripting +- name: Extensions items: - name: Introduction - href: scripts/scripting.md - - name: Reacting to Events - href: scripts/scriptingEvents.md - - name: Working with Game Database - href: scripts/scriptingDatabase.md - - name: UI Interaction - href: scripts/scriptingUI.md - - name: Data directory - href: scripts/dataDirectory.md - -- name: Plugins - items: - - name: Introduction - href: plugins/plugins.md - - name: Generic Plugins - href: plugins/genericPlugins.md + href: extensions/intro.md + - name: Scripts + href: extensions/scripting.md + - name: Plugins + href: extensions/plugins.md - name: Library Plugins - href: plugins/libraryPlugins.md + href: extensions/libraryPlugins.md - name: Metadata Plugins - href: plugins/metadataPlugins.md + href: extensions/metadataPlugins.md + - name: Data directories + href: extensions/dataDirectory.md + - name: Logging + href: extensions/logging.md - name: Plugin settings - href: plugins/pluginSettings.md - - name: Playnite URI support - href: plugins/uriSupport.md - - name: Data directory - href: plugins/dataDirectory.md - -- name: Various - items: - - name: Extension Manifest - href: extensionsManifest.md - - name: Custom menu items - href: menus.md - - name: Working With Dynamic Variables - href: expandingVariables.md - - name: Writing to Log Files - href: logging.md + href: extensions/pluginSettings.md + - name: Working with game library + href: extensions/library.md + - name: Events + href: extensions/events.md + - name: Menu items + href: extensions/menus.md + - name: UI Interaction + href: extensions/ui.md - name: Custom windows - href: windows.md + href: extensions/windows.md + - name: Game variables + href: extensions/expandingVariables.md + - name: Playnite URI support + href: extensions/uriSupport.md - name: Themes items: @@ -63,3 +50,6 @@ href: themes/installing.md - name: Manifest file href: themes/manifestFile.md + +- name: Toolbox utility + href: toolbox.md \ No newline at end of file