# PRINTER

{% embed url="<https://youtu.be/QcqT5QVjGgU?si=PJbTjgdtmUThqPEe>" %}

### 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)


---

# 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://codeforge.gitbook.io/codeforge/mini-scripts/printer.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.