Gameplay

2D physics

Give entities bodies and shapes with RigidBody2DComponent and Collider2DComponent, move them with forces or a CharacterBody2DComponent, and react to collisions, sensors and queries.

RigidBody2DComponent says how a body moves and Collider2DComponent gives it a shape. Put them on an entity that has a TransformComponent and the engine simulates it. The 3D components use the same names with a 3D suffix, so what you learn here carries over to 3D physics.

How it fits together

Physics2DSystem is one of the default systems (DefaultSystem.physics, part of DefaultSystems.all). Each fixed step it makes a body for every entity with a Collider2DComponent, applies the forces and velocities you asked for, steps engine.physics, writes the results back to TransformComponent and VelocityComponent, and fires collision and sensor events on world.events. It runs at SystemPriorities.physics (90), after input (100) and player control (95), so a velocity you set in a step moves the body in that same step. See ECS for how priorities work.

Units are world units (pixels in a 2D game) and +Y is down: gravity points along +Y and a jump is −Y. The default gravity is 981 units/s², real gravity at 1 unit = 1 cm. Platformers usually want more, for example engine.physics.setGravity(0, 2000).

Bodies and colliders

A Collider2DComponent on its own is a static body, so floors and walls need nothing else. It behaves like RigidBody2DComponent(bodyType: Body2DType.static) with the default settings. Add a RigidBody2DComponent when the body should move, or when a static body needs its own friction, bounce or layer.

lib/playground.dart
import 'package:flutter/material.dart';
import 'package:just_game_engine/just_game_engine.dart';

void buildPlayground(Engine engine) {
  engine.physics.setGravity(0, 2000);
  final world = engine.world;

  // Static ground: a collider alone. matchShape follows the rectangle.
  world.createEntityWithComponents([
    TransformComponent(position: Vector3(0, 200, 0)),
    Rectangle2DComponent(
      width: 900,
      height: 40,
      fillStyle: const ShapePaintStyle(color: Colors.brown),
    ),
    Collider2DComponent(shape: Collider2DShape.matchShape),
  ], name: 'Ground');

  // A dynamic ball.
  world.createEntityWithComponents([
    TransformComponent(position: Vector3(-100, -200, 0)),
    VelocityComponent(),
    Circle2DComponent(
      radius: 20,
      fillStyle: const ShapePaintStyle(color: Colors.red),
    ),
    RigidBody2DComponent(restitution: 0.7),
    Collider2DComponent(shape: Collider2DShape.circle, radius: 20),
    TagComponent('ball'),
  ], name: 'Ball');

  // A sensor reports overlaps and blocks nothing.
  world.createEntityWithComponents([
    TransformComponent(position: Vector3(300, 140, 0)),
    RigidBody2DComponent(bodyType: Body2DType.static, isSensor: true),
    Collider2DComponent(size: Vector2(80, 80)),
  ], name: 'Goal');

  world.events.on<CollisionEnter2DEvent>((e) {
    debugPrint('${e.entityA.name} touched ${e.entityB.name}');
  });
  world.events.on<SensorEnter2DEvent>((e) {
    if (e.other.hasTag('ball')) debugPrint('Goal!');
  });
}

Body types

bodyTypeMovesUse it for
Body2DType.dynamic (default)by gravity, forces and collisionscrates, balls, debris
Body2DType.kinematiconly by the velocity you give it, and cannot be pushedmoving platforms, lifts
Body2DType.staticneverlevel geometry

isStatic, isKinematic and isDynamic read the type back. A kinematic body you move by writing its transform carries what stands on it.

Rigid body settings

FieldDefaultWhat it does
mass0Mass in kg. 0 works it out from the collider's area: a 100 × 100 box weighs 1000 kg (Collider2DGeometry.autoMassPerSquareUnit).
friction0.5Grip, from 0 (ice) up. A contact uses both bodies' friction.
restitution0Bounce, 0 to 1.
linearDamping0.05Speed a dynamic body loses on its own each second.
angularDamping0.05The same, for spin.
gravityScale10 floats, 2 falls hard. To change it for a while (variable jump height), set gravityScaleOverride; see below.
isSensorfalseReport overlaps and stop nothing: triggers, pickups, zones.
lockRotationfalseNever turn.
continuousCollisionfalseSweep a small, fast body so it cannot pass through thin walls. Native backend only.
canSleeptrueLet a body at rest fall asleep until something touches it.
initialVelocity, initialAngularVelocityzeroWhat the body starts with. A VelocityComponent wins.
layer, collidesWith, groupIndex0, null, 0Collision filtering; see below.

A platformer character usually wants friction: 0, so it slides down walls instead of sticking to them, and lockRotation: true. Friction, bounce and damping you change while the game runs take effect on every platform.

After each step Physics2DSystem fills in linearVelocity, angularVelocity, isAwake, isGrounded, groundEntity and groundNormal. isGrounded stays true for as long as a contact from below lasts.

