box2d README

The project's README from github.com/erincatto/box2d. As one markdown file: README.md.

Box2D

Box2D is a 2D physics engine for games.

Box2D Logo

Box2D Version 3.0 Release Demo

Build Status

Build Status

Features

Collision

Physics

System

Samples

Building All Platforms

Building with CMake presets

The presets in CMakePresets.json give one build flow on every platform and are picked up automatically by Visual Studio, VS Code, and CLion (open the folder and choose a preset). From the command line:

Use the *-debug build presets for a debug build (not recommended for the replay viewer). The presets use the default native toolchain (the installed Visual Studio on Windows, Make on Linux, Xcode on macOS), so no specific compiler version is required.

Building for Visual Studio

Building for Linux

Building for Xcode

Building and installing

Installing also provides a pkg-config file, so pkg-config --modversion box2d reports the installed version and pkg-config --cflags --libs box2d gives the build flags.

Building with zig

Fetch and link Box2D from a Zig project:

In build.zig:

const box2d_dep = b.dependency("box2d", .{});
exe.root_module.addImport("box2d", box2d_dep.module("box2d"));

In Zig code, start using box2d

const box2d = @import("box2d");

pub fn main(init: std.process.Init) !void {
    var world_def = box2d.b2DefaultWorldDef();
    world_def.gravity.y = 9.8;
    const world_id = box2d.b2CreateWorld(&world_def);
}

Building with Swift Package Manager

Add box2d as a dependency in your Package.swift:

.package(url: "https://github.com/erincatto/box2d.git", from: "main")

And add the product to your target:

.target(
    name: "MyGame",
    dependencies: [.product(name: "box2d", package: "box2d")]
),

In Swift code, the C API is imported directly:

import box2d

var worldDef = b2DefaultWorldDef()
let worldId = b2CreateWorld(&worldDef)

C structs are passed as inout arguments using &.

Replay viewer

The samples app doubles as a viewer for Box2D recordings (.b2rec files). Any preset above builds it. Pass a recording on the command line to open it directly:

On Windows you can also drag a .b2rec file onto samples.exe. The viewer runs from any directory. Without an argument, open a recording from the Replay menu. See docs/recording.md for how to make a recording.

Compatibility

The Box2D library and samples build and run on Windows, Linux, and Mac.

You will need a compiler that supports C17 to build the Box2D library.

You will need a compiler that supports C++20 to build the samples.

Box2D uses SSE2 and Neon (AArch64) SIMD math to improve performance. This can be disabled by defining BOX2D_DISABLE_SIMD.

Documentation

Community

Contributing

Please do not submit pull requests. Instead, please file an issue for bugs or feature requests. For support, please visit the Discord server.

Giving feedback

Please file an issue or start a chat on discord. You can also use GitHub Discussions.

License

Box2D is developed by Erin Catto and uses the MIT license.

Sponsorship

Support development of Box2D through Github Sponsors.

Please consider starring this repository and subscribing to my YouTube channel.

LLM Usage

LLMs are used in the following areas:

Elsewhere all code is developed and written by me. I take responsibility for every line of code in Box2D/3D.

External ports, wrappers, and bindings (unsupported)

box2d (erincatto/box2d)

simd
Searching Database…

10.4K ·GitHub
Box2d
What is this?Box2D is a 2D physics engine for games, handling collision detection, rigid body dynamics, and joints so you can simulate realistic physics in a game.
Is this a full game engine or just a physics library I plug into my own project?It is a C library you build and link into your own game or engine, written in portable C17, not a standalone engine or editor.
How do I build and add Box2D to a project?Install CMake and git, then use the included CMake presets, e.g. 'cmake --preset windows' followed by 'cmake --build --preset windows-release' (similar linux-release/macos presets exist), or build manually with 'cmake .. && cmake --build . && cmake --install .'.
What do I need installed before building it?You need CMake and git on every platform, plus a compiler supporting C17 for the library itself; building the bundled samples app additionally requires a C++20-capable compiler.
Does it only run on specific platforms?The library and samples build and run on Windows, Linux, and macOS with native toolchains (Visual Studio, Make, Xcode respectively).
Can I use Box2D from Zig or Swift instead of C/C++?Yes, it can be fetched as a Zig package with 'zig fetch --save git+...' or added as a dependency via Swift Package Manager, where the C API is imported directly and structs are passed with '&' as inout arguments.
What's the replay viewer for?The samples app doubles as a viewer for recorded physics sessions (.b2rec files); you pass a recording on the command line or drag it onto samples.exe on Windows to play it back.
What shapes and joints does it support?It handles convex polygons, capsules, circles, rounded polygons and chains, plus revolute, prismatic, distance, mouse, weld and wheel joints with limits, motors, springs and friction.
Does it use multithreading or SIMD to go faster?Yes, Box2D uses extensive multithreading and SSE2/Neon SIMD math for performance, which can be turned off via a build flag if needed.
What are similar projects?JoltPhysics, box3d, flame, 2010-rust-rewrite-mashup, matter-js, GDevelop, ebiten, BRUTAL
Which topics is it in?physics-engine, physics-simulation, simd, 2d, physics, multithreading, game-engine, cmake, game-development, game, swift, c
Creator
erincatto
Size
18 MB
Stars
10.4K
Updated
CommitOct 04Releasev3.1.1Jun 04
Age
11y
Commits · 90 Days