@needle-tools/engine/lib/engine-components/CharacterController.d.ts

Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.

import { Vector2, Vector3 } from "three";
import { Collision } from "../engine/engine_types.js";
import { Animator } from "./Animator.js";
import { Behaviour } from "./Component.js";
import { Rigidbody } from "./RigidBody.js";
/**
 * The [CharacterController](https://engine.needle.tools/docs/api/CharacterController) adds a capsule collider and rigidbody to the object, constrains rotation, and provides movement and grounded state.
 * It is designed for typical character movement in 3D environments.
 *
 * The controller automatically:
 * - Creates a {@link CapsuleCollider} if one doesn't exist
 * - Creates a {@link Rigidbody} if one doesn't exist
 * - Locks rotation on all axes to prevent tipping over
 * - Tracks ground contact for jump detection
 *
 * @example Basic character movement
 * ```ts
 * export class MyCharacter extends Behaviour {
 *   @serializable(CharacterController)
 *   controller?: CharacterController;
 *
 *   update() {
 *     const input = this.context.input;
 *     const move = new Vector3();
 *     if (input.isKeyPressed("KeyW")) move.z = 0.1;
 *     if (input.isKeyPressed("KeyS")) move.z = -0.1;
 *     this.controller?.move(move);
 *   }
 * }
 * ```
 *
 * @summary Character Movement Controller
 * @category Character
 * @group Components
 * @see {@link CharacterControllerInput} for ready-to-use input handling
 * @see {@link Rigidbody} for physics configuration
 * @see {@link CapsuleCollider} for collision shape
 */
export declare class CharacterController extends Behaviour {
    /** Center offset of the capsule collider in local space */
    center: Vector3;
    /** Radius of the capsule collider */
    radius: number;
    /** Height of the capsule collider */
    height: number;
    private _rigidbody;
    get rigidbody(): Rigidbody;
    private _activeGroundCollisions;
    awake(): void;
    onEnable(): void;
    /**
     * Moves the character by adding the given vector to its position.
     * Movement is applied directly without physics simulation.
     * @param vec The movement vector to apply
     */
    move(vec: Vector3): void;
    onCollisionEnter(col: Collision): void;
    onCollisionExit(col: Collision): void;
    /** Returns true if the character is currently touching the ground */
    get isGrounded(): boolean;
    private _contactVelocity;
    /**
     * Returns the combined velocity of all objects the character is standing on.
     * Useful for moving platforms - add this to your movement for proper platform riding.
     */
    get contactVelocity(): Vector3;
}
/**
 * CharacterControllerInput handles user input to control a {@link CharacterController}.
 * It supports movement, looking around, jumping, and double jumping.
 *
 * Default controls:
 * - **W/S**: Move forward/backward
 * - **A/D**: Rotate left/right
 * - **Space**: Jump (supports double jump)
 *
 * The component automatically sets animator parameters:
 * - `running` (bool): True when moving
 * - `jumping` (bool): True when starting a jump
 * - `doubleJump` (bool): True during double jump
 * - `falling` (bool): True when falling from height
 *
 * @example Custom input handling
 * ```ts
 * const input = this.gameObject.getComponent(CharacterControllerInput);
 * input?.move(new Vector2(0, 1)); // Move forward
 * input?.jump(); // Trigger jump
 * ```
 *
 * @summary User Input for Character Controller
 * @category Character
 * @group Components
 * @see {@link CharacterController} for the movement controller
 * @see {@link Animator} for animation integration
 */
export declare class CharacterControllerInput extends Behaviour {
    /** The CharacterController to drive with input */
    controller?: CharacterController;
    /** Movement speed multiplier */
    movementSpeed: number;
    /** Rotation speed multiplier */
    rotationSpeed: number;
    /** Impulse force applied when jumping from ground */
    jumpForce: number;
    /** Impulse force applied for the second jump (set to 0 to disable double jump) */
    doubleJumpForce: number;
    /** Optional Animator for character animations */
    animator?: Animator;
    lookForward: boolean;
    awake(): void;
    update(): void;
    move(move: Vector2): void;
    look(look: Vector2): void;
    jump(): void;
    private lookInput;
    private moveInput;
    private jumpInput;
    onBeforeRender(): void;
    private _currentSpeed;
    private _currentAngularSpeed;
    private _temp;
    private _jumpCount;
    private _currentRotation;
    handleInput(move: Vector2, look: Vector2, jump: boolean): void;
    private _raycastOptions;
}