Ares Scratchers - Installation & Configuration Guide

Version: 1.0.0 Author: Roroleroh Framework Support: ESX, QB-Core, QBX

📋 Table of Contents

Overview
Installation
Dependencies
Creating Scratchers
Configuration Guide
Adding Custom Scratchers
Item Configuration

🎯 Overview

Ares Scratchers is a modular scratch card system that allows players to purchase and scratch lottery tickets for prizes. Features include:

Visual scratch mechanics - Interactive scratch card UI with realistic effects
Customizable prizes - Configure win chances, cash rewards, and item rewards
Prize pools - Weighted probability system for balanced gameplay
Web-based builder - Create and export scratchers using visual tools
Particle effects - Customizable visual feedback when scratching
Rate limiting - Per-player cooldowns to prevent abuse
Multi-framework support - Works with ESX, QB-Core, and QBX

🚀 Installation

⚠️ Important: Resource Name

The resource folder MUST be named exactly:

ares_scratchers

Do not rename the folder. The script will not work correctly with any other name.

Setup Steps

Extract the resource to your server's resources folder
Add to server.cfg:
```
ensure ares_scratchers
```
Install dependencies (see Dependencies)
Create your first scratcher using the web builder
Restart your server

No database setup required - scratchers use JSON-based storage.

📦 Dependencies

Required

ox_lib - Core library for NUI/menu helpers

Framework (Choose One)

ESX (es_extended)
QB-Core (qb-core)
QBX Core (qbx_core)

Optional

ox_target or qb-target - Entity/zone targeting
ox_inventory or qb-inventory - Enhanced inventory integration

The script automatically detects your framework and inventory system.

🎨 Creating Scratchers

Web-Based Scratcher Builder

Use the official Ares Scratchers builder to create custom scratchers visually:

🔗 https://scratchers-tools.ares-studio.net/

Builder Features

1. Upload Assets

Upload front and back images (PNG format)
Both images must have the same resolution
Recommended: 512x512px or 1024x1024px

2. Font Settings

Font Family - Choose from web-safe fonts
Font Size - Adjust prize text size (px)
Color - Set text color for prize reveal
Alignment - Left, Center, or Right alignment
Preview - Position text using live preview panel

3. Web Config Settings

Scratch Behavior:

Brush Size - Size of the scratch area (pixels)
Complete Threshold - Percentage scratched to auto-reveal (%)

Particle Effects:

Particle Count - Number of particles when scratching
Particle Lifetime - How long particles exist (ms)
Particle Gravity - Downward force on particles
Particle Size - Min/max size range (px)

Base Dimensions:

Automatically calculated from uploaded images
Used for proper UI scaling

4. Item Metadata

Item Name - Internal ID (lowercase, no spaces)
Display Label - Name shown in inventory
Description - Item description text
Weight - Item weight in grams
Stackable - Can players stack multiple?

5. Prize Pool

Add multiple prizes with win chances
Total must equal 100%
Reward types:
- None (Lose) - No prize
- Give Cash - Money to player's wallet
- Give Bank Money - Money to player's bank
- Give Dirty Money - Black money (ESX)
- Give Item - Specific inventory item

6. Export

Click Export ZIP to download complete package
Package includes everything needed for installation

📥 Adding Custom Scratchers

Installation Process (3 Steps)

After exporting from the web builder, you'll receive a ZIP with this structure:

editor/
├── INSTALL.txt                    # Step-by-step instructions
├── backend/                       # SERVER FILES
│   ├── list.json                  # Registry file
│   └── my_scratcher/
│       ├── data.json              # Scratcher configuration
│       ├── prizes.json            # Prize pool
│       └── assets/
│           ├── front.png
│           └── back.png
├── frontend/                      # CLIENT UI FILES
│   └── my_scratcher/
│       ├── config.json            # Web configuration
│       └── assets/
│           ├── front.png
│           └── back.png
└── _framework_configs/            # Framework item definitions

Step 1: Copy Backend Files (Server-Side)

Copy the contents of the backend/ folder to:

resources/ares_scratchers/scratchers/

Result:

ares_scratchers/
└── scratchers/
    ├── list.json            ← Add/merge this
    └── my_scratcher/        ← Copy this folder
        ├── data.json
        ├── prizes.json
        └── assets/

⚠️ IMPORTANT - Merging list.json:

If this is your FIRST scratcher:

Just copy the entire backend/ folder
The list.json file is already complete

If you ALREADY HAVE other scratchers:

DO NOT replace list.json
Open your existing list.json
Add the new entry to the "scratchers" array:

{
  "scratchers": [
    {
      "itemName": "existing_scratcher",
      "label": "Existing Scratcher"
    },
    {
      "itemName": "my_scratcher",
      "label": "My Scratcher"
    }
  ]
}

Step 2: Copy Frontend Files (Client-Side)

Copy the contents of the frontend/ folder to:

resources/ares_scratchers/html/scratchers/

Result:

