box2d

Kind	ffi-zig
Capabilities	ffi
Categories	physics game-development
Keywords	box2d physics collision rigid-body joints simulation

Kit bindings for Box2D v3 - 2D physics engine with rigid bodies, joints, and collision detection

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and generated files
`.tool-versions`	asdf tool versions for local development
`LICENSE`	MIT license file
`README.md`	This file
`examples/basic.kit`	Basic world, body, and fixture example
`examples/contact-events.kit`	Example using world contact callbacks
`examples/joints.kit`	Example creating and stepping joints
`examples/queries.kit`	Example using AABB queries and ray casts
`kit.toml`	Package manifest with metadata, native build settings, and tasks
`src/body.kit`	Body types and body lifecycle/state helpers
`src/contact.kit`	Contact callback record helpers
`src/fixture.kit`	Fixture creation, sensors, and contact queries
`src/joint.kit`	Revolute, distance, and prismatic joint wrappers
`src/material.kit`	Material presets used for fixture creation
`src/package.kit`	Public package entry point exported as `Kit.Box2d`
`src/shape.kit`	Circle, box, and polygon shape constructors
`src/vec2.kit`	Shared 2D vector type
`src/world.kit`	World lifecycle, stepping, queries, and callback registration
`tests/world.test.kit`	Integration-style tests covering world, bodies, fixtures, joints, queries, and callbacks
`zig/box2d.zig`	Zig FFI bridge to the native Box2D library
`zig/kit_ffi.zig`	Shared FFI support used by the Zig bridge

Dependencies

No Kit package dependencies.

Native dependency:

Box2D v3 development libraries must be installed locally.

Install Box2D with your system package manager:

# macOS
brew install box2d

# Ubuntu / Debian
sudo apt install libbox2d-dev

# Fedora
sudo dnf install box2d-devel

Installation

kit add gitlab.com/kit-lang/packages/kit-box2d.git

This package requires FFI support and links against your local Box2D installation during native builds.

Usage

import Kit.Box2d as Box2d

main = fn() =>
  world = Box2d.world-create {x: 0.0, y: -9.8} |> Result.unwrap

  ground = Box2d.body-create world :static{x: 0.0, y: 0.0} |> Result.unwrap
  ground-fixture = Box2d.fixture-create ground (Box2d.shape-box 10.0 1.0) Box2d.Material.ground |> Result.unwrap

  box = Box2d.body-create world :dynamic{x: 0.0, y: 5.0} |> Result.unwrap
  box-fixture = Box2d.fixture-create box (Box2d.shape-box 1.0 1.0) Box2d.Material.wood |> Result.unwrap

  Box2d.world-step world 0.016 |> Result.unwrap

  pos = Box2d.body-get-position box |> Result.unwrap
  println "Box position: ${pos.x}, ${pos.y}"

  Box2d.fixture-destroy box-fixture |> Result.unwrap
  Box2d.fixture-destroy ground-fixture |> Result.unwrap
  Box2d.body-destroy box |> Result.unwrap
  Box2d.body-destroy ground |> Result.unwrap
  Box2d.world-destroy world |> Result.unwrap

main

The public API includes:

World lifecycle and stepping
Static, kinematic, and dynamic bodies
Circle, box, and polygon fixtures
Fixture sensor toggling and current contact queries
Revolute, distance, and prismatic joints
AABB queries and closest-hit ray casting
Contact callbacks with "begin", "end", and "hit" events

Development

Running Examples

Run examples with the interpreter:

kit run --allow=ffi examples/basic.kit

Compile an example to a native binary:

kit build --allow=ffi examples/basic.kit -o /tmp/kit-box2d-basic
/tmp/kit-box2d-basic

Running Tests

Run the test suite:

kit test

The test suite exercises:

World creation, destruction, and invalid-handle behavior
Body state accessors, impulses, and forces
Fixture creation, sensors, and current contact queries
World queries, ray casts, and contact callbacks
Revolute, distance, and prismatic joints

Running kit dev

Run the standard development workflow:

