Scripting for Kodi Game addons

This project supports Team-Kodi members in maintaining the game add-ons for Libretro game and emulator cores as used by Kodi's RetroPlayer.

While the direct support of Libretro cores in RetroPlayer offers access to a multitude of platforms and games, it's cumbersome to maintain because every Libretro core needs to be built and packaged as a Kodi binary add-on. This project tries to add some scripting to simplify the maintenance efforts.

How does it work

The Kodi game add-ons that wrap Libretro cores are all very similar in the way they are built and in the way the metadata (such as name, version or description or version) is maintained.

kodi-game-scripting maintains a set of Jinja2 templates from which we can completely generate an add-on that wraps a Libretro core. The templates define the overall structure of the add-on files and fill variable fields with content from a set of metadata (descriptions from libretro-super, the compiled Libretro core, and the current version of already existing files).

Additionally to the generation steps, kodi-game-scripting automates dealing with Git(Hub) repos (creating, cloning, pulling, committing, pushing) and also generates overview pages that can be used to fill for example Kodi Wiki - Game_add-ons.

Use-cases

This project was designed to support the following use-cases:

Fully automatic updates of build and add-on files (e.g. unify CMakeLists.txt, version numbers in addon.xml).
Support manual work (e.g. automatic pushing after adding images to a set of add-ons).
Create new add-ons for missing Libretro cores (as explained in this forum post).
Simplify creating test builds for a given set of add-ons.
Generate Kodi Wiki - Game_add-ons.

Dependencies and installation

First of all you'll need the Kodi sources checked out to a local directory.

To compile the add-ons, you will need CMake >= 3.6.

kodi-game-scripting runs on Linux (and macOS with the constraint that not all add-ons compile on macOS) and requires Python 3.

Additionally you will need the following Python packages:

gitpython
jinja2
keyring
PyGithub>=1.43.2
xmljson

On Ubuntu, these can be installed using:

sudo apt-get install python3-pip
sudo pip3 install -r requirements.txt

In addition you can also install the script through its setup.py. The most convenient way is a development installation that even let's you modify the files in this repo. Note that the script is then executed with the globally available process_game_addons.py:

sudo pip3 install -e .

The script will ask you for GitHub credentials as GitHub API calls are limited when unauthorized. For pushing changes or creating new Repos, you need to have write access to https://github.com/kodi-game/.

Usage

The most typical use case is to generate updates for all cores. WORKING_D:

./process_game_addons.py --game-addons-dir=working_directory \
                         --kodi-source-dir=<KODI_SOURCE_DIR> \
                         --git --compile

--git activates Git usage (and clones and resets add-on directories in the given WORKING_DIRECTORY.
--compile compiles the add-ons (as some of the information such as version or supported extensions can only be retrieved from a compiled add-on binary). As the compilation takes a lot of time it's recommended to first compile the add-ons and then push the changes in a second step.
--filter allows to filter the add-ons (e.g. --filter=bnes).

Once the generation is done the script creates a summary html page in working_directory/summary.html. This shows an overview of all add-ons and also shows a diff of changes to their upstream versions.

The changed add-on files can now be pushed to GitHub:

./process_game_addons.py --game-addons-dir=working_directory \
                         --kodi-source-dir=<KODI_SOURCE_DIR> \
                         --git --push-branch=master

--push-branch <BRANCH> pushes the generated add-on files to the given BRANCH in kodi-game.

It's also possible to push changes to a separate branch and update the add-on description files as well that are required for compiling the add-ons as part of Kodi. This allows to easily trigger a test-build with modified add-ons.

./process_game_addons.py --game-addons-dir=working_directory \
                         --kodi-source-dir=<KODI_SOURCE_DIR> \
                         --git --push-branch=testing \
                         --push-description --clean-description

--push-description pushes the add-on description files to the existing remote origin of the local KODI_SOURCE_DIR.
--clean-description removes other existing add-on description files.

The script can also be used to create the add-on files for currently missing Libretro cores. First update kodi-game-scripting/config.py, and then run:

./process_game_addons.py --game-addons-dir=working_directory \
                         --kodi-source-dir=<KODI_SOURCE_DIR> \
                         --git --compile --filter=<NEWCORE>

Then once the compilation succeeded and you have verified the results in working_directory/summary.html, run the following command to push the add-on files and build descriptions:

./process_game_addons.py --game-addons-dir=working_directory \
                         --kodi-source-dir=<KODI_SOURCE_DIR> \
                         --git --filter=<NEWCORE> \
                         --push-branch=master --push-description

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

kodi-game / kodi-game-scripting