Joints

Joints are used to connect two different bodies together in various ways. They help to simulate interactions between objects to create hinges, wheels, ropes, chains etc.

One Body in a joint may be of type BodyType.static. Joints between BodyType.static and/or BodyType.kinematic are allowed, but have no effect and use some processing time.

To construct a Joint, you need to create a corresponding subclass of JointDefand initialize it with its parameters.

To register a Joint use world.createJointand later use world.destroyJoint when you want to remove it.

Built-in joints

Currently, Forge2D supports the following joints:

• ConstantVolumeJoint

• DistanceJoint

• FrictionJoint

• GearJoint

• MotorJoint

• MouseJoint

• PrismaticJoint

• PulleyJoint

• RevoluteJoint

• RopeJoint

• WeldJoint

• WheelJoint

ConstantVolumeJoint

This type of joint connects a group of bodies together and maintains a constant volume within them. Essentially, it is a set of DistanceJoints, that connects all bodies one after another.

It can for example be useful when simulating “soft-bodies”.

  final constantVolumeJoint = ConstantVolumeJointDef()
    ..frequencyHz = 10
    ..dampingRatio = 0.8;

  bodies.forEach((body) {
    constantVolumeJoint.addBody(body);
  });
    
  world.createJoint(ConstantVolumeJoint(world, constantVolumeJoint));

Run

constant_volume_joint.dart

import 'dart:math';

import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/balls.dart';
import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/boundaries.dart';
import 'package:flame/components.dart';
import 'package:flame/events.dart';
import 'package:flame_forge2d/flame_forge2d.dart';

class ConstantVolumeJointExample extends Forge2DGame {
  static const description = '''
    This example shows how to use a `ConstantVolumeJoint`. Tap the screen to add
    a bunch off balls, that maintain a constant volume within them.
  ''';

  ConstantVolumeJointExample() : super(world: SpriteBodyWorld());
}

class SpriteBodyWorld extends Forge2DWorld
    with TapCallbacks, HasGameReference<Forge2DGame> {
  @override
  Future<void> onLoad() async {
    super.onLoad();
    addAll(createBoundaries(game));
  }

  @override
  Future<void> onTapDown(TapDownEvent info) async {
    super.onTapDown(info);
    final center = info.localPosition;

    const numPieces = 20;
    const radius = 5.0;
    final balls = <Ball>[];

    for (var i = 0; i < numPieces; i++) {
      final x = radius * cos(2 * pi * (i / numPieces));
      final y = radius * sin(2 * pi * (i / numPieces));

      final ball = Ball(Vector2(x + center.x, y + center.y), radius: 0.5);

      add(ball);
      balls.add(ball);
    }

    await Future.wait(balls.map((e) => e.loaded));

    final constantVolumeJoint = ConstantVolumeJointDef()
      ..frequencyHz = 10
      ..dampingRatio = 0.8;

    balls.forEach((ball) {
      constantVolumeJoint.addBody(ball.body);
    });

    createJoint(
      ConstantVolumeJoint(
        physicsWorld,
        constantVolumeJoint,
      ),
    );
  }
}

Code

ConstantVolumeJointDef requires at least 3 bodies to be added using the addBody method. It also has two optional parameters:

• frequencyHz: This parameter sets the frequency of oscillation of the joint. If it is not set to 0, the higher the value, the less springy each of the compound DistantJoints are.

• dampingRatio: This parameter defines how quickly the oscillation comes to rest. It ranges from 0 to 1, where 0 means no damping and 1 indicates critical damping.

DistanceJoint

A DistanceJoint constrains two points on two bodies to remain at a fixed distance from each other.

You can view this as a massless, rigid rod.

final distanceJointDef = DistanceJointDef()
  ..initialize(firstBody, secondBody, firstBody.worldCenter, secondBody.worldCenter)
  ..length = 10
  ..frequencyHz = 3
  ..dampingRatio = 0.2;

world.createJoint(DistanceJoint(distanceJointDef));

Run

distance_joint.dart

import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/balls.dart';
import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/boundaries.dart';
import 'package:flame/components.dart';
import 'package:flame/events.dart';
import 'package:flame_forge2d/flame_forge2d.dart';

class DistanceJointExample extends Forge2DGame {
  static const description = '''
    This example shows how to use a `DistanceJoint`. Tap the screen to add a
    pair of balls joined with a `DistanceJoint`.
  ''';

  DistanceJointExample() : super(world: DistanceJointWorld());
}

class DistanceJointWorld extends Forge2DWorld
    with TapCallbacks, HasGameReference<Forge2DGame> {
  @override
  Future<void> onLoad() async {
    super.onLoad();
    addAll(createBoundaries(game));
  }

  @override
  Future<void> onTapDown(TapDownEvent info) async {
    super.onTapDown(info);
    final tap = info.localPosition;

    final first = Ball(tap);
    final second = Ball(Vector2(tap.x + 3, tap.y + 3));
    addAll([first, second]);

    await Future.wait([first.loaded, second.loaded]);

    final distanceJointDef = DistanceJointDef()
      ..initialize(
        first.body,
        second.body,
        first.body.worldCenter,
        second.center,
      )
      ..length = 10
      ..frequencyHz = 3
      ..dampingRatio = 0.2;

    createJoint(DistanceJoint(distanceJointDef));
  }
}

