An advanced, premium, and fully standalone scratchcard system for FiveM.

🌟 Features

• 100% Framework Agnostic: Automatically detects and bridges ESX, QBCore, and QBox without any required modifications.

• Universal Inventory Support: Works out of the box with `ox_inventory`, `qs-inventory`, `qb-inventory`, and core defaults.

• Multi-Lingual: Built-in dynamic locale system (`pl`, `en`, `es`, `de`).

• Luxurious NUI: Interactive, high-performance HTML5 canvas scratching with foil shaders, particle noises, and custom cursors.

• Highly Configurable: `scratches.js` allows buyers to theme the cards entirely via CSS variables (backgrounds, fonts, colors, icons) without touching the core UI logic.

• Security: Advanced Anti-Spam and Exploit Protection natively integrated via Discord Webhooks.

📦 Installation

1. Drag and drop the `bj_scratch` folder into your server `resources` directory.

2. Ensure it is started in your `server.cfg`:

ensure bj_scratch

3. Copy the item names (`scratch_premium`, `scratch_regular`, `scratch_cash`) to your inventory's `items.lua` or database.

 🛠 Configuration

Open `config.lua` to manage global variables:

- `Config.Locale`: Available options are 'en', 'pl', 'es', or 'de'.

- `Config.Framework`: Leave as `autodetect` or explicitly strictly define an environment (`esx`, `qb`).

- `Config.DiscordWebhook`: Paste your Discord Webhook URL for reward and exploit logs.

🏦 Physical Rewards System (Winning Tickets)

You can configure the script to either give raw cash directly after winning, or give an interactive **Winning Ticket** inventory item (`winning_ticket` with integrated metadata).

Inside `config.lua`, the `Config.PhysicalRewards` block handles this logic:

- `Enabled = true`: Gives a physical metadata ticket.

- `SpawnPeds = true`: Spawns banker NPCs on the map at `Locations` coords.

- `UseTarget = 'autodetect'`: Automatically assigns `ox_target` or `qb-target` to the banker NPCs so players can exchange tickets for cash!

💡 How to add a NEW Custom Scratchcard

This script was built to be infinitely scalable. You can create as many unique scratchcards as you want.

Step 1. Define the item in `config.lua`:

Add a new dictionary entry inside the `Config.Items` table mapping logical data:

['scratch_gold'] = {

    label = "Golden Scratch",

    type = 'gold', -- This specific string links to the JS Config logic!

    cellsCount = 9, -- Example: 3x3 grid size

    winRequirement = 3, -- Must match 3 identical symbols to trigger win

    jackpotAmount = 50000,

    rewards = {

        { amount = 0, chance = 60.0 },

        { amount = 1000, chance = 30.0 },

        { amount = 50000, chance = 10.0 }

    }

}

Step 2. Translate the Titles:

Go to the `locales/` folder and open your active language file (e.g., `en.lua` or `pl.lua`). Register the exact UI translation strings:

-- Append the following lines under the others:

['scratch_gold_label'] = "GOLD EXTREME",

['scratch_gold_inst'] = "Scratch and win big! Find exact amounts to win.",

Step 3. Style it visually in `scratches.js`:

Open `scratches.js` located in the root directory. Add your new `'gold'` identifier under `ScratchesConfig` containing aesthetic properties:

'gold': {

    theme: {

        background: "url('assets/bg_gold.png')",

        borderColor: "#ffcc00",

        // Copy the styling parameters from the other cards and customize...

    },

    icons: {

        "50000": '<i class="fa-solid fa-gem" style="color: gold;"></i>',

        "1000": '<i class="fa-solid fa-coins"></i>',

        "default": '<i class="fa-solid fa-xmark"></i>'

    }

}

The script backend automatically intercepts, bridges, and registers the usable items dynamically!