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

# Installation

> Install vrs_newspaper: requirements, resource order, item setup, and default configuration.

## Overview

`vrs_newspaper` is a newspaper delivery job. Players clock in at the depot, pick a district, ride a bike out, and throw papers at ten houses. Pays on completion, with tips, bonuses, and cooldowns.

<CardGroup cols={2}>
  <Card title="Framework support" icon="layers">
    Fully supports QBox, QBCore, and ESX via [vrs\_bridge](/getting-started/submitting-a-request).
  </Card>

  <Card title="Auto-detected systems" icon="wand-sparkles">
    Inventory, target script, and vehicle keys are all detected automatically by `vrs_bridge`.
  </Card>

  <Card title="Persistent cooldowns" icon="database">
    Cooldowns are stored against the character in MySQL, so relogs and restarts do not clear them.
  </Card>

  <Card title="Open configuration" icon="sliders-horizontal">
    Every file in `config/` ships open, no escrow, so routes, pay, and throwing feel are yours to edit.
  </Card>
</CardGroup>

## Prerequisites

| Requirement     | Details                                               |
| --------------- | ----------------------------------------------------- |
| Game build      | **2802 or newer** (for `WEAPON_ACIDPACKAGE`)          |
| `vrs_bridge`    | v1.3.0 or newer. Must start **before** this resource. |
| `ox_lib`        | Points, keybinds, dialogs                             |
| `oxmysql`       | Stats and cooldown persistence                        |
| A target script | Optional. `ox_target` or `qb-target` if present       |

<Note>
  Framework, inventory, target, and vehicle-key system are all detected automatically by `vrs_bridge`, see its `config.lua` to pin anything by hand.
</Note>

## Installation steps

<Steps>
  <Step title="Resource deployment" icon="folder-down">
    Drop `vrs_bridge` and `vrs_newspaper` into your resources folder.
  </Step>

  <Step title="Register the newspaper item" icon="newspaper">
    GTA has no newspaper weapon, so this is an alias onto a real throwable. For ox\_inventory it goes in `data/weapons.lua`, **not** `items.lua`:

    ```lua data/weapons.lua theme={null}
    ['WEAPON_NEWSPAPER'] = {
        label = 'Newspaper',
        weight = 50,
        throwable = true,
        model = 'WEAPON_ACIDPACKAGE',
        client = { image = 'WEAPON_NEWSPAPER.png' },
    },
    ```

    Drop a `WEAPON_NEWSPAPER.png` into `ox_inventory/web/images/` for the icon.
  </Step>

  <Step title="Update server.cfg" icon="list-ordered">
    Add each resource **individually**, bridge first:

    ```cfg server.cfg theme={null}
    ensure oxmysql
    ensure ox_lib
    ensure vrs_bridge
    ensure vrs_newspaper
    ```

    <Warning>
      **Critical load order:** name resources individually, not `ensure [folder]`, a folder-wide ensure starts in arbitrary order. `vrs_bridge` has to come after `oxmysql` and before `vrs_newspaper`.
    </Warning>
  </Step>

  <Step title="Verify and boot" icon="circle-check">
    Boot the server. The database tables create themselves, `sql/install.sql` is there if you prefer to provision by hand.

    With `Config.Debug = true` in `vrs_bridge`, the console prints what it detected:

    ```bash theme={null}
    [vrs_bridge:SERVER] exports registered, framework = qbox
    ```
  </Step>
</Steps>

## Optional: lock it behind a job

Set `Config.Job.require = true` in `config.lua`, then add the job to your framework:

<Tabs>
  <Tab title="QBox / QBCore">
    Add to `shared/jobs.lua`:

    ```lua shared/jobs.lua theme={null}
    ['newspaper'] = {
        label = 'Newspaper',
        defaultDuty = true,
        grades = {
            [0] = { name = 'Carrier', payment = 50 },
        },
    },
    ```
  </Tab>

  <Tab title="ESX">
    Insert directly into the database:

    ```sql theme={null}
    INSERT INTO `jobs` (name, label) VALUES ('newspaper', 'Newspaper');
    INSERT INTO `job_grades` (job_name, grade, name, label, salary, skin_male, skin_female)
    VALUES ('newspaper', 0, 'carrier', 'Carrier', 50, '{}', '{}');
    ```
  </Tab>
</Tabs>

## Reference

### Configuration files

| File               | Contents                                                     |
| ------------------ | ------------------------------------------------------------ |
| `config.lua`       | Job gating, round size, pay, cooldowns, papers, HUD          |
| `routes.lua`       | The depot and the three districts' house pools               |
| `throwing.lua`     | The bag, the paper item, hit radius, markers, aim prediction |
| `vehicles.lua`     | The delivery bike and its paint                              |
| `interactions.lua` | Depot ped, target zone, blips                                |

### Key settings (`config.lua`)

| Setting                      | Default        | Effect                                                   |
| ---------------------------- | -------------- | -------------------------------------------------------- |
| `Config.Pay.perRoute`        | `150`          | Base for a full round, split across the houses           |
| `Config.Pay.payPerHouse`     | `false`        | `true` pays each house on the spot instead of at the end |
| `Config.Route.handInAtDepot` | `true`         | `false` pays the instant the last paper lands            |
| `Config.Cooldowns.enabled`   | `false`        | Master switch for every cooldown                         |
| `Config.Throw.hitRadius`     | `5.0`          | 3.0 is a real skill test, 8.0 is forgiving               |
| `Config.HUD.position`        | `middle-right` | Nine anchors; text alignment follows                     |

### Admin commands

| Command                          | Description                                 |
| -------------------------------- | ------------------------------------------- |
| `/npbuilder [action] [district]` | Route builder                               |
| `/npreset <id>`                  | Clear a player's cooldowns and active round |
| `/npstats <id>`                  | Show a player's record                      |

<Info>
  Gated behind `Config.Misc.adminPermission`, `group.admin` by default.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="&#x22;The depot has no papers to give out&#x22;" icon="triangle-alert">
    `WEAPON_NEWSPAPER` is not registered. Add it to `data/weapons.lua` and restart ox\_inventory. New items usually need a full server restart.
  </Accordion>

  <Accordion title="The weapon vanishes from your hands" icon="triangle-alert">
    Something else is stripping it. This job never force-equips; another resource is managing weapons.
  </Accordion>

  <Accordion title="Every throw costs two papers" icon="triangle-alert">
    `Config.Papers.inventoryConsumes` is `false` on an inventory that consumes throwables itself. Set it back to `true`.
  </Accordion>

  <Accordion title="Markers float or sit underground" icon="triangle-alert">
    `groundSnap` is off for that district. Set `groundSnap = true` on that district in `routes.lua`.
  </Accordion>

  <Accordion title="vrs_bridge errors on boot" icon="triangle-alert">
    It needs `oxmysql` started before it for the cooldown store. Check the ordering in `server.cfg`.
  </Accordion>

  <Accordion title="Cooldowns never expire, or never apply" icon="triangle-alert">
    `vrs_bridge` is older than v1.3.0. Earlier versions have no cooldown system at all, update it.
  </Accordion>
</AccordionGroup>