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

# sh-robNPCs: Rob Pedestrian NPCs at Gunpoint in FiveM

> sh-robNPCs lets players rob pedestrian NPCs by aiming a weapon at them. Features NPC retaliation, cop alerts, and a configurable cooldown.

sh-robNPCs turns every pedestrian in Los Santos into a potential robbery target. The moment a player aims a weapon at a nearby NPC, a robbery sequence fires automatically — no interaction key, no target prompt. The NPC reacts after a short delay, a timed progress bar counts down, and on success the player pockets a random cash reward. Between the chance that the NPC calls the police, the chance it pulls a weapon and fights back, and the per-player cooldown that prevents back-to-back robberies, sh-robNPCs adds genuine risk to what could otherwise be a free-money exploit.

## Supported Frameworks

| Value        | Framework                              |
| ------------ | -------------------------------------- |
| `standalone` | No framework — cash handled internally |
| `nat`        | NAT2K15 framework                      |
| `nd`         | ND\_Core                               |

## How a Robbery Works

<Steps>
  <Step title="Player aims at an NPC">
    When a player raises a weapon within `Config.DistanceToRob` metres of a pedestrian NPC, the script detects the aim automatically. No keybind or menu is needed.
  </Step>

  <Step title="NPC reacts">
    After `Config.Wait.NPCReactTime` seconds, the NPC raises its hands and enters a fear animation.
  </Step>

  <Step title="Progress bar runs">
    A progress bar appears on-screen for `Config.Wait.TimeToRob` seconds. The player must keep the weapon aimed and stay within range for the bar to complete.
  </Step>

  <Step title="NPC potentially alerts police">
    After `Config.Wait.AlertCopsTime` seconds (which may overlap with the progress bar), the script rolls against `Config.ChanceToCallCops`. On a hit, a server-wide notification broadcasts the robbery's street name to all online players.
  </Step>

  <Step title="NPC potentially retaliates">
    If `Config.PedTakesAim.Enabled` is `true`, the script rolls against `Config.PedTakesAim.Chance`. On a hit, the NPC draws `Config.PedTakesAim.Weapon` and opens fire.
  </Step>

  <Step title="Reward paid and cooldown starts">
    On a successful robbery (progress bar completed), the player receives a random cash amount between `Config.MinCash` and `Config.MaxCash`. The per-player cooldown (`Config.Wait.Cooldown`) begins immediately.
  </Step>
</Steps>

<Note>
  The cop alert broadcasts the robbery's street name to all players on the server. No ACE permissions are required on the player side — the broadcast is server-side and fires automatically.
</Note>

## Configuration

All settings live in `config.lua` in the resource root. The values below are the shipped defaults.

```lua config.lua theme={null}
Config.Framework = 'standalone'  -- 'standalone', 'nat', 'nd'

Config.DistanceToRob    = 4     -- Max distance from NPC to initiate robbery
Config.MinCash          = 0     -- Minimum cash reward (0 = chance of nothing)
Config.MaxCash          = 1000  -- Maximum cash reward
Config.ChanceToCallCops = 20    -- % chance NPC alerts police

Config.PedTakesAim = {
    Enabled = true,          -- Can NPCs fight back?
    Chance  = 20,            -- % chance NPC pulls weapon
    Weapon  = 'weapon_pistol',
}

Config.Wait = {
    NPCReactTime  = 0.7,   -- Seconds before NPC reacts
    TimeToRob     = 8,     -- Robbery progress bar duration (seconds)
    AlertCopsTime = 6,     -- Delay before NPC alerts police
    Cooldown      = 10,    -- Per-player cooldown in minutes
}
```

<Tip>
  Set `Config.ChanceToCallCops = 0` to disable police alerts entirely. This is useful for lighter RP servers that want the robbery mechanic without mandatory law enforcement involvement.
</Tip>

## Configuration Options Explained

<Accordion title="DistanceToRob">
  Controls how close a player must be to a pedestrian for the robbery to trigger. Lower values (2–3) demand the player be nearly on top of the NPC; higher values (6–8) let players rob from a safer distance. The default of `4` balances realism with usability.
</Accordion>

<Accordion title="MinCash and MaxCash">
  The script picks a random integer between these two values when paying out a successful robbery. Setting `MinCash = 0` means there is a chance the NPC has no cash at all, adding unpredictability. For a low-risk economy, keep `MaxCash` below \$500; for high-crime servers, you can push it higher and compensate with a steeper cop-call chance.
</Accordion>

<Accordion title="ChanceToCallCops">
  A value from `0` to `100`. At `20`, roughly one in five robberies triggers a server-wide alert. At `100`, every robbery is reported. At `0`, alerts are disabled. Tune this alongside `AlertCopsTime` — a longer delay gives players more time to flee before the alert fires.
</Accordion>

<Accordion title="PedTakesAim">
  When enabled, NPCs have a percentage chance to draw a weapon and fight back instead of staying passive. The weapon is set as a GTA V weapon hash string (e.g. `weapon_pistol`, `weapon_knife`). Disable this entirely by setting `Enabled = false` if you prefer purely passive pedestrians.
</Accordion>

<Accordion title="Cooldown">
  The cooldown is set in **minutes**. At the default of `10` minutes, a player can rob at most 6 NPCs per hour. Lower this for action-heavy servers or raise it to discourage farming.
</Accordion>

## Installation

<Steps>
  <Step title="Add to server.cfg">
    Add sh-robNPCs to your resource list. No additional dependencies are required:

    ```cfg server.cfg theme={null}
    ensure sh-robNPCs
    ```
  </Step>

  <Step title="Set your framework">
    Open `config.lua` and set `Config.Framework` to match your server:

    ```lua theme={null}
    Config.Framework = 'nd'  -- 'standalone', 'nat', or 'nd'
    ```
  </Step>

  <Step title="Tune reward and risk values">
    Adjust `MinCash`, `MaxCash`, `ChanceToCallCops`, and the `PedTakesAim` block to match your server's economy and risk level.
  </Step>

  <Step title="Set the cooldown">
    Set `Config.Wait.Cooldown` in minutes. The default is `10` minutes. Consider a longer cooldown on economy servers to prevent cash farming.
  </Step>

  <Step title="Restart and verify">
    Restart the resource and test in-game by aiming at a pedestrian. Confirm the progress bar appears, the NPC reacts, and the reward and cooldown apply correctly.
  </Step>
</Steps>

<Warning>
  Setting `Config.MinCash` and `Config.MaxCash` too high without an appropriate `ChanceToCallCops` or cooldown will allow players to farm large amounts of cash very quickly. Balance these values together when configuring sh-robNPCs for the first time.
</Warning>