> ## 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-npcbartend: NPC Bartender Script for FiveM Servers

> sh-npcbartend spawns NPC bartenders at configurable locations. Players purchase drinks that apply timed gameplay effects to their character.

sh-npcbartend places a bartender NPC at any world coordinates you define, giving players a place to buy drinks that trigger timed screen intoxication effects. The script is lightweight by design — drop it in, point it at your existing money system (or run it fully standalone), and configure as many bar locations as your server needs. Each drink has its own price, command, and effect duration, all set in plain Lua with no encrypted config files to work around.

## Dependencies

| Dependency                                        | Required   | Notes                                                             |
| ------------------------------------------------- | ---------- | ----------------------------------------------------------------- |
| [ox\_lib](https://github.com/overextended/ox_lib) | ✅ Yes      | Menu and utility functions                                        |
| ox\_target **or** qb-target                       | ❌ Optional | Enables third-eye interaction; falls back to proximity if `false` |
| NAT2K15                                           | ❌ Optional | Required when `Config.Framework = 'nat'`                          |
| ND\_Core                                          | ❌ Optional | Required when `Config.Framework = 'nd'`                           |

## Configuration

Everything you need to customise is in `shared/config.lua`. No other files require editing for a standard setup.

```lua shared/config.lua theme={null}
Config.Framework = 'standalone'  -- 'standalone', 'nat' (NAT2K15), or 'nd' (ND_Core)
Config.Target    = false          -- false (proximity [E]), 'ox' (ox_target), or 'qb' (qb-target)

-- Ped model for the bartender NPC
Config.BarNPC = 'u_f_m_casinoshop_01'

-- World positions for each bartender (x, y, z, heading)
Config.BarNPCLocations = {
    vector4(1984.46, 3054.71, 46.22, 253.76),
    vector4(-562.0,  286.17,  81.18, 264.94),
    -- Add as many locations as you need
}

-- Map blip settings applied to every NPC location
Config.BlipConfig = {
    Enabled = true,
    Sprite  = 93,          -- Blip icon (see FiveM blip reference)
    Color   = 46,          -- Blip colour index
    Scale   = 0.6,         -- Blip size
    Name    = 'Bartender',
}
```

### Drink Configuration

Each drink is its own config block with a command, display name, description, price, and effect duration in seconds. sh-npcbartend ships with five drinks — Vodka, Tequila, Beer, Water, and Shots — and you can add more by copying the pattern below.

```lua shared/config.lua theme={null}
Config.Drink1 = {
    Command    = 'drinkvodka',   -- /command players type to purchase
    Title      = 'Vodka',
    Desc       = 'Buy Vodka',
    Price      = 100,
    EffectTime = 10,             -- Seconds the screen effect lasts
}

Config.Drink2 = {
    Command    = 'drinktequila',
    Title      = 'Tequila',
    Desc       = 'Buy Tequila',
    Price      = 100,
    EffectTime = 10,
}

Config.Drink3 = {
    Command    = 'drinkbeer',
    Title      = 'Beer',
    Desc       = 'Buy Beer',
    Price      = 100,
    EffectTime = 10,
}

Config.Drink4 = {
    Command    = 'drinkwater',
    Title      = 'Water',
    Desc       = 'Buy Water',
    Price      = 100,
    EffectTime = 10,
}

Config.Drink5 = {
    Command    = 'drinkshot',
    Title      = 'Shots',
    Desc       = 'Buy Shots',
    Price      = 100,
    EffectTime = 10,
}
```

<Note>
  The `EffectTime` value is in seconds. Setting it to `0` disables the screen effect for that drink while still processing the purchase and animation.
</Note>

## Adding Multiple Bar Locations

Add as many `vector4` entries to `Config.BarNPCLocations` as your server needs. The script spawns one bartender NPC and one map blip per entry automatically — no additional scripting required.

```lua shared/config.lua theme={null}
Config.BarNPCLocations = {
    vector4(1984.46, 3054.71, 46.22, 253.76),  -- Default location 1
    vector4(-562.0,  286.17,  81.18, 264.94),   -- Default location 2
    vector4(247.49,  -1387.35, 29.32, 338.0),   -- Example: additional location
}
```

<Tip>
  Use a tool like **CodeWalker** or your server's in-game coordinate grabber to get accurate `vector4` values for NPC placement. The fourth value is the NPC's heading in degrees — `0.0` faces north, `90.0` faces east.
</Tip>

## Map Blips

When `BlipConfig.Enabled = true`, a blip appears on the minimap and main map for every NPC location in `Config.BarNPCLocations`. Adjust `Sprite`, `Color`, and `Scale` using standard FiveM blip values to match your server's map style.

<Accordion title="Common blip sprite and colour reference">
  | Value | Sprite               | Notes                       |
  | ----- | -------------------- | --------------------------- |
  | `93`  | Bar / cocktail glass | Default for sh-npcbartend   |
  | `53`  | Dollar sign          | Useful for shop-style blips |
  | `1`   | Standard circle      | Generic fallback            |

  | Value | Colour               |
  | ----- | -------------------- |
  | `0`   | White                |
  | `1`   | Red                  |
  | `2`   | Green                |
  | `3`   | Blue                 |
  | `5`   | Yellow               |
  | `46`  | Light blue (default) |
</Accordion>

## Target Interaction

<Tabs>
  <Tab title="Proximity (default)">
    When `Config.Target = false`, players walk up to the NPC and press `[E]` to open the drinks menu. No additional resources are required.
  </Tab>

  <Tab title="ox_target">
    Set `Config.Target = 'ox'` to enable third-eye interaction via ox\_target. Players hover over the NPC and press their target key to see the purchase option.

    ```lua shared/config.lua theme={null}
    Config.Target = 'ox'
    ```
  </Tab>

  <Tab title="qb-target">
    Set `Config.Target = 'qb'` to use qb-target instead. The interaction box appears when a player looks at the NPC.

    ```lua shared/config.lua theme={null}
    Config.Target = 'qb'
    ```
  </Tab>
</Tabs>