API Getting started

Getting started

This page explains the basics for making a plugin for Nature's Debris/the Modernity.

THIS PAGE IS OUTDATED!!!!!!!!!!!!!!!!!!!!!!!

Adding the API to the dependencies

TODO

Making a plugin

Making a plugin for the Modernity is a pretty simple task. Create a class that should only be loaded when the Modernity is available, and annotate it with @ModernityPlugin:

import modernity.api.plugin.ModernityPlugin;

@ModernityPlugin
public class MyModernityPlugin {
    public ModernityPlugin() {
        System.out.println( "Plugin loaded!" );
    }
}

The Modernity recognizes this class using Forge's ASM scan data and this class is loaded right before the Modernity initializes. Make sure your class is public and has a public nullary constructor (specifying no constructor will imply a public nullary constructor and will also work). Once the plugin class is loaded, an instance is created and the message "Plugin loaded!" appears in the console.

Don't try to load this class yourself when the Modernity is not installed. It will cause a crash as the @ModernityPlugin annotation is not available.

Mods can specify multiple plugin classes. Each class annotated with @ModernityPlugin is recognized and all plugins are loaded in some unspecified order.

Sided plugins

Plugins can be excluded to a single distribution (client or dedicated server). To do that, specify a side in the value of the @ModernityPlugin annotation:

import modernity.api.plugin.ModernityPlugin;

@ModernityPlugin( ModernityPlugin.Side.CLIENT )
public class MyClientOnlyModernityPlugin {
    public ModernityPlugin() {
        System.out.println( "Plugin loaded!" );
    }
}

In this case, the plugin is only loaded on the client distribution. Try to run the client and dedicated server and you will find out that the "Plugin loaded!" message is only printed on the client distribution. The following Sides are available:

• Side.COMMON causes your plugin to be loaded on both client and dedicated server. This is the default side: omitting the annotation parameter will imply this side.
• Side.CLIENT loads your plugin on the client only.
• Side.SERVER loads your plugin on the dedicated server only.

Don't just annotate your class with @OnlyIn( Dist.CLIENT ) for client-only plugins: your class will always be loaded on both sides if no Side is specified in the plugin annotation.

Making your plugin known to specific parts of the Modernity

Once you made a plugin class, there are several interfaces that your plugin class can implement to make your plugin interact with specific parts of the Modernity. Such an interface is recognized by the Modernity and plugins with that interface will be hinted by the part of the Modernity the interface belongs to.

The most common, and most important plugin interface is the ILifecycleListener interface. This interface receives loading lifecycle events of the Modernity so that plugins can safely interact with the Modernity while loading. FML loads mods off-thread, so when your mod receives a loading lifecycle update, the Modernity may or may not be in that loading phase yet. To ensure your plugin interacts correctly with the Modernity during mod loading, your plugin should implement ILifecycleListener and override one or more of its methods.

import modernity.api.plugin.ModernityPlugin;
import modernity.api.plugin.ILifecycleListener;

@ModernityPlugin
public class MyModernityPlugin implements ILifecycleListener {

    // Called once the Modernity has done loading in its bootstrap class. This callback is called first.
    @Override
    public void modernityConstruct( IModernity modernity ) {
        System.out.println( "Modernity constructed!" );
    }

    // Called once the Modernity has done loading during the FMLCommonSetupEvent. This callback is called second.
    @Override
    public void modernitySetup( IModernity modernity ) {
        System.out.println( "Modernity set up!" );
    }

    // Called once the Modernity has done loading during the FMLLoadCompleteEvent. This callback is called third.
    // At this moment, the Modernity is fully loaded.
    @Override
    public void modernityLoaded( IModernity modernity ) {
        System.out.println( "Modernity loaded!" );
    }
}

This example prints a message after each loading stage of the Modernity.

1. It will print "Modernity constructed!" once the Modernity mod was constructed and did some early loading.
2. It will print "Modernity set up!" once the Modernity did most mod loading during FMLCommonSetupEvent.
3. It will print "Modernity loaded!" once the Modernity did some late loading during FMLLoadCompleteEvent.

The IModernity instance passed to each method of ILifecycleListener is the root instance of the Modernity. The interface will provide you the necessary modules of the Modernity which you can interact with. The IModernity instance can be obtained at any time by calling IModernity.get().