• Stars
    star
    122
  • Rank 292,031 (Top 6 %)
  • Language
    Java
  • License
    Other
  • Created almost 6 years ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Integrate Bullet Physics and V-HACD into jMonkeyEngine projects (code has New BSD license)

Minie Project logo

The Minie Project is about improving the integration of Bullet real-time physics simulation and Khaled Mamou's V-HACD Library into the jMonkeyEngine (JME) game engine.

It contains 8 sub-projects:

  1. MinieLibrary: the Minie runtime library and its automated tests
  2. DacWizard: a GUI application to configure a ragdoll
  3. VhacdTuner: a GUI application to tune the V-HACD algorithm for a particular mesh
  4. TutorialApps: tutorial apps
  5. MinieExamples: demos, examples, and non-automated test software
  6. MinieAssets: generate assets used in MinieExamples
  7. MinieDump: a command-line utility to dump J3O assets
  8. Jme3Examples: physics examples from jme3-examples

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

Contents of this document

Why use Minie?

jMonkeyEngine comes with jme3-jbullet, its own Bullet integration library. Why use Minie instead of jme3-jbullet?

  • Minie has many more features. (See the feature list below.)
  • Minie fixes many bugs found in jme3-jbullet.
  • Due to its shorter release cycle, future features and bug fixes will probably appear first in Minie.
  • Minie uses automated testing to reduce the risk of regressions and new bugs.
  • Minie's classes are better encapsulated, with fewer public/protected fields and less aliasing of small objects like vectors. This reduces the risk of accidentally corrupting its internal data structures.
  • Minie validates method arguments. This helps detect usage errors that can lead to subtle bugs.
  • Minie's source code is more readable and better documented.

Summary of added features:

  • Extensions to DynamicAnimControl
  • Soft-body simulation based on btSoftBody and btSoftRigidDynamicsWorld, including anchors and soft-body joints
  • Multi-body simulation based on btMultiBody and btMultiBodyDynamicsWorld
  • Convex decomposition of meshes using Khaled Mamou's V-HACD Library, including progress listeners
  • New6Dof physics joints based on btGeneric6DofSpring2Constraint
  • Alternative contact-and-constraint solvers based on btDantzigSolver, btLemkeSolver, btSolveProjectedGaussSeidel, and btNNCGConstraintSolver
  • collision shapes:
    • MultiSphere shapes based on btMultiSphereShape
    • Box2dShape shapes based on btBox2dShape
    • Convex2dShape shapes based on btConvex2dShape
    • EmptyShape shape based on btEmptyShape
  • debugging aids:
    • dump the contents of a BulletAppState, PhysicsSpace, CollisionShape, or MultiBody
    • visualize physics objects in multiple viewports
    • customize debug material per collision object
    • visualize the local axes, velocities, bounding boxes, CCD swept spheres, and gravity vectors of collision objects
    • visualize the children of compound collision shapes
    • optional high-resolution debug meshes for convex shapes
    • options to generate debug meshes that include indices, normals (for shading), and/or texture coordinates (for texturing)
  • all joints, shapes, collision objects, and multibodies implement the JmeCloneable and Comparable interfaces
  • enable/disable a PhysicsJoint
  • single-ended physics joints
  • ignore lists for collision objects
  • application-specific data for collision objects
  • access more parameters of rigid bodies, vehicles, characters, joints, collision shapes, contact/constraint solvers, etcetera
  • option to apply scaling with a RigidBodyControl

Some jme3-jbullet classes that Minie omits:

  • KinematicRagdollControl, HumanoidRagdollPreset, and RagdollPreset: use DynamicAnimControl instead
  • RagdollUtils: not needed

Other important differences:

  • PhysicsSpace.addAll() and PhysicsSpace.removeAll() add/remove collision objects only; they do not add/remove joints.
  • RagdollCollisionListener interface changed and moved from the com.jme3.bullet.collision package to the com.jme3.bullet.animation package.

Jump to table of contents

Downloads

Newer releases (since v0.5.0) can be downloaded from GitHub.

Older releases (v0.1.1 through v0.4.5) can be downloaded from the Jme3-utilities Project.

Maven artifacts since v3.1.0 are available from MavenCentral.

Jump to table of contents

