Third Party Extension Support in the libGDX setup

The libGDX setup includes a section for 3rd party extensions, these are extensions made by members of the community that aren’t managed by the libGDX development team. This gives users an easy way to generate projects that depend on these 3rd party extensions without having to edit build scripts themselves. (Not that that is terribly difficult).

How to get your extension in the libGDX setup

Requirements

Am I an extension?

As much as you may try… no you are not (Unless you are an advanced AI extension, in which case, citation needed), but you may be developing one!

Does your project aim to extend libGDX with a specific goal in mind?
Is your project useful to libGDX users?
Is your project well established?
Is your project being pushed to Maven central?

Congratulations! It’s an extension!

Approval

To get your beautiful extension in the setup, you must sneak past/bribe/bewitch the libGDX developers into thinking that your extension belongs in the setup. To do this, make sure:

  • Your project is open source, for security issues
  • Your project is well established
  • Your project is well maintained, (we will remove it if it becomes unsupported/not maintained!)

Extension definition

We use a simple xml file in the libGDX core repository to define external extensions.

The file can be found here

An example of this file:

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <extensions>
  3.     <extension>
  4.        <name>My Extension</name> <!-- Extension name -->
  5.        <description>What my extension does</description> <!-- Short description of your extension-->
  6.        <package>my.package.cheeky</package> <!-- Package name-->
  7.        <version>0.0.1</version>             <!-- Current release version of your extension-->
  8.        <compatibility>1.5.3</compatibility> <!-- Latest version of libGDX your extension is compatible with-->
  9.        <website>http://mywebsite.com</website>  <!-- Url of your extension, either your extension website/github-->
  10.        <gwtInherits>
  11.               <inherit>cheeky</inherit>     <!-- GWT module of your extension, for the HTML project -->
  12.        </gwtInherits>
  13.        <projects>
  14.            <core>                                 <!-- All dependencies for the core project-->
  15.                <dependency>groupId:artifactId</dependency> <!--A single dependency-->
  16.            </core>
  17.            <desktop>
  18.                <dependency>groupId:artifactId:classifier</dependency> <!--Multiple dependencies -->
  19.                <dependency>groupId:artifactIdTwo:classifierTwo</dependency> <!--Multiple dependencies -->
  20.            </desktop>                                          <!--All dependencies for the desktop project-->
  21.            <android></android>                                <!--All dependencies for the android project-->
  22.            <ios>null</ios>                                    <!--All dependencies for the ios project-->
  23.            <ios-moe>null</ios-moe>                            <!--All dependencies for the ios-moe project-->
  24.            <html>groupId:artifactIdTwo:classifierTwo</html>   <!--All dependencies for the html project-->
  25.        </projects>
  26.     </extension>
  27. </extensions>

How dependencies are declared in the extensions.xml file

Under the tag are all the libGDX supported platforms. Core/Desktop/ios/Android/HTML. In each of these project tags, you can include the dependency deceleration/s for each platform.

In the above example, there is a dependency for the core project on the artifact: groupId:artifactId This means that when the project is generated with the extension ticked, we end up with:

  1. compile "groupId:artifactId:0.0.1"

In our core project dependency section.

We also have two dependencies for the desktop platform, groupId:artifactId:classifier and groupId:artifactIdTwo:classifierTwo. This would result in:

  1. compile "groupId:artifactId:0.0.1:classifier"
  2. compile "groupId:artifactIdTwo:0.0.1:classifierTwo"

In our desktop project dependency section.

This is the same for all platorms.
A few notes:

  • If you don’t support a platform, you must put null like in the ios project above.
  • If you don’t have any extras dependencies for platform, (as they are inherited from core for example) leave the section clear, like android in the example above.
  • Html projects require the source of dependencies! Make sure you push this source artifact and declare it in the extensions.xml!

This provides all the information required to display your extension and add it to user’s projects in the setup.

You must provide all the data shown above, appended to the extensions.xml file and submit your addition as a PR.