# Usage

## Usage

This page explains how the script is used in-game and what admins should know.

***

### Player Flow – Starting a Robbery

1. **Find a start location**
   * Players must walk to one of the coordinates defined in `Config.StartLocations`.
   * If they are within `Config.StartRadius`, they see a help notification (e.g. “Press E to start break-in”).
2. **Check requirements**
   * Script checks if the player has the `Config.RequiredItem` in their inventory (e.g. `lockpick`).
   * Script checks if enough police are online based on `Config.Police.minOnline`.
3. **Consume item and cooldown**
   * If requirements are met:
     * The required item is consumed server-side using the inventory bridge.
     * The player is put into a per-player cooldown (`Config.Cooldown` minutes) before they can try again.
4. **Play the minigame**
   * The configured minigame provider is used:
     * `boii_minigames` wire
     * `ps-ui` circles
     * `ox_lib` skillCheck
     * `t3_lockpick`
     * or the fallback progress bar
   * If the minigame fails:
     * There is a chance to trigger a **dispatch break-in call**.
     * Cooldown still applies.
5. **Teleport into a house**
   * On success:
     * A house is chosen from `Config.Houses` based on `chance` weights.
     * The house's IPL is requested and the player is teleported to the configured `coord`.
     * A Discord log is sent if `Config.Discord.Webhook` is set.
     * Internal flags (`insideHouse`, `noiseLevel`, etc.) are reset.

***

### Inside the House

#### Noise System

* When inside the house, the script constantly tracks the player’s behavior:
  * Walking
  * Running / sprinting
  * Shooting / actions
  * Crouching
* Noise logic:
  * Running and actions increase noise faster.
  * Walking increases noise slowly.
  * Crouching causes noise to decay.
  * Noise is clamped between `0` and `Config.Noise.Threshold`.
* HUD:
  * A bar at the bottom of the screen shows current noise percentage.
* Alarm:
  * When `noiseLevel >= Config.Noise.Threshold` for the first time:
    * The alarm is triggered.
    * A dispatch “alarm” call is sent using the configured dispatcher.
    * Alarm will not retrigger again for that run.

***

#### Looting

* The script spawns target zones (via `ox_target` or `qb-target`) for:
  * Each loot spot defined in `Config.Loot.zones[house.ipl]`.
  * A house exit zone.
* When the player interacts with a loot zone:
  * The client checks if that zone was already looted in this run.
  * If not, it triggers the server event:
    * `nasty:houseRobbery:loot(ipl, zoneIndex)`
* On the server:
  * It resolves the correct zone and item list.
  * It rolls a random item based on `chance` weights.
  * It rolls a random amount between `min` and `max`.
  * It gives the item via the inventory bridge.
  * It sends a localized loot notification using `Notify` and `L('loot_found', amount, label)`.
  * If Discord logging is enabled, it posts a loot embed.

***

#### Exiting the House

* A target zone is created near the house exit.
* Interacting with the exit:
  * Shows the localized label (e.g. “Exit house”).
  * Removes all loot zones and the exit zone.
  * Fades the screen out.
  * Teleports the player back to the **door position** they used to start the robbery.
  * Fades the screen back in.

After that, the player is outside and the robbery run is finished. Cooldown remains active until it expires.

***

### Dispatch Behavior

The dispatch bridge separates two main events:

1. **Break-in alert**
   * Triggered when starting/failing the minigame (depending on configuration).
   * Uses `Dispatch.HouseBreakin` on the server.
   * Sends a “possible break-in” dispatch call with:
     * Player coords
     * Translated title/description
     * Configured job (police)
2. **Alarm alert**
   * Triggered by noise threshold via `Dispatch.HouseAlarm`.
   * Uses the player’s position and interior context.

Supported systems:

* **LB Tablet** (`lb-tablet` resource)
* **tk\_dispatch**
* **ps-dispatch**
* **Next Scripts dispatch** (`dispatch` resource)
* Or no dispatch (`Config.Dispatch = 'none'`)

***

### Admin Notes

* You can freely edit:
  * Start locations
  * Interiors and their chances
  * Loot tables per interior
  * Noise system values
  * Required item and cooldown
  * Minigame provider and difficulty
* All texts are fully localized via `locale/locales.lua`.
* If you run only one framework / inventory / target:
  * You can leave `Config.Framework` and `Config.Inventory` on `'auto'`.
* If dispatch or minigame resources are missing:
  * Script prints clean console warnings.
  * Fallback minigame is used when needed.