Code

To create a DistanceJointDef, you can use the initialize method, which requires two bodies and a world anchor point on each body. The definition uses local anchor points, allowing for a slight violation of the constraint in the initial configuration. This is useful when saving and loading a game.

The DistanceJointDef has three optional parameters that you can set:

• length: This parameter determines the distance between the two anchor points and must be greater than 0. The default value is 1.

• frequencyHz: This parameter sets the frequency of oscillation of the joint. If it is not set to 0, the higher the value, the less springy the joint becomes.

• dampingRatio: This parameter defines how quickly the oscillation comes to rest. It ranges from 0 to 1, where 0 means no damping and 1 indicates critical damping.

Warning

Do not use a zero or short length.

FrictionJoint

A FrictionJoint is used for simulating friction in a top-down game. It provides 2D translational friction and angular friction.

The FrictionJoint isn’t related to the friction that occurs when two shapes collide in the x-y plane of the screen. Instead, it’s designed to simulate friction along the z-axis, which is perpendicular to the screen. The most common use-case for it is applying the friction force between a moving body and the game floor.

The initialize method of the FrictionJointDef method requires two bodies that will have friction force applied to them, and an anchor.

The third parameter is the anchor point in the world coordinates where the friction force will be applied. In most cases, it would be the center of the first object. However, for more complex physics interactions between bodies, you can set the anchor point to a specific location on one or both of the bodies.

final frictionJointDef = FrictionJointDef()
  ..initialize(ballBody, floorBody, ballBody.worldCenter)
  ..maxForce = 50
  ..maxTorque = 50;

  world.createJoint(FrictionJoint(frictionJointDef));

Run

friction_joint.dart

import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/balls.dart';
import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/boundaries.dart';
import 'package:flame/components.dart';
import 'package:flame/events.dart';
import 'package:flame_forge2d/flame_forge2d.dart';

class FrictionJointExample extends Forge2DGame {
  static const description = '''
    This example shows how to use a `FrictionJoint`. Tap the screen to move the
    ball around and observe it slows down due to the friction force.
  ''';

  FrictionJointExample()
      : super(gravity: Vector2.all(0), world: FrictionJointWorld());
}

class FrictionJointWorld extends Forge2DWorld
    with TapCallbacks, HasGameReference<Forge2DGame> {
  late Wall border;
  late Ball ball;

  @override
  Future<void> onLoad() async {
    super.onLoad();
    final boundaries = createBoundaries(game);
    border = boundaries.first;
    addAll(boundaries);

    ball = Ball(Vector2.zero(), radius: 3);
    add(ball);

    await Future.wait([ball.loaded, border.loaded]);

    createFrictionJoint(ball.body, border.body);
  }

  @override
  Future<void> onTapDown(TapDownEvent info) async {
    super.onTapDown(info);
    ball.body.applyLinearImpulse(Vector2.random() * 5000);
  }

  void createFrictionJoint(Body first, Body second) {
    final frictionJointDef = FrictionJointDef()
      ..initialize(first, second, first.worldCenter)
      ..collideConnected = true
      ..maxForce = 500
      ..maxTorque = 500;

    createJoint(FrictionJoint(frictionJointDef));
  }
}

Code

When creating a FrictionJoint, simulated friction can be applied via maximum force and torque values:

• maxForce: the maximum translational friction which applied to the joined body. A higher value

• simulates higher friction.

• maxTorque: the maximum angular friction which may be applied to the joined body. A higher value

• simulates higher friction.

In other words, the former simulates the friction, when the body is sliding and the latter simulates the friction when the body is spinning.

GearJoint

The GearJoint is used to connect two joints together. Joints are required to be a RevoluteJoint or a PrismaticJoint in any combination.

Warning

The connected joints must attach a dynamic body to a static body. The static body is expected to be a bodyA on those joints

final gearJointDef = GearJointDef()
  ..bodyA = firstJoint.bodyA
  ..bodyB = secondJoint.bodyA
  ..joint1 = firstJoint
  ..joint2 = secondJoint
  ..ratio = 1;

world.createJoint(GearJoint(gearJointDef));

Run

gear_joint.dart

import 'dart:ui';

import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/balls.dart';
import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/boxes.dart';
import 'package:flame/components.dart';
import 'package:flame_forge2d/flame_forge2d.dart';

class GearJointExample extends Forge2DGame {
  static const description = '''
    This example shows how to use a `GearJoint`.

    Drag the box along the specified axis and observe gears respond to the
    translation.
  ''';

  GearJointExample() : super(world: GearJointWorld());
}

class GearJointWorld extends Forge2DWorld with HasGameReference<Forge2DGame> {
  late PrismaticJoint prismaticJoint;
  Vector2 boxAnchor = Vector2.zero();

  double boxWidth = 2;
  double ball1Radius = 4;
  double ball2Radius = 2;

