gdx-box2d

This project contains java bindings for the v3.1.1 release of Box2D.
The project is build from commit 8c661469c9507d3ad6fbd2fea3f1aa71669c2fe3.

Installation

The current version is: 3.1.1-0

gdx-box2d provides the following artifacts:

• com.badlogicgames.gdx:gdx-box2d:$version
• com.badlogicgames.gdx:gdx-box2d-platform:$version:natives-desktop
• com.badlogicgames.gdx:gdx-box2d-platform:$version:natives-ios
• com.badlogicgames.gdx:gdx-box2d-platform:$version:natives-arm64-v8a
• com.badlogicgames.gdx:gdx-box2d-platform:$version:natives-armeabi-v7a
• com.badlogicgames.gdx:gdx-box2d-platform:$version:natives-x86
• com.badlogicgames.gdx:gdx-box2d-platform:$version:natives-x86_64

Additionally, the following utility artifact is provided:

• com.badlogicgames.gdx:gdx-box2d-utils:$version

Usage

At first, you need to call com.badlogic.gdx.box2d.Box2d#initialize. This will load the shared libraries and set up the native code.
After that, com.badlogic.gdx.box2d.Box2d provides all entry points into Box2D.

Closure

Closures can be allocated with ClosureObject#fromClosure.

Memory handling

Structs and Pointer are part of the java GC cycle. If a struct/pointer gets allocated in java, it will be freed once the GC collects the java object.
All pointer types provide constructors to make them not freed by GC. You need to free those manually.
Closures always need to be freed manually.
If a box2d method returns a pointer, it will not be registered for GC.

Note

For more information on the bindings see the documentation.

Working with VoidPointer context or user data

Box2d supports passing a void* context to callbacks or attaching user data to a type.
In java interop, we usually want this to be a java object. In a thread-safe manner, this can be achieved like this:

public class Box2DIDFactory<T> {

    private long id = 0;
    private LongMap<T> map = new LongMap<>();

    public VoidPointer putData(T obj) {
        synchronized (this) {
            id += 1;
            map.put(id, obj);
            return new VoidPointer(id, false);
        }
    }

    public void putData(T obj, VoidPointer pointer) {
        synchronized (this) {
            id += 1;
            map.put(id, obj);
            pointer.setPointer(id);
        }
    }

    public long putDataRaw(T obj) {
        synchronized (this) {
            id += 1;
            map.put(id, obj);
            return id;
        }
    }

    public T obtainData(VoidPointer pointer) {
        synchronized (this) {
            return map.get(pointer.getPointer());
        }
    }

    public T obtainDataRaw(long pointer) {
        synchronized (this) {
            return map.get(pointer);
        }
    }
}

This is a very barebones example. It assumes you would want a factory per type. It is also designed thread-safe, which is not necessary.

Java 8

The project needs java 8 language features to build. However, it doesn't use any java 8 APIs and is therefor still safe to use with mobiVM.

Deviation from box2d

The following changes have been applied that are more than sole bindings:

• On initialization a custom routine for assertion handling gets installed. This will throw the assertion as an Box2DAssertionError.
  The behaviour can be overwritten with b2SetAssertFcn, see the box2d docs for more infos.

Supported OS

Windows:

• i686
• x86_64

MacOS:

• x86_64
• arm64

Linux:

• arm
• arm64
• x86_64
• riscv64

iOS:

• arm64 iphoneos
• arm64 iphonesimulator
• x86_64 iphonesimulator

Android:

• arm64-v8a
• armeabi-v7a
• x86
• x86_64