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 dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`examples/basic.kit`	Basic usage example
`kit.toml`	Package manifest with metadata and dependencies
`src/body.kit`	Body creation and management
`src/contact.kit`	Contact and collision handling
`src/fixture.kit`	Fixture and shape attachment
`src/joint.kit`	Joint creation and configuration
`src/material.kit`	Material properties (friction, restitution, density)
`src/package.kit`	Package entry point and exports
`src/shape.kit`	Shape definitions (box, circle, polygon)
`src/world.kit`	Physics world management
`tests/world.test.kit`	Tests for world functionality
`zig/build.zig.zon`	Zig build configuration
`zig/physics.zig`	Zig FFI wrapper for Box2D

Dependencies

Package	Source	Description
`geometry`	gitlab.com/kit-lang/packages/kit-geometry	2D and 3D geometry primitives and operations

Installation

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

Usage

import Box2d

main = fn() =>
  # Create world with gravity
  world = Box2d.world-create {x: 0.0, y: -9.8}

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

  # Create a dynamic box
  box = Box2d.body-create world :dynamic{x: 0.0, y: 5.0}
  Box2d.fixture-create box (Box2d.shape-box 1.0 1.0) Box2d.Material.wood

  # Step simulation
  Box2d.world-step world 0.016

  # Get position
  pos = Box2d.body-get-position box
  println "Box position: ${pos.x}, ${pos.y}"

  # Cleanup
  Box2d.world-destroy world

main

Features

World Management - Create and manage physics worlds with custom gravity
Rigid Bodies - Dynamic, static, and kinematic bodies with mass and velocity
Shapes - Boxes, circles, and polygons for collision detection
Fixtures - Attach shapes to bodies with material properties
Joints - Connect bodies with distance, revolute, prismatic, and weld joints
Materials - Configure friction, restitution (bounciness), and density
Collision Detection - Broad-phase and narrow-phase collision detection
Contact Events - Handle collision events between bodies

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit

Compile examples to a native binary:

kit build examples/basic.kit && ./basic

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

Format and check source files in src/
Run tests in tests/ with coverage

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

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 ~/.kit/packages/@kit/box2d/, making it available for import as Box2d in other projects.

License

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

Box2D is 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

`world-destroy`

Destroy a physics world and all its contents

`world-step`

Step the simulation forward by dt seconds

`world-query-aabb`

Query the world for bodies intersecting an AABB

`world-ray-cast`

Cast a ray and return the first body hit

`world-set-contact-callback`

Set a callback for collision events

`BodyType`

Body types

Variants

static

kinematic

dynamic

`body-create`

Create a new body in the world

`body-destroy`

Destroy a body

`body-set-position`

Set body position

`body-get-position`

Get body position

`body-set-angle`

Set body angle (in radians)

`body-get-angle`

Get body angle

`body-set-linear-velocity`

Set linear velocity

`body-get-linear-velocity`

Get linear velocity

`body-apply-force`

Apply force at world point

`body-apply-impulse`

Apply impulse at world point (immediate velocity change)

`body-is-awake?`

Check if body is awake

`body-set-awake`

Set body awake state

`body-get-mass`

Get body mass in kg

`Shape`

Union of all shape types

Variants

Circle {CircleShape}

Box {BoxShape}

Polygon {PolygonShape}

`shape-circle`

Create a circle shape

`shape-box`

Create a box shape (width x height)

`shape-polygon`

Create a polygon from vertices

Contact point information

`ContactCallback`

Callback function type for contact events Return false to ignore this collision

`accept-all?`

Default callback that accepts all collisions

Fixture definition

`fixture-create`

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

`fixture-destroy`

Destroy a fixture

`fixture-set-sensor`

Set fixture as sensor (detects collisions without response)

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

`joint-distance-create`

Create a distance (spring) joint

`joint-prismatic-create`

Create a prismatic (slider) joint

`joint-destroy`

Destroy a joint

`joint-set-motor-speed`

Set motor speed (for motorized joints)

`joint-get-motor-speed`

Get motor speed

`joint-set-max-motor-force`

Set max motor force/torque