  @override
  Future<void> onLoad() async {
    super.onLoad();

    final box =
        DraggableBox(startPosition: boxAnchor, width: boxWidth, height: 20);
    add(box);

    final ball1Anchor = boxAnchor - Vector2(boxWidth / 2 + ball1Radius, 0);
    final ball1 = Ball(ball1Anchor, radius: ball1Radius);
    add(ball1);

    final ball2Anchor = ball1Anchor - Vector2(ball1Radius + ball2Radius, 0);
    final ball2 = Ball(ball2Anchor, radius: ball2Radius);
    add(ball2);

    await Future.wait([box.loaded, ball1.loaded, ball2.loaded]);

    prismaticJoint = createPrismaticJoint(box.body, boxAnchor);
    final revoluteJoint1 = createRevoluteJoint(ball1.body, ball1Anchor);
    final revoluteJoint2 = createRevoluteJoint(ball2.body, ball2Anchor);

    createGearJoint(prismaticJoint, revoluteJoint1, 1);
    createGearJoint(revoluteJoint1, revoluteJoint2, 0.5);
    add(JointRenderer(joint: prismaticJoint, anchor: boxAnchor));
  }

  PrismaticJoint createPrismaticJoint(Body box, Vector2 anchor) {
    final groundBody = createBody(BodyDef());

    final prismaticJointDef = PrismaticJointDef()
      ..initialize(
        groundBody,
        box,
        anchor,
        Vector2(0, 1),
      )
      ..enableLimit = true
      ..lowerTranslation = -10
      ..upperTranslation = 10;

    final joint = PrismaticJoint(prismaticJointDef);
    createJoint(joint);
    return joint;
  }

  RevoluteJoint createRevoluteJoint(Body ball, Vector2 anchor) {
    final groundBody = createBody(BodyDef());

    final revoluteJointDef = RevoluteJointDef()
      ..initialize(
        groundBody,
        ball,
        anchor,
      );

    final joint = RevoluteJoint(revoluteJointDef);
    createJoint(joint);
    return joint;
  }

  void createGearJoint(Joint first, Joint second, double gearRatio) {
    final gearJointDef = GearJointDef()
      ..bodyA = first.bodyA
      ..bodyB = second.bodyA
      ..joint1 = first
      ..joint2 = second
      ..ratio = gearRatio;

    final joint = GearJoint(gearJointDef);
    createJoint(joint);
  }
}

class JointRenderer extends Component {
  JointRenderer({required this.joint, required this.anchor});

  final PrismaticJoint joint;
  final Vector2 anchor;
  final Vector2 p1 = Vector2.zero();
  final Vector2 p2 = Vector2.zero();

  @override
  void render(Canvas canvas) {
    p1
      ..setFrom(joint.getLocalAxisA())
      ..scale(joint.getLowerLimit())
      ..add(anchor);
    p2
      ..setFrom(joint.getLocalAxisA())
      ..scale(joint.getUpperLimit())
      ..add(anchor);

    canvas.drawLine(p1.toOffset(), p2.toOffset(), debugPaint);
  }
}

Code

• joint1, joint2: Connected revolute or prismatic joints

• bodyA, bodyB: Any bodies form the connected joints, as long as they are not the same body.

• ratio: Gear ratio

Similarly to PulleyJoint, you can specify a gear ratio to bind the motions together:

coordinate1 + ratio * coordinate2 == constant 

The ratio can be negative or positive. If one joint is a RevoluteJoint and the other joint is a PrismaticJoint, then the ratio will have units of length or units of 1/length.

Since the GearJoint depends on two other joints, if these are destroyed, the GearJoint needs to be destroyed as well.

Warning

Manually destroy the GearJoint if joint1 or joint2 is destroyed

MotorJoint

A MotorJoint is used to control the relative motion between two bodies. A typical usage is to control the movement of a dynamic body with respect to the fixed point, for example to create animations.

A MotorJoint lets you control the motion of a body by specifying target position and rotation offsets. You can set the maximum motor force and torque that will be applied to reach the target position and rotation. If the body is blocked, it will stop and the contact forces will be proportional the maximum motor force and torque.

final motorJointDef = MotorJointDef()
  ..initialize(first, second)
  ..maxTorque = 1000
  ..maxForce = 1000
  ..correctionFactor = 0.1;

  world.createJoint(MotorJoint(motorJointDef));

Run

motor_joint.dart

import 'dart:ui';

import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/balls.dart';
import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/boxes.dart';
import 'package:flame/components.dart';
import 'package:flame/events.dart';
import 'package:flame_forge2d/flame_forge2d.dart';

class MotorJointExample extends Forge2DGame {
  static const description = '''
    This example shows how to use a `MotorJoint`. The ball spins around the
    center point. Tap the screen to change the direction.
  ''';

  MotorJointExample()
      : super(gravity: Vector2.zero(), world: MotorJointWorld());
}

class MotorJointWorld extends Forge2DWorld with TapCallbacks {
  late Ball ball;
  late MotorJoint joint;
  final motorSpeed = 1;

  bool clockWise = true;

  @override
  Future<void> onLoad() async {
    super.onLoad();

    final box = Box(
      startPosition: Vector2.zero(),
      width: 2,
      height: 1,
      bodyType: BodyType.static,
    );
    add(box);

    ball = Ball(Vector2(0, -5));
    add(ball);

    await Future.wait([ball.loaded, box.loaded]);

    joint = createMotorJoint(ball.body, box.body);
    add(JointRenderer(joint: joint));
  }

