Created Hooking into MobArena (markdown)

2024-11-22 18:46:45 +01:00 · 2018-09-23 18:07:07 +02:00 · 2018-09-23 18:07:07 +02:00 · f546c1142f
commit f546c1142f
parent dcf8344efc
1 changed files with 110 additions and 0 deletions
--- a/Hooking-into-MobArena.md
+++ b/Hooking-into-MobArena.md
@ -0,0 +1,110 @@
+**On this page:**
+* [Overview](./Hooking-into-MobArena#wiki-overview)
+* [Maven setup](./Hooking-into-MobArena#wiki-maven-setup)
+* [Getting the plugin instance](./Hooking-into-MobArena#wiki-get-a-hold-of-the-plugin-instance)
+* [The Things API](./Hooking-into-MobArena#wiki-the-things-api)
+* [MobArena's custom events](./Hooking-into-MobArena#wiki-mobarena-events)
+* [The ArenaMaster](./Hooking-into-MobArena#wiki-the-arenamaster)
+
+### Overview
+
+If you are a plugin developer and want to hook into MobArena, this page has all you need to get started:
+
+- Add MobArena as a dependency to your project ([with Maven](./Hooking-into-MobArena#wiki-maven-setup))
+- Get a hold of the [plugin instance](./Hooking-into-MobArena#wiki-getting-the-plugin-instance)
+- Register parsers in the [Things API](./Hooking-into-MobArena#wiki-the-things-api)
+- Listen to MobArena's [custom events](./Hooking-into-MobArena#wiki-mobarena-events)
+
+### Maven setup
+
+There is no official Maven repository for MobArena, but you can use the excellent [JitPack](https://jitpack.io/#garbagemule/MobArena) service to get up and running anyway.
+
+In your `pom.xml`, you'll need to add the JitPack repository:
+
+    <repositories>
+      <repository>
+        <id>jitpack.io</id>
+        <url>https://jitpack.io</url>
+      </repository>
+    </repositories>
+
+Then add MobArena as a dependency:
+
+    <dependency>
+      <groupId>com.github.garbagemule</groupId>
+        <artifactId>MobArena</artifactId>
+        <version>0.103</version>
+    </dependency>
+
+You will also likely have to modify your `plugin.yml` to softdepend on MobArena:
+
+    name: BestPlugin
+    author: you
+    main: me.you.best.BestPlugin
+    version: '1.0.0'
+    api-version: 1.13
+    softdepend: [MobArena]        <-- like this
+
+### Get a hold of the plugin instance
+
+Here are the building blocks you need to get a hold of the MobArena plugin instance.
+
+    import com.garbagemule.MobArena.MobArena;
+
+    public MyPlugin extends JavaPlugin {
+         private MobArena mobarena;
+
+         @Override
+         public void onEnable() {
+             setupMobArena()
+         }
+
+         private void setupMobArena() {
+             Plugin plugin = getServer().getPluginManager().getPlugin("MobArena");
+             if (plugin == null) {
+                 // MobArena isn't loaded
+                 return;
+             }
+             this.mobarena = (MobArena) plugin;
+             // You now have a MobArena plugin instance!
+         }
+    }
+
+### The Things API
+
+MobArena has a concept of Things. A [Thing](https://github.com/garbagemule/MobArena/blob/master/src/main/java/com/garbagemule/MobArena/things/Thing.java) is something that can be given to, taken from, and/or held by a player. The operations are not mandatory, which means you can have Things that can be given to players, but not taken from them or held by them. Examples of Things are ItemStacks, commands, potion effects, and economy money.
+
+You can create your own Thing implementations and hook into the Things API by providing custom [ThingParsers](https://github.com/garbagemule/MobArena/blob/master/src/main/java/com/garbagemule/MobArena/things/ThingParser.java). If you are just providing special ItemStacks, you can hook into MobArena's own ItemStackThingParser by registering an [ItemStackParser](https://github.com/garbagemule/MobArena/blob/master/src/main/java/com/garbagemule/MobArena/things/ItemStackParser.java) instead of a full ThingParser.
+
+To register a ThingParser or ItemStackParser in MobArena, you could do something like this:
+
+        private MobArena mobarena;
+
+        private void registerParsers() {
+            ThingParser customThingParser = ...
+            ItemStackParser customItemStackParser = ...
+
+            ThingManager thingman = mobarena.getThingManager();
+            thingman.register(customThingParser);
+            thingman.register(customItemStackParser);
+        }
+
+All of MobArena's internal parsing of Things happens via the Things API, so you should be able to do just as much as MobArena itself with your own parsers. By default, MobArena's core parsers will run before yours, so it is good practice to put a prefix on your own Things.
+
+For an example of a plugin that hooks into MobArena's Things API, check out [Magic](https://github.com/elBukkit/MagicPlugin/tree/master/Magic/src/main/java/com/elmakers/mine/bukkit/integration/mobarena) by NathanWolf.
+
+### MobArena events
+
+If you want to listen to stuff that happens in MobArena, you can listen for MobArena's custom events. You can find a list of all of MobArena's custom events in the `events` package: [com.garbagemule.MobArena.events](https://github.com/garbagemule/MobArena/tree/master/src/main/java/com/garbagemule/MobArena/events)
+
+The events should be self-explanatory, but feel free to hop on Discord if you need a rundown of what they do and when they're fired. You can also check the ArenaImpl, ArenaListener, and MASpawnThread classes, which are where most of the events are fired from.
+
+### The ArenaMaster
+
+Most of MobArena's internals can be reached via the ArenaMaster instance that you can get by calling `getArenaMaster()` on the plugin instance. It has various methods for accessing:
+
+- MobArena's global messenger instance
+- Arenas and arena classes
+- Players in MobArena arenas
+
+Since a lot of the ArenaMaster, Arena, and ArenaClass methods are being replaced, removed, or rewritten, it is pretty gnarly territory at the moment. Please hop on Discord for a chat about what you're trying to do before you get too far into it. Perhaps the rewrites can accommodate your specific needs :)