Skip to content

Latest commit

 

History

History
614 lines (495 loc) · 24.1 KB

readme.md

File metadata and controls

614 lines (495 loc) · 24.1 KB
Raw

The More Advanced Vehicles Project demonstrates vehicle simulation using the jMonkeyEngine (JME) game engine and provides a library to support driving simulations.

It contains 5 subprojects:

  1. MavLibrary: the MaVehicles library
  2. MavDemo1: a demo application with a Lemur-based GUI
  3. MavDemo2: a demo application with a Nifty-based GUI
  4. HelloMav: a very simple application using the MaVehicles library
  5. MavCommon: examples of vehicles, worlds, skies, etcetera

Contents of this document

Important features

  • 4 example worlds, 8 example vehicles, and 4 example skies
  • vehicle customization:
    • engine
    • brakes
    • automatic transmission
    • wheels
    • tires with Pacejka model for friction (only the latitudinal forces are applied)
    • suspensions
    • speedometer units
    • passengers
  • graphical user interfaces:
    • buttons and animated menus
    • compass
    • speedometer
    • tachometer
    • steering-wheel indicator
    • automatic-transmission mode indicator
    • edit vehicle parameters
    • camera selection
  • special effects:
    • skid marks
    • tire smoke
    • engine/horn sounds

Jump to the table of contents

A silver sports car flies out of a pipe. There are driving controls in the foreground and a racetrack in the background.

How to download and run the MavDemo1 application

  1. Install a 64-bit Java, if you don't already have one. (MavDemo1 no longer supports 32-bit Java.)
  2. 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 '
  1. Install the latest MavDemo1 release from GitHub:
  1. cd to the extracted "MavDemo1" directory/folder that contains "bin" and "lib".
  2. Run the Maud startup script:
  • using Bash or Fish or or Zsh: ./bin/MavDemo1
  • using Windows Command Prompt: ./bin/MavDemo1.bat
  • using PowerShell: .\bin\MavDemo1.bat

The demo runs in a 1280x720 window. After a brief loading animation, the Main Menu appears in the upper-left corner of the window.

  • Navigate menus by clicking with the left mouse button (LMB).
  • If you have a wheel mouse, use the wheel to change the field of view.

Jump to the table of contents

How to build and run More Advanced Vehicles from source

  1. Install a 64-bit Java Development Kit (JDK), if you don't already have one.
  2. 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 '
  1. Download and extract the More Advanced Vehicles source code from GitHub:
  • using Git:
    • git clone https://github.com/stephengold/jme-vehicles.git
    • cd jme-vehicles
    • git checkout -b latest project-1.6.0
  • using a web browser:
    • browse to the latest release
    • follow the "Source code (zip)" link
    • save the ZIP file
    • extract the contents of the saved ZIP file
    • cd to the extracted directory/folder
  1. 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 "MavLibrary/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

You can run the MavDemo1 application:

  • using Bash or Fish or PowerShell or Zsh: ./gradlew :MavDemo1:run
  • using Windows Command Prompt: .\gradlew :MavDemo1:run

You can run the MavDemo2 application:

  • using Bash or Fish or PowerShell or Zsh: ./gradlew :MavDemo2:run
  • using Windows Command Prompt: .\gradlew :MavDemo2:run

You can run the HelloMav application:

  • using Bash or Fish or PowerShell or Zsh: ./gradlew :HelloMav:run
  • using Windows Command Prompt: .\gradlew :HelloMav:run

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

Jump to the table of contents

Controls

In the MavDemo1 application

During the JmePower loading animation:

  • Pause : pause the animation
  • Tab : cancel the animation

General controls:

  • Numpad9 or wheel up : zoom in (narrow the field of view)
  • Numpad3 or wheel down : zoom out (widen the field of view)
  • Numpad6 : reset the field of view (to 90 degrees vertical angle)
  • "." or Pause : toggle the physics simulation paused/running
  • "/" : toggle physics debug visualization on/off
  • F6 : toggle the detailed profile of per-frame CPU/GPU time
  • F12 : capture a screenshot to the current working directory
  • C : print details about the default Camera (viewpoint) to standard output
  • O : print details about the BulletAppState (physics) to standard output
  • P : print details about the RenderManager (graphics) to standard output

When the physics simulation is paused:

  • "," : single-step the physics simulation

When driving:

  • F5 : toggle viewpoints between dash camera and chase camera
  • Y : toggle the engine on/off
  • W : accelerate forward
  • S : apply the main brakes
  • Space : apply the parking brake
  • E : toggle the automatic transmission forward/reverse
  • A : steer left
  • D : steer right
  • H : sound the horn
  • R : reset the vehicle to a stable state
  • Esc : return to the Main Menu

Additional controls when the chase camera or orbit camera is active:

  • Numpad7 : dolly forward (toward the vehicle)
  • Numpad1 : dolly back (away from the vehicle)
  • Numpad8 or drag upward with MMB : orbit upward (to look down on the vehicle)
  • Numpad2 or drag downward with MMB : orbit downward (to look up at the vehicle)
  • Numpad5 or RMB : reset the viewpoint's position relative to the vehicle

Additional controls when the orbit camera is active:

  • Drag left with MMB : orbit leftward
  • Drag right with MMB : orbit rightward

In the MavDemo2 application

During the JmePower loading animation:

  • Pause : pause the animation
  • Tab : cancel the animation

