Home

Awesome

alt tag

Actions Status License Language Java Maven Central javadoc Code Coverage

Java Collision Detection and Physics Engine

A 100% Java 2D collision detection and physics engine. Designed to be fast, stable, extensible, and easy to use. dyn4j is free for use in commercial and non-commercial applications.

The project is comprised of the main project and tests managed here and a samples project:

Requirements

Getting Started

dyn4j comes with a lot of features and extensibility, but getting started is easy. If you are looking for a quick start, take a look at the following video.

Getting started with dyn4j

Step 1: Add dyn4j to Your Project

Add dyn4j to your classpath by adding a Maven dependency from Maven Central or GitHub Packages

<dependency>
    <groupId>org.dyn4j</groupId>
    <artifactId>dyn4j</artifactId>
    <version>5.0.2</version>
</dependency>

If you are not using Maven you can download the jar from either of the links above.
NOTE: Releases are no longer being created as of 3.4.0.

Step 2: Create a World

World<Body> world = new World<Body>();

This creates a new simulation environment with default settings. The default settings use the meter-kilogram-seconds system and include the default pipeline classes for collision detection, manifold generation, and collision resolution. You can adjust the pipeline classes using the respective methods on the World class and update the settings using the getSettings method.

Step 3: Add Some Bodies

Body body = new Body();
body.addFixture(Geometry.createCircle(1.0));
body.translate(1.0, 0.0);
body.setMass(MassType.NORMAL);
world.addBody(body);

A Body is the primary unit of simulation and completely rigid. A Body is comprised of one or more BodyFixtures. Each Fixture has one Shape. While the shapes of dyn4j are all convex (and must be), a collection of these shapes can be used to create a body that is not. A body can be initially placed in a scene by translating or rotating it. Once the shape(s) of a body is defined, it must be given a mass by calling a setMass method. The mass type is typically MassType.NORMAL or MassType.INFINITE. When set to NORMAL, the mass will be calculated based on the shapes. An INFINITE mass body might represent a floor, ground, or something immovable.

Step 4: Add Some Joints

PinJoint<Body> joint = new PinJoint<Body>(body, new Vector2(0, 0));
joint.setSpringEnabled(true);
joint.setSpringDamperEnabled(true);
joint.setMaximumSpringForceEnabled(true);
joint.setSpringFrequency(8.0);
joint.setSpringDampingRatio(0.3);
joint.setMaximumSpringForce(1000.0);
world.addJoint(joint);

A Joint is a constraint on the motion of one or more Bodys. There are many joint types that serve different purposes. Generally, joints are used to link bodies together in a specified way. Bodies can have multiple joints attached to them making for some interesting combinations. Review each joint's class documentation for details on usage.

Step 5: Run the Simulation

for (int i = 0; i < 100; i++) {
    world.step(1);
}

Unlike this example, a GUI based application you would call the World.update(elapsedTime) method in it's render loop. Either way, each time the world is advanced forward in time (which may or may not occur when using the World.update(elapsedTime) methods) the bodies added to it will be moved based on the world gravity (if any) and will interact with other bodies placed in the world.

Step 6: Get output from the simulation

After each update of the world, each body's Transform reflects the changes caused by the simulation. Each Body stores it's current position and rotation in a Transform. Using the Transform you can convert from local body space to world space coordinates. For example:

for (Body body : world.getBodies()) {
    // get the updated body center
    Vector2 xy = body.getWorldCenter();
    
    for (BodyFixture fixture : body.getFixtures()) {
        Convex c = fixture.getShape();

        // if your fixture shape has vertices
        if (c instanceof Wound) {
            Wound w = (Wound)c;
            Vector2[] vertices = w.getVerticies();
            for (int i = 0; i < vertices.length; i++) {
                // get the updated fixture vertices
                xy = body.getWorldPoint(vertices[i]);
                // or
                // body.getTransform().getTransformed(vertices[i]);
            }
        }
    }
}

Next Steps

From here you should take a look at the dyn4j-samples sub project to get a jump start with a simple Java2D framework. You can also check out the full getting started documentation.

Links

Building