# 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](/docs/resources/qb-houserobbery) and [qb-crypto](/docs/resources/qb-crypto) both
declare it in their manifests. Do not confuse it with
[progressbar](/docs/resources/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`](https://github.com/qbcore-fivem/qb-minigames/blob/f930a9fe84e5350c816087505c73997fada46888/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

```lua
-- 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:

```lua
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](/docs/resources/qb-storerobbery) for a worked version of that pattern, and
[Safe server events](/docs/security/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:

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

## Sources

- [fxmanifest.lua](https://github.com/qbcore-fivem/qb-minigames/blob/f930a9fe84e5350c816087505c73997fada46888/fxmanifest.lua)
- [README.md](https://github.com/qbcore-fivem/qb-minigames/blob/f930a9fe84e5350c816087505c73997fada46888/README.md)
- [client/](https://github.com/qbcore-fivem/qb-minigames/tree/f930a9fe84e5350c816087505c73997fada46888/client)