Gameplay that changes a body for a while sets a run-time field, never a saved one: the components are what a scene saves, so a save in the meantime would keep the change. gravityScaleOverride stands in for gravityScale until it is set back to null, and the body falls by effectiveGravityScale; collidesWithNothing empties the body's collision mask until it is set back to false (effectiveCollidesWith). Neither is saved, and a scene loads without them. A CharacterBody2DComponent has gravityScaleOverride too.

Collider shapes

shapeSized by
Collider2DShape.box (default)size, the full width and height (64 × 64 by default); cornerRadius rounds the corners
Collider2DShape.circleradius
Collider2DShape.capsuleradius and height, the whole height along Y, ends included
Collider2DShape.polygonpoints, a convex polygon of at most 8 points; cornerRadius
Collider2DShape.segmentthe first two points, thickness thick
Collider2DShape.chainevery one of points, closed with loop, thickness thick: terrain
Collider2DShape.matchShapewhatever the entity draws: a rectangle, circle, capsule, polygon or line component, else its sprite's box

A match shape follows the drawing as it changes. Every shape is centred on the entity unless offset moves it, and rotation and scale turn and stretch the collider itself. The collider also grows and shrinks with the entity's scale, as its sprite does; a negative scale on a box, circle or upright capsule does not rebuild the body, so flipping a character to face the other way stays cheap.

oneWay: true makes a platform you can jump up through. oneWayDirection picks the solid side: fromAbove (the default), fromBelow, fromLeft or fromRight. showDebugOutline: false leaves a collider out of the debug outlines (see Debugging).

Moving bodies from code

Push a RigidBody2DComponent with addForce, addImpulse, addTorque, addAngularImpulse, setVelocity, setAngularVelocity and wakeUp. Each applies at the next physics step. You can also write the entity's VelocityComponent, which the physics system picks up, and teleport a body by writing its TransformComponent.

A simple platformer controller is a system at SystemPriorities.playerControl that sets velocity.x from the move action and, when body.isGrounded and jump was pressed, sets velocity.y = -800 (up is −Y). Reading actions is covered in Input.

Character bodies

A CharacterBody2DComponent is a character that gameplay moves rather than the simulation. It walks slopes up to maxSlopeAngle (50° by default), climbs steps up to stepHeight, keeps to the floor going down (stickToFloor), rides moving platforms, stands on one-way platforms and jumps up through them, and pushes dynamic bodies. It needs no RigidBody2DComponent or Collider2DComponent: its shape is its own, a capsule or a box (CharacterBody2DShape), centred on the entity plus offset.

lib/hero.dart
Entity addHero(World world) => world.createEntityWithComponents([
  TransformComponent(),
  InputComponent(),
  Rectangle2DComponent(width: 32, height: 48),
  CharacterBody2DComponent(shape: CharacterBody2DShape.box, width: 32, height: 48),
  TagComponent('player'),
], name: 'Hero');

class HeroControlSystem extends System {
  @override
  int get priority => SystemPriorities.playerControl;

  @override
  List<Type> get requiredComponents => [InputComponent, CharacterBody2DComponent];

  @override
  void update(double deltaTime) {
    forEach((entity) {
      final input = entity.getComponent<InputComponent>()!;
      final body = entity.getComponent<CharacterBody2DComponent>()!;
      body.moveVelocity = Offset(input.vector('move').dx * 260, 0);
      if (body.isGrounded && input.wasPressed('jump')) body.jump(800);
    });
  }
}

While useGravity is on (the default) only the sideways part of moveVelocity counts; the system adds gravity and the ground's own velocity. After each step read velocity, groundState (a Ground2DState), isGrounded, groundNormal, groundVelocity and groundEntity. The character's own body is kinematic, so sensors see it and dynamic bodies bump into it, but it touches static ground through its mover rather than through contacts: read groundEntity to know what it stands on. Set detectable: false to hide it from sensors and rays.

Joints

Put a joint on an entity that has a body and point connectedBody at the other one with an EntityTarget, such as EntityTarget.name('Anchor'). Physics2DSystem makes the joint once both bodies exist, in the same step as them, and remakes it when a setting changes or either body is made again.

JointWhat it doesMain fields
DistanceJoint2DComponentkeeps two bodies a set distance apart, springilylength, stiffness (Hz; 0 holds the length rigidly), damping (a damping ratio)
FixedJoint2DComponentholds two bodies rigidly togethernone
SliderJoint2DComponentlets the bodies slide along one axisaxis, useLimits, minPosition, maxPosition, enableMotor, motorSpeed, motorMaxForce
WheelJoint2DComponenta wheel on a suspensionaxis, stiffness, damping, enableMotor, motorSpeed, motorMaxTorque

Every joint also has anchor, connectedAnchor, collideConnected (false: the two bodies pass through each other) and enabled. Anchors and axes are in their entity's own space, and an anchor of zero is the entity's position. A distance joint keeps anchor on its body and connectedAnchor on the other its length apart; a fixed joint welds the bodies at its anchor; a slider's axis and a wheel's axle run through the other body's connectedAnchor. The inspector shows the anchors each joint takes.

Layers and filtering