  @override
  void onTapDown(TapDownEvent info) {
    super.onTapDown(info);
    clockWise = !clockWise;
  }

  MotorJoint createMotorJoint(Body first, Body second) {
    final motorJointDef = MotorJointDef()
      ..initialize(first, second)
      ..maxForce = 1000
      ..maxTorque = 1000
      ..correctionFactor = 0.1;

    final joint = MotorJoint(motorJointDef);
    createJoint(joint);
    return joint;
  }

  final linearOffset = Vector2.zero();

  @override
  void update(double dt) {
    super.update(dt);

    var deltaOffset = motorSpeed * dt;
    if (clockWise) {
      deltaOffset = -deltaOffset;
    }

    final linearOffsetX = joint.getLinearOffset().x + deltaOffset;
    final linearOffsetY = joint.getLinearOffset().y + deltaOffset;
    linearOffset.setValues(linearOffsetX, linearOffsetY);
    final angularOffset = joint.getAngularOffset() + deltaOffset;

    joint.setLinearOffset(linearOffset);
    joint.setAngularOffset(angularOffset);
  }
}

class JointRenderer extends Component {
  JointRenderer({required this.joint});

  final MotorJoint joint;

  @override
  void render(Canvas canvas) {
    canvas.drawLine(
      joint.anchorA.toOffset(),
      joint.anchorB.toOffset(),
      debugPaint,
    );
  }
}

Code

A MotorJointDef has three optional parameters:

• maxForce: the maximum translational force which will be applied to the joined body to reach the target position.

• maxTorque: the maximum angular force which will be applied to the joined body to reach the target rotation.

• correctionFactor: position correction factor in range [0, 1]. It adjusts the joint’s response to deviation from target position. A higher value makes the joint respond faster, while a lower value makes it respond slower. If the value is set too high, the joint may overcompensate and oscillate, becoming unstable. If set too low, it may respond too slowly.

The linear and angular offsets are the target distance and angle that the bodies should achieve relative to each other’s position and rotation. By default, the linear target will be the distance between the two body centers and the angular target will be the relative rotation of the bodies. Use the setLinearOffset(Vector2) and setLinearOffset(double) methods of the MotorJoint to set the desired relative translation and rotate between the bodies.

For example, this code increments the angular offset of the joint every update cycle, causing the body to rotate.

@override
void update(double dt) {
  super.update(dt);
  
  final angularOffset = joint.getAngularOffset() + motorSpeed * dt;
  joint.setAngularOffset(angularOffset);
}

MouseJoint

The MouseJoint is used to manipulate bodies with the mouse. It attempts to drive a point on a body towards the current position of the cursor. There is no restriction on rotation.

The MouseJoint definition has a target point, maximum force, frequency, and damping ratio. The target point initially coincides with the body’s anchor point. The maximum force is used to prevent violent reactions when multiple dynamic bodies interact. You can make this as large as you like. The frequency and damping ratio are used to create a spring/damper effect similar to the distance joint.

Warning

Many users have tried to adapt the mouse joint for game play. Users often want to achieve precise positioning and instantaneous response. The mouse joint doesn’t work very well in that context. You may wish to consider using kinematic bodies instead.

final mouseJointDef = MouseJointDef()
  ..maxForce = 3000 * ballBody.mass * 10
  ..dampingRatio = 1
  ..frequencyHz = 5
  ..target.setFrom(ballBody.position)
  ..collideConnected = false
  ..bodyA = groundBody
  ..bodyB = ballBody;

  mouseJoint = MouseJoint(mouseJointDef);
  world.createJoint(mouseJoint);
}

Run

mouse_joint.dart

import 'package:examples/stories/bridge_libraries/flame_forge2d/revolute_joint_with_motor_example.dart';
import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/balls.dart';
import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/boundaries.dart';
import 'package:flame/components.dart';
import 'package:flame/events.dart';
import 'package:flame_forge2d/flame_forge2d.dart';

class MouseJointExample extends Forge2DGame {
  static const description = '''
    In this example we use a `MouseJoint` to make the ball follow the mouse
    when you drag it around.
  ''';

  MouseJointExample()
      : super(gravity: Vector2(0, 10.0), world: MouseJointWorld());
}

class MouseJointWorld extends Forge2DWorld
    with DragCallbacks, HasGameReference<Forge2DGame> {
  late Ball ball;
  late Body groundBody;
  MouseJoint? mouseJoint;

  @override
  Future<void> onLoad() async {
    super.onLoad();
    final boundaries = createBoundaries(game);
    addAll(boundaries);

    final center = Vector2.zero();
    groundBody = createBody(BodyDef());
    ball = Ball(center, radius: 5);
    add(ball);
    add(CornerRamp(center));
    add(CornerRamp(center, isMirrored: true));
  }

  @override
  void onDragStart(DragStartEvent info) {
    super.onDragStart(info);
    if (mouseJoint != null) {
      return;
    }
    final mouseJointDef = MouseJointDef()
      ..maxForce = 3000 * ball.body.mass * 10
      ..dampingRatio = 0.1
      ..frequencyHz = 5
      ..target.setFrom(ball.body.position)
      ..collideConnected = false
      ..bodyA = groundBody
      ..bodyB = ball.body;

    mouseJoint = MouseJoint(mouseJointDef);
    createJoint(mouseJoint!);
  }

  @override
  void onDragUpdate(DragUpdateEvent info) {
    mouseJoint?.setTarget(info.localEndPosition);
  }

  @override
  void onDragEnd(DragEndEvent info) {
    super.onDragEnd(info);
    destroyJoint(mouseJoint!);
    mouseJoint = null;
  }
}

