Documentation
Install Lottery Creator on your FiveM server: requirements, server.cfg load order, the database, the scratchcard item for ox_inventory, qs-inventory, qb-inventory and ESX, creator access and upgrading.
Before installing Lottery Creator, make sure your server meets the requirements. Three resources and a framework are mandatory; everything else is optional and detected on its own.
Requirement | Status | Notes |
|---|---|---|
| Required | Declared as a dependency, so the resource will not start without it. |
| Required |
Database access. |
| Required | Callbacks, model and animation loading, shared helpers. |
Framework | Required |
|
| Included | Streams the lottery machine and the scratch ticket props. It comes in the same download. |
Target | Optional |
|
| Optional | Draws those 3D prompts with Quasar's text UI instead of plain game text. |
| Optional | Its HUD is hidden, with the radar, while the creator is open. |
Quasar Smartphone | Optional | Adds the Lottery app to the phone. |
The framework and the target are picked by looking at what is already running:
Layer | Detection |
|---|---|
Framework |
|
Target |
|
Prompts |
|
Every optional integration stands down silently when its resource is missing. Integrations has the details.
After purchasing Lottery Creator, the resource is automatically linked to your CFX Portal account.
Sign in to the CFX Portal using the same account used during checkout, open Granted Assets, and download Lottery Creator.
After extracting the download, you should have two resources:
[lottery]/
├── lottery_machine/ -- streamed props: the machine and the scratch ticket
└── qs-lottery-creator/
├── config/main.lua -- every setting you may edit
├── custom/ -- framework bridges (editable)
├── database/ -- database.sql
├── locales/ -- 41 languages
└── web/ -- the interface, nothing to editKeep the folder named
qs-lottery-creator. The phone app looks for the lottery under that exact name, so a renamed copy works at the machines but the Lottery app reports that it is not running.
Move the [lottery] folder — both resources — into your server's resources directory. It can live inside a category folder:
resources/
└── [qs]/
└── [lottery]/
├── lottery_machine/
└── qs-lottery-creator/Then open your server.cfg and make sure every dependency — and everything it should detect — starts before Lottery Creator:
ensure oxmysql
ensure ox_lib
# Framework
ensure es_extended
# ensure qb-core
# ensure qbx_core
# Target and prompts (optional)
ensure ox_target
ensure qs-textui
# Lottery
ensure lottery_machine
ensure qs-lottery-creatorThe loading order matters. The framework and the target are detected once, when Lottery Creator starts: a framework that starts later stops the resource from loading, and a target that starts later is not seen, so machines fall back to prompts. ensure [lottery] also works, as long as it comes after them.
Every machine lives in one table, qs_lottery_vendors. Import database/database.sql once, before the first start, with HeidiSQL or any other MariaDB / MySQL client.
Columns | Hold |
|---|---|
| The machine itself: its name, its model, its position and heading. |
| What a ticket costs, the item it gives and the account it is paid from. |
| The map blip, and who may use the machine. |
| The identifier of whoever last saved it in the creator. |
| The player who owns it, the name shown for them, and the earnings waiting to be collected. |
| Whether players can buy it, and for how much. |
| Tickets loaded in an owned machine, lifetime sales and gross revenue. |
CREATE TABLE IF NOT EXISTS `qs_lottery_vendors` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`creator` varchar(50) NOT NULL,
`label` varchar(255) NOT NULL,
`prop` varchar(100) NOT NULL,
`price` int(11) NOT NULL DEFAULT 100,
`item` varchar(100) NOT NULL DEFAULT 'scratchcard',
`account` varchar(50) NOT NULL DEFAULT 'money',
`coords` longtext NOT NULL,
`blip` longtext DEFAULT NULL,
`job` longtext DEFAULT NULL,
`job_grades` longtext DEFAULT NULL,
`owner` varchar(60) DEFAULT NULL,
`owner_name` varchar(100) DEFAULT NULL,
`balance` int(11) NOT NULL DEFAULT 0,
`for_sale` tinyint(1) NOT NULL DEFAULT 1,
`purchase_price` int(11) NOT NULL DEFAULT 25000,
`tickets_sold` int(11) NOT NULL DEFAULT 0,
`total_revenue` int(11) NOT NULL DEFAULT 0,
`stock` int(11) NOT NULL DEFAULT 0,
`created_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
`updated_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
KEY `creator` (`creator`),
KEY `owner` (`owner`),
KEY `label` (`label`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;A lottery ticket is an inventory item: a machine hands it out, and using it opens the card. The item must exist in your inventory under the name in Config.VendorDefaults.item — scratchcard by default. Lottery Creator registers it as usable through your framework when it starts; you only add the definition.
In ox_inventory/data/items.lua. This is also the one for Qbox.
['scratchcard'] = {
label = 'Scratch & Win',
weight = 10,
stack = true,
close = true,
description = 'A lottery scratchcard. Scratch the surface and test your luck.',
},In qs-inventory/shared/items.lua.
['scratchcard'] = {
['name'] = 'scratchcard',
['label'] = 'Scratch & Win',
['weight'] = 10,
['type'] = 'item',
['image'] = 'scratchcard.png',
['unique'] = false,
['useable'] = true,
['shouldClose'] = true,
['combinable'] = nil,
['description'] = 'A lottery scratchcard. Scratch the surface and test your luck — you might win some cash or nothing at all.'
},In qb-core/shared/items.lua.
scratchcard = { name = 'scratchcard', label = 'Scratch & Win', weight = 10, type = 'item', image = 'scratchcard.png', unique = false, useable = true, shouldClose = true, description = 'A lottery scratchcard. Scratch the surface and test your luck — you might win some cash or nothing at all.' },The default ESX inventory reads its items from the database:
INSERT INTO `items` (`name`, `label`, `weight`) VALUES
('scratchcard', 'Scratch & Win', 10);Add an icon named scratchcard.png to your inventory's image folder so the ticket does not show as a blank square.
Renaming the item? Change
Config.VendorDefaults.itemand the inventory entry together. Only that item opens a card — the Scratch Item field of a single machine changes what that machine hands out, not what can be scratched.
Machines are placed and edited from /lotterycreator, and every save is checked on the server. Any of these routes lets a player in:
Players in the admin or superadmin group. From the server console:
setgroup <server id> adminPlayers with the admin or god permission, or with the command ace — the one txAdmin admins already have. In server.cfg:
add_ace group.admin command allow
add_principal identifier.license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx group.adminJobs listed in Config.CreatorJobs can open the creator too. grade is either false for every grade, or a list of the exact grades allowed:
Config.CreatorJobs = {
{ job = 'police', grade = false }, -- every grade
{ job = 'realestate', grade = { 3, 4 } }, -- only grades 3 and 4
}A creator job places and edits machines. The admin controls of an owned machine — listing it for sale, evicting its owner — stay with framework admins.
Every setting lives in one file, config/main.lua, with a comment above each block. The other editable folders are for plumbing:
File | Contents |
|---|---|
| Language, money format, creator access, payment accounts, defaults for new machines, props, ownership, interaction, prizes, the phone, creator keys and camera, debug. |
| Every line of text, one file per language. |
| The bridges to your framework: money, items, jobs, admins and character names. |
| The table, for a fresh install only. |
The values worth reviewing first:
Config.Locale = 'en' -- any file in locales/
Config.VendorDefaults = {
label = 'Lottery Machine',
item = 'scratchcard', -- the ticket item
price = 30, -- new machines and the phone app
account = 'money', -- money · bank · black_money
prop = 'lotrrery_vending_machine',
}
Config.Ownership.enabled = true -- players can buy and run machines
Config.Phone.enabled = true -- the Lottery app in Quasar Smartphone
Config.Debug = false -- extra console outputThe machine's model really is spelled
lotrrery_vending_machine— that is its name insidelottery_machine. Keep the spelling wherever you reference it. Every option is explained in Usage → The Settings.
Restart your server and read the console. The server and every client print the bridge they loaded:
[INFO] Successfully loaded the framework. esxAn error in its place means the framework was not running yet when Lottery Creator started — move its ensure higher. With Config.Debug = true, the server also says how many machines it loaded:
[DEBUG 2.0.1] Loaded lottery vendors from database: 0Then join your server and work through the first loop:
/lotterycreator → Create Vendor. Give it a name, press Select under Vendor Position, look at the spot and left-click. Back in the form, press Save — the machine appears for everyone at once. Leave For sale unticked for this first test.
Walk up to it and pick Buy Lottery Machine - $30 on the target, or press E at the prompt. A scratchcard lands in your inventory.
Use the scratchcard from your inventory and drag the mouse across the card. Once it is revealed, Claim prize pays what you won in cash.
From here, Usage covers the prize table, player-owned machines and the phone app.
Replace both folders with the new download. Keep a copy of your old config/main.lua and carry your values across, rather than copying the old file over the new one — it has new blocks. Do not import database.sql again.
On the first start with Config.Ownership.enabled = true, the resource adds the columns it is missing — owner, owner_name, balance, for_sale, purchase_price, tickets_sold, total_revenue and stock — and logs each one:
VENDING INFO: Added missing ownership column: ownerWith ownership turned off, the columns are not added and saving a machine fails. Run the update by hand instead:
ALTER TABLE `qs_lottery_vendors`
ADD COLUMN IF NOT EXISTS `owner` varchar(60) DEFAULT NULL,
ADD COLUMN IF NOT EXISTS `owner_name` varchar(100) DEFAULT NULL,
ADD COLUMN IF NOT EXISTS `balance` int(11) NOT NULL DEFAULT 0,
ADD COLUMN IF NOT EXISTS `for_sale` tinyint(1) NOT NULL DEFAULT 1,
ADD COLUMN IF NOT EXISTS `purchase_price` int(11) NOT NULL DEFAULT 25000,
ADD COLUMN IF NOT EXISTS `tickets_sold` int(11) NOT NULL DEFAULT 0,
ADD COLUMN IF NOT EXISTS `total_revenue` int(11) NOT NULL DEFAULT 0,
ADD COLUMN IF NOT EXISTS `stock` int(11) NOT NULL DEFAULT 0;
ALTER TABLE `qs_lottery_vendors`
ADD INDEX IF NOT EXISTS `owner` (`owner`);