# PRINTER

### Features

* **Document printing** with customizable templates (LSPD, EMS, Fire, Federal, Government, Blank)
* **Photo printing** from image URLs
* **Copy system** to duplicate existing documents (with watermark)
* **Job & grade restrictions** per template
* **Command-based access** for non-job players
* **Paginated document viewer** with 3D flip animations
* **Zoom on documents & photos** (scroll wheel, follows cursor)
* **Dark / Light theme** configurable
* **Multi-framework**: auto-detects ESX or QBCore
* **Target support**: ox\_target & qb-target (or marker fallback)
* **Fully translatable** via locale files

***

### Installation

1. Place `forge-printer` in your server's `resources` folder.
2. Add `ensure forge-printer` to your `server.cfg`.
3. Add the required items to your inventory system:
   * `printed_document`
   * `printed_photo`

#### Item Setup (ox\_inventory example)

Add to your `ox_inventory/data/items.lua`:

```lua
['printed_document'] = {
    label = 'Printed Document',
    weight = 0,
    stack = false,
    close = true,
},

['printed_photo'] = {
    label = 'Printed Photo',
    weight = 0,
    stack = false,
    close = true,
},
```

For **QBCore shared items**, add the equivalent entries to `qb-core/shared/items.lua`.

***

### Configuration

All configuration is done in `config.lua`:

| Option                   | Description                                                                         |
| ------------------------ | ----------------------------------------------------------------------------------- |
| `Config.Locale`          | Language code (`'en'` by default). Create new files in `locales/` for translations. |
| `Config.InteractionMode` | `'target'` (ox\_target / qb-target) or `'marker'`                                   |
| `Config.UITheme`         | `'dark'` or `'light'`                                                               |
| `Config.CopyEnabled`     | Enable/disable the copy system                                                      |
| `Config.CopyJobs`        | Restrict who can make copies (`nil` = everyone)                                     |
| `Config.Printers`        | Table of printer locations with coords, cost, and allowed templates                 |
| `Config.Templates`       | Document templates with job access, fields, and styling                             |

#### Adding a Printer

```lua
{
    label     = 'My Printer',
    coords    = vector4(x, y, z, heading),
    prop      = 'prop_printer_01',
    cost      = 100,       -- 0 = free
    costType  = 'cash',    -- 'cash' or 'bank'
    templates = nil,       -- nil = all templates, or { 'blank', 'lspd' }
},
```

#### Adding a Template

```lua
{
    id           = 'mytemplate',
    label        = 'My Template',
    icon         = 'fa-solid fa-file',
    jobs         = { 'police' },              -- nil = everyone
    commandAccess = 'printer_mytemplate',      -- command to grant access
    accentColor  = '#3b82f6',
    sealText     = 'MY ORGANIZATION',
    headerTitle  = 'MY ORGANIZATION',
    headerSub    = 'OFFICIAL DOCUMENT',
    badgeIcon    = 'fa-solid fa-file-lines',
    fields       = { title = true, body = true, signature = true, image = true },
},
```

#### Job Access Formats

```lua
-- Simple: anyone with the job
jobs = { 'police', 'ambulance' }

-- With minimum grade
jobs = { { name = 'police', minGrade = 2 } }

-- Mixed
jobs = { 'fbi', { name = 'police', minGrade = 3 } }
```

***

### Locales

To add a new language:

1. Copy `locales/en.lua` to `locales/xx.lua` (e.g. `es.lua`)
2. Change `Locales['en']` to `Locales['xx']`
3. Translate all values
4. Set `Config.Locale = 'xx'` in `config.lua`

***

### Escrow

The following files are **not escrowed** and can be freely edited:

* `config.lua`
* `locales/*.lua`
* `bridge/*.lua`

***

### Support

For help, questions, or bug reports, join our Discord:

🔗 [**Discord Server**](https://discord.gg/UTVssdrXRV)