General controls:

  • Esc : quit the application
  • Numpad9 or wheel up : zoom in (narrow the field of view)
  • Numpad3 or wheel down : zoom out (widen the field of view)
  • Numpad6 : reset the field of view (to 90 degrees vertical angle)
  • "." or F7 or Pause : toggle the physics simulation paused/running
  • "/" : toggle physics debug visualization on/off
  • F5 : cycle through various viewpoints
  • F6 : toggle the basic graphical profile of update time versus render time
  • F11 : toggle video recording on/off
  • F12 : capture a screenshot to the sandbox directory
  • C : print details about the default Camera (viewpoint) to standard output
  • O : print details about the BulletAppState (physics) to standard output
  • P : print details about the RenderManager (graphics) to standard output
  • I : print details about the StateManager to standard output
  • Y : toggle the engine running/off
  • S : apply the main brakes
  • X : apply the parking brake
  • A : steer left
  • D : steer right
  • E : toggle the automatic transmission forward/reverse
  • H : sound the horn
  • Backslash : add a prop at the mouse pointer
  • R : reset the vehicle to a stable state
  • F1 : edit the hotkey bindings
  • F2 : edit the video settings
  • F4 : cycle through various performance displays

Additional controls when the physics simulation is paused:

  • "," : single-step the physics simulation

Additional controls when the engine is running:

  • W : accelerate forward

Additional controls when the chase camera or orbit camera is active:

  • Numpad7 : dolly forward (toward the vehicle)
  • Numpad1 : dolly back (away from the vehicle)
  • Numpad8 or Q or drag upward with MMB : orbit upward (to look down on the vehicle)
  • Numpad2 or Z or drag downward with MMB : orbit downward (to look up at the vehicle)
  • Numpad5 or RMB : reset the viewpoint's position relative to the vehicle

Additional controls when the orbit camera is active:

  • RightArrow or drag left with MMB : orbit leftward
  • Leftarrow or Drag right with MMB : orbit rightward

In the HelloMav application

  • W : accelerate forward
  • A : steer left
  • D : steer right
  • Wheel up : zoom in (narrow the field of view)
  • Wheel down : zoom out (widen the field of view)
  • Esc : exit the application

Jump to the table of contents

How to add the MaVehicles library to an existing project

The MaVehicles library comes pre-built as a single JVM library that depends on Minie. However, the Minie dependency is intentionally omitted from the MaVehicles POM so developers can specify which Minie library should be used.

For projects built using Maven or Gradle, it is not sufficient to specify the dependency on the MaVehicles Library. You must also explicitly specify the Minie dependency. The following examples specify "+big4", but "+debug" or the default Minie library should also work.

Gradle-built projects

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

repositories {
    mavenCentral()
}
dependencies {
    implementation 'com.github.stephengold:MaVehicles:0.7.1'
    implementation 'com.github.stephengold:Minie:8.0.0+big4'
}

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

Maven-built projects

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>MaVehicles</artifactId>
  <version>0.7.1</version>
</dependency>

<dependency>
  <groupId>com.github.stephengold</groupId>
  <artifactId>Minie</artifactId>
  <version>8.0.0+big4</version>
</dependency>

Jump to the table of contents

Wish list

More Advanced Vehicles is a work in progress. Some ideas for future development:

  • More alternatives for:
    • Worlds, such as: 3-D maze, block world, drag strip, parking garage, parking lot, showroom, and urban grid
    • Surface conditions, such as: wet pavement, dirt, sand, snow, and grass
    • Propulsion, such as: draft animals, jets, human power, propellers, and sails
    • Skies, such as TehLeo's SevenSky
    • User interface, such as: joystick and NiftyGUI
    • Vehicle dynamics, such as that used in Murph9's RallyGame
    • Vehicle types, such as: buses, tanks, golf carts, rolling chairs, tractors, rail locomotives, palanquins, rickshaws, aerial trams, bulldozers, snowmobiles, snowplows, speedboats, airplanes, boats, and helicopters
    • Viewpoints, such as: FlyCam, front view, side view, and plan view
  • More obstacles:
    • AI-controlled vehicles
    • Animated non-vehicles, such as: gates, drawbridges, deer, and pedestrians
  • More vehicle equipment:
    • Anti-lock braking
    • Artificial horizon
    • Brake lights and turn signals
    • Clock/stopwatch/timer
    • Cruise control
    • Door/hood/trunk animation
    • Fuel gauge
    • Headlamps
    • Manual transmission with clutch
    • Maps
    • Mirrors and backup assist
    • Nitrous oxide
    • Odometer
    • Oil-temperature gauge
    • Operable doors, hood, and trunk
    • Passengers and cargo
    • Sirens
    • Speed limiter
    • Starter motor
    • Steering-yoke animation
    • Traction indicator
    • Trailers
    • Weaponry
    • Windshield wipers
  • More scenarios:
    • Crazy taxi
    • Demolition derby
    • Night driving
    • Performance tests, such as: braking distance, turning radius, and zero-to-60
    • Player-vs-player over a network
    • Pursuit and evasion
    • Time trial
    • Career mode
  • More details:
    • Scoring for stunts
    • Simulate damage, brake wear, and tire wear
    • Sound effects for crashes, squealing tires, and wind

See also the project's issue tracker.

Jump to the table of contents

Licensing

The source code has a BSD 3-Clause license.

Resources/assets/media:

Jump to the table of contents

Conventions

Package names begin with com.jayfella.jme.vehicle

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

The world (and physics-space) coordinate system is right-handed:

  • the +X axis points toward the northern horizon
  • the +Y axis points up (toward the zenith)
  • the +Z axis points toward the eastern horizon

The world (and physics-space) units of distance are meters.

Jump to the table of contents

External links

Jump to the table of contents

Acknowledgments

Like most projects, More Advanced Vehicles builds on the work of many who have gone before. I therefore acknowledge the following artists and software developers:

CC Attribution

Hosting

I am grateful to GitHub, Sonatype, Imgur, JFrog, and YouTube 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