# Godot Essentials Motion Component

Whether top-down, platformer or grid-based, this component offers the functionality you need without having to rewrite it yourself for each project. The movement can be made flexible with the exposed parameters and contains an internal API that facilitates the most common actions that can occur in a 2D game.

[Top-Down Movement Component](/addons-documentation/components/godot-essentials-motion-component/top-down-movement-component.md)

[Platform Movement Component](/addons-documentation/components/godot-essentials-motion-component/platform-movement-component.md)

[Grid Movement Component](/addons-documentation/components/godot-essentials-motion-component/grid-movement-component.md)

## Getting Started

:warning: This is not a component intended for direct use. It serves as a foundational component for building others and contains common functionality that can be utilized by all.

## Exported parameters

These parameters can be modified to achieve different behaviors. Below, we explain the purpose of each parameter and its impact on the component

### Speed

* Max Speed
* Acceleration
* Friction
* Air friction horizontal factor
* Air friction vertical factor

The **max speed** as the name say, defines the maximum reachable limit of speed that will be apply to the velocity.

The **acceleration** makes smoother to reach the maximum speed if you want to increase the juiciness of the movement. In case you don't want it **just assign a zero value to it** and the node will reach the maximum speed immediately

The **friction** brakes the node smoothly to give a sliding effect when changing directions or terminating motion. In case you don't want it **just assign a zero value** to it and the node will not decelerate using friction

The **air friction factor** simulates friction for the character when in the air. This friction needs to be manually applied since it's not directly used within the component. It provides additional functionality to simulate air friction when necessary. The values of this factor apply horizontally to `velocity.x` and vertically to `velocity.y`

### Modifiers

This exported group is saved for the various modifiers that may be temporarily applied to the existing parameters

* Default temporary speed time

The **Default temporary speed time** In seconds, the amount of time a speed modification will endure. This value is being used on the function `change_speed_temporary()`

### Dash

* Dash speed multiplier
* Times can dash
* Dash Cooldown
* Dash duration
* Can dash while dashing

The **dash speed multiplier** is applied on maximum speed value to achieve the dash effect and move immediately the node.

The **times can dash** defines the number of times a dash can be performed in a row after finishing the previous one.

The **dash cooldown** is the recovery time to use the dash again, this applies individually even if several can be performed. Each of the dashes has its own cooldown.

The **dash duration** turn off the gravity the amount in seconds defined to avoid unwanted diagonal directions to the ground when is dashing.

The **can dash while dashing** parameter determines whether the character can initiate another dash while already in the dashing state. **It is enabled by default**. When this parameter is set to false, the character must wait for the first dash to finish before performing a second one.

### Optional Signals

This group collect the signals that can affect the performance because of the number of times they can be executed in context. From here, you can enable or disable them:

* Max speed reached signal
* Stopped signal
* Knockback received signal *(true by default)*

## Accessible normal variables

* body: CharacterBody2D
* original\_max\_speed: float *(This value is used to return to `MAX_SPEED` after a modifier has been applied)*
* velocity: Vector2
* facing\_direction: Vector2
* last\_faced\_direction: Vector2
* temporary\_speed\_timer: Timer
* dash\_duration\_timer: Timer
* dash\_queue: Array\[Vector2]
* is\_dashing: bool

## Upon entered the scene tree:

When this node enter the scene tree happens multiple things:

* Creates the **coyote timer** that it will be used when coyote jump is enabled
* Creates the **dash duration timer** that disables gravity the time amount from the value **dash\_gravity\_time\_disabled**

## Chaining methods

Almost every method makes it return to itself *(except those functions that return other values)* so you can accomplish thinks like the following:

```python
velocity_component_2d.apply_gravity()\
     .wall_climb(input_direction)\
    .wall_slide()\
    .move()
```

##  Interactive functions

### move()

