# Gizmo `[Client]`

Gizmo module is a specialized tool for manipulating entities in 3D space within RedM. It provides a visual interface for moving, rotating, and precisely positioning objects with optional camera controls.

## Configuration Variables (Convars)

| Convar | Side | Type | Default | Description |
|--------|------|------|---------|-------------|
| `jo_libs:gizmo:allowRotateX` | `[Client]` | Boolean | `true` | Allow rotation on X-axis |
| `jo_libs:gizmo:allowRotateY` | `[Client]` | Boolean | `true` | Allow rotation on Y-axis |
| `jo_libs:gizmo:allowRotateZ` | `[Client]` | Boolean | `true` | Allow rotation on Z-axis |
| `jo_libs:gizmo:allowSnapToGround` | `[Client]` | Boolean | `true` | Allow snapping to ground |
| `jo_libs:gizmo:allowTranslateX` | `[Client]` | Boolean | `true` | Allow translation on X-axis |
| `jo_libs:gizmo:allowTranslateY` | `[Client]` | Boolean | `true` | Allow translation on Y-axis |
| `jo_libs:gizmo:allowTranslateZ` | `[Client]` | Boolean | `true` | Allow translation on Z-axis |
| `jo_libs:gizmo:enableCam` | `[Client]` | Boolean | `true` | Enable/Disable camera feature |
| `jo_libs:gizmo:keys:cameraSpeedDown` | `[Client]` | Integer | ``INPUT_SELECT_NEXT_WEAPON`` | Decrease camera speed |
| `jo_libs:gizmo:keys:cameraSpeedUp` | `[Client]` | Integer | ``INPUT_SELECT_PREV_WEAPON`` | Increase camera speed |
| `jo_libs:gizmo:keys:cancel` | `[Client]` | Integer | ``INPUT_GAME_MENU_TAB_RIGHT_SECONDARY`` | Cancel operation |
| `jo_libs:gizmo:keys:confirm` | `[Client]` | Integer | ``INPUT_FRONTEND_ACCEPT`` | Confirm placement |
| `jo_libs:gizmo:keys:focusEntity` | `[Client]` | Integer | ``INPUT_SHOP_SPECIAL`` | Toggle focus on entity |
| `jo_libs:gizmo:keys:moveDown` | `[Client]` | Integer | ``INPUT_FRONTEND_RUP`` | Move down |
| `jo_libs:gizmo:keys:moveUp` | `[Client]` | Integer | ``INPUT_FRONTEND_X`` | Move up |
| `jo_libs:gizmo:keys:moveX` | `[Client]` | Integer | ``INPUT_SCRIPTED_FLY_LR`` | Move left/right |
| `jo_libs:gizmo:keys:moveY` | `[Client]` | Integer | ``INPUT_SCRIPTED_FLY_UD`` | Move forward/backward |
| `jo_libs:gizmo:keys:rotationSnap` | `[Client]` | Integer | ``INPUT_FRONTEND_Y`` | Rotation snap key |
| `jo_libs:gizmo:keys:snapToGround` | `[Client]` | Integer | ``INPUT_INTERACT_OPTION1`` | Snap entity to ground |
| `jo_libs:gizmo:keys:switchMode` | `[Client]` | Integer | ``INPUT_RELOAD`` | Switch between translate/rotate modes |
| `jo_libs:gizmo:maxCamDistance` | `[Client]` | Integer | `80` | Maximum distance camera can be moved from player |
| `jo_libs:gizmo:maxDistance` | `[Client]` | Integer | `100` | Maximum distance entity can be moved from starting position (set to false to disable) |
| `jo_libs:gizmo:maxMovementSpeed` | `[Client]` | Float | `0.2` | Maximum movement speed for camera |
| `jo_libs:gizmo:maxY` | `[Client]` | Integer | `40` | Maximum Y value for camera rotation |
| `jo_libs:gizmo:minMovementSpeed` | `[Client]` | Float | `0.001` | Minimum movement speed for camera |
| `jo_libs:gizmo:minY` | `[Client]` | Integer | `-40` | Minimum Y value for camera rotation |
| `jo_libs:gizmo:movementSpeed` | `[Client]` | Float | `0.1` | Default movement speed for camera |
| `jo_libs:gizmo:movementSpeedIncrement` | `[Client]` | Float | `0.01` | Increment value when adjusting camera speed |
| `jo_libs:gizmo:onlyOnMove` | `[Client]` | Boolean | `false` |  |
| `jo_libs:gizmo:rotationSnap` | `[Client]` | Integer | `5` | Rotation snap value |

### Runtime Configuration

You can also override specific configuration options when calling `jo.gizmo.moveEntity()` by passing a configuration table as the second parameter:

```lua
local result = jo.gizmo.moveEntity(object, {
    enableCam = false,           -- Disable camera for this specific call
    maxDistance = 200,           -- Allow movement up to 200 units away
    movementSpeed = 0.2          -- Set faster movement speed for this instance
})
```

This allows for flexible configuration on a per-call basis without changing the server-wide defaults.

## JO Functions

### jo.gizmo.cancel()

Cancels the currently active gizmo interface <br>

#### Syntax

```lua
jo.gizmo.cancel()
```

---

### jo.gizmo.moveEntity()

Setup a gizmo interface to move an entity in 3D space <br>
Allows for precise positioning and rotation of entities through a visual interface <br>
Uses a camera system for better manipulation when enabled <br>

#### Syntax

```lua
jo.gizmo.moveEntity(entity, cfg, allowPlace)
```

#### Parameters

`entity` : _integer_
> The entity to move
>

`cfg` : _table_ `[Optional]`

> Configuration options to override [defaults](#default-configuration)
>

> `cfg.enableCam` : _boolean_ - Enable/disable camera feature - default based on config
> 
> `cfg.maxDistance` : _number_ - Max distance the entity can be moved from starting position - default based on config
> 
> `cfg.maxCamDistance` : _number_ - Max distance the camera can be moved from player - default based on config
> 
> `cfg.minY` : _number_ - Min Y value from starting position for camera - default based on config
> 
> `cfg.maxY` : _number_ - Max Y value from starting position for camera - default based on config
> 
> `cfg.movementSpeed` : _number_ - Movement speed for camera - default based on config
> 
> `cfg.allowTranslateX` : _boolean_ - Allow translation on X-axis - default `true`
> 
> `cfg.allowTranslateY` : _boolean_ - Allow translation on Y-axis - default `true`
> 
> `cfg.allowTranslateZ` : _boolean_ - Allow translation on Z-axis - default `true`
> 
> `cfg.allowRotateX` : _boolean_ - Allow rotation on X-axis - default `true`
> 
> `cfg.allowRotateY` : _boolean_ - Allow rotation on Y-axis - default `true`
> 
> `cfg.allowRotateZ` : _boolean_ - Allow rotation on Z-axis - default `true`
> 
> `cfg.allowSnapToGround` : _boolean_ - Allow snapping to ground - default `true`
> 
> `cfg.rotationSnap` : _number_ - Rotation snap value - default `5`
> 
> `cfg.onMove` : _function_ - Optional function fired when the entity move with the gizmo
> 
> `cfg.onlyOnMove` : _boolean_ - Optional if onMove set the position or rotation will only be send to the function
> 

`allowPlace` : _function_ `[Optional]`
> Optional callback to validate placement - receives proposed position as parameter
>

#### Return Value

Type : _table|nil_

> Returns entity position and rotation data when completed, nil if already active