The V-Sport Project implementsaVulkan-based graphics enginefor theLibbulletjme 3-D physics library.

It contains 2 subprojects:

1. lib: the V-Sport graphics engine (a single JVM runtime library)
2. apps: demos, tutorial examples, and non-automated test software

Complete source code (inJava) is provided undera 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
• Conventions
• What's missing
• Acknowledgments

V-Sport is a Simple Physics-ORienTed graphics engine written in Java 1.8.In addition toLibbulletjme,it usesLWJGL,Assimp,GLFW,JOML,jSnapLoader, andVulkan.It has been tested on Windows, Linux, and macOS.

Jump to the table of contents

V-Sport comes pre-built as a single librarythat can be downloaded from Maven Central or GitHub.However, the native-library dependencies are intentionally omitted from V-Sport's POMso developers can specifywhich Libbulletjme and LWJGL natives should be used.

For projects built usingMaven orGradle, it isnot sufficient to specify thedependency on the V-Sport Library.You must also explicitly specify the native-library dependencies.

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

repositories {    mavenCentral()}dependencies {    // JVM library:    implementation("com.github.stephengold:V-Sport:0.9.1")    // Libbulletjme native libraries:    runtimeOnly("com.github.stephengold:Libbulletjme-Linux64:22.0.1:SpDebug")      // Libbulletjme native libraries for other platforms could be added.    // LWJGL native libraries:    runtimeOnly("org.lwjgl:lwjgl:3.3.6:natives-linux")    runtimeOnly("org.lwjgl:lwjgl-assimp:3.3.6:natives-linux")    runtimeOnly("org.lwjgl:lwjgl-glfw:3.3.6:natives-linux")    runtimeOnly("org.lwjgl:lwjgl-opengl:3.3.6:natives-linux")      // LWJGL native libraries for other platforms could be added.}

For some older versions of Gradle,it's necessary to replaceimplementation withcompile.

Every V-Sport application should extend theBasePhysicsApp 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,calledgeometries.Instantiating a geometry automatically adds it to the listand causes it to be visualized.

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

By default, physics objects are not visualized.

• To visualize the shapeof aPhysicsCollisionObject other than aPhysicsSoftBody,invoke thevisualizeShape() method on it.
• To visualize the local coordinate axes of aPhysicsCollisionObject,invoke thevisualizeAxes() method on it.
• To visualize the wheels of aPhysicsVehicle,invoke thevisualizeWheels() method on the vehicle.
• To visualize the bounding box of aPhysicsCollisionObject,instantiate anAabbGeometry for the object.
• To visualize aConstraint,instantiate aConstraintGeometry for each end.
• To visualize the wind acting on aPhysicsSoftBody,instantiate aWindVelocityGeometry for the body.

Jump to the table of contents

1. Install aJava Development Kit (JDK),if you don't already have one.
2. Point theJAVA_HOME environment variable to your JDK installation:(In other words, set it to the path of a directory/foldercontaining 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"
• usingFish: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'

3. Download and extract the V-Sport source code from GitHub:

• usingGit:
  • git clone https://github.com/stephengold/V-Sport.git
  • cd V-Sport

4. Run theGradle 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

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 athttps://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.

Jump to the table of contents

Package names begin withcom.github.stephengold orjme3utilities.minie.

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

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

Angles are quantified inradians unless otherwise noted.

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

Jump to the table of contents

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)

Jump to the table of contents

Portions of the V-Sport Project are derived fromVulkan-Tutorial-Javaby Cristian Herrera, which was in turn ported fromAlexander Overvoorde's Vulkan tutorial.I am deeply grateful for all the work that went into these invaluable tutorials.

The ConveyorDemo app derives from source codecontributed 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:

• theCheckstyle tool
• theFirefox web browser
• theGit revision-control system and GitK commit viewer
• theGitKraken client
• theGLFW library
• theGradle build tool
• theJava compiler, standard doclet, and runtime environment
• the Java OpenGL Math Library
• thejSnapLoader dynamic-library loader
• the Lightweight Java Gaming Library
• theLinux Mint operating system
• theMarkdown document-conversion tool
• theMeld visual merge tool
• theNetBeans integrated development environment
• the Open Asset Import (Assimp) Library
• the shaderc project
• Microsoft Windows
• theVulkan API

I am grateful toGitHub andImgurfor providing free hosting for this projectand 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 cancorrect the situation:sgold@sonic.net

Jump to the table of contents