What Finn Physics Actually Is
Finn Physics is a lightweight 2D rigid-body physics engine built for game development and interactive simulations. It handles collision detection, response resolution, rigid body dynamics, and joint constraints out of the box. The project is written in C++ with bindings available for Python, C#, and Lua. It sits in the same space as Box2D and Chipmunk but makes different tradeoffs — smaller footprint, simpler API, and a focus on gameplay-scale physics rather than simulation-grade accuracy. The maintainer released the first public build around 2019. The core design philosophy is "good enough for games, fast enough to ignore." That means continuous collision detection is optional rather than default, sub-stepping is manual, and some edge-case behaviors are left to the implementer. If you're building a platformer, a top-down shooter, or a casual puzzle game, it works well. If you're simulating fluid dynamics or structural engineering, look elsewhere.
Getting Started with Finn Physics
Installation varies by language binding. For C++ projects, you clone the repository and run cmake with your preferred build system. The library links cleanly against standard Makefiles and CMakeLists. Python users can install via pip using the pre-built wheel, though you'll want to match your Python version exactly since the bindings are not polymorphic across versions. The CNuGet package has been stable for a while and plays nicely with Unity and Godot projects. Here's a minimal C++ setup that creates a dynamic body, adds it to a world, and runs one simulation step:
Finn::World world;
world.setGravity(Finn::Vector2(0, -9.81));
auto body = world.createBody(Finn::BodyType::Dynamic);
body.setPosition(Finn::Vector2(0, 10));
body.setVelocity(Finn::Vector2(3, 0));
auto circle = std::make_shared<Finn::CircleShape>(1.0);
body.addShape(circle);
world.step(1.0f / 60.0f);
That's basically it for a bare minimum. The world object manages memory, collision broadphase, and the integration loop. You don't manually clean up bodies — they're scoped to the world and freed when the world is destroyed.
Get the Full Details
How It Handles Collisions Under the Real World
Finn Physics uses a separating axis theorem (SAT) for convex polygon collisions and GJK/EPA for convex hull overlap depth queries. Circle-circle and circle-polygon tests are baked into the broadphase so you get those for free. The contact solver is a position-based iterative solver with a velocity correction pass. It resolves penetrations over multiple iterations, and the default iteration count is 10, which works for most casual games but can let heavy stacks tunnel or jitter under load. One thing beginners consistently get wrong is that Finn Physics does not clamp restitution automatically. If you set a restitution value above 0.8 on multiple stacked bodies, they'll bounce apart over successive frames. I ran into this on a project where a simple stacking puzzle had crates that wouldn't settle because each crate had a default restitution of 0.6 and the solver was adding energy back into the stack every frame. The fix was setting the world's combined restitution threshold to 0.2 and explicitly capping per-body restitution at 0.3. Another common mistake is not enabling CCD for fast-moving objects. Without it, a projectile moving at high velocity can pass through thin walls on a single timestep because the discrete collision test only checks start and end positions. Finn Physics has CCD built in as a per-body flag. Set it on anything moving faster than roughly its own size times the timestep frequency and you'll avoid most tunneling issues. This added about 12% overhead to my last project's physics step, which was acceptable for the improvement in reliability.
Performance Characteristics and Bottlenecks
In practice, Finn Physics handles about 500 active rigid bodies at 60fps on a mid-range consumer CPU without sub-stepping. Beyond that, you start seeing frame time spikes because the broadphase and solver scale worse than linearly. The main bottleneck is usually the contact manifold generation — every new pair of touching shapes requires manifold computation, and with 500 bodies that's potentially tens of thousands of pair checks per frame. The solver iterations are the second bottleneck. Each iteration runs through all contacts and adjusts velocities and positions. With the default 10 iterations and a lot of touching bodies, that's a lot of work. Reducing iterations to 6 saved about 8ms per frame in my project without noticeable quality loss. The tradeoff is slightly more penetration and a bit more visual jitter on stacked objects. For a fast-paced game, the tradeoff is usually worth it. Joints are cheaper than you might expect. Finn Physics handles revolute, prismatic, distance, and spring joints efficiently because they're resolved within the same solver pass as contacts. But composite joints — like a chain of revolute joints — can accumulate numerical drift over time. I've seen ragdolls gradually collapse into weird shapes after several minutes of simulation. The workaround is periodically reinitializing the joint limits or applying a small corrective impulse to the base body.
A Real Debugging Story: The Staircase Problem
I spent three days debugging an issue in a platformer prototype where the player character would occasionally get stuck on stairs that were only two pixels taller than the step height. The collision geometry looked fine. The movement code was standard AABB-based. Everything should have worked. The problem turned out to be a combination of Finn Physics's default collision layer configuration and the way I was creating static shapes. By default, all static shapes are assigned to the "World" layer, and dynamic bodies are on the "Dynamic" layer. Collision between these two layers is enabled, but there's a separate flag for whether static shapes participate in CCD. They don't by default. My stairs were static shapes, and the player was a dynamic circle with a radius of 8 pixels moving at a speed that, combined with the timestep, meant the player could cross more than 8 pixels in a single step. The fix was two-part. First, I enabled CCD on the player body. Second, I created the stair geometry as sensor shapes with a custom collision layer that forced narrow-phase overlap checks at every substep. This added about 4ms to the physics step but eliminated the sticking issue entirely. The root cause was that Finn Physics assumes static geometry doesn't need CCD because it's not moving, but that assumption breaks when the dynamic body is large enough to bridge gaps between static elements.
If you're building a platformer or any game with precise character movement on static geometry, enable CCD on your character and consider using a smaller timestep or sub-stepping. Finn Physics supports sub-stepping through the step function's optional parameter — just pass a smaller delta time and call the step function multiple times per frame. It's not free, but it's significantly cheaper than increasing the solver iteration count.
When Finn Physics Won't Work For You
The biggest limitation is the lack of built-in soft body or deformable body support. If your game needs squash-and-stretch characters, cloth simulation, or destructible terrain with realistic deformation, you'll need to integrate a second library or implement it yourself. There are community plugins for simple cloth simulation, but they're not officially maintained and tend to be unstable. A second limitation is the documentation quality. The API reference is accurate but sparse, and there are very few examples beyond the basic ones in the repository. The GitHub issues section has some valuable discussions about edge cases, but you'll spend time reading through threads to understand why certain behaviors happen. The maintainer is responsive but can only do so much with a single-person project. A third limitation is the 2D-only focus. If you need 3D physics, you're better off with PhysX, Bullet, or even Unity's built-in 3D physics. Finn Physics is not going to do 3D, and the maintainer has stated there are no plans to add it. That's a reasonable boundary to set, but it means the project will always be niche.
Practical Tips That Save Time
Set your fixed timestep to 1/60 and don't try to variable-step the physics. Finn Physics is designed around a fixed timestep, and variable stepping introduces non-deterministic behavior that makes debugging a nightmare. If you need smoother rendering, interpolate the visual position between the last two physics states. Use shape caching where possible. Finn Physics recomputes shape bounding volumes on every collision test, and if you have many similar-shaped objects, you can cache the bounding volumes and reuse them. This saved roughly 15% in CPU time on a project with hundreds of identical crate shapes. Profile your collision layer setup. Finn Physics allows you to disable entire collision layers, which can dramatically reduce pair checks if your game has distinct logical groups that don't need to interact. I disabled collisions between enemy bodies and environmental hazards in one project and cut the physics overhead in half without affecting gameplay.
Don't use the default iteration count blindly. Run a quick benchmark with different iteration counts and pick the lowest number that gives acceptable stability for your specific scene. Going from 10 to 6 iterations is almost always safe. Going from 6 to 3 can introduce noticeable jitter.
Downloading and Setting Up
The source code is available on GitHub under the MIT license, which means you can use it in commercial projects without restrictions. The Python bindings are on PyPI and can be installed with pip install finn-physics. The Cpackage is on NuGet. All bindings track the same version as the C++ core, so you can mix languages if needed — though I don't recommend it unless you have a very specific reason. For C++ projects, the recommended approach is to build the library from source rather than using pre-built binaries, because the pre-built binaries sometimes lag behind the latest commit and you'll miss bug fixes. The build process takes about two minutes on a modern machine. If you run into compilation issues, check the README's dependency list. Finn Physics requires OpenGL 3.3+ for its visualization tools but does not require OpenGL for the core physics library. You can compile without visualization support by setting a cmake flag. Most people hit issues because they try to build the visualization tools on systems that don't have a recent enough OpenGL driver.
Final Thoughts on Using It Productively
Finn Physics is a solid choice for 2D games that need reliable collision and rigid body dynamics without the complexity of a full-featured engine like Box2D. The API is simpler, the performance is adequate for most use cases, and the community is small but active. The tradeoffs are real — limited documentation, no 3D support, no soft bodies — but they're acceptable tradeoffs for the right project. If you're starting a new 2D game and the requirements are straightforward, give Finn Physics a try. The learning curve is shallow, and you'll have a working simulation running in an afternoon. If your project needs advanced features or has unusual performance requirements, evaluate it against alternatives before committing. The best physics engine is the one that fits your game, not the one with the most features on paper. The project is maintained as a side project, so feature requests take time to be addressed. If you need something urgently, consider contributing to the codebase or forking it. The code is clean and well-organized, which makes it relatively easy to modify for your specific needs. That's one of the advantages of a smaller project — you're not fighting against a massive codebase to get the behavior you want.
