JPhysics

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.

🔧 Recent Improvements (2025)

Critical Bug Fixes

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² to I = 0.5*m*r² (correct for solid disk)
- Impact: Circles now rotate with physically accurate resistance
Orientation Overflow Prevention (World.java:152-154)
- Added modulo wrapping (θ % 2π) to prevent floating-point overflow
- Impact: Improved stability in long-running simulations
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

Comprehensive Test Suite

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

Architecture Improvements

Decoupled Dependencies: Created ICamera and IRenderSettings interfaces 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

Tech demos

The testbed includes numerous tech demos to show what the engine is capable of. Some examples are given below:

Feature List

Physics

Rigid body dynamics
Primitive joint constraints
Momentum
Friction
Restitution
Collision response (Sequential Impulses Solver)
Stable object stacking
Orbits
Explosions
Object slicing

Collision

AABB queries (Broadphase)
One-shot contact manifolds
Discrete collision detection
Convex polygon and circle collisions
Ray casting
Position resolution handling

Explosion types

Proximity
Ray casting
Particle

Testbed

Java swing for demo graphics
Junit4 for junit tests

Getting Started

Follow these simple steps!

Prerequisites

An appropriate IDE for example Intellij (with java 1.8+ JDK installed)
Junit4 library (for junit tests)

Main files

All you need to do is clone the repository and place the JPhysics/src files in the source directory of your chosen IDE.

Adding JUnit library

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.

Testing

Now you can go to "src/testbed/junittests/" and run the tests!

Documentation

Java documentation on the library can be found in the Javadoc folder or follow the link! java documentation

Authors

Hayden Marshall

License

The repository falls under the MIT license. See LICENSE.txt for more information.

Credits

Dirk Gregorius and Erin Catto's gdc talks and documentation have been of great help with the theoretical approach of creating a physics engine.

HaydenMarshalla/JPhysics