nwnx_jvm - native JVM integration

[elven]

Hi,

another side project of mine for those looking to embed java directly in nwserver. Anyone wanting to give it a try is welcome to do so.

It provides the usual goodies:
- direct NWScript->JVM event calls
- direct NWScript calls from inside the JVM (benchmarked to be around the many millions per second, virtually the same as native nwscript)
- all features and libraries available for the JVM

Note: This is beta and there are a few things left to do to get it production-ready - though I have OSGi R4 running quite successfully on it.

This not implemented yet (due to lack of time and nothing else):
* transparent configuration of which NW* classes to use
* common NWN constants as enum types to tighten up the API
* a great README

Quickstart:
- put the .so in your nwserver directory
- you need to prefix LD_LIBRARY_PATH=/path/to/libjvm.so to your nwserver start script, where the LD_PRELOAD to nwnx2.so is too.
- Note: do NOT use openoverride.so together with nwnx_jvm.
- edit nwnx2.ini to include the given example file
- include the provided .jar file in your classpath (see nwnx2.ini)
- write some code, compile it, put it in your class path and set your init/event/token listeners in nwnx2.ini accordingly, or use the included TestRunner class to see things in action.
- Note: a sample tokenlistener is shipped with the bundled .jar file, you do not need to implement it yourself.
- Also, there are example .java source files in the same directory which outline the API required.
- Add inc_jvm.nss to your module, and place some JVM_EVENT("name") in event scripts throughout your module. Each call done such will yield context do nwnx_jvm (and call event(..) in your configured eventListener).
- add jvm_token.nss to your module and compile it. It is used to change OBJECT_SELF for Assign*() and does not otherwise need configuring or tweaking by you.

Other pointers:
- AssignCommand() is not implemented natively; instead, a round-trip is made to nwscript to change OBJECT_SELF and a stored anonymous function is executed, containing your code. The provided org.nwnx.nwnx2.jvm.Scheduler class has helpers to do that for you (Yes, Java is missing closures ..). This can be hidden inside a more abstract API later on, though. The scheduler is intelligent enough to group assigns per object and execute them all at once.

[PlasmaJohn]

... as if I already didn't have enough toys to play with ...

[elven]

The cool thing is, with OSGi and your module code properly encapsulated, you can load/unload modules runtime and on-the-fly without effecting other systems. With some cool sco/rco wrapping (and resman, and nwnx_areas), you can even embed related resource files inside OSGi bundles instead of having them in the module itself.
And embed a webserver that displays a live map with players, or a chat-interface, or a place to organise ingame events. Or a RMI graphical interface that can directly inspect and invoke methods on ingame objects. Or anything, really. :)

[elven]

The sources are available in svn.

You will need ruby1.8.x, a recent JDK, and a recent NWNX2 svn to build. You will also tweak the Makefile for your JVM pathes - I can't be bothered to wrestle with autoconf and integrate properly.

[elven]

New Features:

- renamed to nwnx_jvm
- added wrappers for getFirst/getNext stuff, do not export those anymore
- simple TestRunner class to test nwnx_jvm without having to write some code
- various bugfixes
- updated first post

[elven]

Updates! Again!

- fix not having nwn context in NWObject.apply() while yielding a event to the JVM
- fix TestRunner having no .class file
- NWLocation NWVector are case classes with final local fields now (= .equals works)
- a handler in NWObject that can be used to register own classes to map NWObjects onto a object hierarchy (this will be documented in detail later on)

Please note that the last item requires you to call NWObject.registerDefaultHandler(); in your eventHandler init() method or it will throw an Exception "can't find object class" or some such. I have updated the example code to reflect this.

[elven]

Bugfixes:

- all iterator-collector functions now work as advertised (GetPCs, GetObjectsInArea, etc)
- NWObject.oid is now a int instead of long
- NWObject now case class (overrides equals to match oid() == oid())
- NWEffect/NWItemProperty should not mismatch anymore
- JNI exceptions are more verbose in their error text

Changed files at the usual location: the .so, the .jar

[elven]

Changes:

- iterator-collectors are now more efficient
- the .jar now contains pre-generated class files for all constants, grouped by prefix.

.so and .jar updated.

[elven]

- removed getModule; use NWObject.MODULE instead (faster)
- added NWObject.INVALID constant
- Scheduler.delay() now takes a long in milliseconds, as does NWObject.delay()
- NWScript and Scheduler are now singletons

Updated files: jar, .so

[elven]

- fixed jarfile packaging
- don't export badBadReplaceMeThisDoesNothing()
- re-add @Override annots for core classes
- passing in null for a NWObject parameter no longer throws NullPointerException, it gets instead handled as OBJECT_INVALID
- NWObject.oid now has a ceiling of 0x7fffffff
- NWLocation, NWVector implement Serializable
- NWVector.ORIGIN points at (0, 0, 0)
- Scheduler has a SchedulerListener interface to act on token()
- NWObject has a ApplyListener interface to act on successful applies
- NWObject.classListener is now a sorted List instead of a Set (booo!)
- NWScript fun header generated with proper @param tags

jar and so updated at the usual place.

[elven]

Just java changes for now:

- ApplyListeners receive newObject()
- ApplyListeners send out preApply()
- SchedulerListener sends out missedToken(), postFlushQueues()
- NWItemProperty, NWEffect now have classHandlers too
- Evaluation for all classHandlers is in REVERSED order now (core classes registered first, then all other matching ones)
- generated constants: don't miss constants with // comments at the end
- generated constants: generate static class files for constants down to 3 (previous: 8) - now DurationType et al included
- NWObject.registerDefaultHandlers() is gone now

[motu99]

Nice plugin.

So basically we have all of NWScript's basic functionality at our fingertips?! (e.g. all functions in nwscript.nss; plus some nice additions by yourself, such as get* functions that return arrays - like NWEffect[] getEffects)

This means that from now on we can do everything that NWScript can do (although often very awkwardly and inefficient, because NWScript doesn't even have arrays, not to mention references) in java!

Mmh.

On the one hand that is great news, because I much prefer programming in an object oriented language - not necessarily Java, C# are C++ are great as well, although not as portable. What bothered me alot with NWScript is the lack of references and arrays. And then, for the larger projects, the (pre) C age #include "management" (or rather no management) becomes quite cumbersome. So basically, with nwnx_jvm I could write any complicated nwscript in java?! The ideal situation being the replacement of all code in all nwscript main() functions by one single call (including the passing of all necessary parameters) to the JVM.

On the other hand, replacing virtually all nwscript code with Java code just for a few scripts doesn't seem worth the effort. Meaning the JVN plugin would be of more interest to the really large projects. But here is the catch: If your project relies on a lot of includes (not only Bioware's, but a bunch of custom made includes), the JVM wouldn't know about these, meaning all includes would have to be ported to Java. Doable, but quite a hassle for a large existing project. For a new project this wouldn't be such a bother, although so far the functions provided by the Bioware includes haven't yet found their way into your NWScript.java implementation...

Bottom line. I am intrigued, but not yet fully convinced.

Just one question: Can I run the other plugin-functions (such as acaos nwnx_func) directly from the JVM, or would I have to go through the usual NWScript.setLocalString(Object.MODULE, "NWNX!****!****") routine?

[elven]

[motu99]

[elven]

Just to put this into context: You can actually attach Eclipse with a running remote debugger to the JVM inside nwserver, set breakpoints, and hotpatch running code. You have ALL of the Java world at your disposal, including full native multithreading, all available libraries and any native code you care to load. It's much more than "making scripts more concise" - but it certainly does that.