# Big David

***

### ✨ Highlights

| Feature                        | Description                                                                   |
| ------------------------------ | ----------------------------------------------------------------------------- |
| 🧩 **Multi-Framework**         | Native support for QBCore, QBox, and ESX with automatic detection.            |
| 🎒 **Multi-Inventory**         | Compatible with ox\_inventory, qs-inventory, qb-inventory, and ESX inventory. |
| 🎯 **Multi-Target**            | Works with ox\_target, qb-target, and interact systems.                       |
| 👨‍💼 **Two Distinct NPCs**    | A vendor (Big David) and a buyer (Miss Boney), each fully configurable.       |
| 🌙 **Time-Based Availability** | Restrict NPCs to night, day, or custom hour windows.                          |
| 💰 **Flexible Payments**       | Pay players in cash, bank transfers, or custom items.                         |
| 📦 **Dynamic Stock**           | Item availability rotates between configurable min/max ranges.                |
| 🗂️ **Categorized Shop UI**    | Filterable categories (Tools, Heist, Weapons, Ammo).                          |
| 📡 **Discord Logging**         | Webhook integration for transactions and security events.                     |
| 🗺️ **Map Blips**              | Optional map markers for both NPCs.                                           |
| ⚡ **Performance Optimized**    | Minimal resmon footprint, no idle loops, event-driven design.                 |

***

### 🧠 Concept

Big David runs on a closed criminal economy loop:

1. **Acquire** — Players visit Big David to purchase heist tools (thermite, keys, zip ties, breakers, weapons, ammo).
2. **Execute** — Players use those tools across other heist scripts to obtain stolen goods.
3. **Launder** — Players bring stolen goods to Miss Boney, who pays them out in clean money.

This creates a self-sustaining gameplay cycle where heist activity has both an entry cost and a clear payout path, encouraging meaningful in-character economic decisions.

***

### 🏗️ Architecture

The script is built on a clean, modular architecture with strict separation of concerns:

```
📦 X8-BigDavid/
 ┣ 📂 bridge/
 ┃  ┣ Detect.lua      → Runtime framework & inventory detection
 ┃  ┣ Shared.lua      → Shared utilities (client + server)
 ┃  ┣ Server.lua      → Server-side abstraction layer
 ┃  ┗ Client.lua      → Client-side abstraction layer
 ┣ 📂 client/         → NPC spawning, target zones, UI logic
 ┣ 📂 server/         → Transactions, validation, callbacks
 ┣ 📂 html/           → NUI interface (HTML / CSS / JS)
 ┗ config.lua         → Centralized configuration
```

#### Layered Design

| Layer              | Responsibility                                         |
| ------------------ | ------------------------------------------------------ |
| **Configuration**  | All gameplay parameters, prices, NPCs, and items.      |
| **Bridge**         | Framework, inventory, and target abstraction.          |
| **Business Logic** | Transaction handling, stock rotation, time validation. |
| **Presentation**   | NUI shop interface and in-game notifications.          |

This separation means a developer can replace the entire framework or inventory layer without touching the gameplay code, and a server owner can fully customize behavior without touching code at all.

***

### 🛡️ Security Model

Security is enforced server-side at every step:

* **Authoritative Server** — All transactions are validated on the server. The client only requests; the server decides.
* **Item Verification** — Every sale verifies the player actually owns the item before any payout occurs.
* **Stock Validation** — Purchase requests are validated against the live server-side stock, never trusting client state.
* **Time Validation** — Time-based access checks happen on the server using the in-game world clock.
* **Webhook Auditing** — Optional Discord webhook logs every transaction for forensic review.

{% hint style="danger" %} The script never trusts client-sent values for prices, quantities, or stock. All economic decisions are computed and validated server-side. {% endhint %}

***

### 🎮 Player Experience

When a player approaches Big David, they trigger a target interaction that opens a custom NUI shop. The shop features:

* A category filter bar for browsing item types.
* Live stock counters that update as items are purchased.
* Item cards displaying icon, label, price, description, and current availability.
* Real-time inventory feedback through framework-native notifications.

Selling to Miss Boney follows the same pattern — a target interaction opens a sell interface where players choose items and quantities, and receive payment instantly upon confirmation.

***

### 📋 Requirements

| Dependency    | Purpose                                                     | Required       |
| ------------- | ----------------------------------------------------------- | -------------- |
| **Framework** | QBCore / QBox / ESX                                         | ✅ One required |
| **Inventory** | ox\_inventory / qs-inventory / qb-inventory / ESX inventory | ✅ One required |
| **Target**    | ox\_target / qb-target / interact                           | ⚠️ Recommended |
| **ox\_lib**   | Notifications & callbacks (QBox / ESX)                      | ⚠️ Recommended |

***

### 🚀 Quick Start

1. **Install** — Drop the resource folder into your server's `resources/` directory.
2. **Configure** — Open `config.lua` and adjust framework, inventory, and target settings (or leave them on `auto`).
3. **Customize** — Edit NPC locations, item prices, categories, and time windows to match your server's economy.
4. **Add Items** — Ensure all referenced items exist in your inventory's item registry.
5. **Start** — Add `ensure bigdavid` to your `server.cfg` and restart your server.

{% hint style="success" %} Continue to the [Configuration](/x8project/projects/big-david/configuration.md) and [Bridge System](/x8project/projects/big-david/bridge-system.md) pages for full reference documentation. {% endhint %}

***

### 💡 Use Cases

This script is ideal for servers that want to:

* Build a **realistic criminal economy** with clear progression and risk/reward loops.
* Provide a **centralized hub** for heist tools instead of scattering them across multiple shops.
* Offer **roleplay-driven black market interactions** with NPCs that feel alive.
* Create **time-restricted gameplay** that encourages organized planning.
* Maintain **clean, auditable transactions** through Discord webhook logging.

{% content-ref url="/pages/ARubZ5fB78APED8nPMPY" %}
[Configuration](/x8project/projects/big-david/configuration.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://x8project.gitbook.io/x8project/projects/big-david.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.