Code

• maxForce: This parameter defines the maximum constraint force that can be exerted to move the candidate body. Usually you will express as some multiple of the weight (multiplier mass gravity).

• dampingRatio: This parameter defines how quickly the oscillation comes to rest. It ranges from 0 to 1, where 0 means no damping and 1 indicates critical damping.

• frequencyHz: This parameter defines the response speed of the body, i.e. how quickly it tries to reach the target position

• target: The initial world target point. This is assumed to coincide with the body anchor initially.

PrismaticJoint

The PrismaticJoint provides a single degree of freedom, allowing for a relative translation of two bodies along an axis fixed in bodyA. Relative rotation is prevented.

PrismaticJointDef requires defining a line of motion using an axis and an anchor point. The definition uses local anchor points and a local axis so that the initial configuration can violate the constraint slightly.

The joint translation is zero when the local anchor points coincide in world space. Using local anchors and a local axis helps when saving and loading a game.

Warning

At least one body should by dynamic with a non-fixed rotation.

The PrismaticJoint definition is similar to the RevoluteJoint definition, but instead of rotation, it uses translation.

final prismaticJointDef = PrismaticJointDef()
  ..initialize(
    dynamicBody,
    groundBody,
    dynamicBody.worldCenter,
    Vector2(1, 0),
  )

Run

prismatic_joint.dart

import 'dart:ui';

import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/boxes.dart';
import 'package:flame/components.dart';
import 'package:flame_forge2d/flame_forge2d.dart';

class PrismaticJointExample extends Forge2DGame {
  static const description = '''
    This example shows how to use a `PrismaticJoint`.

    Drag the box along the specified axis, bound between lower and upper limits.
    Also, there's a motor enabled that's pulling the box to the lower limit.
  ''';

  final Vector2 anchor = Vector2.zero();

  @override
  Future<void> onLoad() async {
    super.onLoad();

    final box = DraggableBox(startPosition: anchor, width: 6, height: 6);
    world.add(box);
    await Future.wait([box.loaded]);

    final joint = createJoint(box.body, anchor);
    world.add(JointRenderer(joint: joint, anchor: anchor));
  }

  PrismaticJoint createJoint(Body box, Vector2 anchor) {
    final groundBody = world.createBody(BodyDef());

    final prismaticJointDef = PrismaticJointDef()
      ..initialize(
        box,
        groundBody,
        anchor,
        Vector2(1, 0),
      )
      ..enableLimit = true
      ..lowerTranslation = -20
      ..upperTranslation = 20
      ..enableMotor = true
      ..motorSpeed = 1
      ..maxMotorForce = 100;

    final joint = PrismaticJoint(prismaticJointDef);
    world.createJoint(joint);
    return joint;
  }
}

class JointRenderer extends Component {
  JointRenderer({required this.joint, required this.anchor});

  final PrismaticJoint joint;
  final Vector2 anchor;
  final Vector2 p1 = Vector2.zero();
  final Vector2 p2 = Vector2.zero();

  @override
  void render(Canvas canvas) {
    p1
      ..setFrom(joint.getLocalAxisA())
      ..scale(joint.getLowerLimit())
      ..add(anchor);
    p2
      ..setFrom(joint.getLocalAxisA())
      ..scale(joint.getUpperLimit())
      ..add(anchor);

    canvas.drawLine(p1.toOffset(), p2.toOffset(), debugPaint);
  }
}

Code

• b1, b2: Bodies connected by the joint.

• anchor: World anchor point, to put the axis through. Usually the center of the first body.

• axis: World translation axis, along which the translation will be fixed.

In some cases you might wish to control the range of motion. For this, the PrismaticJointDef has optional parameters that allow you to simulate a joint limit and/or a motor.

Prismatic Joint Limit

You can limit the relative rotation with a joint limit that specifies a lower and upper translation.

jointDef
  ..enableLimit = true
  ..lowerTranslation = -20
  ..upperTranslation = 20;

• enableLimit: Set to true to enable translation limits

• lowerTranslation: The lower translation limit in meters

• upperTranslation: The upper translation limit in meters

You change the limits after the joint was created with this method:

prismaticJoint.setLimits(-10, 10);

Prismatic Joint Motor

You can use a motor to drive the motion or to model joint friction. A maximum motor force is provided so that infinite forces are not generated.

jointDef
  ..enableMotor = true
  ..motorSpeed = 1
  ..maxMotorForce = 100;

• enableMotor: Set to true to enable the motor

• motorSpeed: The desired motor speed in radians per second

• maxMotorForce: The maximum motor torque used to achieve the desired motor speed in N-m.

You change the motor’s speed and force after the joint was created using these methods:

