An experimental version of AndModPlug for libgdx - GdxModPlug??
This is an example of using my tracker music player code with libgdx.
AndModPlug is a package intended to interface Android Java games/apps with the MOD/XM "tracker" music player libmodplug. This modified version here expands on that to add support for libgdx's desktop projects on Windows, Linux, and Mac computers.
libmodplug itself was originally created by Olivier Lapicque and now maintained by a team of tracker music enthusiast coders.
libmodplug is public domain. My Java & JNI code to interface with it is not public domain, however. But don't worry, you can do whatever you want with it, modify it, use it in paid apps or games, anything really.
I just ask that you give me a mention in your app/game's credits or on your website or a similar place.
The Java & JNI code consists of only three files: PlayerThread.java, MODResourcePlayer.java and jni_stubs.cpp. Log.java is also included, but is just a simple class to mimic Android's Log output using standard Java System.out calls
Note that the name AndModPlug comes from a combination of Android & libmodplug. However with this experimental code created to work with libgdx, perhaps I should name it GdxModPlug or something, which is what I've tentatively done below.
See below to find zip archives of the ModPlug-for-libgdx javadocs and a simple example libgdx project 'dropmodplug'.
How to use AndModPlug with libgdx
AndModPlug for use with libgdx currently consists of a jar file with the Java classes and a few native libraries (compiled C++ code) for each platform:
Note that the armeabi, armeabi-v7a, and x86 versions of the library have the same name, but are unique builds of the library.
Windows: libmodplug.dll, libmodplug64.dll
Linux: libmodplug.so, libmodplug64.so
OSX: libmodplug.jnilib, libmodplug64.jnilib
These haven't been tested since I don't have a Mac. Hopefully, they work since libmodplug is fairly portable across platforms.
iOS??: I'm not an expert in library formats, but since iOS devices are ARM-based, perhaps the same Android native libraries will work on iOS. Especially since they don't use any platform specific APIs. It's worth a try at least. Try them with the standard 'libmodplug.so' names and/or rename them to 'libmodplug.jnilib' (since OSX uses the .jnilib extension, so maybe iOS would, too?)
The above desktop libraries with 64 in the name are the 64bit complements to the 32bit libraries. The Java classes MODResourcePlayer & PlayerThread automatically load the correct library by detecting the system they are running on at startup time.
How to use this example project
First, use the new gdx-setup.jar tool to make a project called dropmodplug.
Fill in the fields like this:
Game class: DropModplug
Destination: [anywhere you like] since we'll import it into Eclipse, etc. afterwards.
Android SDK: [point to where your Android SDK is installed] or uncheck the Android Sub Project box to just play around with a desktop build.
Sub Projects: check Desktop, and Android (my modplug code currently only supports those two)
Extensions: uncheck all the boxes since we don't need any of them for this simple example game.
Click the "Advanced" button and check Eclipse so that it makes an Eclipse compatible project. The other IDEs will likely also work, but may take some tinkering.
Then click "Generate" button and wait a bit.
Importing into Eclipse
NOTE: with this example project below, you likely cannot simply import it into Eclipse until I figure out how to deliver it cleanly integrated with Gradle. For now, make a new project as described above, import THAT project and modify it with the JAR, native libraries and classes from the example project downloadable below.
Click File->Import then select General and Existing Projects into Workspace and the Next button.
For "Select Root Directory" click the Browse button and navigate to the directory you selected above (the Destination line in the
Then make sure all three sub-projects show up and are checked (dropmodplug-android, dropmodplug-core and dropmodplug-desktop) and check the "Copy projects into workspace" box and then click Finish.
After downloading and uncompressing the example project archive, you can use your OS UI to copy the src, libs, assets, etc. folders from the example project and then paste them over top the project in your workspace to merge the extra stuff included here, e.g. the actual DropModplug class in dropmodplug-core, the compiled libraries (.so, .dll, etc.) in dropmodplug-desktop/libs, etc.
Then Refresh the projects and subdirectories, and Clean the projects.
You'll also need to add the gdxmodplug JAR library to the dropmodplug-core and dropmodplug-android by right-clicking them, selecting Properties, Java Build Path, the Libraries tab and Add JAR, navigate to dropmodplug-core/libs and select gdxmodplug-0.1.1.jar. Then in the Order and Export tab, check the box to export gdxmodplug-0.1.1.jar. Do this for both dropmodplug-core and dropmodplug-android and note that for dropmodplug-android, you'll actually be pointing to the jar in dropmodplug-core/libs
Finally, you'll want to make a run configuration to run the desktop project (refer to the images below). Click the Run Configurations menu (in Eclipse, the drop-down menu from the triangle next to the Green-Circle-Play-Button looking icon). Select Run Configurations, Java Application, then click the new button (the page with a +), give it a name like run_dropmodplug-desktop, in the Main Class text box type main and then click the Search button and select "DesktopLauncher - com.example.dropmodplug.desktop" and Apply the changes.
Then click the Arguments tab and put:
in the VM arguments area.
For Working Directory, select Other, click the Workspace button, and navigate to dropmodplug-android/assets. Apply this and Run it.
After doing this, from now on you can just click the dropmodplug-desktop project and hit Ctrl-F11 to run the desktop project game.
See the run_conf_main.png and run_conf_args.png images for a picture of how to setup the run configuration described above.
Anyway, hopefully this code is useful to people!
Below are three zip archives:
If you find the code useful in your projects and would like to say thanks you can donate a few dollars.
Buy one of my games!
If you just download the gdxmodplug-0.1.1.zip instead of the example project (dropmodplug), read on for a bit of explanation about where things go so you can add the JAR and libraries to your own project.
libgdx games generally have a base project (now called 'core') and then additional projects for each platform. The example code in this archive has a modified version of the well-known "Drop" example game, where you catch raindrops in a bucket.
I've modified the game, however, by removing the background sound and replacing it with an xm tracker song (from my Android game, Microchip Monsters) to demonstrate using AndModPlug in a libgdx game.
So where to put the libraries?
I'm a libgdx newbie, but here's what I've found works:
That's pretty much it!
Eclipse can be finicky - you may have to Clean the projects or refresh them with F5 to have all changes picked up.
AndModPlug is meant for single use in an app or game, so you currently
cannot use more than one instance to play two or more MOD songs at
once. I hope to remove this limitation in the future.
Also a WARNING ABOUT LINUX MACHINES and libgdx's AudioDevice (which AndModPlug uses). I fought for a couple of days trying to figure out
why the songs played badly when I booted my PC in Ubuntu Linux and tried dropmodplug.
Eventually I found this libgdx issue:
that details the fact that OpenAL on Linux is non-optimal, so you effectively can't use CD quality playback rates (44100KHz) under Linux (or perhaps it depends on the machine's specs?). At any rate, it doesn't run well on my old notebook computer running Ubuntu, so in the example project, in dropmodplug-core's DropModplug class, you'll see comments about how I have to lower the rate for Linux. There's code in place to detect Linux and lower the rate from 44100Hz (which is fine for Android/Windows) to 16000Hz for Linux...
A fellow modplug enthusiast did some research and got in touch with this very useful info:
"I ... found out that you can change the LwjglApplicationConfiguration config -file's audio parameters in DesktopLauncher.java. By adding these parameter changes
before launching your core application, the issue seems to be gone! [One] can play music just fine with low CPU usage and 44100 playback rate."
Which seems like a fantastic solution to the linux problem!
AndModPlug works pretty well. I've used it in three Android games so far and a few other apps.
This "gdxmodplug" port is experimental, but should actually work pretty well also. The compiled library in particular is pretty solid.
I DID see that in the Android app for this example 'DropModplug' game, the Android system complained about text blocks or something in the library. I'll look into this in the future.