# Minigame

<figure><img src="https://2088945756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkHcyR2RbVMcj5NHJ2HEa%2Fuploads%2Fdnsij4IB8owj6XozngtI%2F5.png?alt=media&#x26;token=6b6eb6b2-cff1-4fa2-a93c-c99ee4129a20" alt=""><figcaption></figcaption></figure>

The `ak47_lib` provides a versatile, highly configurable "tension" style minigame. It is perfect for activities like fishing, lockpicking, hacking, or repairing. The minigame yields the current thread using promises, meaning it pauses your script's execution until the player either wins or loses, keeping your code clean and synchronous-looking.

### 🛠️ Methods

#### `StartTensionMinigame`

Triggers the minigame UI and waits for the player's result.

```lua
-- Using Exports
local success = exports.ak47_lib:StartTensionMinigame(variant, difficulty, customSettings)

-- Using the Global Object (if initialized in your script)
local success = Lib47.StartTensionMinigame(variant, difficulty, customSettings)
```

Parameters:

* `variant` (string): The playstyle of the minigame.
  * *Options:* `'classic'`, `'momentum'`, `'shrinking'`, `'frenzy'`
  * *Default:* `'classic'`
* `difficulty` (string): The preset difficulty level.
  * *Options:* `'easy'`, `'medium'`, `'hard'`, `'expert'`, `'impossible'`
  * *Default:* `'medium'`
* `customSettings` (table, *optional*): A table of specific parameters to override the default config for this specific run (e.g., custom icons, bar sizes, speeds).

Returns:

* `success` (boolean): Returns `true` if the player successfully completes the minigame, and `false` if they fail or cancel it.

***

#### `CancelMinigame`

Forcefully closes the minigame and resolves the pending promise as `false`.

```lua
exports.ak47_lib:CancelMinigame()

-- Or via Global
Lib47.CancelMinigame()
```

***

### ⚙️ Variants & Configuration

The minigame relies on predefined settings found in `Config.Defaults.Minigame.tension`. You can select different variants depending on the context of the action:

1. Classic: A standard tension bar where the player must keep the target inside the zone.
2. Momentum: Introduces physics (thrust, gravity, friction). Great for mechanical tasks like lockpicking or hotwiring.
3. Shrinking: The safe zone dynamically changes size. Excellent for hacking or precision tasks.
4. Frenzy: The target speed randomly spikes. Perfect for catching aggressive fish or subduing a target.

**Available Override Settings (`customSettings`)**

You can pass any of these keys into the `customSettings` table to dynamically alter the minigame without changing `config.lua`:

* `icon`: FontAwesome class string (e.g., `'fa-solid fa-key'`).
* `barSize`: Width/size of the capture zone.
* `fishSpeed` / `normSpeed` / `frenzySpeed`: Movement speed of the target.
* `jumpChance` / `jumpNorm` / `jumpFrenzy`: Probability of the target sporadically jumping.
* `gain` / `loss`: Rate at which the progress bar fills or depletes.
* `thrust` / `gravity` / `friction`: (Momentum variant only) Physics modifiers.
* `startSize` / `minSize`: (Shrinking variant only) Size constraints.

***

### 💻 Usage Examples

#### Example 1: Basic Fishing

Using the `frenzy` variant on `medium` difficulty. This uses the default config settings and standard icon.

```lua
RegisterNetEvent('my_fishing:catchFish', function()
    -- Start the minigame and wait for result
    local success = exports.ak47_lib:StartTensionMinigame('frenzy', 'medium')
    
    if success then
        print("You successfully caught the fish!")
        -- Give item logic here
    else
        print("The fish got away...")
    end
end)
```

#### Example 2: Lockpicking with Custom Icon

Using the `momentum` variant on `easy` difficulty. We will override the default icon to look like a key, and manually adjust the bar size to make it slightly harder.

```lua
RegisterNetEvent('my_robbery:lockpickDoor', function()
    local customOverrides = {
        icon = 'fa-solid fa-key',  -- Changes the UI icon to a key
        barSize = 15               -- Overrides the default barSize for 'easy' (which is normally 35)
    }
    
    local success = exports.ak47_lib:StartTensionMinigame('momentum', 'easy', customOverrides)
    
    if success then
        print("Door successfully unlocked!")
        -- Unlock logic here
    else
        print("Your lockpick broke!")
        -- Break item logic here
    end
end)
```

#### Example 3: Hacking a Terminal

Using the `shrinking` variant on `hard` difficulty with an adjusted gain rate to make the hack take longer.

```lua
RegisterNetEvent('my_heist:hackTerminal', function()
    local hackerSettings = {
        icon = 'fa-solid fa-terminal',
        gain = 0.15, -- Slower progress gain (hard preset is 0.35)
        loss = 0.30  -- Faster progress loss (hard preset is 0.15)
    }
    
    local success = exports.ak47_lib:StartTensionMinigame('shrinking', 'hard', hackerSettings)
    
    if success then
        print("Firewall bypassed. Downloading data...")
    else
        print("Access Denied. Alarm triggered!")
    end
end)
```

#### Example 4: Canceling the Minigame Externally

If the player takes damage or gets arrested while doing the minigame, you can forcefully cancel it.

```lua
-- Assume the minigame is currently active from another thread
AddEventHandler('gameEventTriggered', function(eventName, data)
    if eventName == "CEventNetworkEntityDamage" then
        local victim = data[1]
        if victim == PlayerPedId() then
            -- Player took damage, cancel the UI immediately
            exports.ak47_lib:CancelMinigame()
            print("Minigame interrupted due to taking damage!")
        end
    end
end)
```