Kodi Documentation 22.0
Kodi is an open source media player and entertainment hub.
No Matches
Game Controller

Used to display a game controller, with optional effects.

The game controller control is used for displaying a game controller, such as joysticks, keyboards, mice, lightguns, etc.

In v21 Omega, the control was expanded to give skinners more control over how it behaves, including manually specifying a controller to show, allowing for a fallback image, and applying a highlighting diffuse effect when the underlying controller is active.


<control type="gamecontroller">
<description>My first game controller</description>
const char const uint8_t size_t unsigned int unsigned int * height
Definition kodi-dev-kit/include/kodi/c-api/addon-instance/imagedecoder.h:417
const char const uint8_t size_t unsigned int * width
Definition kodi-dev-kit/include/kodi/c-api/addon-instance/imagedecoder.h:416

Available tags

The default control tags are applicable to this control. Note that each tag is lower case only. This is important, as xml tags are case-sensitive.

In v21 and above, the control derives from an Image Control to allow for a fallback texture. All tags and attributes for images can be used, and any game-specific tags will cause the texture to be overridden.

The game-specific tags added in v21 are:

Tag Description
controllerid The add-on ID of the controller profile to render, e.g. game.controller.snes.
controllerdiffuse A diffuse color used to highlight the controller when activity is detected on the in-game port or on the underlying peripheral held by the user.
controlleraddress The in-game "address" of the controller, e.g. /1/game.controller.snes for a SNES controller connected to console port 1. Used to highlight the controller on port activity. Overrides <controllerid> and <portaddress>.
portaddress The in-game "address" of the port the controller is connected to, e.g. /1 for port 1 of a SNES emulator. Used to highlight the controller on port activity.
peripherallocation The location of the underlying peripheral providing input, e.g. /joystick/0 for the first physical controller held by the user. Used to hightlight the controller on peripheral activity.
v21 Skinning engine changes
The control has been greatly expanded to allow for more use cases in the new Player Viewer (GameAgents) dialog.

Controller address

The controller address is connected to the in-game input. It's formed by the emulated console's port, followed by the controller ID.

For example, on SNES controllers, the address of the first port is /1. The address of a SNES controller connected to that port is /1/game.controller.snes.

Old consoles used multitaps (controller hubs) to allow for more players than console ports. A multitap connected to port /2 would have the address /2/game.controller.snes.multitap.

A SNES controller connected to port 1 on a multitap would then have the address /2/game.controller.snes.multitap/1/game.controller.snes.

Peripheral location

Peripherals are located by their driver and peripheral index. For example, the first controller connected via the peripheral.joystick add-on (joystick driver) would be /joystick/0.

List item info

List item info can be used for all tag values. For example, if the control defintion looks like:

<itemlayout width="96" height="96">
<control type="gamecontroller">

Static list items can be provided and each control will inherit the properties:

<property name="controllerid">game.controller.snes</property>
enum const char * name
Definition addon_base.h:203

The in-game dialogs that highlight game controllers on button presses (GamePorts and GameAgents) use a similar strategy with list items populated by core.

See also