Free scripts

Poggy Util

A set of small, optional server utilities: an area-of-play box with clock and duty count, music zones, object cleanup, unstuck, weapon jams, a /help guide, armor protection and a stipend. Each one has its own switch.

poggy_utilv2.0.7
FrameworksVORP Core, RSG Core, QBCore RedM
Updated5 Oct 2026

Store page Ask in Discord

Overview#

Poggy Util bundles small utilities most servers want. Each has its own on/off switch, so you turn on only what you use. Everything framework-related (characters, jobs, duty, money, inventory, notifications) comes from poggy_core.

Utility	What it does	Default
Area of play	A box on screen with the busiest zone and the player count	on
Clock and weather	Game time and weather under the area-of-play box	on
Duty count	On-duty law and doctors, inside the box	on
Music zones	A YouTube track plays near set locations	on
Object removal	Deletes listed object models on a timer	on
Dead entity cleanup	Clears dead NPCs, horses, animals and wrecked wagons	off
Unstuck	Teleports a stuck player to the nearest road	on
Weapon jam	Dirty guns can jam	on
Help menu	A searchable `/help` guide	on
Armor protection	Armor clothing blocks torso shots until it breaks	off
Government stipend	Pays unemployed characters on a timer (VORP only)	off

Requirements#

Needs	Why
poggy_core 0.13.0 or newer	The framework layer.
oxmysql	The database.
weathersync	Only for the clock and weather widget.

Every utility works on VORP Core, RSG Core and QBCore RedM, except the government stipend, which is VORP only: it reads VORP's character table. On another framework it prints one line in the console at start and stays off.

Installation#

Download Poggy Util and put the poggy_util folder in your resources folder.

Add it to server.cfg, after poggy_core and oxmysql:

ensure oxmysql
ensure poggy_core
ensure poggy_util

For the armor repair kit, copy docs/armor_kit.png into your inventory's item image folder.
Set your server name for the help menu, and replace the example guide with your own (see Using it in game).
Restart the server.

There is no SQL to import. When the script starts it automatically creates its table (the armor icon position per character), adds the armor_kit item on VORP, and adds a created_at column to VORP's character table for the stipend. On RSG, add armor_kit to rsg-core/shared/items.lua yourself; the console prints one line while it is missing.

Characters that existed before poggy_util get the creation date 2025-11-01 00:00:00 for the stipend. To use another date, change it in sql/install.sql before poggy_util first starts. Changing Config.Stipend.LegacyDate alone does nothing.

Configuration#

Every setting can be changed in game: type /poggy, open Poggy Util, save, and restart poggy_util. The switches are on the General tab. You can also edit config.lua (every utility) and config/help.lua (the help pages) by hand. Config.Debug = true prints debug lines from every utility.

Area of play, clock and duty count

Setting	Default	What it does
`Config.AOP.Enabled`	`true`	The area-of-play box. Off also hides the clock and duty count, which sit inside it.
`Config.AOP.Zones`	10 towns	The zones, each a name and a position. The server picks the zone with the most players every 5 seconds.
`Config.AOP.SearchRadius`	`1000.0`	A player counts for the nearest zone within this many metres; further from every zone counts for none.
`Config.AOP.UpdateInterval`	`20`	Seconds between each player's refresh of the box.
`Config.ClockWeather.Enabled`	`true`	Clock with sun, moon and weather. Needs weathersync.
`Config.ClockWeather.UpdateInterval`	`5`	Seconds between time and weather updates.
`Config.DutyCount.Enabled`	`true`	On-duty law and doctors in the box.
`Config.DutyCount.LawJobs`	`police`, `sheriff`, `marshal`	Jobs counted as law. Case-sensitive. Doctors are the jobs poggy_core counts as medical (`PoggyCoreConfig.MedicalJobs`).
`Config.DutyCount.UpdateInterval`	`10`	Seconds between recounts.

Music zones

Setting	Default	What it does
`Config.MusicZones.Enabled`	`true`	Master switch. Off also removes `/togglemusic`.
`Config.MusicZones.Zones`	one example	Each zone: `name`, `youtubeId`, `radius`, `volume`, `loop`, optional `timestamps`, and one or more `locations`.
`Config.MusicZones.VolumeMultiplier`	`0.5`	Multiplies every zone's volume. 0 silences all zones.
`Config.MusicZones.Falloff`	`2.0`	How volume drops toward the edge: 1 straight line, 2 realistic.
`Config.MusicZones.DirectionalAudio`	`true`	The music drops to 60% when the camera faces away from the source.
`Config.MusicZones.UnloadDistance`	`100.0`	The track stays loaded (silent) until the player is this far away. Keep it larger than every zone's radius.
`Config.MusicZones.Quality`	`'small'`	Quality YouTube is asked for. Only the audio is used, so the lowest saves bandwidth.