The basic [move\_and\_slide](https://docs.godotengine.org/en/stable/classes/class_characterbody2d.html#class-characterbody2d-method-move-and-slide) from godot engine, applies the velocity to the **CharacterBody2D.**

### move\_and\_collide(delta: float = get\_physics\_process\_delta\_time()) -> KinematicCollision2D

Same as above but using [move\_and\_collide](https://docs.godotengine.org/en/stable/classes/class_physicsbody2d.html#class-physicsbody2d-method-move-and-collide), the motion vector used internally is the `body.velocity * delta`

### accelerate(direction: Vector2, delta: float = get\_physics\_process\_delta\_time())

When the `ACCELERATION` value is greater than zero, acceleration is applied to the movement. When this value is zero, applies the speed as constant.

If enabled, the `max_speed_reached` signal is emitted when the velocity reaches the `MAX_SPEED` value.

### decelerate(delta: float = get\_physics\_process\_delta\_time(), force\_stop: bool = false)

The velocity is decelerated until it reaches `Vector2.ZERO` when the `FRICTION` value is provided. In the opposite case, the velocity is set to `Vector2.ZERO` instantaneously. This deceleration can be forced using the `force_stop` parameter.

When the velocity reaches `Vector2.ZERO`, and the `stopped` signal is enabled, it is emitted.

### accelerate\_to\_position(position: Vector2)

Accelerate to position defined as parameter, uses `accelerate()` function internally.

### apply\_air\_friction\_horizontal(friction\_factor: float = AIR\_FRICTION\_HORIZONTAL\_FACTOR)

Apply horizontal air friction to the **velocity.x** when this value is greater than zero. The character does not need to return `is_on_floor()` and `is_on_wall()` to true.

### apply\_air\_friction\_vertical(friction\_factor: float = AIR\_FRICTION\_HORIZONTAL\_FACTOR)

Apply horizontal air friction to the **velocity.y** when this value is greater than zero. The character does not need to return `is_on_floor()` and `is_on_wall()` to true.

### knockback(direction: Vector2, power: float)

Executes a **knockback** on the character with the provided direction and force parameters for this function. A `knockback_received` signal is emitted

### teleport\_to\_position(position: Vector2, valid\_position\_callback: Callable = \_default\_valid\_position\_callback)

This function immediately relocates the character to the specified position and emits a "teleported" signal. You can provide a callback as the second parameter to determine the validity of the target position. This callback receives both the CharacterBody2D and the target position of the function as parameters.

The `_default_valid_position_callback` always return true when no callable has been provided.

### change\_speed\_temporary(new\_speed: float, time: float = DEFAULT\_TEMPORARY\_SPEED\_TIME)

Change the maximum speed of the character over the specified duration in seconds, setting the new speed as the current speed. `temporary_speed_started`  signal is emitted. 

When the timer reaches the timeout, a `temporary_speed_finished` signal is emitted, and the maximum speed **returns to the original value** before the function call.

### has\_available\_dashes() -> bool

Returns a boolean value confirming whether dashes are available

### can\_dash(direction: Vector2 = Vector2.ZERO)

Returns a boolean value confirming if the character can dahs to the direction provided as parameter.

### dash(target\_direction: Vector2 = facing\_direction, speed\_multiplier: float = DASH\_SPEED\_MULTIPLIER)

It internally checks whether it can execute the dash, and if it can, a speed boost is applied. The `dashed` signal is emitted when the dash could be executed.

### reset\_dash\_queue()

Force a clear on the `dash_queue` variable. This function is used internally but can also be applied manually in any case where you want to make dashes available again.

### Signals

You can listen a variety of signals from this component that allow you to react and perform other actions such as displaying animations or collecting statistics.

* *max\_speed\_reached* 
* *stopped*
* *knockback\_received(direction: Vector2, power: float)* 
* *temporary\_speed\_started(previous\_speed: float, current\_speed: float)* 
* *temporary\_speed\_finished signal teleported(from: Vector2, to: Vector2)* 
* *dashed(position: Vector2)* 
* *finished\_dash(initial\_position: Vector2, final\_position: Vector2)* 
* *dash\_free\_from\_cooldown(dash\_position: Vector2, current\_dash\_queue: Array\[Vector2])*
* *dash\_restarted*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://godot-essentials.gitbook.io/addons-documentation/components/godot-essentials-motion-component.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.