Awesome
jdkgdxds_interop
Inter-operate between libGDX and jdkgdxds
We have libGDX already.
There's several collection types in libGDX that have no convenient way to interoperate with the
JDK interfaces. ObjectMap
doesn't implement Map
, Array
doesn't implement List
, and in general nothing more than
Iterable
is available. But, libGDX also provides its Json
class and related code, which is a nice way of serializing
data so that all platforms can both read and write it.
And then there's jdkgdxds.
The new jdkgdxds library takes the JDK interfaces like Map
and List
,
applies them to data structures closely derived from the libGDX ones, and then keeps going to extend the data structure
coverage to things like insertion-ordered long-to-float maps and case-insensitive sets of CharSequence items. It does
not have a way to serialize to JSON out-of-the-box, though things that can serialize the JDK interfaces can at least
write and read the all-Object types like ObjectList
, ObjectObjectMap
and ObjectOrderedSet
.
So what do we have here?
Here's jdkgdxds_interop, for conversions both ways between jdkgdxds and libGDX data structures, and also to write the
jdkgdxds data structures using libGDX's Json. This consists of just three classes, all in the
com.github.tommyettinger.ds.interop
package. ConversionToGDX
has methods that take any class that implements one of
the JDK or one of jdkgdxds' interfaces, like Collection
or PrimitiveCollection.OfLong
, and converts it to a narrower
libGDX data structure. ConversionToJDK
has methods that take a specific libGDX class, typically, and convert it to a
similar jdkgdxds data structure. JsonSupport
is probably the star of the show, and allows registering serializers on a
Json
object, so it can read and write jdkgdxds types. This registration could be all at once, using registerAll()
,
or one at a time using any of its other methods.
The Json serialization also uses an especially-concise format to store each of the EnhancedRandom
implementations in
juniper. Even though juniper is not a direct dependency of jdkgdxds, it used
to be part of that library, and its use is recommended with any of the randomized methods in jdkgdxds, so it still makes
sense to have here. These classes (DistinctRandom
, LaserRandom
, TricycleRandom
, uhh... there's a lot in the
com.github.tommyettinger.random
package) are sometimes serializable
without jdkgdxds-interop, but work regardless of JDK version if
you do use this library. Better still, you can register EnhancedRandom
for serialization, so places that have an
EnhancedRandom
but don't specify an implementation can still store one (which includes its implementing class) and
read an EnhancedRandom
back. If you have your own class that extends java.util.Random
, which is admittedly unlikely,
you should probably write your own serializer modeled after the serializer for the RandomXS128
class in libGDX here.
Java 17 and higher block libGDX's Json
class from accessing the state of java.util.Random
, which also prevents any
serialization of subclasses unless they use custom serialization. This also means that java.util.Random
can't be
serialized or deserialized by libGDX Json
on JDK 17 or higher, even with a custom serializer, unless some special
additional work happens (and even that might not work on future JDKs). digital
's AlternateRandom
class is also now
serializable here; its algorithm is the same as PasarRandom
from juniper, but it doesn't have as many features, so
simply using PasarRandom
is preferable if you depend on juniper anyway.
Starting with juniper 0.1.0, it now contains quite a few statistical distributions, each of which stores some parameter
or parameters and an EnhancedRandom to generate numbers. These can all be registered individually or as a group by
JsonSupport.registerDistribution()
. Once registered, you can store a Distribution
much like an EnhancedRandom
, and
it uses a similar compact storage system. You can also store a Distribution
and deserialize it as a Distribution
,
allowing any implementation to be fit into that variable.
The digital library is a direct dependency of jdkgdxds, and it has the
Hasher
, Interpolator
, and AlternateRandom
classes that can be registered, as well as a Base
class. Base
is
especially important here because you can
configure the numeral base that numbers are printed in by specifying one to JsonSupport.setNumeralBase(Base)
; this can
be handy to weakly obfuscate numbers if you pass a scrambled base (as Base
can generate).
The Json flavor in libGDX allows specifying class tags as a kind of shorter alias for a package-qualified class name. As
of jdkgdxds-interop 1.1.1.1, when registering any class, this will add a very short class tag unless you had previously
called JsonSupport.setAddClassTags(false);
. The class tags can be hard to read if you want human-readable JSON files,
but long packages add to file size and can also be strenuous to read repeatedly. Class tags are added by default.
How do I get it?
The Gradle dependency, with the usual caveats about optionally replacing implementation
with api
, is:
implementation "com.github.tommyettinger:jdkgdxds_interop:1.7.2.0"
It's not unlikely that you might need api
instead of implementation
, especially if you are writing a library, or a
module that needs to be used from another section.
If you use GWT (libGDX's HTML target), then you also need this in your html/build.gradle
file:
implementation "com.github.tommyettinger:funderby:0.1.2:sources"
implementation "com.github.tommyettinger:digital:0.5.4:sources"
implementation "com.github.tommyettinger:juniper:0.6.3:sources"
implementation "com.github.tommyettinger:jdkgdxds:1.7.2:sources"
implementation "com.github.tommyettinger:jdkgdxds_interop:1.7.2.0:sources"
Newer versions of funderby, digital, and possibly juniper and jdkgdxds may be usable as well.
You also need the GWT inherits
in your GdxDefinition.gwt.xml
file:
<inherits name="com.badlogic.gdx.backends.gdx_backends_gwt" />
<inherits name="com.github.tommyettinger.funderby" />
<inherits name="com.github.tommyettinger.digital" />
<inherits name="com.github.tommyettinger.juniper" />
<inherits name="com.github.tommyettinger.jdkgdxds" />
<inherits name="com.github.tommyettinger.jdkgdxds_interop" />
I hope that's all you need! It's a small-ish simple library!