Object removal and dead entity cleanup

Setting	Default	What it does
`Config.ObjectRemoval.Enabled`	`true`	Master switch. Off also turns off dead entity cleanup and both admin commands.
`Config.ObjectRemoval.Objects`	`s_coachlock02x`	Object models deleted on every player's game.
`Config.ObjectRemoval.IntervalMinutes`	`1`	Minutes between removals. The first runs 30 seconds after start.
`Config.ObjectRemoval.AdminGroups`	`admin`, `superadmin`, `moderator`	Staff groups allowed to use `/removeobjects` and `/cleandead`.
`DeadEntityCleanup.Enabled`	`false`	Clears dead bodies and wrecks on a timer.
`DeadEntityCleanup.IntervalMinutes`	`60`	Minutes between cleanups.
`CleanPeds`, `CleanHorses`, `CleanAnimals`, `CleanWagons`	all `true`	What the cleanup removes: dead NPCs (never players), dead horses, dead animals (carcasses a player wants to skin go too), destroyed wagons.

Unstuck

Setting	Default	What it does
`Config.Unstuck.Enabled`	`true`	Master switch.
`Config.Unstuck.Command`	`"unstuck"`	The command name. The help menu's I'M STUCK button uses it too.
`Config.Unstuck.DelaySeconds`	`10`	Countdown before the teleport. The player is frozen meanwhile.
`Config.Unstuck.MoveTolerance`	`2.0`	Metres the player may drift during the countdown before it is cancelled.

Weapon jam

Setting	Default	What it does
`Config.WeaponJam.Enabled`	`true`	Master switch.
`JamStartThreshold`	`0.2`	Gun dirt (0 clean, 1 filthy) at which jams become possible.
`MaxJamProbability`	`0.25`	Jam chance per shot for a filthy gun (25%). Cleaner guns scale down from this.
`JamChanceExponent`	`1.5`	How steeply the chance rises with dirt. Higher means only very dirty guns jam often.
`UnjamThreshold`	`0.05`	A jammed gun works again once it is this clean.
`JamSound.Enabled`	`true`	A dry click when a gun jams. Only the shooter hears it.
`GunsToJam`	27 pistols, revolvers, rifles and shotguns	Weapon names that can jam. Any gun not listed never jams.

Help menu

Setting	Default	What it does
`Config.Help.Enabled`	`true`	Off: the `/help` command is not registered.
`Config.Help.ServerName`	`"Your Server Name"`	Shown in the guide's header.
`Config.Help.Logo`	`""`	Optional image left of the name: a full https:// URL. Empty for no logo.

Armor protection

Setting	Default	What it does
`Config.ArmorProtection.Enabled`	`false`	Master switch.
`MaxShots`	`10`	Torso hits blocked before the armor breaks. Each character starts full every session.
`ShotsPerStage`	`2`	Hits per stage of the 10-stage HUD icon. Keep `MaxShots` ÷ this at exactly 10.
`RepairKitItem`	`"armor_kit"`	The item that repairs the armor. Used up only when the repair finishes.
`RepairTime`	`8000`	Milliseconds for the repair animation and progress bar.
`NotifyPlayer`	`false`	Shows a tip each time the armor absorbs a hit.
`HUD.Enabled`	`true`	Shows the durability icon while armor is worn. Its position and size are CSS values (default 80px from the bottom, 30px from the left).

Government stipend (VORP only)

Setting	Default	What it does
`Config.Stipend.Enabled`	`false`	Master switch.
`IntervalMinutes`	`60`	Minutes between pay rounds. Only players online at that moment are paid.
`BasePay`	`5.00`	Cash paid each round.
`MinimumTenureDays`	`30`	A character must be this many days old before being paid.
`IncreaseAmount`	`0.25`	Added to the pay for each full step of tenure past the minimum.
`IncreaseIntervalDays`	`30`	Length of one tenure step, in days.
`UnemployedJobName`	`"unemployed"`	Only characters with this job are paid. Not case-sensitive.

