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.