This is a spongepowered.org Minecraft Server plugin which embeds an OSGi Framework (Apache Felix).
This Minecraft plugin can then (dynamically, HOT, re-*) load OSGi bundles as additional Minecraft plugins. This dynamicity is very useful particularly during development of extensions to a game which has a relatively "heavy" start-up time, incl. the typical disconnecting of game clients, and thus gives you a very quick in-game change turn around experience while coding.
Watch this early POC video on YouTube demonstrating live Minecraft mod development, and see the vorburger/HoTea project for an earlier pre-OSGi take on (and superseded by) this. Also check out the ch.vorburger.osgi.gradle companion project.
Licensed under the GNU Affero General Public License v3.0 (AGPLv3). Contributions most welcome.
Please Star & Watch this project if it's of any interest or use to you!
How to use this
git clone https://github.com/vorburger/ch.vorburger.minecraft.osgi/ cd ch.vorburger.minecraft.osgi git submodule update --init --recursive cd ch.vorburger.osgi.gradle ./gradlew install test cd .. ./gradlew install test
NB: You must use
install and not just
build (because the MinecraftOSGiTest fails otherwise).
Get a Sponge powered Minecraft server
Create a home directory for the Minecraft server, and download the matching version (see
ch.vorburger.minecraft.osgi/build.gradle) of the Sponge Vanilla JAR from spongepowered.org (e.g. spongevanilla-1.10.2-5.1.0-BETA-374.jar) into it, and try starting it once:
cd .. mkdir spongevanilla-1.10.2-5.1.0-BETA-374 cd spongevanilla-1.10.2-5.1.0-BETA-374 wget https://repo.spongepowered.org/maven/org/spongepowered/spongevanilla/1.10.2-5.1.0-BETA-374/spongevanilla-1.10.2-5.1.0-BETA-374.jar echo "eula=true" >eula.txt java -jar spongevanilla-*.jar
Install minecraft.osgi & its dependencies
We now copy the Sponge OSGi mod we just built from source above into the
mods/ directory of our Sponge Vanilla server we just set up:
cp ../ch.vorburger.minecraft.osgi/ch.vorburger.minecraft.osgi/build/libs/*.jar mods/
This mod embeds an OSGi "kernel" (framework), and you could now start your Sponge server with this mod alone - this will work, but it's not particularly interesting; it won't "do" anything, yet.
But we can now install a few OSGi mod bundles built earlier; those JARs need to be put under a (new)
osgi/boot directory (NOT
mods/), like so:
mkdir -vp osgi/boot/ cp ../ch.vorburger.minecraft.osgi/ch.vorburger.osgi.gradle/org.gradle.tooling.osgi/build/libs/*.jar osgi/boot/4_org.gradle.tooling.osgi-3.3.jar cp ../ch.vorburger.minecraft.osgi/ch.vorburger.osgi.gradle/ch.vorburger.osgi.gradle/build/libs/*.jar osgi/boot/4_ch.vorburger.osgi.gradle-1.0.0-SNAPSHOT.jar cp ../ch.vorburger.minecraft.osgi/ch.vorburger.minecraft.osgi.templates/build/libs/*.jar osgi/boot/5_ch.vorburger.minecraft.osgi.templates-1.0.0-SNAPSHOT.jar cp ../ch.vorburger.minecraft.osgi/ch.vorburger.minecraft.osgi.dev/build/libs/*.jar osgi/boot/5_ch.vorburger.minecraft.osgi.dev-1.0.0-SNAPSHOT.jar cp ../ch.vorburger.minecraft.osgi/ch.vorburger.minecraft.osgi.users/build/libs/*.jar osgi/boot/6_ch.vorburger.minecraft.osgi.users-1.0.0-SNAPSHOT.jar
Some of these bundles above have dependencies to some external 3rd party libraries, which are all valid OSGi bundles themselves, that must now ALL (!) also be installed into
wget -N http://search.maven.org/remotecontent?filepath=com/google/guava/guava/18.0/guava-18.0.jar -O osgi/boot/3_guava-18.0.jar wget -N http://search.maven.org/remotecontent?filepath=com/google/guava/guava/19.0/guava-19.0.jar -O osgi/boot/3_guava-19.0.jar wget -N http://search.maven.org/remotecontent?filepath=com/google/guava/guava/20.0/guava-20.0.jar -O osgi/boot/3_guava-20.0.jar wget -N http://search.maven.org/remotecontent?filepath=org/apache/felix/org.apache.felix.log/1.0.1/org.apache.felix.log-1.0.1.jar -O osgi/boot/1_org.apache.felix.log-1.0.1.jar wget -N http://search.maven.org/remotecontent?filepath=org/everit/osgi/org.everit.osgi.loglistener.slf4j/1.0.0/org.everit.osgi.loglistener.slf4j-1.0.0.jar -O osgi/boot/2_org.everit.osgi.loglistener.slf4j-1.0.0.jar wget -N http://search.maven.org/remotecontent?filepath=org/eclipse/xtext/org.eclipse.xtext.xbase.lib/2.10.0/org.eclipse.xtext.xbase.lib-2.10.0.jar -O osgi/boot/3_org.eclipse.xtext.xbase.lib-2.10.0.jar wget -N http://search.maven.org/remotecontent?filepath=org/eclipse/xtend/org.eclipse.xtend.lib.macro/2.10.0/org.eclipse.xtend.lib.macro-2.10.0.jar -O osgi/boot/3_org.eclipse.xtend.lib.macro-2.10.0.jar wget -N http://search.maven.org/remotecontent?filepath=org/eclipse/xtend/org.eclipse.xtend.lib/2.10.0/org.eclipse.xtend.lib-2.10.0.jar -O osgi/boot/3_org.eclipse.xtend.lib-2.10.0.jar
Note how, thanks to OSGi, we have no "classpath hell" issues - we can, easily, have several different versions of the same library, such as Guava!
Later, you can also add any other OSGi bundles into the
osgi/ directory. (Note that the numeric prefix indicates the order in which the bundles are installed and started.)
Developing OSGi bundled Minecraft mods
minecraft.osgi.users which we just installed above makes it easy to now develop your own OSGi bundled Minecraft mods:
Create a directory, where your own mods will go:
mkdir -vp dev/
Start the Sponge Vanilla server create above, and verify that there are no errors shown in the log on the console:
java -jar spongevanilla-*.jar
Connect your Minecraft client to this local server
In game, you should have just been greeted with a
HELOmessage followed by
.. will install ... This chat message is issued by
minecraft.osgi.userson join. More importantly, it has created a new development project for you under the
dev/directory (which you created above). The project is under a sub-directory with your player's Minecraft UUID.
Open this new dev project in your favourite Java IDE (like e.g. Eclipse, or IntelliJ's IDEA). Note that this project uses Gradle for dependency management, so you must have Gradle support in your IDE (e.g. the latest Eclipse version Oxygen already includes Buildship). (Gradle is also used to produced a valid OSGi MANIFEST.MF for the JAR, via BND.)
Try out the example command this project registered by typing
/hellointo the in-game chat window (it should reply with the obligatory
Hello World!). Likewise, if you bump into anything, it will say
boingin the chat.
Your mod can use the full Sponge API. But note how this OSGi-based Minecraft Mod uses an OSGi Bundle
Activator(or BP or DS), instead of the typical Sponge
@Pluginannotated class, to register its Minecraft Commands and Event Listeners. (BTW: You could, of course, make your own Mod have both a Sponge Plugin class as well as an OSGi Activator, and register the same commands and listeners in it; thus creating a JAR which could be used in both environments.)
Try changing something, say fix the chat message printed the
HelloWorldCommandclass from the (wrong)
"Hello World!"to the (correct)
"hello, world"... ;-)
Now note how, as soon as you save this changed Java source file (even if your IDE were to not have any build), a Gradle running in continous mode, launched in the Minecraft server, by the
minecraft.osgi.devplugin, will detect the change, execute a re-build, which will re-create the bundle JAR, which will get (HOT) re-loaded into OSGi! Do check out the Sponge Vanilla server console to see the log messages piped through from Gradle, and the OSGi reload notifications.
If you re-try typing
/hellonow, you'll get the changed message. This will work for ANY code changes, incl. new classes, etc.
/osgi:install <URI> command, where URI is typically a
file:/ prefixed path to an OSGi bundle JAR file, or a directory to a Gradle project, installs (and, if it's a directory, continuously builds and HOT reloads) that OSGi bundle. This lets you work with projects outside of your
osgi/installedBundles file lists all so installed bundles. What is listed here is started on server boot, after those in the
osgi/system directory. You can edit this file, and e.g. remove the example
dev/<User-UUID>/project1 from here.
When using it like this, you do not need to copy the
osgi.users (but all the other ones listed above).
ch.vorburger.minecraft.worlds are two example OSGi mods which you don't need to write your own, but can have a look at, and could also optionally install into
osgi/boot (with boot order prefix
6_...) if you like.