Each body sits on one of 16 collision layers, layer: 0 to 15. The project names the layers and says which ones collide in assets/project/physics.json, a PhysicsLayers that the editor's Physics Layers dock writes. Engine.initialize reads it when the app bundles it, so list the file under flutter: assets:. Without it every body collides with every other.

The file lists each layer by number, for example {"version": 1, "layers": [{"index": 1, "name": "Player"}, {"index": 2, "name": "Enemy", "ignores": [2]}]}, where enemies pass through each other. Read the grid in code with engine.context.physicsLayers, for example engine.context.physicsLayers.collides(1, 2).

  • collidesWith is a mask (bit n for layer n) that overrides the grid for one body: RigidBody2DComponent(layer: 2, collidesWith: (1 << 0) | (1 << 2)). Two bodies collide only when each collides with the other's layer.
  • To make a body collide with nothing for a while, such as a crumbling platform, set collidesWithNothing = true, and false to bring it back. Its saved layer and collidesWith stay as they were.
  • groupIndex overrides layers for a group: a positive group always collides with itself, a negative one never does, and 0 leaves it to the layers.

Collision and sensor events

Listen on world.events. Events are per pair of entities, so a chain collider sends one enter and one exit.

EventWhenFields
CollisionEnter2DEventtwo bodies begin touchingentityA, entityB, point, normal (from A towards B), depth
CollisionStay2DEventevery step they keep touching, once you turn it onthe same
CollisionExit2DEventthey stop touchingentityA, entityB
SensorEnter2DEventsomething enters a sensorsensor, other
SensorExit2DEventsomething leaves a sensorsensor, other

Stay events are off so that nothing pays for them unasked. Turn them on with engine.world.getSystem<Physics2DSystem>()?.reportContactStay = true.

Queries

Physics2DQueries casts rays and circles and finds overlaps, answering with entities; Physics2DSystem.queries is the physics system's own. Every query takes a layerMask (all layers by default), an entity to ignore (usually the one asking) and includeSensors (false by default).

lib/vision.dart
/// Whether [guard] can see the player straight ahead.
bool canSeePlayer(Engine engine, Entity guard) {
  final queries = engine.world.getSystem<Physics2DSystem>()!.queries;
  final eyes = guard.getComponent<TransformComponent>()!.position;
  final hit = queries.raycast(
    Offset(eyes.x, eyes.y),
    const Offset(1, 0),
    maxDistance: 300,
    ignore: guard,
  );
  return hit?.entity?.hasTag('player') ?? false;
}

raycastAll returns every hit, nearest first, and circleCast sweeps a circle. overlapCircle and overlapBox (a Rect) return the entities whose shapes they touch. A hit (Physics2DHit) carries entity, body, point, normal, distance and fraction.

Bouncing rays

RayTracer2D traces a ray that bounces: a laser off mirrors, a ricochet. Each straight stretch is a Physics2DQueries.raycast with the same layerMask, ignore and includeSensors, so a trace hits exactly what a ray does. What happens at a hit is up to the collider's Reflectivity (Collider2DComponent.reflectivity, in the inspector's Rays group, saved with the scene): 0, the default, absorbs the ray and ends the trace; above 0, the ray is mirrored about the surface and goes on with what was left of its length times the reflectivity. A body with no collider component (a character) absorbs it. maxBounces (3 by default) caps the bounces, and minReflectivity makes a tracer ignore duller surfaces.

lib/laser.dart
/// The path of a laser from [turret] along [aim], off any mirrors.
List<(Offset, Offset)> laserPath(Engine engine, Entity turret, Offset aim) {
  final queries = engine.world.getSystem<Physics2DSystem>()!.queries;
  final at = turret.getComponent<TransformComponent>()!.position;
  final trace = RayTracer2D(queries, maxBounces: 5).trace(
    Offset(at.x, at.y),
    aim,
    maxDistance: 1200,
    ignore: turret,
  );
  return [for (final segment in trace.segments) (segment.from, segment.to)];
}

Each RayTrace2DSegment has from, to and the hit that ended it (null where the ray ran out); trace.hits lists what the ray struck, in order, and totalLength how far it went. A RayRenderable per segment draws the beam.

Two backends

engine.physics is a Physics2DEngine from just_physics_engine. On native platforms it is Box2D v3 through FFI; on the web (JavaScript and WebAssembly), or wherever the native library does not load, it is a pure-Dart engine with the same API and the same behaviour: joints take their anchors, springs and collideConnected alike, and view culling takes a body out of the simulation on both. Your components, events and queries are the same on both. To choose the engine yourself, pass EngineConfig(createPhysics: ...): for example createPhysics: Physics2DEngine.pureDart runs the pure-Dart engine on every platform.

Known limitations

These wait on just_physics_engine. The fields involved are saved as usual, so scenes need no change when the limits lift.

  • On native Box2D, queries skip bodies whose collision mask is 0 (such as collidesWith: 0, or collidesWithNothing); the pure-Dart backend finds them.
  • continuousCollision works on the native backend only.
  • CollisionEnter2DEvent.depth is always 0, and its point is worked out from where the two bodies' bounds meet, because neither backend reports them in 2D.
  • On native Box2D a static sensor does not report static colliders.
This page as Markdown