[The SPORT Project][project] implements an [OpenGL]-based graphics engine for the Libbulletjme 3-D physics library.

It contains 2 subprojects:

lib: the SPORT graphics engine (a single JVM runtime library)
apps: demos and non-automated test software

Complete source code (in Java) is provided under a 3-clause BSD license.

About SPORT

SPORT is a Simple Physics-ORienTed graphics engine written in Java 1.8. In addition to Libbulletjme, it uses LWJGL, Assimp, GLFW, JOML, jSnapLoader, and [OpenGL]. It has been tested on Windows, Linux, and macOS.

Jump to the table of contents

How to add SPORT to an existing project

SPORT comes pre-built as a single library that can be downloaded from Maven Central or GitHub. However, the native-library dependencies are intentionally omitted from SPORT's POM so developers can specify which Libbulletjme and LWJGL natives should be used.

For projects built using [Maven] or Gradle, it is not sufficient to specify the dependency on the SPORT Library. You must also explicitly specify the native-library dependencies.

Gradle-built projects

Add to the project’s "build.gradle" or "build.gradle.kts" file:

repositories {
    mavenCentral()
}
dependencies {
    // JVM library:
    implementation("com.github.stephengold:sport:0.9.9")

    // Libbulletjme native libraries:
    runtimeOnly("com.github.stephengold:Libbulletjme-Linux64:23.0.0:SpDebug")
      // Libbulletjme native libraries for other platforms could be added.

    // LWJGL native libraries:
    runtimeOnly("org.lwjgl:lwjgl:3.4.1:natives-linux")
    runtimeOnly("org.lwjgl:lwjgl-assimp:3.4.1:natives-linux")
    runtimeOnly("org.lwjgl:lwjgl-glfw:3.4.1:natives-linux")
    runtimeOnly("org.lwjgl:lwjgl-opengl:3.4.1:natives-linux")
      // LWJGL native libraries for other platforms could be added.
}

For some older versions of Gradle, it's necessary to replace implementation with compile.

Coding a SPORT application

Every SPORT application should extend the BasePhysicsApp class, which provides hooks for:

initializing the application,
creating and configuring the application's physics space,
populating the space with physics objects, and
updating the space before each frame is rendered.

The graphics engine doesn't have a scene graph. Instead, it maintains an internal list of renderable objects, called geometries. Instantiating a geometry automatically adds it to the list and causes it to be visualized.

To visualize the world (physics-space) coordinate axes, instantiate one or more LocalAxisGeometry objects.

By default, physics objects are not visualized.

To visualize the shape of a PhysicsCollisionObject other than a PhysicsSoftBody, invoke the visualizeShape() method on it.
To visualize the local coordinate axes of a PhysicsCollisionObject, invoke the visualizeAxes() method on it.
To visualize the wheels of a PhysicsVehicle, invoke the visualizeWheels() method on the vehicle.
To visualize the bounding box of a PhysicsCollisionObject, instantiate an AabbGeometry for the object.
To visualize a Constraint, instantiate a ConstraintGeometry for each end.
To visualize the faces of a PhysicsSoftBody, instantiate a FacesGeometry for it.
To visualize the links of a PhysicsSoftBody, instantiate a LinksGeometry for it.
To visualize the pins of a PhysicsSoftBody, instantiate a PinsGeometry for it.
To visualize the wind acting on a PhysicsSoftBody, instantiate a WindVelocityGeometry for the body.

Jump to the table of contents

How to build and run SPORT from source

Initial build

Install a Java Development Kit (JDK), version 17 or higher, if you don't already have one.
Point the JAVA_HOME environment variable to your JDK installation: (In other words, set it to the path of a directory/folder containing a "bin" that contains a Java executable. That path might look something like "C:\Program Files\Eclipse Adoptium\jdk-17.0.3.7-hotspot" or "/usr/lib/jvm/java-17-openjdk-amd64/" or "/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home" .)

