Package de.ellpeck.rockbottom.api.mod

Interface IMod

All Known Subinterfaces:
IGameInstance
public interface IMod
This is the base interface for any mod. When creating a mod, you should have a class that implements this interface, making it automatically get loaded and initialized when the mod's compiled jar is in the mods folder.

Notice that, when a mod can be disabled (isDisableable()), the mod's main method will still be initialized, but none of its initializing lifecycle methods will be called. For this reason, you shouldn't statically initialize any of your tiles, items or functionalities outside of the designated initializing lifecycle methods.

For more information on how to create mods, check out the modding example and tutorial repository.

  • Method Details

    • getDisplayName

      String getDisplayName()
      Returns:
      The mod's display name. This is the name that will be displayed in the mods menu. It can contain spaces, capitalization and special characters.

    • getId

      String getId()
      Returns:
      The mod's unique id. It needs to be all lowercase, contain no spaces and be unique, meaning that no other mods that are currently installed are allowed to have the same id. Make sure that your mod id isn't too short or too simple, for this very reason.

    • getVersion

      String getVersion()
      Returns:
      The version of the mod. This doesn't follow any specific naming or versioning scheme, you can use any style you want. This will not be checked against anything or used in any way other than to display the version to the user as the provided string.

    • getResourceLocation

      String getResourceLocation()
      Returns the location that resources are stored in, starting in any of the root folders that are marked as source (meaning they will be at the root of the compiled mod jar). The folder specified here needs to contain an assets.json file that contains information on all of the assets that need to be loaded and used during the game.

      For example, if your directory structure is /assets/mymod/assets.json, then this method should return assets/mymod, meaning there should be no leading or trailing slash.

      Returns:
      The resource location

    • getContentLocation

      default String getContentLocation()
      Returns the location that content is stored in, starting in any of the root folder that are marked as source (meaning they will be at the root of the compiled mod jar). The folder specified here needs to contain a content.json file that contains ifnormation on all of the content (recipes, structures etc) that need to be loaded and used during the game.

      For example, if your directory structure is /assets/content/mymod/content.json, then this method should return assets/content/mymod, meaning there should be no leading or trailing slash.

      Returns:
      The content location

    • getDescription

      default String getDescription()
      Returns:
      A short description of the mod to be displayed to the user in the mods gui

    • getAuthors

      default String[] getAuthors()
      Returns:
      A list of names of the people that have worked on the mod. This list will be displayed, each entry seperated by a comma, to the user in the mods gui.

    • getSortingPriority

      default int getSortingPriority()
      Gets the priority of how to sort the mod in the list of mods, meaning this changes the order in which mods will be loaded. The higher the priority, the sooner a mod will be loaded. For instance, if there are two installed mods like mod1 with priority 1000 and mod2 with priority 2000, then the latter will be loaded first, meaning all of its initialization lifecycle methods will be called before mod1's.

      Note that Rock Bottom has a sorting priority of Integer.MAX_VALUE.

      Returns:
      The sorting priority

    • getModGuiClass

      default Class<? extends Gui> getModGuiClass()
      Gets a class that can be initialized by the mods gui to open a special new gui where the mod can have its own information or settings. This class needs to contain a constructor that takes a single Gui which acts as the parent. When this gui is initialized, it will then be passed the currently opened mods gui.
      Returns:
      A gui class

    • getModConfig

      default ModConfig getModConfig()
      Gets an optional ModConfig instance that you can use to save and load settings for your mod that the player will be able to change. The ModConfig class automatically picks a location for your settings to be, along with automatically loading them from disk before this mod's preInit(IGameInstance, IApiHandler, IEventHandler) phase. If you want to change the settings in game, say, using the getModGuiClass(), you will still have to call IJsonSettings.save() for them to be saved to file.

      Keep in mind that the config returned does actually have to be cached as a class variable for loading and saving to properly function.

      Returns:
      A config for the mod

    • isDisableable

      default boolean isDisableable()
      Return true on this method if you want your mod to be able to be disabled from the mods menu or the mod settings file. Note that disabling a mod will still make its main class (the one that extends this interface) be initialized on startup, but have none of its intializiation lifecycle events be called. For that reason, you should never initialize anything statically in your mod's main class if you return true on this method, and instead always use the initialization lifecycle events.
      Returns:
      If the mod should be disableable

    • isRequiredOnClient

      default boolean isRequiredOnClient()
      Return true on this method if you want the mod to be needed on the client when trying to join a server. If this method returns false, then the mod is serverside only, meaning that players that do not have it installed on their clients can join the server without being kicked. Note that this can cause desynchronizations and crashes with mods that add tiles or items, and this setting should only be changed if a mod does not add anything that contributes to clientside behavior.
      Returns:
      If the mod should be required on the client

    • isRequiredOnServer

      default boolean isRequiredOnServer()
      Return true on this method if you want the mod to be needed on the server when trying to join it. If this method returns false, then a player that has this mod installed can join a server without the mod on it. If this mod adds tiles or items, then they will, naturally, not be available to the player on that server.
      Returns:
      If the mod should be required on the server

    • isCompatibleWithModVersion

      default boolean isCompatibleWithModVersion(String version)
      Return something other than the default on this method if you want a client to be able to join a server (or vice versa) that has the same mod, but with a different version, installed. The parameter passed to this method is the version that the client trying to join the server has installed.
      Parameters:
      version - The version that the client has
      Returns:
      If the client version and the current version are compatible

    • receiveMessage

      default DataSet receiveMessage(IMod sender, String messageIdentifier, DataSet message)
      This method is called when another loaded mod sends a message to this mod using IModLoader.sendMessage(IMod, String, String, DataSet). You can process any type of message in this method, and return any type of response back to the mod that originally sent the message. This way of communication can be used for several things, like registering custom content to different mods, notifying mods of certain requirements or items, and so on. Messages like this can be sent at any time. Note that sending a message to a mod that isn't installed will always yield an empty response with the message simply being discarded.
      Parameters:
      sender - The mod that sent the message
      messageIdentifier - A name for the message or type of message, can be null
      message - The message data that the mod sent
      Returns:
      Some reply data, or null if there should be none

    • prePreInit

      default void prePreInit(IGameInstance game, IApiHandler apiHandler, IEventHandler eventHandler)
      This method is called before pre initialization. The base game does not initialize anything in this method.
      Parameters:
      game - The game instance
      apiHandler - The api handler instance
      eventHandler - The event handler instance

    • preInit

      default void preInit(IGameInstance game, IApiHandler apiHandler, IEventHandler eventHandler)
      This method is called as pre initialization. The base game initializes the following things in this method: All threads the game uses, the Settings (or ServerSettings on the dedicated server), the IAssetManager and the IRenderer.
      Parameters:
      game - The game instance
      apiHandler - The api handler instance
      eventHandler - The event handler instance

    • init

      default void init(IGameInstance game, IApiHandler apiHandler, IEventHandler eventHandler)
      This method is called as the main initialization phase. The base game initializes the following things in this method: The GameContent, meaning all Item, Tile, Biome and IEffect instances along with all IWorldGenerator classes.
      Parameters:
      game - The game instance
      apiHandler - The api handler instance
      eventHandler - The event handler instance

    • postInit

      default void postInit(IGameInstance game, IApiHandler apiHandler, IEventHandler eventHandler)
      This method is called after the initialization. The base game initializes the following things in this method: All TileLayer objects and their (final!) sorting, the loading of all of the IContent files from the getContentLocation(), the IChatLog, the IGuiManager, the IInteractionManager, the IParticleManager, and lastly the IToaster.
      Parameters:
      game - The game instance
      apiHandler - The api handler instance
      eventHandler - The event handler instance

    • postPostInit

      default void postPostInit(IGameInstance game, IApiHandler apiHandler, IEventHandler eventHandler)
      This method is called after post initialization. The base game initializes the following things in this method: The base game's Statistic instances and all of its Command instances.
      Parameters:
      game - The game instance
      apiHandler - The api handler instance
      eventHandler - The event handler instance

    • preInitAssets

      default void preInitAssets(IGameInstance game, IAssetManager assetManager, IApiHandler apiHandler)
      This method will not be called on the dedicated server, meaning this is the place to load and initialize assets and rendering-related operatios of any kind. This method is called before the game's IAssetManager initializes any assets, and especially before the ITextureStitcher stitches the textures into one.
      Parameters:
      game - The game instance
      assetManager - The asset manager instance
      apiHandler - The api handler instance

    • initAssets

      default void initAssets(IGameInstance game, IAssetManager assetManager, IApiHandler apiHandler)
      This method will not be called on the dedicated server, meaning this is the place to load and initialize assets and rendering-related operatios of any kind. This method is called after the game's IAssetManager initializes all of the IAsset instances from the getResourceLocation(), stitches the textures together using the ITextureStitcher and also after the game loads its own ISpecialCursor objects.
      Parameters:
      game - The game instance
      assetManager - The asset manager instance
      apiHandler - The api handler instance

    • postInitAssets

      default void postInitAssets(IGameInstance game, IAssetManager assetManager, IApiHandler apiHandler)
      This method will not be called on the dedicated server, meaning this is the place to load and initialize assets and rendering-related operatios of any kind. This method is called after all of the assets have been initialized and finalized, especially all of the fallback assets have been initialized, but before the IAssetManager gets locked, meaning assets can still be added to it at this point.
      Parameters:
      game - The game instance
      assetManager - The asset manager instance
      apiHandler - The api handler instance