Poggy Skillcheck

Overview#

Poggy Skillcheck is a small minigame library. It does nothing on its own: other scripts ask for a skillcheck when a player does something that should take a bit of skill, and the player answers it.

A ring appears on screen with a turning needle. The player presses Space while the needle is inside the white zone. Inside that zone is a smaller gold "great" zone, which scripts can reward with a bonus. The game keeps running while the ring is up; the player is not locked into a menu.

Poggy scripts that use it:

• Poggy Fishing needs it: reeling in a fish is a skillcheck.
• Poggy Crafting can use it for recipes that ask for a skillcheck instead of a progress bar. It is optional there.

What it can do:

• Needle speed and zone size from 1 (easy) to 5 (hard).
• Several hits in a row (up to 10), with a counter on screen. One miss fails the whole check.
• A gold "great" zone of any size, or none.
• Clockwise, anticlockwise or random direction, a random start position, a shake, and a ring that can appear away from the centre of the screen.
• A warning tone one second before the ring appears, and sounds for hits and great hits.
• It follows the Poggy theme chosen in poggy_core (0.23.0 or newer).

It is free. It is not open source: please do not resell or re-upload it.

Requirements#

No database tables, no items and no server-side setup. Everything runs on the player's game.

Installation#

1. Download poggy_skillcheck from your Cfx portal and put the folder in your server's resources folder.
2. In server.cfg, start it after poggy_core and before any script that uses it:

   ensure poggy_core
   ensure poggy_skillcheck
   ensure poggy_fishing

3. Restart the server.

Configuration#

Every setting is in the /poggy settings hub under Skillcheck, or in config.lua if you prefer to edit the file. Restart the script after a change.

General

Default difficulty (Config.SkillCheck.Defaults)

Speed, zone size, shake speed and shake distance are whole numbers. A value outside its range is pulled back to the nearest end.

Making it harder without making it frustrating

• Change speed or zone size, not both. A fast needle and a small zone together is very hard.
• Ask for 2 or 3 repetitions instead.
• Set the direction to random, or raise the start position scatter, so players cannot learn one rhythm.

Sounds (Config.SkillCheck.Sounds)

To use your own sounds, replace the files in ui/sfx/skillcheck/ and keep their names: incoming.mp3, good.mp3, great.mp3.

Commands#

The options go in this order; give as many as you like:

/skillcheck [speed] [difficulty] [repetition] [randomizer] [shake] [shakeSpeed] [shakeDist] [timeBetween] [direction] [great]

The command is only added when the script starts with Test command on, so restart the script after switching it. It has no permission check: turn it off again when you are done.

Key: Space (the game's context control) hits the ring. It is not rebindable.

Using it in game#

What a player sees:

1. A warning tone plays. About one second later the ring fades in.
2. Press Space while the needle is in the white zone. In the gold part it is a great hit.
3. If the check needs several hits, a counter shows progress, for example 2 / 3, and the ring resets after a short pause. The needle may change direction between hits.
4. Pressing outside the zone, or letting the needle go round without pressing, fails the whole check.

What happens after a pass or a fail is up to the script that asked for the check.

For developers#

Call it from client-side Lua. The call waits until the player finishes (about one second of warning, then the ring), so always run it inside a thread or a callback.

CreateThread(function()
    local result = exports.poggy_skillcheck:StartSkillCheck({
        speed      = 3,
        difficulty = 3,
        repetition = 2,
    })

    if result.success then
        -- passed: reward the player from your own server code
    end
end)

Make poggy_skillcheck a dependency in your manifest if your script cannot work without it, or check that it is running first if it is optional.

Exports

Options

Every option can be left out; anything left out uses the server's defaults from Configuration.

The result

Treat any success = false as a fail. greatCount is only filled in when the ring was actually played, so write result.greatCount or 0.

Good to know

• One at a time. A call made while another skillcheck is running returns success = false at once; it does not wait. Check IsSkillCheckBusy() first.
• Switched off. When the server owner turns Skillchecks enabled off, every call returns success = true at once.
• Client only. There are no server events. Never trust the client's result for anything valuable without your own server-side checks.

Examples

Hard crafting, three hits, a bonus for all great:

local result = exports.poggy_skillcheck:StartSkillCheck({
    speed       = 5,
    difficulty  = 5,
    repetition  = 3,
    timeBetween = 300,
})

if result.success then
    if result.great then
        TriggerServerEvent('myscript:bonusItem')
    else
        TriggerServerEvent('myscript:normalItem')
    end
end

Shake and a random direction:

local result = exports.poggy_skillcheck:StartSkillCheck({
    repetition = 5,
    shake      = true,
    shakeSpeed = 3,
    shakeDist  = 3,
    direction  = "rand",
    great      = 20,
})

Troubleshooting#

Every skillcheck passes straight away

Skillchecks enabled is off. Turn it on and restart the script.

A skillcheck fails at once without showing

Another skillcheck was still running on that player's game. Scripts should check IsSkillCheckBusy() before asking for one.

Changing a default made no difference

The script asking for the check sets that option itself, and its value wins. Change it in that script's settings instead.

No sound

Check Volume is above 0. A player who typed /skillcheck off has muted their own sounds until they reconnect or type /skillcheck on.

/skillcheck does nothing

Test command is off, or was switched on without restarting the script, or Skillchecks enabled is off.

Poggy Fishing will not start

Fishing needs this script running first. Put ensure poggy_skillcheck above ensure poggy_fishing.

Updating#

poggy_core's updater keeps it up to date, and your config.lua settings are kept: see Updates. If you replaced the sound files with your own, keep a copy of them somewhere safe.