prismaticJoint.setMotorSpeed(2);
prismaticJoint.setMaxMotorForce(200);

Also, you can get the joint angle and speed using the following methods:

prismaticJoint.getJointTranslation();
prismaticJoint.getJointSpeed();

PulleyJoint

A PulleyJoint is used to create an idealized pulley. The pulley connects two bodies to the ground and to each other. As one body goes up, the other goes down. The total length of the pulley rope is conserved according to the initial configuration:

length1 + length2 == constant

You can supply a ratio that simulates a block and tackle. This causes one side of the pulley to extend faster than the other. At the same time the constraint force is smaller on one side than the other. You can use this to create a mechanical leverage.

length1 + ratio * length2 == constant

For example, if the ratio is 2, then length1 will vary at twice the rate of length2. Also the force in the rope attached to the first body will have half the constraint force as the rope attached to the second body.

final pulleyJointDef = PulleyJointDef()
  ..initialize(
    firstBody,
    secondBody,
    firstPulley.worldCenter,
    secondPulley.worldCenter,
    firstBody.worldCenter,     
    secondBody.worldCenter,
    1,
  );

world.createJoint(PulleyJoint(pulleyJointDef));

Run

pulley_joint.dart

import 'dart:ui';

import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/balls.dart';
import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/boxes.dart';
import 'package:flame/components.dart';
import 'package:flame_forge2d/flame_forge2d.dart';

class PulleyJointExample extends Forge2DGame {
  static const description = '''
    This example shows how to use a `PulleyJoint`. Drag one of the boxes and see
    how the other one gets moved by the pulley
  ''';

  @override
  Future<void> onLoad() async {
    super.onLoad();
    final distanceFromCenter = camera.visibleWorldRect.width / 5;

    final firstPulley = Ball(
      Vector2(-distanceFromCenter, -10),
      bodyType: BodyType.static,
    );
    final secondPulley = Ball(
      Vector2(distanceFromCenter, -10),
      bodyType: BodyType.static,
    );

    final firstBox = DraggableBox(
      startPosition: Vector2(-distanceFromCenter, 20),
      width: 5,
      height: 10,
    );
    final secondBox = DraggableBox(
      startPosition: Vector2(distanceFromCenter, 20),
      width: 7,
      height: 10,
    );
    world.addAll([firstBox, secondBox, firstPulley, secondPulley]);

    await Future.wait([
      firstBox.loaded,
      secondBox.loaded,
      firstPulley.loaded,
      secondPulley.loaded,
    ]);

    final joint = createJoint(firstBox, secondBox, firstPulley, secondPulley);
    world.add(PulleyRenderer(joint: joint));
  }

  PulleyJoint createJoint(
    Box firstBox,
    Box secondBox,
    Ball firstPulley,
    Ball secondPulley,
  ) {
    final pulleyJointDef = PulleyJointDef()
      ..initialize(
        firstBox.body,
        secondBox.body,
        firstPulley.center,
        secondPulley.center,
        firstBox.body.worldPoint(Vector2(0, -firstBox.height / 2)),
        secondBox.body.worldPoint(Vector2(0, -secondBox.height / 2)),
        1,
      );
    final joint = PulleyJoint(pulleyJointDef);
    world.createJoint(joint);
    return joint;
  }
}

class PulleyRenderer extends Component {
  PulleyRenderer({required this.joint});

  final PulleyJoint joint;

  @override
  void render(Canvas canvas) {
    canvas.drawLine(
      joint.anchorA.toOffset(),
      joint.getGroundAnchorA().toOffset(),
      debugPaint,
    );

    canvas.drawLine(
      joint.anchorB.toOffset(),
      joint.getGroundAnchorB().toOffset(),
      debugPaint,
    );

    canvas.drawLine(
      joint.getGroundAnchorA().toOffset(),
      joint.getGroundAnchorB().toOffset(),
      debugPaint,
    );
  }
}

Code

The initialize method of PulleyJointDef requires two ground anchors, two dynamic bodies and their anchor points, and a pulley ratio.

• b1, b2: Two dynamic bodies connected with the joint

• ga1, ga2: Two ground anchors

• anchor1, anchor2: Anchors on the dynamic bodies the joint will be attached to

• r: Pulley ratio to simulate a block and tackle

PulleyJoint also provides the current lengths:

joint.getCurrentLengthA()
joint.getCurrentLengthB()

Warning

PulleyJoint can get a bit troublesome by itself. They often work better when combined with prismatic joints. You should also cover the anchor points with static shapes to prevent one side from going to zero length.

RevoluteJoint

A RevoluteJoint forces two bodies to share a common anchor point, often called a hinge point. The revolute joint has a single degree of freedom: the relative rotation of the two bodies.

To create a RevoluteJoint, provide two bodies and a common point to the initialize method. The definition uses local anchor points so that the initial configuration can violate the constraint slightly.

final jointDef = RevoluteJointDef()
  ..initialize(firstBody, secondBody, firstBody.position);
world.createJoint(RevoluteJoint(jointDef));

Run

revolute_joint.dart

import 'dart:math';

import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/balls.dart';
import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/boundaries.dart';
import 'package:flame/components.dart';
import 'package:flame/events.dart';
import 'package:flame_forge2d/flame_forge2d.dart';