kit dev

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to your local Kit package directory, making it available for import as Kit.Box2d in other projects.

License

This package is released under the MIT License - see LICENSE for details.

Box2D is also released under the MIT License.

Exported Functions & Types

`ground`

Ground material - high friction, no bounce

`wood`

Wood material - medium density and friction

`metal`

Metal material - high density

`bouncy`

Bouncy material - low density, high restitution

Types

`world-create`

Create a new physics world with the given gravity

Vec2 -> Result World String

`world-destroy`

Destroy a physics world and all its contents

World -> Result Unit String

`world-step`

Step the simulation forward by dt seconds

World -> Float -> Result Unit String

`world-query-aabb`

Query the world for bodies intersecting an AABB

World -> Record -> Result List Record String

`world-ray-cast`

Cast a ray and return the first body hit

World -> Vec2 -> Vec2 -> Result Option Record String

`world-set-contact-callback`

Set a callback for collision events

World -> (Record -> Bool) -> Result Unit String

2D vector with x and y coordinates.

Type

`Body`

Body module with rigid body types and helpers.

Module

`Contact`

Contact module with collision callback helpers.

Module

`Fixture`

Fixture module with shape attachment helpers.

Module

`Joint`

Joint module with constraint types and constructors.

Module

`Material`

Material presets and material record helpers.

Module

`Shape`

Shape constructors for circles, boxes, and polygons.

Module

`Vec2`

Vec2 module with the shared 2D vector type.

Module

`World`

World module with simulation lifecycle helpers.

Module

`world-create`

Create a physics world with gravity.

Vec2.Vec2 -> Result World.World String

`world-destroy`

Destroy a physics world.

World.World -> Result Unit String

`world-step`

Advance the simulation by dt seconds.

World.World -> Float -> Result Unit String

`world-query-aabb`

Query the world with an axis-aligned bounds record.

World.World -> Record -> Result List Record String

`world-ray-cast`

Cast a ray through the world.

World.World -> Vec2.Vec2 -> Vec2.Vec2 -> Result Option Record String

`world-set-contact-callback`

World.World -> (Record -> Bool) -> Result Unit String

`body-create`

Create a body in the given world.

World.World -> Body.BodyType -> Vec2.Vec2 -> Result Body.Body String

`body-destroy`

Destroy a body.

Body.Body -> Result Unit String

`body-set-position`

Set a body's position.

Body.Body -> Vec2.Vec2 -> Result Unit String

`body-get-position`

Get a body's position.

Body.Body -> Result Vec2.Vec2 String

`body-set-angle`

Set a body's angle in radians.

Body.Body -> Float -> Result Unit String

`body-get-angle`

Get a body's angle in radians.

Body.Body -> Result Float String

`body-set-linear-velocity`

Set a body's linear velocity.

Body.Body -> Vec2.Vec2 -> Result Unit String

`body-get-linear-velocity`

Get a body's linear velocity.

Body.Body -> Result Vec2.Vec2 String

`body-apply-force`

Apply a force at a world point.

Body.Body -> Vec2.Vec2 -> Vec2.Vec2 -> Result Unit String

`body-apply-impulse`

Apply an impulse at a world point.

Body.Body -> Vec2.Vec2 -> Vec2.Vec2 -> Result Unit String

`body-is-awake?`

Check whether a body is awake.

Body.Body -> Result Bool String

`body-set-awake`

Set whether a body is awake.

Body.Body -> Bool -> Result Unit String

`body-get-mass`

Get a body's mass.

Body.Body -> Result Float String

`shape-circle`

Create a circle shape.

Float -> Shape.Shape

`shape-box`

Create a box shape.

Float -> Float -> Shape.Shape

`shape-polygon`

Create a polygon shape from vertices.

List Vec2.Vec2 -> Shape.Shape

`fixture-create`

Create a fixture for a body and shape.

Body.Body -> Shape.Shape -> Material.Material -> Result Fixture.Fixture String

`fixture-destroy`

Destroy a fixture.

Fixture.Fixture -> Result Unit String

`fixture-set-sensor`

