Guides Physics 3D Move a 3D Object with CharacterController

Physics 3D 1 min read Updated Aug 2026

Move a 3D Object with CharacterController

Use `CharacterController` when gameplay code should own the movement.

This is a good fit for characters that need controlled blocking, sliding, and predictable steering.

When to Use It

Use CharacterController for:

  • player characters
  • endless runner characters
  • enemies with scripted movement
  • objects that should move deliberately rather than fall or roll freely

Use Rigidbody3D instead when physics should own the motion.

Scene Setup

In the editor:

  1. Select the character GameObject.
  2. Add a visible renderer or model.
  3. Add a collider shape that matches the gameplay body.
  4. Add CharacterController.
  5. Add your movement Behaviour.

Do not also make the same GameObject a dynamic Rigidbody3D. Pick one movement model for the object.

Simple Forward Movement

<?php

declare(strict_types=1);

namespace Game\Scripts;

use Lenga\Engine\Core\Behaviour;
use Lenga\Engine\Core\CharacterController;
use Lenga\Engine\Core\Time;
use Lenga\Engine\Core\Vector3;

final class RunnerController extends Behaviour
{
    public float $moveSpeed = 8.0;

    private ?CharacterController $controller = null;

    public function start(): void
    {
        $this->controller = $this->gameObject->getComponent(CharacterController::class);
    }

    public function update(): void
    {
        if (!$this->controller instanceof CharacterController) {
            return;
        }

        $motion = new Vector3(0.0, 0.0, -1.0);
        $motion = Vector3::scaleNew($motion, $this->moveSpeed * Time::deltaTime());

        $this->controller->move($motion);
    }
}

Keep Movement Ownership Clear

The practical rule is:

  • Rigidbody3D owns motion for physics-driven bodies.
  • CharacterController owns motion for character-style bodies.

When movement feels unpredictable, check that the object is not being moved by both systems at the same time.

Next Guides