SimplePlugins¶

Create simple minecraft mods (Plugins) without setting up a complete forge development environment.

Usage¶

Clone the blueprint repo version matching the version of SimplePlugins you want to use or download the .zip-Archive of it and extract it (You can rename the directory containing the extracted files to anything you want). The link to the correct blueprint version and the download of the .zip-Archive can be found alongside every release of SimplePlugins.

Inside the directory, run gradlew setupDecompWorkspace to initialize forge. Then, depending on the IDE you use, run gradlew eclipse or gradlew idea genIntellijRuns.

You can now begin creating your plugin:

Adjust the build.gradle (group and archiveBaseName ) to your needs.
Either delete and start from scratch or rename the default plugin class
Enter the name into the manifest attributes

Look at the documentation to get an idea of how achieve certain things.

Bug Reports¶

Please report any and all issues you encounter while using this mod on the issue tracker. It is important to include the SimplePlugins, Minecraft and Forge version you are using, in your reports/ideas/suggestions.

Documentation¶

Many things are already documented right in the source code and the javadoc. For all other things and further research, the documentation of SimplePlugins is available at https://simpleplugins.readthedocs.io/en/latest.

Development¶

Help with the development is highly appreciated, e. g. pull requests, writing missing documentation or adding ideas.

SimplePlugins’s source code is hosted on GitHub at https://github.com/liketechnik/SimplePlugins.

If you want to work on SimplePlugins, clone the repository from github and initialize the forge modding environment as described above.

Versioning scheme¶

The first number stands for the minecraft version: The first version 1.x was released for MC version 1.12, so version 3.x would refer to MC Version 1.14.
The second number stands for added features: For every added feature/release, the number gets increased, i. e the current version is x.0 and a new feature is added, the new version would be x.1.
The third number gets increased for every forge update (inside one MC version).
The number after the bullet point gets increased after bugfixes.
The numbers can only increase for the same MC version, after a new MC Version, all other numbers are reset to 0

Acknowledgements¶

Thanks to the Forge project for creating a great framework for modding minecraft. Without forge, this would not be possible.

I had the idea for this mod after I met the Canary project, a framework for creating server side plugins for minecraft. Sadly, the latest version was made for the minecraft version 1.8, which was one of the reasons for me to start this project.

Documentation¶

Setup SimplePlugins¶

In this part, you will learn how to setup your plugin. When you finished the setup, you can start looking at the other parts of the tutorial and play with MC.

Setup your plugin¶

First download the blueprint .zip-Archive, which is marked with a b in front of the version, for your preferred version from the release page at github. Unpack the archive to a location where you want to work at your plugin, this place is going to be referred to as the project directory. You can rename the folder containing all the stuff to whatever you want to call your plugin.

Next head over the forge setup tutorial and step over steps 1-3, because everything is ready to start with step 4 in your project directory. After you finished step 6, your ready to start customizing your plugin.

Make it yours¶

Now you can start making your plugin truly yours:

First open the build.gradle file, this file contains information such as the name of your plugin. Change the values of the lines group and archivesBaseName to your liking (they can both have the same name), in our case this name will be demoPlugin. Then choose a name for the main class of the plugin, it is recommended to choose the same name you just used, so our main class will be called DemoPlugin. Your build.gradle file will then roughly look like this (the lines you should have changed are highlighted):

build.gradle¶

buildscript {
repositories {
    jcenter()
    maven { url = "http://files.minecraftforge.net/maven" }
}
dependencies {
    classpath 'net.minecraftforge.gradle:ForgeGradle:2.3-SNAPSHOT'
}
}
apply plugin: 'net.minecraftforge.gradle.forge'
//Only edit below this line, the above code adds and enables the necessary things for Forge to be setup.


version = "1.0"
group = "demoPlugin" // http://maven.apache.org/guides/mini/guide-naming-conventions.html
archivesBaseName = "demoPlugin"

jar {
    manifest {
        attributes(
                'Main-Class': 'DemoPlugin'
        )
    }
}

sourceCompatibility = targetCompatibility = '1.8' // Need this here so eclipse task generates correctly.
compileJava {
    sourceCompatibility = targetCompatibility = '1.8'
}

minecraft {
    version = "1.12.2-14.23.2.2618"
    runDir = "run"

    // the mappings can be changed at any time, and must be in the following format.
    // snapshot_YYYYMMDD   snapshot are built nightly.
    // stable_#            stables are built at the discretion of the MCP team.
    // Use non-default mappings at your own risk. they may not always work.
    // simply re-run your setup task after changing the mappings to update your workspace.
    mappings = "snapshot_20171003"
    // makeObfSourceJar = false // an Srg named sources jar is made by default. uncomment this to disable.
}

