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.
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
bodyType | Moves | Use it for |
|---|---|---|
Body2DType.dynamic (default) | by gravity, forces and collisions | crates, balls, debris |
Body2DType.kinematic | only by the velocity you give it, and cannot be pushed | moving platforms, lifts |
Body2DType.static | never | level 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
| Field | Default | What it does |
|---|---|---|
mass | 0 | Mass in kg. 0 works it out from the collider's area: a 100 × 100 box weighs 1000 kg (Collider2DGeometry.autoMassPerSquareUnit). |
friction | 0.5 | Grip, from 0 (ice) up. A contact uses both bodies' friction. |
restitution | 0 | Bounce, 0 to 1. |
linearDamping | 0.05 | Speed a dynamic body loses on its own each second. |
angularDamping | 0.05 | The same, for spin. |
gravityScale | 1 | 0 floats, 2 falls hard. To change it for a while (variable jump height), set gravityScaleOverride; see below. |
isSensor | false | Report overlaps and stop nothing: triggers, pickups, zones. |
lockRotation | false | Never turn. |
continuousCollision | false | Sweep a small, fast body so it cannot pass through thin walls. Native backend only. |
canSleep | true | Let a body at rest fall asleep until something touches it. |
initialVelocity, initialAngularVelocity | zero | What the body starts with. A VelocityComponent wins. |
layer, collidesWith, groupIndex | 0, null, 0 | Collision 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
shape | Sized by |
|---|---|
Collider2DShape.box (default) | size, the full width and height (64 × 64 by default); cornerRadius rounds the corners |
Collider2DShape.circle | radius |
Collider2DShape.capsule | radius and height, the whole height along Y, ends included |
Collider2DShape.polygon | points, a convex polygon of at most 8 points; cornerRadius |
Collider2DShape.segment | the first two points, thickness thick |
Collider2DShape.chain | every one of points, closed with loop, thickness thick: terrain |
Collider2DShape.matchShape | whatever 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.
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.
| Joint | What it does | Main fields |
|---|---|---|
DistanceJoint2DComponent | keeps two bodies a set distance apart, springily | length, stiffness (Hz; 0 holds the length rigidly), damping (a damping ratio) |
FixedJoint2DComponent | holds two bodies rigidly together | none |
SliderJoint2DComponent | lets the bodies slide along one axis | axis, useLimits, minPosition, maxPosition, enableMotor, motorSpeed, motorMaxForce |
WheelJoint2DComponent | a wheel on a suspension | axis, 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).
collidesWithis a mask (bitnfor layern) 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, andfalseto bring it back. Its savedlayerandcollidesWithstay as they were. groupIndexoverrides 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.
| Event | When | Fields |
|---|---|---|
CollisionEnter2DEvent | two bodies begin touching | entityA, entityB, point, normal (from A towards B), depth |
CollisionStay2DEvent | every step they keep touching, once you turn it on | the same |
CollisionExit2DEvent | they stop touching | entityA, entityB |
SensorEnter2DEvent | something enters a sensor | sensor, other |
SensorExit2DEvent | something leaves a sensor | sensor, 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).
/// 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.
/// 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, orcollidesWithNothing); the pure-Dart backend finds them. continuousCollisionworks on the native backend only.CollisionEnter2DEvent.depthis always 0, and itspointis 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.