Configure whether a fixture is a sensor.

Fixture.Fixture -> Bool -> Result Unit String

`fixture-get-contacts`

Get the current contacts for a fixture.

Fixture.Fixture -> Result List Record String

`joint-revolute-create`

Create a revolute joint.

Joint.RevoluteJoint -> Result Joint.Joint String

`joint-distance-create`

Create a distance joint.

Joint.DistanceJoint -> Result Joint.Joint String

`joint-prismatic-create`

Create a prismatic joint.

Joint.PrismaticJoint -> Result Joint.Joint String

`joint-destroy`

Destroy a joint.

Joint.Joint -> Result Unit String

`joint-set-motor-speed`

Set a joint motor speed.

Joint.Joint -> Float -> Result Unit String

`joint-get-motor-speed`

Get a joint motor speed.

Joint.Joint -> Result Float String

`joint-set-max-motor-force`

Set a joint max motor force or torque.

Joint.Joint -> Float -> Result Unit String

`accept-all?`

Accept every contact in a callback.

Contact.Contact -> Bool

`BodyType`

Body types

Variants

static

kinematic

dynamic

`body-create`

Create a new body in the world

Record -> BodyType -> Vec2 -> Result Body String

`body-destroy`

Destroy a body

Body -> Result Unit String

`body-set-position`

Set body position

Body -> Vec2 -> Result Unit String

`body-get-position`

Get body position

Body -> Result Vec2 String

`body-set-angle`

Set body angle (in radians)

Body -> Float -> Result Unit String

`body-get-angle`

Get body angle

Body -> Result Float String

`body-set-linear-velocity`

Set linear velocity

Body -> Vec2 -> Result Unit String

`body-get-linear-velocity`

Get linear velocity

Body -> Result Vec2 String

`body-apply-force`

Apply force at world point

Body -> Vec2 -> Vec2 -> Result Unit String

`body-apply-impulse`

Apply impulse at world point (immediate velocity change)

Body -> Vec2 -> Vec2 -> Result Unit String

`body-is-awake?`

Check if body is awake

Body -> Result Bool String

`body-set-awake`

Set body awake state

Body -> Bool -> Result Unit String

`body-get-mass`

Get body mass in kg

Body -> Result Float String

`Shape`

Union of all shape types

Variants

Circle {CircleShape}

Box {BoxShape}

Polygon {PolygonShape}

`shape-circle`

Create a circle shape

Float -> Shape

`shape-box`

Create a box shape (width x height)

Float -> Float -> Shape

`shape-polygon`

Create a polygon from vertices

List Vec2 -> Shape

Contact point information

Type

`accept-all?`

Default callback that accepts all collisions

Contact -> Bool

Fixture definition

Type

`fixture-create`

Create a fixture on a body with the given shape and material

Record -> Record -> Record -> Result Fixture String

`fixture-destroy`

Destroy a fixture

Fixture -> Result Unit String

`fixture-set-sensor`

Set fixture as sensor (detects collisions without response)

Fixture -> Bool -> Result Unit String

`fixture-get-contacts`

Get the current touching contacts for a fixture

Fixture -> Result List Record String

Revolute joint (hinge)

Distance joint (spring/rope)

Prismatic joint (slider)

`Joint`

Joint union

Variants

Revolute {RevoluteJoint}

Distance {DistanceJoint}

Prismatic {PrismaticJoint}

`joint-revolute-create`

Create a revolute (hinge) joint

RevoluteJoint -> Result Joint String

`joint-distance-create`

Create a distance (spring) joint

DistanceJoint -> Result Joint String

`joint-prismatic-create`

Create a prismatic (slider) joint

PrismaticJoint -> Result Joint String

`joint-destroy`

Destroy a joint

Joint -> Result Unit String

`joint-set-motor-speed`

Set motor speed (for motorized joints)

Joint -> Float -> Result Unit String

`joint-get-motor-speed`

Get motor speed

Joint -> Result Float String

`joint-set-max-motor-force`

Set max motor force/torque

Joint -> Float -> Result Unit String