class RevoluteJointExample extends Forge2DGame {
  static const description = '''
    In this example we use a joint to keep a body with several fixtures stuck
    to another body.

    Tap the screen to add more of these combined bodies.
  ''';

  RevoluteJointExample()
      : super(gravity: Vector2(0, 10.0), world: RevoluteJointWorld());
}

class RevoluteJointWorld extends Forge2DWorld
    with TapCallbacks, HasGameReference<Forge2DGame> {
  @override
  Future<void> onLoad() async {
    super.onLoad();
    addAll(createBoundaries(game));
  }

  @override
  void onTapDown(TapDownEvent info) {
    super.onTapDown(info);
    final ball = Ball(info.localPosition);
    add(ball);
    add(CircleShuffler(ball));
  }
}

class CircleShuffler extends BodyComponent {
  final Ball ball;

  CircleShuffler(this.ball);

  @override
  Body createBody() {
    final bodyDef = BodyDef(
      type: BodyType.dynamic,
      position: ball.body.position.clone(),
    );
    const numPieces = 5;
    const radius = 6.0;
    final body = world.createBody(bodyDef);

    for (var i = 0; i < numPieces; i++) {
      final xPos = radius * cos(2 * pi * (i / numPieces));
      final yPos = radius * sin(2 * pi * (i / numPieces));

      final shape = CircleShape()
        ..radius = 1.2
        ..position.setValues(xPos, yPos);

      final fixtureDef = FixtureDef(
        shape,
        density: 50.0,
        friction: 0.1,
        restitution: 0.9,
      );

      body.createFixture(fixtureDef);
    }

    final jointDef = RevoluteJointDef()
      ..initialize(body, ball.body, body.position);
    world.createJoint(RevoluteJoint(jointDef));

    return body;
  }
}

Code

In some cases you might wish to control the joint angle. For this, the RevoluteJointDef has optional parameters that allow you to simulate a joint limit and/or a motor.

Revolute Joint Limit

You can limit the relative rotation with a joint limit that specifies a lower and upper angle.

jointDef
  ..enableLimit = true
  ..lowerAngle = 0
  ..upperAngle = pi / 2;

• enableLimit: Set to true to enable angle limits

• lowerAngle: The lower angle in radians

• upperAngle: The upper angle in radians

You change the limits after the joint was created with this method:

revoluteJoint.setLimits(0, pi);

Revolute Joint Motor

You can use a motor to drive the relative rotation about the shared point. A maximum motor torque is provided so that infinite forces are not generated.

jointDef
  ..enableMotor = true
  ..motorSpeed = 5
  ..maxMotorTorque = 100;

• enableMotor: Set to true to enable the motor

• motorSpeed: The desired motor speed in radians per second

• maxMotorTorque: The maximum motor torque used to achieve the desired motor speed in N-m.

You change the motor’s speed and torque after the joint was created using these methods:

revoluteJoint.setMotorSpeed(2);
revoluteJoint.setMaxMotorTorque(200);

Also, you can get the joint angle and speed using the following methods:

revoluteJoint.jointAngle();
revoluteJoint.jointSpeed();

RopeJoint

A RopeJoint restricts the maximum distance between two points on two bodies.

RopeJointDef requires two body anchor points and the maximum length.

final ropeJointDef = RopeJointDef()
  ..bodyA = firstBody
  ..localAnchorA.setFrom(firstBody.getLocalCenter())
  ..bodyB = secondBody
  ..localAnchorB.setFrom(secondBody.getLocalCenter())
  ..maxLength = (secondBody.worldCenter - firstBody.worldCenter).length;

world.createJoint(RopeJoint(ropeJointDef));

Run

rope_joint.dart

import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/balls.dart';
import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/boxes.dart';
import 'package:flame/components.dart';
import 'package:flame/events.dart';
import 'package:flame_forge2d/flame_forge2d.dart';
import 'package:flutter/material.dart';

class RopeJointExample extends Forge2DGame {
  static const description = '''
    This example shows how to use a `RopeJoint`.

    Drag the box handle along the axis and observe the rope respond to the
    movement.
  ''';

  RopeJointExample() : super(world: RopeJointWorld());
}

class RopeJointWorld extends Forge2DWorld
    with DragCallbacks, HasGameReference<Forge2DGame> {
  double handleWidth = 6;

  @override
  Future<void> onLoad() async {
    super.onLoad();

    final handleBody = await createHandle();
    createRope(handleBody);
  }

  Future<Body> createHandle() async {
    final anchor = game.screenToWorld(Vector2(0, 100))..x = 0;

    final box = DraggableBox(
      startPosition: anchor,
      width: handleWidth,
      height: 3,
    );
    await add(box);

    createPrismaticJoint(box.body, anchor);
    return box.body;
  }

  Future<void> createRope(Body handle) async {
    const length = 50;
    var prevBody = handle;

    for (var i = 0; i < length; i++) {
      final newPosition = prevBody.worldCenter + Vector2(0, 1);
      final ball = Ball(newPosition, radius: 0.5, color: Colors.white);
      await add(ball);

      createRopeJoint(ball.body, prevBody);
      prevBody = ball.body;
    }
  }

  void createPrismaticJoint(Body box, Vector2 anchor) {
    final groundBody = createBody(BodyDef());
    final halfWidth = game.screenToWorld(Vector2.zero()).x.abs();

    final prismaticJointDef = PrismaticJointDef()
      ..initialize(
        box,
        groundBody,
        anchor,
        Vector2(1, 0),
      )
      ..enableLimit = true
      ..lowerTranslation = -halfWidth + handleWidth / 2
      ..upperTranslation = halfWidth - handleWidth / 2;

    final joint = PrismaticJoint(prismaticJointDef);
    createJoint(joint);
  }

  void createRopeJoint(Body first, Body second) {
    final ropeJointDef = RopeJointDef()
      ..bodyA = first
      ..localAnchorA.setFrom(first.getLocalCenter())
      ..bodyB = second
      ..localAnchorB.setFrom(second.getLocalCenter())
      ..maxLength = (second.worldCenter - first.worldCenter).length;

    createJoint(RopeJoint(ropeJointDef));
  }
}

