JPhysics is a 2D physics engine with no third-party-library dependencies.
The engine is written in Java and has been created with the intention of being used in games.
As part of a comprehensive code quality initiative, I identified and fixed 4 critical physics bugs:
-
Circle Inertia Calculation (
Circle.java:35)- Fixed incorrect moment of inertia formula from
I = m*r²toI = 0.5*m*r²(correct for solid disk) - Impact: Circles now rotate with physically accurate resistance
- Fixed incorrect moment of inertia formula from
-
Orientation Overflow Prevention (
World.java:152-154)- Added modulo wrapping (
θ % 2π) to prevent floating-point overflow - Impact: Improved stability in long-running simulations
- Added modulo wrapping (
-
Floating-Point Comparison Safety (
Polygon.java:232)- Replaced exact comparison with epsilon tolerance for collinearity detection
- Impact: More robust polygon construction from arbitrary vertices
-
Collision Tangent Normalization (
Arbiter.java:484-490)- Added zero-length check before normalizing tangent vector
- Impact: Handles pure normal collisions without NaN errors
Created 324 unit tests achieving comprehensive coverage of core physics components:
| Test File | Tests | Coverage |
|---|---|---|
CircleTest.java |
26 | Mass calculation, inertia (bug fix verified), AABB |
BodyTest.java |
60 | Force/impulse application, mass/inertia, static bodies |
PolygonTest.java |
78 | Convex hull, normals, mass/inertia, AABB rotation |
WorldTest.java |
60 | Integration, gravity, collision detection, body management |
ArbiterTest.java |
100 | Circle-circle, circle-polygon, polygon-polygon collisions, friction |
| TOTAL | 324 | ✅ All tests passing (0.043s) |
Test Highlights:
- Validates all bug fixes with specific regression tests
- Tests edge cases: zero-distance collisions, extreme values, high velocities
- Verifies physics accuracy: momentum conservation, energy transfer
- Covers all collision combinations across shape types
- Decoupled Dependencies: Created
ICameraandIRenderSettingsinterfaces to separate library from testbed - Encapsulation: Made public fields private with proper getters/setters in core classes
- Enhanced API: Added
getPenetration(),getStaticFriction(),getDynamicFriction()to Arbiter
The testbed includes numerous tech demos to show what the engine is capable of. Some examples are given below:
- Rigid body dynamics
- Primitive joint constraints
- Momentum
- Friction
- Restitution
- Collision response (Sequential Impulses Solver)
- Stable object stacking
- Orbits
- Explosions
- Object slicing
- AABB queries (Broadphase)
- One-shot contact manifolds
- Discrete collision detection
- Convex polygon and circle collisions
- Ray casting
- Position resolution handling
- Proximity
- Ray casting
- Particle
- Java swing for demo graphics
- Junit4 for junit tests
Follow these simple steps!
- An appropriate IDE for example Intellij (with java 1.8+ JDK installed)
- Junit4 library (for junit tests)
All you need to do is clone the repository and place the JPhysics/src files in the source directory of your chosen IDE.
For JUnit 4, you will need to add junit4 jar file to class path. This can be done as follows in intellij:
Go to file -> project structure (Ctrl-Alt-Shift-S)
Click the plus button at the top and select "From Maven as shown below"
In the search box, type in "junit:junit:4.12" and press ok. This is the JUnit dependency I use and have tested on.
After this, Keep hitting OK until you're back to the original project code.
Now you can go to "src/testbed/junittests/" and run the tests!
Java documentation on the library can be found in the Javadoc folder or follow the link! java documentation
Hayden Marshall
The repository falls under the MIT license. See LICENSE.txt for more information.
Dirk Gregorius and Erin Catto's gdc talks and documentation have been of great help with the theoretical approach of creating a physics engine.