How to make API for mod?

[TehStoneMan]

I was wondering how do you make an API for your mod?

 

I would like to be able to supply an API for my mod that other mod could use to supply a set of optional properties for their blocks, and to assume a set of default properties if not supplied, or for vanilla blocks.

 

Also, if possible, I would like to have these properties available for other mods that may be interested in these properties to query, without needing my mod installed, just by including the API.

 

Thank you for any help.

[jabelar]

Also I think that the API portion of your code should not be obfuscated so that means in your build you need to specify the API part. I haven't done an API in a while so can't remember the details, but there should be some tutorial out there.

 

Another tip I would give is that to make a good API you should use it yourself. For example, if your mod adds vampire mobs and you have an API for making new vampires then in your own mod whenever you want a new vampire you should invoke it through the API. This will help prevent bugs in the API (since you'll encounter any problem yourself) and will make sure it is easy to use and complete.

[Naosyth]

As for shipping it separately, that is not needed anymore. There are mechanisms in Forge that allow mods to interact with your code and not break when your mod is not there.

 

Could you please elaborate on this or link to an example of some sort?

 

Are you referring to optional annotations? If I don't ship my API separately, how would another mod go about utilizing it?

 

Thanks!

[coolAlias]

Here is some information about how others might go about using your API, whether shipped separately or included in your mod.

 

I don't think there is actually a need anymore to create a specially deobfuscated version - you should be able to simply drop the compiled .jar into your /eclipse/libs or /eclipse/mods folder, drop the source code next to it (so it's not in YOUR src folder), and then link the .jar to the .src from within your IDE.

 

If you run gradlew eclipse, it should even automatically add the dependency to your project's build path; if not, you can include it manually by configuring the build path and adding it, which lets you (or another modder) access the API class files from within your own project.

 

Also, I think Jabelar's point is worth emphasizing: use your API in your own code. If you are not using your own API, chances are either your mod design has some major issues, or your API is not worth using. Obviously this is not always the case, but it very often is.

[TehStoneMan]

An API is nothing special. It's just some part of your code that you promise to not change so that people can interact with it and their code will not break when your mod updates.

 

I'm sorry, but that still doesn't explain how to actually make one.

 

Another tip I would give is that to make a good API you should use it yourself.

 

I don't think that would be a problem. NOT using the API myself didn't even occur to me.

 

Here is some information about how others might go about using your API, whether shipped separately or included in your mod.

 

That would be should be some very useful information, too.

 

What could be good if there was an easy to follow tutorial on making a mod API.

[coolAlias]

There will not and can not ever really be a tutorial on making an API, because an API is just code, and is always specific to whatever it is designed for.

 

There is nothing special about 'making an API' - it's simply a way for other programs / mods to interact with yours, in whatever way you specify.

 

So if I want to allow other mods to add their items as weapons in my mod, I create a 'registerWeapon(Item item)' method that specifies 'if you call this method with your Item, it will for all intents and purposes be considered a weapon in my mod', whatever that is supposed to mean.

 

That's all it is, which is why there are no (or few) tutorials.

[tiffit]

Basically, people that use your API will use it the same way you use your API. You do not need to add/change anything (unless you have everything hard coded)

[TehStoneMan]

So it would simple be making a project with just my API functions, and nothing else? Any specific Minecraft / Forge specific classes I need to import, or just the ones the API uses?

[coolAlias]

Only import what you need for your code to compile.

 

You may also want to include a package-info.java file within any packages that contain API files - this is a specially formatted file that Forge / FML uses to detect packages that should be loaded first, so they are available to all mods which may need them. As such, it is important not to put any non-API files in such packages.

 

This is all the package-info.java file should contain:

@API(owner = "yourmodid", provides = "YourModAPI", apiVersion = "1.0")
package yourmod.path.to.your.api.package;

import net.minecraftforge.fml.common.API;

[Jedispencer21]

How to create the package.info file?

[shadowfacts]

It's not package.info but package-info.java.

[coolAlias]

It's not package.info but package-info.java.

Oops, so it is! Maybe I should get some reading glasses

[TehStoneMan]

After some study on this, I have come to the conclusion that an API on it's own is insufficient for what I want to do, and may need to supply an optional library to go along with it.

What would I need to do to create a library as opposed to a regular mod?

[tiffit]

After some study on this, I have come to the conclusion that an API on it's own is insufficient for what I want to do, and may need to supply an optional library to go along with it.

What would I need to do to create a library as opposed to a regular mod?

 

Same way you create a mod, except not add anything new.

[coolAlias]

After some study on this, I have come to the conclusion that an API on it's own is insufficient for what I want to do, and may need to supply an optional library to go along with it.

What would I need to do to create a library as opposed to a regular mod?

A "library" is really just a collection of classes / methods. An API can also be a collection of classes and methods, but with the intent that there are some, usually interfaces, that, if used, will provide some functionality with your mod.

 

Think of vanilla Minecraft's IInventory interface - you can trust that any class implementing that interface has inventory-like functionality, and can therefore treat any such class as an inventory. You can retrieve or set the inventory contents, etc.

 

It's a vanilla interface, but many mods use it because it implies a certain behavior. This is a type of API. Another type is the GameRegistry - you can add new Blocks and Items simply by extending the appropriate class and registering them to the GameRegistry.

 

We are able to interact with Minecraft code in many such ways - this is the whole point of an Application Programming Interface, to be able to interact with a program via our own code. That's all it is.

 

Whether you call it a library, an API, or anything else is really kind of irrelevant; what matters is how you intend whatever code you write to interact with others' code, and that should determine how you design it.

 

Again, there is nothing special about it - you just write code and provide that to others with it stating "These classes / methods are part of my API which you can use to interact with X, Y, and Z when used in combination with my mod."