# Grid Movement Component

## Getting Started

This component ***does not inherit*** from [](https://godot-essentials.gitbook.io/addons-documentation/components/godot-essentials-motion-component "mention"), so it does not have access to this functionality. Grid movement requires its own dedicated logic.

:warning: *This component can only be used on **CharacterBody2D*** node

## Once upon the scene tree

When this node enter the scene tree happens multiple things

* Snap the body position to align with the `TILE_SIZE` and prevent it from remaining in an invalid position.
* Connects to `moved` signal
* Connects to `flushed_recorded_grid_movements` signal

"When the `move()` function is executed and emits the `moved` signal, the component performs the following calculations:

1. Records the movement in the `recorded_grid_movements` array if the maximum recorded grid movements value has not been exceeded.
2. Increments the `movements_count` by 1.
3. Emits the `movements_completed signal` when `movements_count` exceeds the `emit_signal_every_n_movements` value. The `movements_count` is then reset to zero.
4. If the `recorded_grid_movements` array exceeds the `max_recorded_grid_movements` value, this array is cleared, and the `flushed_recorded_grid_movements` signal is emitted.

## Exported parameters

* *Tile size*
* *Max recorded grid movements*
* *Emit signal every 'n' movements*

The **Tile size** this grid based movement, we recommend to be multiples of 2 but nothing happens if you used another tile size dimensions.

The **Max recorded grid movements** is the number of grid movements recorded before deletion *(set to 0 to keep them indefinitely)*

The **emit signal every n movements** is the number of movements to be performed before emitting a signal notification. The signal emitted is `movements_completed`

## Accessible normal parameters

* *body: CharacterBody2D*
* *recorded\_grid\_movements: Array\[Vector2]*
* *movements\_count: int*

## Interactive functions

The `_default_valid_position_callback` is an internal function that always return true and keep the execution of movement when no custom function is passed as callback.

### move(direction: Vector2, valid\_position\_callback: Callable = \_default\_valid\_position\_callback)

The fundamental function that moves the character within a grid. It accepts a `direction` and a `callback function`, which can be used to implement custom functionality for detecting valid grid positions, among other things.

* If the callback returns true the movement is done and emit the signal `moved`
* If the callback returns false the movement is not done and emit the signal `move_not_valid`

### follow\_path(moves: Array\[Vector2], valid\_position\_callback: Callable = \_default\_valid\_position\_callback)

Executes a series of sequential moves, utilizing the `move()` function internally.

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

Moves instantly to the target position. The `_default_valid_position_callback` always return true

### snap\_body\_position(body: CharacterBody2D)

Snap the character to align with a nearby valid vector that maintains consistency with the tile size.

### snap\_position(position: Vector2) -> Vector2

Similar to the previous description, but using the parameter of a specific position.

## Signals

The result is defined on the next structure:

```python
var result = {
		"from": original_position, 
		"to": next_position, 
		"direction": direction
}
	
```

*moved(result: Dictionary)* 

*move\_not\_valid(result: Dictionary)* 

*flushed\_recorded\_grid\_movements(recorded\_movements: Array\[Dictionary])* 

*movements\_completed(movements: Array\[Dictionary])*