> For the complete documentation index, see [llms.txt](https://jiffyjrdevelopment.gitbook.io/jiffyjrdevelopmentdocs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://jiffyjrdevelopment.gitbook.io/jiffyjrdevelopmentdocs/jiffy-jr-development-docs/jiffy-minigames/api.md).

# API

All exports are called from **client-side** scripts. Every game supports two calling styles.

***

## Calling styles

{% tabs %}
{% tab title="Callback style" %}
Pass a function as the second argument. The export returns immediately and calls your function when the game finishes.

```lua
exports['jiffy-minigames']:Circle({ difficulty = 'medium' }, function(success, result)
    if success then
        -- player won
    end
end)
```

{% endtab %}

{% tab title="Promise / blocking style" %}
Omit the callback. The export blocks the current thread and returns a boolean.

```lua
-- Must be called from inside a thread (CreateThread / citizen thread):
local success = exports['jiffy-minigames']:Circle({ difficulty = 'medium' })
if success then
    -- player won
end
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Never call a blocking export from the main resource body — always wrap it in `CreateThread(function() ... end)`.
{% endhint %}

***

## Result object

The callback receives two arguments: `success` (boolean) and `result` (table).

```lua
{
    success       = true,       -- boolean
    game          = 'circle',   -- canonical game type that ran
    reason        = 'win',      -- 'win' | 'fail' | 'timeout' | 'cancel' | 'error' | 'busy'
    score         = 87,         -- 0–100 performance score
    timeRemaining = 6.3,        -- seconds left when the game ended
}
```

Most scripts only need `success`. The full `result` is there if you want to log scores, give partial rewards, or handle timeouts differently from plain fails.

***

## Exports

### Generic start

Use this when the game type is a variable:

```lua
exports['jiffy-minigames']:Start(gameType, options, cb)
```

```lua
local gameType = GetConvarString('myserver:minigame', 'circle')
local success  = exports['jiffy-minigames']:Start(gameType, { difficulty = 'hard' })
```

***

### Per-game exports

| Export                     | Game page                                                                                             |
| -------------------------- | ----------------------------------------------------------------------------------------------------- |
| `Circle(options, cb)`      | [Circle](/jiffyjrdevelopmentdocs/jiffy-jr-development-docs/jiffy-minigames/games/circle.md)           |
| `Skillbar(options, cb)`    | [Skillbar](/jiffyjrdevelopmentdocs/jiffy-jr-development-docs/jiffy-minigames/games/skillbar.md)       |
| `Lockpick(options, cb)`    | [Lockpick](/jiffyjrdevelopmentdocs/jiffy-jr-development-docs/jiffy-minigames/games/lockpick.md)       |
| `Safecrack(options, cb)`   | [Safecrack](/jiffyjrdevelopmentdocs/jiffy-jr-development-docs/jiffy-minigames/games/safecrack.md)     |
| `Keypad(options, cb)`      | [Keypad](/jiffyjrdevelopmentdocs/jiffy-jr-development-docs/jiffy-minigames/games/keypad.md)           |
| `Pattern(options, cb)`     | [Pattern](/jiffyjrdevelopmentdocs/jiffy-jr-development-docs/jiffy-minigames/games/pattern.md)         |
| `Memory(options, cb)`      | [Memory](/jiffyjrdevelopmentdocs/jiffy-jr-development-docs/jiffy-minigames/games/memory.md)           |
| `Fingerprint(options, cb)` | [Fingerprint](/jiffyjrdevelopmentdocs/jiffy-jr-development-docs/jiffy-minigames/games/fingerprint.md) |
| `Thermite(options, cb)`    | [Thermite](/jiffyjrdevelopmentdocs/jiffy-jr-development-docs/jiffy-minigames/games/thermite.md)       |
| `Wirecutting(options, cb)` | [Wirecutting](/jiffyjrdevelopmentdocs/jiffy-jr-development-docs/jiffy-minigames/games/wirecutting.md) |
| `Hackgrid(options, cb)`    | [Hackgrid](/jiffyjrdevelopmentdocs/jiffy-jr-development-docs/jiffy-minigames/games/hackgrid.md)       |
| `Typer(options, cb)`       | [Typer](/jiffyjrdevelopmentdocs/jiffy-jr-development-docs/jiffy-minigames/games/typer.md)             |

***

### Utility exports

#### Cancel

Cancels the currently running game. The game resolves with `reason = 'cancel'` and `success = false`.

```lua
exports['jiffy-minigames']:Cancel()
```

#### IsActive

Returns `true` if a game is currently in progress.

```lua
if exports['jiffy-minigames']:IsActive() then
    -- don't start another one
end
```

***

## Common patterns

### Difficulty from a player's skill stat

```lua
local xp = QBCore.Functions.GetPlayerData().metadata.craftingrep or 0
local diff = xp > 5000 and 'easy' or xp > 2000 and 'medium' or 'hard'

local success = exports['jiffy-minigames']:Lockpick({ difficulty = diff })
```

### Chained minigames (breach sequence)

```lua
CreateThread(function()
    local step1 = exports['jiffy-minigames']:Keypad({ difficulty = 'medium' })
    if not step1 then return end

    local step2 = exports['jiffy-minigames']:Hackgrid({ daemons = 3, time = 40 })
    if not step2 then return end

    TriggerServerEvent('my-heist:server:open')
end)
```

### Guard against concurrent calls

```lua
if exports['jiffy-minigames']:IsActive() then return end
exports['jiffy-minigames']:Circle({ difficulty = 'easy' }, function(success)
    -- ...
end)
```