qb-minigames

qb-minigames is a NUI skill-check library. It ships no gameplay of its own. Other resources call one of its client exports, the player plays a short browser-rendered game, and the export returns the outcome to the caller.

It is the dependency other resources reach for when they need a lockpick or hack step. qb-houserobbery and qb-crypto both declare it in their manifests. Do not confuse it with progressbar, which is a timed action bar with no pass or fail outcome.

The manifest at the commit linked above declares version 1.0.0.

This is the oldest commit in the set audited for this site. The upstream default branch has not moved since 2024-02-17. Check the repository before assuming the surface below is still current.

Dependencies and start order

The fxmanifest.lua at this commit declares no dependency or dependencies entry, loads client/*.lua only, and registers html/index.html as its ui_page. There is no server script and no shared script.

It does not call into qb-core, so it can start before or after the framework. What matters is that it starts before any resource that calls its exports. Consumers call exports['qb-minigames']:<Name>(...), which fails if the resource is not started.

Exports

All exports are client side. Each one shows NUI, takes focus, blocks the calling coroutine with Citizen.Await, and resolves when the player finishes or quits.

Export	Signature	Returns
`Lockpick`	`Lockpick(pins)`	`boolean` success
`Hacking`	`Hacking(solutionsize, timeout)`	`boolean` success
`Skillbar`	`Skillbar(difficulty, validKeys)`	`boolean` success
`WordGuess`	`WordGuess(word, hint, guesses)`	`boolean` success
`WordScramble`	`WordScramble(word, hint, timer)`	`boolean` success
`Quiz`	`Quiz(questions, correctRequired, timer)`	`boolean` success
`KeyMinigame`	`KeyMinigame(amount)`	`table` with `quit` and `faults`
`StartPinpad`	`StartPinpad(numbers)`	`table` with `quit` and, when not quit, `correct`

Parameters

Parameter	Type	Meaning
`pins`	number	Number of lockpick attempts allowed
`solutionsize`	number	Code block size for the hacking grid
`timeout`	number	Seconds allowed to solve the hack
`difficulty`	string	Defaults to `'easy'` when omitted
`validKeys`	string	Keys the player may be asked for, defaults to `'1234'`
`word`	string	The target word
`hint`	string	Hint shown beside the word
`guesses`	number	Wrong guesses allowed before failure
`timer`	number	Seconds per question (`Quiz`) or total seconds (`WordScramble`)
`questions`	table	Array of `{ question, answer, options }` entries
`correctRequired`	number	Correct answers needed for `Quiz` to return `true`
`amount`	number	Key presses required by `KeyMinigame`
`numbers`	number	The correct pin, digits 1 to 9

Skillbar is the only export with defaults baked in. Calling exports['qb-minigames']:Skillbar() is valid and runs the easy difficulty against 1234.

Integration example


-- client side, inside your own resource
local function TryLockpickDoor(doorId)
    local success = exports['qb-minigames']:Lockpick(5)
    if not success then
        TriggerServerEvent('myresource:server:lockpickFailed', doorId)
        return
    end
    TriggerServerEvent('myresource:server:lockpickSucceeded', doorId)
end

The two table-returning exports need their fields checked in order, because correct is absent when the player quit:


local result = exports['qb-minigames']:StartPinpad(1234)
if result.quit then return end
if not result.correct then return end
-- player entered the right pin

Security boundary

The minigame runs entirely in the player’s own NUI. Its result is a client-side value. A modified client can return success without playing, so treat the outcome as a user experience gate, never as proof of anything.

Apply the same rule the upstream resources apply: have the server re-check the conditions it cares about (distance, job, item possession, cooldown, state flags) before it grants an item or money. qb-storerobbery at its own pinned commit does this with a distance check plus a robbed-state check inside the reward event, and rejects with DropPlayer when they fail. See qb-storerobbery for a worked version of that pattern, and Safe server events for the rule stated on its own.

Troubleshooting

Symptom	Likely cause
`No such export <Name> in resource qb-minigames`	Resource not started, or a typo in the export name. The names are case sensitive and use the exact spelling in the table above
Call never returns	The NUI callback never fired. Check the F8 console for a NUI error and confirm `html/index.html` is reachable
Mouse cursor stays on screen after the game	The resource was restarted mid game, so the NUI callback that calls `SetNuiFocus(false, false)` never ran. Restarting the caller does not clear focus
A tic-tac-toe game is referenced somewhere but never appears	`html/css/tictactoe.css` exists at this commit with no matching client script or export. There is no tic-tac-toe export to call

Proposed manual smoke test

Not yet executed. Run these on a staging server after installing:

Start the resource, then call each export once from a test command.
Confirm every export returns instead of hanging, both on completion and on pressing escape.
Confirm the mouse cursor and NUI focus are released after every outcome.
Restart qb-minigames while a minigame is open and confirm the client recovers.