> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zydrec.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Animations

# zydrec-robbery-lib

## Installation

Keep the resource folder name as:

```text theme={null}
zydrec-robbery-lib
```

Renaming the resource is not supported and may break exports, events, or external integrations.

## Configuration

Configuration is located in:

```lua theme={null}
config/zydrec-gemsjewelry.lua
```

Available settings:

```lua theme={null}
ServerConfig.Enabled
ServerConfig.SmashDistance
ServerConfig.Debug
ServerConfig.CheckPlayerState
ServerConfig.AllowedWeapons
ServerConfig.Locations
```

When `ServerConfig.Enabled = false`, the module does not register exports, events, or cabinet state.

Set:

```lua theme={null}
ServerConfig.AllowedWeapons = false
```

to disable weapon validation entirely.

Set:

```lua theme={null}
ServerConfig.CheckPlayerState = false
```

to disable dead, laststand, handcuffed and escorted state validation.

## Usage

Example smash flow:

```lua theme={null}
local cabinetId = exports['zydrec-robbery-lib']:getNearestCabinetId(source)
if not cabinetId then return end

if not exports['zydrec-robbery-lib']:canSmashCabinet(source, cabinetId) then
    return
end

local success = exports['zydrec-robbery-lib']:smashCabinet(source, cabinetId, true)
if not success then
    return
end
```

## Exports

```lua theme={null}
getNearestCabinetId(source)
getNearestCabinetIdFromCoords(coords, maxDistance)

isCabinetSmashed(cabinetId)

canSmashCabinet(source, cabinetId)

smashCabinet(source, cabinetId, playAnimation)
smashNearestCabinet(source, playAnimation)

resetCabinet(cabinetId)
resetCabinetsInLocation(locationRef)
resetAllCabinets()

shutters(locationRef, action)
isShutterOpen(locationRef)
```

### getNearestCabinetId

Returns the nearest cabinet within `10.0` units.

Returns:

```lua theme={null}
cabinetId | nil
```

### getNearestCabinetIdFromCoords

Accepts:

* `vector3`
* `vector4`
* Table containing `x`, `y`, and `z`

`maxDistance` defaults to `10.0`.

Returns:

```lua theme={null}
cabinetId | nil
```

### canSmashCabinet

Returns `true` when the player can smash the specified cabinet.

Checks:

* Valid player ped
* Valid cabinet
* Cabinet is intact
* Player state validation (if enabled)
* Distance validation
* Weapon validation (if enabled)

### smashCabinet

Returns:

```lua theme={null}
true | false
```

When `playAnimation` is enabled, the server waits for the client animation flow to complete before returning a result.

### smashNearestCabinet

Returns:

```lua theme={null}
cabinetId | nil
```

### resetCabinetsInLocation

Accepts either a configured location name or location index.

Examples:

```lua theme={null}
resetCabinetsInLocation('Paleto')
resetCabinetsInLocation(3)
resetCabinetsInLocation('3')
```

## Shutters

Shutters are controlled server-side and spawned locally on clients from `ServerConfig.Locations`. Each location can define its own `shutters` block next to its cabinet definitions.

Example:

```lua theme={null}
exports['zydrec-robbery-lib']:shutters('paleto', 'closed')
exports['zydrec-robbery-lib']:shutters('paleto', 'open')
exports['zydrec-robbery-lib']:shutters('all', 'toggle')
```

The `shutters` export accepts `open`, `closed` and `toggle`. `close` is accepted as an alias for `closed`.

`isShutterOpen(locationRef)` returns whether every shutter part in the requested location is open. `ServerConfig.Locations[].shutters.parts[].coords` is a direct `vec4` world coordinate, including heading.

Set `ServerConfig.Locations[].shutters.enabled = false` to disable shutter state and visuals for one configured location.

Set `ServerConfig.Locations[].shutters.defaultOpen` to control the initial shutter state for one configured location.

The configured jewelry locations treat `coords` as the closed position; open height, animation timing and resync range are hardcoded in the shutter module.

`zydrec_gj_prop_shutter_02` is hardcoded as a temporary spawned part so it despawns while open and does not clip through the roof.

## Debug

Enable debug rendering with:

```lua theme={null}
ServerConfig.Debug = true
```

When enabled, cabinet labels and prop outlines are rendered for development and testing.