The V-Sport Project implements a Vulkan-based graphics engine for the Libbulletjme 3-D physics library.
It contains 2 subprojects:
- lib: the V-Sport graphics engine (a single JVM runtime library)
- apps: demos, tutorial examples, and non-automated test software
Complete source code (in Java) is provided under a 3-clause BSD license.
- About V-Sport
- How to add V-Sport to an existing project
- How to build and run V-Sport from source
- What's missing
- Acknowledgments
V-Sport is a Simple Physics-ORienTed graphics engine written in Java 1.8. In addition to Libbulletjme, it uses LWJGL, Assimp, GLFW, JOML, and Vulkan. It has been tested on Windows, Linux, and macOS.
V-Sport comes pre-built as a single library that depends on Libbulletjme. However, the Libbulletjme dependency is intentionally omitted from V-Sport's POM so developers can specify which Libbulletjme library should be used.
For projects built using Maven or Gradle, it is not sufficient to specify the dependency on the V-Sport Library. You must also explicitly specify the Libbulletjme dependency.
Add to the project’s "build.gradle" or "build.gradle.kts" file:
repositories {
mavenCentral()
}
dependencies {
implementation("com.github.stephengold:Libbulletjme:21.2.1")
implementation("com.github.stephengold:V-Sport:0.9.0")
}
For some older versions of Gradle,
it's necessary to replace implementation
with compile
.
Add to the project’s "pom.xml" file:
<repositories>
<repository>
<id>mvnrepository</id>
<url>https://repo1.maven.org/maven2/</url>
</repository>
</repositories>
<dependency>
<groupId>com.github.stephengold</groupId>
<artifactId>Libbulletjme</artifactId>
<version>21.2.1</version>
</dependency>
<dependency>
<groupId>com.github.stephengold</groupId>
<artifactId>V-Sport</artifactId>
<version>0.9.0</version>
</dependency>
Every V-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 aPhysicsSoftBody
, invoke thevisualizeShape()
method on the object. - To visualize the local coordinate axes of a
PhysicsCollisionObject
, invoke thevisualizeAxes()
method on the object. - To visualize the wheels of a
PhysicsVehicle
, invoke thevisualizeWheels()
method on the vehicle. - To visualize the bounding box of a
PhysicsCollisionObject
, instantiate anAabbGeometry
for the object. - To visualize a
Constraint
, instantiate aConstraintGeometry
for each end. - To visualize the pins of a
PhysicsSoftBody
, instantiate aPinsGeometry
for the body. - To visualize the wind acting on a
PhysicsSoftBody
, instantiate aWindVelocityGeometry
for the body.
- Install a Java Development Kit (JDK), 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 V-Sport source code from GitHub:
- using Git:
git clone https://github.com/stephengold/V-Sport.git
cd V-Sport
- Run the Gradle wrapper:
- using Bash or Fish or PowerShell or Zsh:
./gradlew build
- using Windows Command Prompt:
.\gradlew build
The tutorial apps all have names starting with "Hello". For instance, the first tutorial app is named "HelloSport".
To execute "HelloSport":
- using Bash or Fish or PowerShell or Zsh:
./gradlew HelloSport
- using Windows Command Prompt:
.\gradlew HelloSport
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
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
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.
This project is incomplete. Future enhancements might include:
- handle more than 1600 geometries
- dynamic meshes (for visualizing soft bodies)
- pre-compiled shaders
- 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)
Portions of the V-Sport Project are derived from Vulkan-Tutorial-Java by Cristian Herrera, which was in turn ported from Alexander Overvoorde's Vulkan tutorial. I am deeply grateful for all the work that went into these invaluable tutorials.
The ConveyorDemo app derives from source code contributed by "qwq" in March 2022.
The ThousandCubes app derives from source code contributed by Yanis Boudiaf.
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 Lightweight Java Gaming Library
- the Linux 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 shaderc project
- Microsoft Windows
- the Vulkan API
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