ares_scratchers/
└── html/
    └── scratchers/
        └── my_scratcher/     ← Copy this folder
            ├── config.json
            └── assets/
                ├── front.png
                └── back.png

Step 3: Register Item in Your Framework

Choose ONE of the following based on your framework. Ready-to-use snippets are in the _framework_configs/ folder.

Step 4: Restart Server

Execute in server console:

ensure ares_scratchers

Or restart your entire server.

⚙️ Configuration Guide

All configuration is done in shared/config.lua.

Rate Limiter Settings

Config.Limiter = {
    Enabled = true,
    MaxUses = 3,
    CooldownSeconds = 100
}

Parameter

Type

Description

Default

Enabled

boolean

Enable per-player rate limiting

true

MaxUses

number

Maximum scratchers before cooldown

3

CooldownSeconds

number

Cooldown duration in seconds

100

How it works:

Players can use up to MaxUses scratchers
After reaching the limit, they must wait CooldownSeconds
Prevents spam and maintains server economy balance

Example - Tighter limits:

Config.Limiter = {
    Enabled = true,
    MaxUses = 5,           -- 5 scratchers
    CooldownSeconds = 300  -- 5 minute cooldown
}

Disable rate limiting:

Config.Limiter = {
    Enabled = false,
    MaxUses = 999,
    CooldownSeconds = 0
}

Animation Settings

Config.Animation = {
    EntryDuration = 500,
    BounceScale = 1.05,
    ExitDuration = 300
}

Parameter

Type

Description

Default

EntryDuration

number

Entry animation duration (milliseconds)

500

BounceScale

number

Bounce overshoot multiplier

1.05

ExitDuration

number

Exit animation duration (milliseconds)

300

Description: Controls the timing and feel of the scratcher UI animations.

Slower animations:

Config.Animation = {
    EntryDuration = 800,   -- Slower entry
    BounceScale = 1.08,    -- More bounce
    ExitDuration = 500     -- Slower exit
}

Scratch Validation

Config.Scratch = {
    Enabled = true,
    MinimumTime = 2000
}

Parameter

Type

Description

Default

Enabled

boolean

Enable minimum scratch time validation

true

MinimumTime

number

Minimum active scratch time (milliseconds)

2000

Description: Prevents instant auto-scratch exploits by requiring players to actively scratch for a minimum duration.

Example - Longer required scratch:

Config.Scratch = {
    Enabled = true,
    MinimumTime = 3500  -- Must scratch for 3.5 seconds
}

Disable validation (not recommended):

Config.Scratch = {
    Enabled = false,
    MinimumTime = 0
}

Notification Settings

Config.Notifications = {
    UseFramework = true,
    WinTitle = "Scratcher",
    WinIcon = "fas fa-ticket-alt",
    LoseMessage = "Better luck next time!"
}

Parameter

Type

Description

UseFramework

boolean

Use framework's notification system

WinTitle

string

Title for win notifications

WinIcon

string

Font Awesome icon for notifications

LoseMessage

string

Message shown when player loses

Customization example:

Config.Notifications = {
    UseFramework = true,
    WinTitle = "🎰 Lottery Result",
    WinIcon = "fas fa-trophy",
    LoseMessage = "Try again! You might win next time!"
}

Logging Settings

Config.Logging = {
    Enabled = true,
    Console = true,
    Database = false,
    Discord = false,
    WebhookURL = ""
}

Parameter

Type

Description

Enabled

boolean

Enable logging system

Console

boolean

Log to server console

Database

boolean

Log to database (requires oxmysql)

Discord

boolean

Send logs to Discord webhook

WebhookURL

string

Discord webhook URL

Discord webhook setup:

Config.Logging = {
    Enabled = true,
    Console = true,
    Database = false,
    Discord = true,
    WebhookURL = "https://discord.com/api/webhooks/YOUR_WEBHOOK_URL"
}

What gets logged:

Player identifier
Scratcher used
Prize won
Timestamp
Win/loss result

Debug Mode

Config.Debug = true

Description: Enable detailed console logging for troubleshooting. Production: Set to false to reduce console spam.

🎒 Item Configuration

Item Properties Explained

When creating scratchers, you'll configure these item properties:

Property

Type

Description

Example

name

string

Internal item ID (lowercase)

'golden_scratcher'

label

string

Display name in inventory

'Golden Scratcher'

weight

number

Item weight (grams)

100

stackable

boolean

Can players stack multiple?

true

useable

boolean

Can item be used?

true

description

string

Item description

'Win big prizes!'

Example Items by Rarity

Common Scratcher:

['bronze_scratcher'] = {
    label = 'Bronze Scratcher',
    weight = 50,
    stack = true,
    description = 'Basic scratcher - Small prizes'
}

Rare Scratcher:

['gold_scratcher'] = {
    label = 'Gold Scratcher',
    weight = 150,
    stack = true,
    description = 'Premium scratcher - Big prizes!'
}

Limited Edition:

['diamond_scratcher'] = {
    label = 'Diamond Scratcher',
    weight = 200,
    stack = false,  -- Make it special, no stacking
    description = 'Legendary scratcher - Jackpot prizes!'
}

📝 Quick Reference

Essential Configuration Checklist

✅ Create scratcher using web builder
✅ Copy backend files to scratchers/
✅ Merge list.json if needed
✅ Copy frontend files to html/scratchers/
✅ Add item to your framework
✅ Configure rate limiter in config.lua
✅ Set Config.Debug = false in production
✅ Test scratcher in-game

Performance Tips

Set Config.Debug = false on live servers
Use reasonable particle counts (50-200)
Keep image resolutions consistent (512px or 1024px)
Enable rate limiting to prevent spam

Common Customizations

Disable cooldowns:

Config.Limiter = {
    Enabled = false,
    MaxUses = 999,
    CooldownSeconds = 0
}

Faster animations:

Config.Animation = {
    EntryDuration = 300,
    BounceScale = 1.02,
    ExitDuration = 200
}

Custom win messages:

Config.Notifications = {
    UseFramework = true,
    WinTitle = "🎉 WINNER!",
    WinIcon = "fas fa-trophy",
    LoseMessage = "Not this time, champ!"
}

🔧 Troubleshooting

Issue

Solution

Scratcher doesn't appear

Check list.json is properly merged

Images not loading

Verify file paths in config.json and data.json

Can't use scratcher

Ensure item is added to framework items

No prize awarded

Check prizes.json - total must equal 100%

Rate limit not working

Verify Config.Limiter.Enabled = true

Particles not showing

Check particle settings in scratcher config.json

🎯 Prize Pool Example

Balanced prize pool for a $100 scratcher:

Prize

Win Chance

Value

Nothing

70%

Small Prize

20%

$50

Medium Prize

$200

Big Prize

1.9%

$1,000

Jackpot

0.1%

$10,000

Total: 100% Expected return: ~$60 per scratcher House edge: 40%

🌐 Web Builder Reference

Builder URL: https://scratchers-tools.ares-studio.net/

What you can configure:

✅ Visual appearance (images, fonts, colors)
✅ Scratch mechanics (brush size, threshold)
✅ Particle effects (count, lifetime, gravity)
✅ Prize pools (chances, rewards, items)
✅ Item metadata (name, weight, description)

What you get:

✅ Complete backend configuration
✅ Frontend UI files
✅ Framework item snippets
✅ Installation instructions
✅ Ready-to-use ZIP package

Support: For issues or questions, please contact Ares Studio. License: This script is protected and should not be redistributed without permission.

PreviousAres-scratchers NextAres Armory

Last updated 22 days ago

Was this helpful?

Good afternoon

hashtag📋 Table of Contents

hashtag🎯 Overview

hashtag🚀 Installation

hashtag⚠️ Important: Resource Name

hashtagSetup Steps

hashtag📦 Dependencies

hashtagRequired

hashtagFramework (Choose One)

hashtagOptional

hashtag🎨 Creating Scratchers

hashtagWeb-Based Scratcher Builder

hashtagBuilder Features

hashtag📥 Adding Custom Scratchers

hashtagInstallation Process (3 Steps)

hashtagStep 1: Copy Backend Files (Server-Side)

hashtagStep 2: Copy Frontend Files (Client-Side)

hashtagStep 3: Register Item in Your Framework

hashtagStep 4: Restart Server

hashtag⚙️ Configuration Guide

hashtagRate Limiter Settings

hashtagAnimation Settings

hashtagScratch Validation

hashtagNotification Settings

hashtagLogging Settings

hashtagDebug Mode

hashtag🎒 Item Configuration

hashtagItem Properties Explained

hashtagExample Items by Rarity

hashtag📝 Quick Reference

hashtagEssential Configuration Checklist

hashtagPerformance Tips

hashtagCommon Customizations

hashtag🔧 Troubleshooting

hashtag🎯 Prize Pool Example

hashtag🌐 Web Builder Reference

📋 Table of Contents

🎯 Overview

🚀 Installation

⚠️ Important: Resource Name

Setup Steps

📦 Dependencies

Required

Framework (Choose One)

Optional

🎨 Creating Scratchers

Web-Based Scratcher Builder

Builder Features

📥 Adding Custom Scratchers

Installation Process (3 Steps)

Step 1: Copy Backend Files (Server-Side)

Step 2: Copy Frontend Files (Client-Side)

Step 3: Register Item in Your Framework

Step 4: Restart Server

⚙️ Configuration Guide

Rate Limiter Settings

Animation Settings

Scratch Validation

Notification Settings

Logging Settings

Debug Mode

🎒 Item Configuration

Item Properties Explained

Example Items by Rarity

📝 Quick Reference

Essential Configuration Checklist

Performance Tips

Common Customizations

🔧 Troubleshooting

🎯 Prize Pool Example

🌐 Web Builder Reference