Commands#

Command	Who	What it does
`/aop`	Everyone	Hides or shows the area-of-play box (with the clock and duty count).
`/aop l`, `/aop r`	Everyone	Moves the box to the left or right. Remembered.
`/help`	Everyone	Opens or closes the help guide.
`/unstuck`	Everyone	Teleports you to the nearest road after a countdown. Moving or dying cancels it.
`/togglemusic`	Everyone	Music zones off or on for yourself. Remembered.
`/movearmor`	Everyone	Drag the armor icon; click anywhere to save. Saved per character.
`/removeobjects [model ...]`	Staff groups, server console	Removes the given models, or every listed one, on every player's game.
`/cleandead`	Staff groups, server console	Runs dead entity cleanup now. Does nothing while it is off.

Each command works only while its utility is on.

Permissions#

Only /removeobjects and /cleandead are restricted. They work for a player in one of the staff groups in Config.ObjectRemoval.AdminGroups (default admin, superadmin, moderator), and from the server console. No ACE is needed.

Using it in game#

Writing your /help guide

The guide ships with example content. Replace it with your own in /poggy → Poggy Util → Help pages, or in config/help.lua.

The guide is a list of pages. Each page has an id (letters, digits and underscores), a title, one of 16 built-in icons, a colour and its sections.
The page with id getting_started is the large first tile; the others are sorted by title.
Section types: info (bullets), steps (numbered), tips (bullets with a light bulb) and commands (write them as /cmd — what it does). Two advanced types for item guides with inventory icons are described at the top of config/help.lua.
Search looks through every title and line, so use the words players will type.
The I'M STUCK button on the front page runs the unstuck command.

Setting up armor protection

In /poggy → Poggy Util, turn on Armor protection (General tab).
On the Combat tab, check the repair kit item. On VORP armor_kit is added for you; on RSG add it to rsg-core/shared/items.lua.
Copy docs/armor_kit.png into your inventory's image folder.
Save and restart poggy_util.

A player wearing something in the native armor clothing slot is protected: shots to the torso are blocked, one hit at a time, until the armor breaks. Head, arm and leg shots are never blocked. Broken armor blocks nothing until the player uses the repair kit. Clothing stores that use the armor slot (vorp_character, jo_libs, jo_clothingstore) work.

Weapon jams

The dirtier a gun, the likelier it jams when fired. A jammed gun clicks instead of firing, and works again once it has been cleaned.

For developers#

Client exports:

exports.poggy_util:ArmorIsWearing()            -- wearing armor
exports.poggy_util:ArmorGetShots()             -- hits left
exports.poggy_util:ArmorIsBroken()             -- no hits left
exports.poggy_util:ArmorShouldBlockBleeding()  -- wearing, not broken, last hit on the torso
exports.poggy_util:IsWeaponJammed(weaponHash)  -- that weapon is jammed
exports.poggy_util:OpenHelp()
exports.poggy_util:CloseHelp()

Server exports:

exports.poggy_util:RemoveObjectsByModel('s_coachlock02x')
exports.poggy_util:RemoveConfiguredObjects()   -- returns how many models were requested

Client event for keybinds: TriggerEvent('poggy_util:unstuck') starts unstuck.

Troubleshooting#

The clock never shows: It needs weathersync running, and the area of play on.
/removeobjects says "You don't have permission.": Add your staff group to Config.ObjectRemoval.AdminGroups, or run it from the server console.
/cleandead does nothing: Turn on dead entity cleanup (Config.ObjectRemoval.DeadEntityCleanup.Enabled).
The stipend never pays: It is VORP only. The character's job must be the unemployed job, the character must be at least MinimumTenureDays old, and they must be online when a pay round runs.
The armor kit does nothing: Armor protection is off by default. Turn it on and restart.

Updating#

Poggy Util updates through poggy_core's updater, which keeps your values in config.lua and config/help.lua (see Updates).

From 1.x

2.0.0 removed everything poggy_core now provides: the notification helpers, character, job, player and database helpers, and the blip and weapon helpers. Scripts that called those poggy_util exports should use poggy_core's Poggy() verbs instead (for example Poggy('notify.styled', ...), Poggy('char.get'), Poggy('job.get')). Config.PoggyDebug is now Config.Debug. The armor icon position moved to its own table, so a player who had moved the icon sets it again with /movearmor.