Skip to content

MackinnonBuck/Box2D.CSharp

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

66 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Logo

Box2D.CSharp

Build and Test

A C# wrapper for Box2D, a 2D physics engine for games.

Targets .NET Standard 2.0 and uses P/Invoke for native interoperability.

About

This project was created to provide a fast, reliable, and memory-efficient 2D physics engine for games written in C#.

Speed is achieved by compiling Erin Catto's Box2D as a dynamic library with wrapper functions that can be called from managed code using P/Invoke.

Reliability is partly inherited from the C++ Box2D implementation, but is also helped by toggleable access-checking mechanisms designed to catch invalid uses of the API and throw meaningful exceptions.

Memory-efficiency comes from the use of structs for both small copies of unmanaged data and handles to native resources whose lifetime is known but controlled by unmanaged code. Temporary handles to unmanaged resources with unknown lifetimes are represented using ref structs. This differs from C# reimplementations of Box2D that, for example, represent bodies, fixtures, and contact information using classes, which can create significant GC pressure in complex simulations (e.g. those with a high contact frequency).

Status

Currently, a significant but incomplete subset of the full Box2D API is supported. This project is still in its early stages, so breaking design changes are not out of the question. If you notice a missing feature, feel free to create an issue or submit a pull request.

Project Structure

Following is a high-level overview of the project structure:

/src/Box2D: The C# class library exposing the Box2D API. Most of the project lives in here.

/src/Box2DWrapper: A C/C++ wrapper that compiles Box2D as a native DLL. Windows is currently the only supported platform, but migrating to a CMake project for Linux/MacOS support is something being considered for the future.

/test/Testbed: A C# translation of the official Box2D testbed.

/test/UnitTests: C# translations of the official Box2D unit tests.

Contributing

If you find a missing feature (there are lots at the moment!), feel free to create an issue or submit a pull request.

The testbed only has ports of a handful of the official testbed entries, so contributions adding more entries are always welcome (and this could be a good way to find gaps in our API).

Documentation

Our C# API aligns very closely with the original C++ API, so we recommend the Official Box2D Documentation.

Acknowledgements

Box2D by Erin Catto, which serves as the core for this project.

BulletSharpPInvoke by Andres Traks, which partially inspired this project.

About

A C# wrapper for Box2D using P/Invoke

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published