Then go into the src/main/java folder where all your classes will reside. It contains a default class you can rename to the class name you chose in step 1. Then open up the file and change the class name and modify the string passed to the constructor of the superclass too. (You can also edit the author and date information of the javadoc or delete it, if you want). After this, your main class should look like this (changes are highlighted again):

src/main/java/DemoPlugin.java¶

import simplePlugins.plugins.api.Plugin;

/**
* @author tutorial
* @version 1.0
* @date 18 of Februar 2018
*/
public class DemoPlugin extends Plugin {

    public DemoPlugin() {
        super("DemoPlugin");
    }
}

Now you’re ready to create your first plugin. You have multiple options what you can start with:

Create your first commands.
React to events and modify the game.

Commands with SimplePlugins¶

With commands you can make minecraft do something, everytime a player uses your command. In this part of the documentation, your are going to learn how to create commands with SimplePlugins.

Your first command¶

If you have already setup your plugin, you are ready to create your first command now. If you did not setup your plugin yet and need help with it, take a look at Setup SimplePlugins.

In this tutorial, we are going to explain the creation of the command steyp by step. In the tutorials that enlarge the topic commands, we will show you the whole command and only explain the new parts.

To begin with the creation of your command, open your plugin’s main class. Add a method starting with the name of your command and ending with Command, that return nothing and takes a simplePlugins.plugins.api.wrappers.EntityPlayerWrapper:

Javadoc¶

simplePlugins.plugins.api¶

EventListener¶

public interface EventListener¶

Author:	Florian Warzecha

Plugin¶

public abstract class Plugin¶

Author:	Florian Warzecha

Fields¶

logger¶

public Logger logger¶

Constructors¶

Plugin¶

public Plugin(String name)¶

Methods¶

getName¶

public String getName()¶

registerCommandClasses¶

public void registerCommandClasses(FMLServerStartingEvent event)¶: This is called during registration of commands. Allows the registration of own command classes via the net.minecraftforge.fml.common.event.FMLServerStartingEvent.registerServerCommand(ICommand) method.

registerEventClasses¶

public void registerEventClasses()¶: This is called during registration of events. Allows the registration of own event classes via the net.minecraftforge.fml.common.eventhandler.EventBus.register(Object) method. Call this method on the following instance: net.minecraftforge.common.MinecraftForge.EVENT_BUS

setLogger¶

public void setLogger(Logger logger)¶

simplePlugins.plugins.api.annotations¶

SimpleCommand¶

public @interface SimpleCommand¶

Author:	Florian Warzecha

simplePlugins.plugins.api.commands¶

SimpleCommand¶

public class SimpleCommand extends CommandBase¶

Author:	Florian Warzecha

Constructors¶

SimpleCommand¶

public SimpleCommand(String name, String usage, Method command, Plugin plugin)¶

Methods¶

execute¶

public void execute(MinecraftServer server, ICommandSender sender, String[] args)¶

getName¶

public String getName()¶

getPlugin¶

public Plugin getPlugin()¶

getUsage¶

public String getUsage(ICommandSender sender)¶

simplePlugins.plugins.api.events¶

EventWrapper¶

public class EventWrapper¶

Author:	Florian Warzecha

Constructors¶

EventWrapper¶

public EventWrapper(Event event)¶

Methods¶

cancel¶

public void cancel()¶

getUnwrapped¶

public Event getUnwrapped()¶

simplePlugins.plugins.api.events.entity¶

EntityEventWrapper¶

public class EntityEventWrapper extends EventWrapper ¶

Author:	Florian Warzecha

Constructors¶

EntityEventWrapper¶

public EntityEventWrapper(EntityEvent event)¶

Methods¶

getEntity¶

public EntityWrapper getEntity()¶

getUnwrapped¶

public EntityEvent getUnwrapped()¶

simplePlugins.plugins.api.events.entity.living¶

LivingEventWrapper¶

public class LivingEventWrapper extends EntityEventWrapper ¶

Author:	Florian Warzecha

Constructors¶

LivingEventWrapper¶

public LivingEventWrapper(LivingEvent event)¶

Methods¶

getEntityLiving¶

public EntityLivingBaseWrapper getEntityLiving()¶

getUnwrapped¶

public LivingEvent getUnwrapped()¶

simplePlugins.plugins.api.events.entity.player¶

PlayerEventWrapper¶

