> For the complete documentation index, see [llms.txt](https://devmosaic.gitbook.io/devmosaic/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://devmosaic.gitbook.io/devmosaic/resources/devmosaic-dm-movement/configuration.md).

# Configuration

Configure obstacle heights, vaulting rules, leaning speeds, camera peeking, and ballistics in config.lua.

All configuration for `dm-movement` is located in the open file:

```
shared/config.lua
```

***

### Traversal Settings

The `Config.Traversal` table controls obstacle detection, height thresholds, vaulting, and climbing mechanics.

```lua
Config.Traversal = {
    -- Turn climbing and vaulting on or off.
    enabled = true,

    -- Lowest obstacle players can climb, in metres.
    minHeight = 0.35,

    -- Obstacles lower than this are vaulted over quickly, in metres.
    lowMax = 1.05,

    -- Obstacles lower than this are climbed onto. Taller ones need a full climb.
    mediumMax = 1.75,

    -- Highest ledge players can ever climb, measured from their feet, in metres.
    highMax = 2.55,

    -- How far above their hands players can grab a ledge, in metres.
    grabReach = 0.65,

    -- How far in front of the player a ledge can be grabbed, in metres.
    forwardReach = 1.0,

    smartVault = {
        -- Jump over low walls and fences and land on the other side.
        enabled = true,

        -- Thickest wall that can be jumped over, in metres.
        maxDepth = 0.9,

        -- Biggest drop allowed on the other side, in metres.
        maxDrop = 0.6
    },

    -- Grab ledges while falling past them.
    catchWhileFalling = true,

    -- Only grab while falling faster than this, in metres per second.
    minFallSpeed = 2.0,

    -- Use GTA's own climb animation when possible. false = always use the script's movement.
    useNativeClamber = true,

    -- How long the script's movement takes, in milliseconds. Lower is faster.
    vaultTime = 400,
    mantleTime = 600,
    climbTime = 900,

    -- Wait time between two climbs, in milliseconds.
    cooldown = 450
}
```

#### Traversal Options Explained

* `enabled`: Master switch for custom climbing, vaulting, and mantling.
* `minHeight`: Obstacles shorter than this value (in metres) are ignored by the traversal raycasts, allowing normal jumping over minor curbs.
* `lowMax`: If an obstacle is lower than this height and has clear landing space on the opposite side, the player executes a quick vault over it.
* `mediumMax`: Obstacles between `lowMax` and `mediumMax` trigger a mantle animation onto the surface.
* `highMax`: The absolute maximum height (from the player's feet) that a player can reach and pull themselves up.
* `grabReach`: Vertical reach distance above the character's hands when checking for overhead ledges mid-jump or mid-fall.
* `forwardReach`: How far in front of the player the script scans for climbable edges.
* `smartVault.maxDepth`: Maximum thickness (depth) of an obstacle (e.g. wall, barrier) that can be vaulted over.
* `smartVault.maxDrop`: Maximum height difference between the top of the obstacle and the ground on the landing side.
* `catchWhileFalling`: When set to `true`, players who jump or drop off roofs/ledges can grab nearby railings or edges on the way down.
* `minFallSpeed`: The minimum downward velocity required before the mid-air ledge catch can trigger.
* `useNativeClamber`: Uses GTA V's native clamber animations whenever available for maximum fluidity.
* `vaultTime`, `mantleTime`, `climbTime`: Transition animation speeds in milliseconds.
* `cooldown`: Cooldown in milliseconds between consecutive climbs to prevent spamming.

***

### Leaning Settings

The `Config.Lean` table controls tactical corner leaning, keybind defaults, camera shifts, and gamepad input.

```lua
Config.Lean = {
    -- Turn leaning on or off.
    enabled = true,

    -- MOUSE_EXTRABTN1 = back side button (mouse 4), MOUSE_EXTRABTN2 = front side button (mouse 5).
    keyLeft = 'MOUSE_EXTRABTN2',
    keyRight = 'MOUSE_EXTRABTN1',

    -- Only allow leaning while aiming.
    requireAiming = false,

    -- Allow leaning while sprinting.
    allowWhileSprinting = false,

    -- How fast the lean moves. Higher is faster.
    blendSpeed = 9.0,

    -- Lean less when a wall is right beside the player.
    blockWhenObstructed = true,

    camera = {
        -- Move the camera to the side while leaning, to peek around corners.
        enabled = true,

        -- How far the camera moves to each side, in metres.
        left = 0.34,
        right = 0.34,

        -- How far the camera moves in towards the player while leaning, in metres.
        forward = 1.0,

        -- Zoom in while leaning, in degrees. 0 = no zoom.
        narrow = 6.0,

        -- Show a small dot in the middle of the screen while peeking.
        crosshair = false
    },

    gamepad = {
        -- Let controller players lean.
        enabled = false,

        -- Controller buttons. 205 = LB, 206 = RB.
        left = 205,
        right = 206
    }
}
```

#### Leaning Options Explained

* `enabled`: Master switch for leaning mechanics.
* `keyLeft` & `keyRight`: Default FiveM key mapping strings (e.g. `MOUSE_EXTRABTN2`, `MOUSE_EXTRABTN1`, `Q`, `E`).
* `requireAiming`: When `true`, players can only lean while holding aim (`Right Mouse Button`). When `false`, players can also lean while standing without aiming.
* `allowWhileSprinting`: When `false`, sprinting immediately breaks or prevents leaning.
* `blendSpeed`: The interpolation rate for smoothly shifting in and out of the lean pose.
* `blockWhenObstructed`: Performs a raycast to the side. If a wall or solid prop is pressed against the player's torso, the lean angle is dynamically reduced or blocked to eliminate clipping through walls.
* `camera.enabled`: Moves the gameplay camera in the direction of the lean for corner peeking.
* `camera.left` & `camera.right`: Lateral camera offset in metres.
* `camera.forward`: Pushes the camera slightly forward to provide an over-the-shoulder peek angle.
* `camera.narrow`: Field-of-view reduction (zoom) in degrees during peek.
* `camera.crosshair`: Displays a subtle center dot during peek.
* `gamepad.enabled`: Enables controller button input detection.

***

### Ballistics & Muzzle Obstruction

The `Config.Ballistics` table handles realistic gun barrel collision against walls, blocking weapon discharge when a barrel is buried into cover.

```lua
Config.Ballistics = {
    -- Block shooting when a wall is right in front of the gun barrel.
    enabled = true,

    -- true = only check while leaning. false = check whenever aiming.
    onlyWhileLeaning = false,

    -- Walls closer to the barrel than this block the shot, in metres.
    coverRange = 2.0,

    -- Show a red X where the shot is blocked.
    indicator = true,

    -- Size of the red X.
    indicatorSize = 0.45
}
```

#### Ballistics Options Explained

* `enabled`: Master switch for muzzle collision protection.
* `onlyWhileLeaning`: When `true`, barrel obstruction is only evaluated while leaning. When `false`, obstruction checks run whenever the player is aiming a firearm.
* `coverRange`: Maximum distance from the gun barrel tip within which an obstacle will block the shot.
* `indicator`: Renders an in-game red "x" marker in the 3D world at the point of barrel blockage.
* `indicatorSize`: Scale of the on-screen blocked indicator.