Minigame

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.

-- 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.

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.

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.

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.

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.

-- 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)