public class PlayerEventWrapper extends LivingEventWrapper ¶

Author:	Florian Warzecha

Constructors¶

PlayerEventWrapper¶

public PlayerEventWrapper(PlayerEvent event)¶

Methods¶

getEntityPlayer¶

public EntityPlayerWrapper getEntityPlayer()¶

getUnwrapped¶

public PlayerEvent getUnwrapped()¶

PlayerInteractEventWrapper¶

public class PlayerInteractEventWrapper extends PlayerEventWrapper ¶

Author:	Florian Warzecha

Fields¶

event¶

PlayerInteractEvent event¶

Constructors¶

PlayerInteractEventWrapper¶

public PlayerInteractEventWrapper(PlayerInteractEvent event)¶

Methods¶

getUnwrapped¶

public PlayerInteractEvent getUnwrapped()¶

simplePlugins.plugins.api.events.entity.player.itemUseEvent¶

ItemUseEvent¶

public class ItemUseEvent extends PlayerInteractEventWrapper ¶

Author:	Florian Warzecha

Constructors¶

ItemUseEvent¶

public ItemUseEvent(PlayerInteractEvent.RightClickItem event)¶

Methods¶

getConverter¶

public static Class<?> getConverter()¶

getUnwrapped¶

public PlayerInteractEvent.RightClickItem getUnwrapped()¶

getWorld¶

public WorldWrapper getWorld()¶

ItemUseEventConverter¶

public class ItemUseEventConverter¶

Author:	Florian Warzecha

Constructors¶

ItemUseEventConverter¶

public ItemUseEventConverter(Method eventReceiver, Plugin plugin)¶

Methods¶

onItemUse¶

public void onItemUse(PlayerInteractEvent.RightClickItem event)¶

simplePlugins.plugins.api.wrappers¶

EntityPlayerWrapper¶

public class EntityPlayerWrapper extends EntityLivingBaseWrapper ¶

Author:	Florian Warzecha

Constructors¶

EntityPlayerWrapper¶

public EntityPlayerWrapper(EntityPlayer player)¶

Methods¶

getUnwrapped¶

public EntityPlayer getUnwrapped()¶

WorldWrapper¶

public class WorldWrapper¶

Author:	Florian Warzecha

Constructors¶

WorldWrapper¶

public WorldWrapper(World world)¶

Methods¶

attemptSetBlock¶

public boolean attemptSetBlock(Block block, BlockPos pos)¶

attemptSetBlock¶

public boolean attemptSetBlock(Block block, double x, double y, double z)¶

forceSetBlock¶

public boolean forceSetBlock(Block block, BlockPos pos)¶

forceSetBlock¶

public boolean forceSetBlock(Block block, double x, double y, double z)¶

getBlockAt¶

public Block getBlockAt(BlockPos pos)¶

getBlockAt¶

public Block getBlockAt(double x, double y, double z)¶

getUnwrapped¶

public World getUnwrapped()¶

isBlockAt¶

public boolean isBlockAt(BlockPos pos)¶

isBlockAt¶

public boolean isBlockAt(double x, double y, double z)¶

removeBlockAt¶

public boolean removeBlockAt(BlockPos pos)¶

removeBlockAt¶

public boolean removeBlockAt(double x, double y, double z)¶

spawnEntity¶

public boolean spawnEntity(Entity entity, double x, double y, double z)¶

spawnEntity¶

public boolean spawnEntity(Entity entity, BlockPos pos)¶

simplePlugins.plugins.api.wrappers.entity¶

EntityLivingBaseWrapper¶

public class EntityLivingBaseWrapper extends EntityWrapper ¶

Author:	Florian Warzecha

Constructors¶

EntityLivingBaseWrapper¶

public EntityLivingBaseWrapper(EntityLivingBase entity)¶

Methods¶

addHealth¶

public void addHealth(float amount)¶

getUnwrapped¶

public EntityLivingBase getUnwrapped()¶

kill¶

public void kill()¶

EntityWrapper¶

public class EntityWrapper¶

Author:	Florian Warzecha

Constructors¶

EntityWrapper¶

public EntityWrapper(Entity entity)¶

Methods¶

forceTeleport¶

public void forceTeleport(double x, double y, double z)¶

forceTeleport¶

public void forceTeleport(BlockPos pos)¶

getUnwrapped¶

public Entity getUnwrapped()¶

getWorld¶

public WorldWrapper getWorld()¶

sendMessageTo¶

public void sendMessageTo(String message, TextFormatting color)¶

sendMessageTo¶

public void sendMessageTo(String message)¶