using Bash or Zsh: export JAVA_HOME=" path to installation "
using Fish: set -g JAVA_HOME " path to installation "
using Windows Command Prompt: set JAVA_HOME=" path to installation "
using PowerShell: $env:JAVA_HOME = ' path to installation '

Download and extract the SPORT source code from GitHub:

using Git:
- git clone https://github.com/stephengold/sport.git
- cd sport

Run the Gradle wrapper:

using Bash or Fish or PowerShell or Zsh: ./gradlew build
using Windows Command Prompt: .\gradlew build

After a successful build, Maven artifacts will be found in "lib/build/libs".

You can install the artifacts to your local Maven repository:

using Bash or Fish or PowerShell or Zsh: ./gradlew install
using Windows Command Prompt: .\gradlew install

Demos

Seven demo applications are included:

ConveyorDemo
NewtonsCradle
Pachinko
SplitDemo
TestGearJoint
ThousandCubes
Windlass

Documentation for the demo apps is at https://stephengold.github.io/Libbulletjme/lbj-en/English/demos.html

Chooser

A Swing-based chooser application is included. However, it doesn't work on macOS yet.

To run the chooser:

using Bash or Fish or PowerShell or Zsh: ./gradlew AppChooser
using Windows Command Prompt: .\gradlew AppChooser

Cleanup

You can restore the project to a pristine state:

using Bash or Fish or PowerShell or Zsh: ./gradlew clean
using Windows Command Prompt: .\gradlew clean

Note: these commands will delete any downloaded native libraries.

Jump to the table of contents

Conventions

Package names begin with com.github.stephengold or jme3utilities.minie.

The source code and pre-built libraries are compatible with JDK 8.

Rotation signs, polygon windings, and 3-D coordinate axes are right-handed/counter-clockwise unless otherwise noted.

Angles are quantified in radians unless otherwise noted.

The world coordinate system is assumed to be Z-forward, Y-up.

Jump to the table of contents

What's missing

This project is incomplete. Future enhancements might include:

graphics and physics on separate threads
graphical user interface
automated tests
shadow rendering
physically-based rendering
more performance statistics
sound effects
skeletal animation
run on mobile platforms (Android and/or iOS)

Jump to the table of contents

History

From March 2022 to March 2024, SPORT was a subproject of the LbjExamples Project.

Since March 2024, SPORT has been a separate project, hosted at [GitHub][project].

Jump to the table of contents

Acknowledgments

The ThousandCubes demo app and most of the original graphics code were authored by Yanis Boudiaf.

The IcosphereMesh class derives from source code published by James Khan in May 2017.

The ConveyorDemo app derives from source code contributed by "qwq" in March 2022.

This project has made use of the following libraries and software tools:

the Checkstyle tool
the Firefox web browser
the Git revision-control system and GitK commit viewer
the GitKraken client
the GLFW library
the Gradle build tool
the Java compiler, standard doclet, and runtime environment
the Java OpenGL Math Library
the jSnapLoader dynamic-library loader
the Lightweight Java Gaming Library
the [Linux Mint][mint] operating system
the [Markdown] document-conversion tool
the [Meld] visual merge tool
the [NetBeans] integrated development environment
the Open Asset Import (Assimp) Library
the [OpenGL] API
Microsoft Windows
the [RenderDoc] graphics debugger

I am grateful to GitHub and Imgur for providing free hosting for this project and many other open-source projects.

I'm also grateful to my dear Holly, for keeping me sane.

If I've misattributed anything or left anyone out, please let me know, so I can correct the situation: sgold@sonic.net

Jump to the table of contents

Sport

Install / Use

README

Contents of this document

About SPORT

How to add SPORT to an existing project

Gradle-built projects

Coding a SPORT application

How to build and run SPORT from source

Initial build

Demos

Chooser

Cleanup

Conventions

What's missing

History

Acknowledgments