# SZ Giveaway — In-Game Giveaway System

Run giveaways your players can't miss. SZ Giveaway lets your staff create, schedule and draw giveaways right in-game, with a live on-screen banner, a slot-style draw animation and automatic prize delivery.

## 🎁 Five Prize Types

- **Items** and **weapons** (ox_inventory or qb-inventory, detected automatically)

- **Cash** and **bank** money

- **Vehicles** — added straight to the winner's garage

Add multiple prizes to a single giveaway and optionally limit winners to one prize per person.

## 📺 Live On-Screen Experience

- A **live banner** shows the giveaway, its prizes and a countdown on every player's screen, then shrinks into a compact badge

- Players join with **one key (E)** while the banner is visible, or from the panel — the key can be rebound in FiveM settings

- **Countdown** in the final seconds

- **Slot-style draw animation** reveals each winner

- A **result board** for everyone and a personal **congratulations card** with sound for winners

## ⚖️ Fair & Verifiable Draws

Winners are picked on the server (Fisher-Yates shuffle). The seed and a **verification digest** are saved and shown on the result board. The animation is visual only: winners are always decided server-side first.

## 🛡️ Entry Rules (per giveaway)

- Whitelisted players only (with sz-whitelist)

- One entry per account

- One entry per device (hardware token check)

- Banned jobs (e.g. police, ambulance)

- Block entries while injured or cuffed

Entries are stored in the database and stay valid even if the player disconnects.

## 📦 Prizes Never Get Lost

Online winners receive their prize instantly. If the winner is offline or their inventory is full, the prize is kept as **pending** and delivered automatically when they log in. They can also claim it from **My History**, and staff can retry deliveries from the **Pending Rewards** page.

## 🧙 Four-Step Giveaway Wizard

**Info → Rewards → Rules → Preview**

- Title, duration and colour theme

- **Scheduled start** at a date and time

- **Templates** — save up to 100 giveaways and reuse them

- **Start now**, **add to queue** (starts automatically after the current one) or **save for later**

## 🛠️ Admin Tools

- **Manage:** draw now, cancel, see participants, mark entries invalid, suspicious same-device entries highlighted

- **Pending Rewards:** online/offline status, delivery attempts, retry

- **Logs:** every action, filterable by player, type, giveaway and date

- **Discord logs:** separate webhook per event plus a rich winner announcement

- Console commands for status, draw and cancel

## 👥 For Players

- **Active Giveaway** with prizes, odds and latest entries

- **History** of past giveaways and winners

- **My History** with wins, streaks and pending prizes

- **Remind me** for upcoming giveaways

## ⚙️ Fully Configurable

Every text, key, command, limit, screen position, sound and Discord setting is in a single **config.lua**. Database tables are created automatically on first start.

## 📋 Requirements

- QBCore

- ox_lib

- oxmysql

- ox_inventory **or** qb-inventory

Panel command: `/giveawaymenu`