Permalink
Find file
54bc5ff Dec 24, 2014
18 lines (11 sloc) 2.09 KB

Spotlight: @API Annotation

So, after some recent discussions in super secret environments that even the NSA doesn't have the clearance to access, it's come to my attention that there are features added to MinecraftForge that... well, have the publicity of that movie you've never heard about from that country you've never heard of. And so, it's time to help rectify the situation! Post a link to this information wherever Minecraft mod developers hang out, so they can learn the latest, greatest way to write APIs for the mods!

The feature in question this time is the @API annotation. This nifty little annotation can be applied to a package in Scala or Java that allows you to say "hey, if this package exists, add the owning mod as a soft dependency." This is useful for mods introducing APIs as it will ensure that the mod providing the API, if present, is loaded first - this way if a mod packages an old version of the BuildCraft API, for instance but BuildCraft|Core is present with an updated version of that API, the version in BuildCraft|Core will be the one that is used (it also means that if a mod packages a newer version than the version of BuildCraft that's installed, the older one will be loaded instead).

So how do you use this wonderful annotation? Simply add a package-info.java file to your package directory (for example, src/main/java/com/minalien/mffs/api/package-info.java) and add the @API annotation to your package like so:

    @API(owner = "ModularForcefieldSystem", apiVersion = "1.0", provides = "ModularForcefieldSystem|API")
    package com.minalien.mffs.api;

    import cpw.mods.fml.common.API;

All of the fields for the API annotation are fairly self-explanatory: owner is the modid of the mod that owns the API, apiVersion is the version number of the API, and provides is the name of the API itself (this allows you to make APIs depend on other APIs, as BuildCraft does).

Once you've done this, you're done! People will be able to include your API and not worry about conflicts!