Conventions

Package names begin with jme3utilities. (if Stephen Gold holds the copyright) or com.jme3./jme3test. (if the jMonkeyEngine Project holds the copyright).

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

Jump to table of contents

Overview and design considerations

The role of physics simulation in games

Most computer games don't require detailed physics simulation.

  • Canned animations usually suffice to illustrate characters walking, jumping, and fighting.
  • Detecting when a character enters a fixed zone or comes into range of another character is a simple geometric calculation, provided the zone or range has a box or sphere shape.
  • For outer-space games, the equations of motion (Newton's 3rd Law) are easily implemented from scratch.

Other games require physics simulation, either because detailed physics is integral to gameplay (as in bowling or auto racing) or else to enhance the verisimilitude of effects such as collapsing buildings and/or people. For such games, a real-time physics library such as Minie should prove useful.

How Minie works

How Minie works

Computational efficiency

The computational cost of collision detection grows rapidly with the number of collision objects and the complexity of their shapes. To simulate physics in real time, with modest CPUs, it's vital to keep the physics simple:

  • Use very simple collision shapes (such as boxes, capsules, and spheres) wherever possible.
  • Minimize the number of collision objects by merging static bodies together and simulating only the most relevant moving bodies.
  • Minimize the number of nodes in each soft body.

Scaling the world

For a physics simulation, it might seem natural to choose kilograms and meters as the units of mass and distance, respectively. However, this is not a requirement, and for many games, MKS units are not the best choice.

Bullet documentation recommends that dynamic bodies have masses as close as possible to 1.

Also, to improve the performance and reliability of collision detection, Bullet applies a margin to most collision objects. By default, this margin is 0.04 physics-space units (psu). While the margin is configurable, Bullet documentation recommends against doing so. For some collision shapes, margin increases the effective size of the object and distorts its effective shape. For this reason, it's undesirable to have a collision object with any radius smaller than about 0.2 psu.

Dynamic bodies in forced contact tend to jiggle. Jiggling is mostly noticeable for sharp-edged bodies (such as boxes) resting on uneven surfaces, under high gravity. The higher the gravity (in psu per second squared), the shorter the simulation time step (in seconds) needs to be. For efficient and realistic simulation of Earth-like gravity (9.8 m/s) with the default margin (0.04 psu) and time step (0.0167 seconds), the psu should be 0.3 meters or larger. This puts a soft lower limit on the dimensions (in psu) of dynamic bodies.

Since Minie's debug visualization assumes that physics coordinates are equivalent to world coordinates, these recommendations could impact model creation and scene-graph design. Physics units should therefore be chosen with care, preferably early in the development process.

Jump to table of contents

How to build Minie from source

How to build Minie from source

Jump to table of contents

Tutorials

Jump to table of contents

An overview of the demo applications

An overview of the demo applications

Jump to table of contents

External links

YouTube videos about Minie:

Jump to table of contents

History

The evolution of this project is chronicled in its release log.

Most of Minie was originally forked from jme3-bullet, a library in the jMonkeyEngine Game Engine.

From January to November 2018, Minie was a sub-project of the Jme3-utilities Project.

Since November 2018, Minie has been a separate project, hosted at GitHub.

Jump to table of contents

Acknowledgments

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

  • Normen Hansen (aka "normen") for creating most of the jme3-bullet library (on which Minie is based) and also for helpful insights
  • RΓ©my Bouquet (aka "nehon") for co-creating KinematicRagdollControl (on which DynamicAnimControl is based), for creating the Jaime model, and also for many helpful insights
  • Jules (aka "dokthar") for creating the soft-body fork of jMonkeyEngine from which Minie's soft-body support is derived
  • Khaled Mamou for creating and licensing the V-HACD Library for decomposing meshes into convex hulls
  • Riccardo Balbo (aka "riccardo") for creating and licensing the V-HACD Java Bindings Project
  • "ndebruyn" for early testing of Minie on Android platforms
  • Pavly Gerges (aka "Pavl_G") for testing Minie on Raspberry Pi
  • Adam T. Ryder (aka "tryder") for creating and licensing the jME-TTF rendering system
  • [Paul Speed (aka "pspeed42")][pspeed], for creating the SimMath library
  • "oxplay2", for reporting a PhysicsRigidBody bug and helping me pin it down
  • "duncanj", for pull request #15
  • "qwq", for suggesting changes to how rigid-body contacts are managed and for authoring the ConveyorDemo application
  • Nathan Vegdahl, for creating the Puppet model
  • Tobias Jung, for distributing ProFont
  • plus the creators of (and contributors to) the following software:

I am grateful to GitHub, Sonatype, JFrog, Travis, MacStadium, YouTube, 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: [email protected]

Jump to table of contents

More Repositories

1

Libbulletjme

A JNI interface to Bullet Physics and V-HACD
C++
86
star
2

Maud

An editor for jMonkeyEngine 3-D models (code has New BSD license)
Java
39
star
3

jme3-utilities

Reusable code and assets for jMonkeyEngine games (code has New BSD license)
Java
33
star
4

Wes

An animation editing and retargeting library for jMonkeyEngine (code has New BSD license)
Java
17
star
5

Heart

A general-purpose add-on library for jMonkeyEngine (code has New BSD license)
Java
15
star
6

SkyControl

A sky simulation library for jMonkeyEngine (code has New BSD license)
Java
15
star
7

jolt-jni

JVM bindings for Jolt Physics
Java
13
star
8

j-ogg-all

Open-source JVM libraries for reading Ogg bitstreams and decoding the media they contain.
Java
12
star
9

MonkeyWrench

A versatile library for loading 3-D assets into JMonkeyEngine (code has New BSD license)
Java
11
star
10

LbjExamples

Documentation and example applications for the Libbulletjme physics simulation library
Java
11
star
11

Garrett

A collection of camera controllers for JMonkeyEngine
Java
11
star
12

asm

A small and fast library for manipulating Java bytecode.
Java
9
star
13

jme3-maze

Game: explore a randomly-generated 3-D maze with a Pharaonic Egypt theme (New BSD license)
Java
7
star
14

BasicGame-on-Gradle

jMonkeyEngine's prototypical BasicGame implemented as a Gradle/Java project
Java
7
star
15

kk-physics

Integrate Jolt Physics into jMonkeyEngine projects (code has New BSD license)
Java
6
star
16

V-Sport

A Vulkan-based 3-D graphics engine, written in Java (code has New BSD license)
Java
6
star
17

JmePower

A JVM library to promote the jMonkeyEngine game engine
Java
5
star
18

Banana

Physics tests and performance benchmarks for the jMonkeyEngine3 game engine.
Java
4
star
19

Acorus

An action-oriented user-interface library for jMonkeyEngine
Java
3
star
20

stephengold.github.io

Stephen Gold's personal website
Ruby
3
star
21

RyzomConverter

Adapt models from the Ryzom Asset Repository for use with jMonkeyEngine.
Java
3
star
22

stack-alloc

Allocate Java objects from method stack instead of the program heap.
Java
3
star
23

characters-for-jme

Animated 3-D character models for use with JMonkeyEngine.
3
star
24

sport

A Simple Physics-ORienTed 3-D graphics engine based on OpenGL.
Java
3
star
25

RyzomDemos

Demonstrates how to use 3-D assets from the Ryzom Asset Repository with JMonkeyEngine.
Java
2
star
26

Minie-site-it

Translation of the Minie project documentation into Italian.
2
star
27

FuzeCreek

A grid-based, real-time river-rafting game with explosives
Java
2
star
28

BasicGame-on-Kotlin

jMonkeyEngine's prototypical BasicGame implemented as a Gradle/Kotlin project
Kotlin
1
star
29

DacWizard

A GUI application to configure a Minie ragdoll (code has New BSD license)
Java
1
star
30

HelloCollision-on-Gradle

jMonkeyEngine's HelloCollision tutorial implemented as a Gradle project
Java
1
star
31

Georg

Procedurally generated textures (New BSD license)
Java
1
star
32

gold-tiles

turn-based multi-player game: draw tiles from a bag and play them onto a 2-D grid (GNU GPL v3 license)
C++
1
star
33

snap-jolt

Testbed for combining jolt-jni with jSnapLoader
Java
1
star
34

macana

Testbed for combining Obsidian with SPORT
Java
1
star