Code

• bodyA, bodyB: Connected bodies

• localAnchorA, localAnchorB: Optional parameter, anchor point relative to the body’s origin.

• maxLength: The maximum length of the rope. This must be larger than linearSlop, or the joint will have no effect.

Warning

The joint assumes that the maximum length doesn’t change during simulation. See DistanceJoint if you want to dynamically control length.

WeldJoint

A WeldJoint is used to restrict all relative motion between two bodies, effectively joining them together.

WeldJointDef requires two bodies that will be connected, and a world anchor:

final weldJointDef = WeldJointDef()
  ..initialize(bodyA, bodyB, anchor);

world.createJoint(WeldJoint(weldJointDef));

Run

weld_joint.dart

import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/balls.dart';
import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/boxes.dart';
import 'package:flame/components.dart';
import 'package:flame/events.dart';
import 'package:flame_forge2d/flame_forge2d.dart';
import 'package:flutter/material.dart';

class WeldJointExample extends Forge2DGame {
  static const description = '''
    This example shows how to use a `WeldJoint`. Tap the screen to add a
    ball to test the bridge built using a `WeldJoint`
  ''';

  WeldJointExample() : super(world: WeldJointWorld());
}

class WeldJointWorld extends Forge2DWorld
    with TapCallbacks, HasGameReference<Forge2DGame> {
  final pillarHeight = 20.0;
  final pillarWidth = 5.0;

  @override
  Future<void> onLoad() async {
    super.onLoad();

    final leftPillar = Box(
      startPosition: game.screenToWorld(Vector2(50, game.size.y))
        ..y -= pillarHeight / 2,
      width: pillarWidth,
      height: pillarHeight,
      bodyType: BodyType.static,
      color: Colors.white,
    );
    final rightPillar = Box(
      startPosition: game.screenToWorld(Vector2(game.size.x - 50, game.size.y))
        ..y -= pillarHeight / 2,
      width: pillarWidth,
      height: pillarHeight,
      bodyType: BodyType.static,
      color: Colors.white,
    );

    await addAll([leftPillar, rightPillar]);

    createBridge(leftPillar, rightPillar);
  }

  Future<void> createBridge(
    Box leftPillar,
    Box rightPillar,
  ) async {
    const sectionsCount = 10;
    // Vector2.zero is used here since 0,0 is in the middle and 0,0 in the
    // screen space then gives us the coordinates of the upper left corner in
    // world space.
    final halfSize = game.screenToWorld(Vector2.zero())..absolute();
    final sectionWidth = ((leftPillar.center.x.abs() +
                rightPillar.center.x.abs() +
                pillarWidth) /
            sectionsCount)
        .ceilToDouble();
    Body? prevSection;

    for (var i = 0; i < sectionsCount; i++) {
      final section = Box(
        startPosition: Vector2(
          sectionWidth * i - halfSize.x + sectionWidth / 2,
          halfSize.y - pillarHeight,
        ),
        width: sectionWidth,
        height: 1,
      );
      await add(section);

      if (prevSection != null) {
        createWeldJoint(
          prevSection,
          section.body,
          Vector2(
            sectionWidth * i - halfSize.x + sectionWidth,
            halfSize.y - pillarHeight,
          ),
        );
      }

      prevSection = section.body;
    }
  }

  void createWeldJoint(Body first, Body second, Vector2 anchor) {
    final weldJointDef = WeldJointDef()..initialize(first, second, anchor);

    createJoint(WeldJoint(weldJointDef));
  }

  @override
  Future<void> onTapDown(TapDownEvent info) async {
    super.onTapDown(info);
    final ball = Ball(info.localPosition, radius: 5);
    add(ball);
  }
}

Code

• bodyA, bodyB: Two bodies that will be connected

• anchor: Anchor point in world coordinates, at which two bodies will be welded together to 0, the higher the value, the less springy the joint becomes.

Breakable Bodies and WeldJoint

Since the Forge2D constraint solver is iterative, joints are somewhat flexible. This means that the bodies connected by a WeldJoint may bend slightly. If you want to simulate a breakable body, it’s better to create a single body with multiple fixtures. When the body breaks, you can destroy a fixture and recreate it on a new body instead of relying on a WeldJoint.