Reference

Physics and Collision

This page describes the current collision and movement model in Sendama.

Main Types

Collider

The general collision-capable component base used by the physics system.

Collider bounds are derived from the owning object's sprite rectangle, so collision behavior depends on the object having a meaningful sprite shape.

CharacterController

A collision-constrained movement component for actor-style movement.

Key behavior:

  • movement only happens when you call move(...)
  • solid collisions block movement
  • trigger collisions do not block movement
  • collision callbacks are dispatched during movement resolution

Important method:

$controller->move(new Vector2(1, 0));

Rigidbody

A force-driven collider component with fixed-step simulation.

Useful methods include:

  • movePosition(Vector2 $position)
  • moveRotation(Vector2 $rotation)
  • movePositionAndRotation(Vector2 $position, Vector2 $rotation)
  • addForce(Vector2 $force)
  • addRelativeForce(Vector2 $force)
  • addForceAtPosition(Vector2 $force, Vector2 $position)
  • addRelativeForceAtPosition(Vector2 $force, Vector2 $position)
  • addForceX(int|float $force)
  • addForceY(int|float $force)

Serializable rigidbody fields include:

  • mass
  • drag
  • angularDrag
  • useGravity
  • freezePositionX
  • freezePositionY
  • freezeRotation

Collision Strategies

Built-in strategies mentioned in the repo docs include:

  • AABBCollisionDetectionStrategy
  • SimpleCollisionDetectionStrategy
  • BasicCollisionDetectionStrategy
  • SeparationBasedCollisionDetectionStrategy

You can swap strategy instances on collider-capable components when you need different behavior.

Trigger Behavior

To make a collider behave like a trigger:

$collider->setTrigger(true);

Trigger contacts:

  • still report collisions to gameplay callbacks
  • do not block CharacterController::move(...)

Physics Queries

Use the physics singleton for predictive checks:

use Sendama\Engine\Physics\Physics;
use Sendama\Engine\Core\Vector2;

$collisions = Physics::getInstance()->checkCollisions($collider, new Vector2(1, 0));

This tests the collider's projected bounds after applying the motion vector.

Environment Collision Maps

Scenes can define:

'environmentCollisionMapPath' => 'Maps/level',

Use this for scene-level environment blocking data separate from the visible background tile map.

Pooling And Inactive Objects

Inactive objects are ignored by collision checks. This matters for object pooling because deactivated bullets, enemies, or pickups do not continue colliding invisibly while waiting to be reused.

Practical Rules

  • give collision-capable objects a valid sprite rectangle
  • use CharacterController for direct, constrained actor movement
  • use Rigidbody when you want forces and accumulated velocity
  • prefer triggers for pickups and detection volumes
  • keep environment visuals and environment collision data distinct when the game needs both