Physics and collisions

Physics lets objects collide, fall, slide, trigger areas, and respond to forces. Opal uses a 2D physics runtime backed by Rapier when available.

Core components

Physics behavior usually starts with two components:

Component	Purpose
Collider 2D	Defines the collision shape
Rigid Body 2D	Defines how the object moves in the physics world

An object can have a collider without a rigid body when it should act as a static obstacle or sensor. Moving physical objects usually need both.

Body types

Body type	Use
Dynamic	Moved by physics, gravity, collisions, impulses
Fixed / static	Immovable walls, floors, platforms
Kinematic	Moved by scripts or animation while still participating in contacts

Use fixed bodies for level geometry. Use dynamic bodies for crates, balls, loose enemies, and objects affected by gravity. Use kinematic bodies for platforms or controlled characters.

Collider shapes

Common shapes:

Shape	Good for
Box	Platforms, walls, rectangular props
Circle	Balls, round pickups, radial trigger zones
Capsule	Characters and enemies
Polygon / custom	Irregular objects when supported

Keep colliders simple. A visually detailed sprite usually plays better with a simple collider than with a collider that exactly traces every pixel.

Sensors and triggers

A sensor detects overlap without physically blocking movement.

Use sensors for:

• Collectible pickup radius
• Door or portal trigger
• Enemy sight range
• Damage zones
• UI-like world interaction areas

Sensor events are handled in Object Flow or Scene Flow, depending on whether the logic belongs to one object or the whole scene.

Collision events in Flow

Physics events can drive graphs.

Common graph patterns:

Pattern	Example
Collision starts	Player touches hazard, take damage
Collision ends	Player leaves ladder or water area
Sensor overlap	Pickup coin, open prompt, trigger dialog
Hit response	Play sound, spawn VFX, destroy projectile

Attach the needed Collider 2D and Rigid Body 2D components before expecting collision events to fire.

For sticky arrows / bolts, add Projectile on top of a dynamic Rigid Body 2D (enable Continuous Collision) and Collider 2D — it aligns to velocity and can weld into what it hits. See Built-in reference — Projectile.

Character movement

For platformers or top-down games, prefer a controller component when one fits the game. Controllers package common movement rules so you do not have to hand-build every gravity, ground, acceleration, and collision detail in a graph.

Common movement components include:

• Side-scroller controller
• Platformer controller
• Top-down controller

Use flow graphs to set intent, such as direction, jump, attack, or interact. Let the controller handle movement details.

Physics tuning

Useful tuning fields can include:

Field	Effect
Gravity scale	How strongly gravity affects the body
Friction	How much surfaces slow sliding
Restitution	Bounce
Mass / density	How strongly forces affect the body
Collision groups	Which objects can collide or overlap

Start with simple defaults, then tune one field at a time while testing in Play mode.

Debugging collisions

If collisions are not working:

1. Confirm both objects have appropriate colliders.
2. Confirm at least one participant is set up to report the event you need.
3. Check whether a collider is a sensor when you expected a blocker, or the reverse.
4. Verify the collider size and offset match the sprite.
5. Check collision groups or filters.
6. Use Play mode and the Flow overlay to confirm the event fires.

Related docs

• Physics reference
• Built-in reference — Physics (Rigid Body 2D, Collider 2D, Joint 2D, Ragdoll, Projectile)
• Components and properties
• Visual scripting
• Testing and debugging