Poggy Core

Overview#

Poggy Core (the poggy_core resource) sits between your framework and every Poggy script. Each script asks Poggy Core for what it needs (a character, money, an item, a job, a storage) and Poggy Core answers the same way on VORP Core, RSG Core and QBCore RedM. That is why one Poggy script works on all three frameworks, and why every Poggy script needs Poggy Core running.

It is free and open source. Install it once; it then looks after the rest of your Poggy scripts for you.

• One framework layer for VORP Core, RSG Core and QBCore RedM, found automatically.
• Automatic updates for every Poggy script you own, with your config values kept.
• Automatic database setup: every script's tables are created for you. You import nothing.
• The /poggy settings hub: edit every Poggy script's settings in game.
• One theme for every Poggy screen, chosen by you, plus /poggyui so each player can size their own screens.
• Bans on the player's account, and the shared Poggy ban network against cheaters.
• Its own menus, text boxes and notifications, so scripts do not need vorp_menu, vorp_inputs or other menu resources.
• Console tools to check that everything works (poggycore ...).

Requirements#

• A RedM server running VORP Core, RSG Core or QBCore RedM (QBR), with that framework's inventory.
• oxmysql. Poggy Core starts without it, but the automatic database setup, bans, and the hub's change history all need it, and most Poggy scripts keep their data in the database.
• Nothing else. Poggy Core draws its own menus, text boxes and notifications.

Installation#

1. Download Poggy Core from its store page.
2. Put the poggy_core folder in your resources folder (you may put it inside a [Poggy] folder with your other Poggy scripts).
3. In server.cfg, start it after oxmysql and your framework, and before every Poggy script.
4. Add the two add_ace lines below. They let Poggy Core run refresh and restart a Poggy script after an update, after a save in /poggy, and after restart poggy_core. If they are missing, Poggy Core prints them in the console.
5. Start the server. There is nothing to import: Poggy Core and every Poggy script create their own tables.

ensure oxmysql
ensure vorp_core          # or rsg-core / qbr-core
ensure vorp_inventory     # or rsg-inventory / qbr-inventory
# ...the rest of your framework...

ensure poggy_core

# every Poggy script after poggy_core
ensure poggy_markets
ensure poggy_fishing

add_ace resource.poggy_core command.refresh allow
add_ace resource.poggy_core command.ensure allow

# who may open /poggy (framework admins can already)
add_ace group.admin poggy.settings allow
add_ace group.admin poggy.settings.takeover allow

Every setting in config.lua has a working default, so Poggy Core works without any changes. Run poggycore in the server console to see that it found your framework.

Configuration#

Every setting below can be changed in game in /poggy → Poggy Core, or in poggy_core/config.lua. Both change the same file. Poggy Core never restarts itself: after changing its settings, restart it by hand when the server is quiet (this restarts every Poggy script too).

Framework

Access and jobs

Storage

Menus and notifications

Database

Settings hub

The Updates, Theme and Bans settings are covered in their own sections below.

The /poggy settings hub#

Type /poggy in chat to open a full-screen hub with a card for every Poggy script on the server. Open a card to change that script's settings and lists (shops, recipes, locations...), read its commands and help pages, see the history of every change, and restart it.

Who can open it

• Players with the ACE poggy.settings, or anyone your framework counts as an admin.
• Taking over a script someone else is editing needs poggy.settings.takeover.
• Restarting a script from the hub needs add_ace resource.poggy_core command.ensure allow in server.cfg.

add_ace group.admin poggy.settings allow
add_ace group.admin poggy.settings.takeover allow
add_ace resource.poggy_core command.ensure allow

Changing a setting

1. Click a script's card.
2. Pick a tab on the left, or search at the top. Hover the ⓘ to read what a setting does.
3. Change the value.
4. Click Save, or Save & Restart to load the change now. Most changes need the script restarted; the hub tells you when.

• Advanced settings stay hidden until you turn on Show advanced.
• A changed badge means the value differs from what the script shipped with. Reset puts the shipped value back.
• History shows every change: who, when, the old and new value.

What it does to your files

The hub edits the script's own config.lua (and its other config and translation files) in place. Only the lines you changed are touched; every comment and every other line stays exactly as it was. There is no second copy of your settings: the config file is the truth. Before each save the old file is copied to poggy_core/update_backups/.

Every value is checked on the server before it is written; one bad value refuses the whole save. A script must be running to be saved (it writes its own files); a stopped script can be viewed, and the hub offers to start it.

One editor at a time

Only one person edits a script at a time. Anyone else sees it read-only, with the editor's name. The script is released when the editor leaves it, closes the hub, disconnects, or is idle for Hub.IdleMinutes. While a script is being edited, updates leave it alone until the next check.

Roles

Many Poggy scripts have their own job or group lists (who counts as a lawman, a doctor, staff). A role is one master list you can link those settings to, so you change the names in one place. Open Roles at the top of the hub. Poggy Core ships with three:

• To link a list: open the script, find the job or group list, click Link to role, pick the role, save.
• Saving a role rewrites every linked list in every script and restarts the scripts that changed. A script someone else is editing, or a stopped one, is skipped and named.
• The link is a short comment on the setting's line, such as -- poggy:role lawmen. Scripts never read it. Unlink, or deleting the comment, keeps the current names and stops later role changes from touching that list.
• Names must match your framework exactly. You can add your own roles.

From the console

poggycore settings lists every script and who is editing it, poggycore settings show <id> prints a script's settings, and two console-only commands change a setting or free a stuck script. See Commands.

Automatic updates#

Poggy Core keeps every Poggy script on your server up to date, itself included. It is on by default: you never need to download an update from the store again. Escrowed scripts update the same way.

How it works

1. About 20 seconds after the server starts, Poggy Core reads the public Poggy update feed. No account, key or token is needed.
2. For each Poggy script you have, it compares the published version with the version in your fxmanifest.lua. A script is only updated when the published version is higher. The same or an older version is never touched.
3. It writes the new files. Config and translation files are merged, not replaced: settings the update adds arrive with their defaults, settings it removes are cleaned up, and every value you set is kept. If a merge cannot be proven safe, your file is left as it is and the new version is saved beside it as <file>.poggyupdate for you to compare.
4. Every file it replaces is backed up first in poggy_core/update_backups/, named <script>__<date-time>__<file>.
5. It runs refresh once and restarts each updated script.

Updates are checked once, at server start. To install updates while the server is running, use poggycore update all apply in the console.

Settings

In /poggy → Poggy Core → Updates, or PoggyCoreConfig.Updates in config.lua:

To review updates yourself, set both switches off:

AutoUpdate   = false,
ApplyOnStart = false,

Poggy Core then only lists what is available. Install everything with poggycore update all apply, or one script with poggycore update <script> apply.

Update commands (server console only)

<script> is the script's product id (for example poggy_markets) or its folder name. You may rename a Poggy script's folder; updates still find it by the product id in its fxmanifest.lua.

Good to know

• A script must be started to be updated: each script writes its own files.
• A script that needs a newer Poggy Core than the one running is installed but not restarted; the console says so. Restart the server (or refresh, ensure poggy_core, ensure <script>) to finish.
• Your escrow licence files (.fxap) are never downloaded, changed or deleted.

Automatic database setup#

You never import a .sql file for a Poggy script. Each script keeps its tables in its own sql/install.sql, and Poggy Core runs it every time the script starts:

• Missing tables, columns and indexes are added. Anything already there is skipped.
• Nothing is dropped and none of your rows are changed.
• One-off changes in a script's sql/migrations/ run once each, in order, and are recorded in the poggy_migrations table.
• A start with nothing to do prints nothing. When something is created you see one green line, for example poggy_scene database: created 2 tables.

Poggy Core makes its own tables the same way: poggy_settings and poggy_settings_log (the hub's settings mirror and change history) and poggy_bans, poggy_ban_hashes and poggy_ban_allow (bans).

To run nothing automatically, set PoggyCoreConfig.Sql.AutoInstall = false and use the console:

poggycore sql check <script|all>     # shows what would change
poggycore sql install <script|all>   # runs it now

Theme#

Every Poggy script's own screens (shops, the market, the auction house, tickets and the rest), Poggy Core's menus and /poggy share one look. You pick it in /poggy → Poggy Core → Theme, or in PoggyCoreConfig.Theme. No restart is needed: Poggy Core's menus change at once, and a script's screens take the new look the next time they open.

Theme settings

Screens drawn with pictures (a brass plate, a leather ledger) keep their art. To give such a screen the theme instead, set that script's own skin setting to default.

Each player's own screens: /poggyui

Every player can type /poggyui to set, for their own screen only:

• Size: every Poggy screen from 50% to 200%. Fit my screen picks the size that suits their resolution (useful on 1440p and 4K monitors); Reset to 100% goes back.
• Look: the server's theme, or Light, an easier-to-read light theme.
• Less motion: no sliding, fading or spinning.

A sample shows each change as it is made. The choice is kept on the player's own PC for your server.

Bans and the ban network#

A Poggy ban is on the player's account, not their character, so it follows them to every character they make. Lifting a ban keeps it on record, marked as lifted, so you keep the history. Bans need oxmysql.

Banning

Three ways, all the same: /poggy → Poggy Core → Bans → Ban a player; the console or chat (poggycore ban); or a script that uses it, such as Poggy Tickets. The player is removed at once and reads your reason.

• Time: 30m, 2h, 7d, 1w (any number with m, h, d or w), or perm.
• Local (the default) is a rule break on your server. Cheating (add the word cheat) is for cheats and exploits, and is shared with the ban network.
• Someone who already left: ban their identifier instead of a server id.

poggycore ban 12 7d combat logging
poggycore ban 12 perm cheat aimbot
poggycore ban license:1a2b3c perm cheat left before the ban
poggycore unban 14 appeal accepted
poggycore baninfo          # active bans
poggycore baninfo 12       # every ban on record for player 12

The Poggy ban network

A cheating ban counts as one vote, shared with every server running Poggy Core. A player with cheating votes from 3 or more servers is refused on every server that enforces the network, yours included. A local ban never leaves your server, and lifting a ban takes your vote back.

• Only scrambled (hashed) identifiers and your player count are shared. Never a name, never a reason.
• A new server's votes start counting after 14 days.
• If the network cannot be reached, nobody is refused because of it.
• A blocked player is sent to poggy.app/appeal, where they sign in with Cfx.re and see which servers banned them and how to appeal to each.
• It is on by default. Turn off either half in /poggy → Poggy Core → Bans.

To let one network-blocked player into your server, use the identifier the console prints when they are refused:

poggycore banallow license:1a2b3c cleared on appeal
poggycore banallow remove license:1a2b3c
poggycore bannet           # the network's status on this server
poggycore bannet refresh   # read the list now, then show the status

Ban settings

Commands#

Chat commands for players and staff:

Console commands. Type them in the server console as poggycore ..., or in chat as /poggycore .... In chat you need the ACE command or poggycore, or to be a framework admin. Commands marked console run from the server console only, because they write files or change the database.

Permissions#

Who is a framework admin. On VORP, the admin groups (admin, superadmin, god, owner, headadmin, developer) on the character or the user record. On RSG Core and QBCore RedM, the framework's ACE permission levels: a server must grant them in server.cfg (for example add_ace rsgcore.admin admin allow or add_ace qbcore.admin admin allow with add_principal lines), or nobody counts as an admin.

For developers#

Poggy Core is open source and you may build your own scripts on it. Every call has the same shape: a verb, a payload table, and three values back.

local ok, value, err = Poggy('money.add', { src = src, amount = 50, reason = 'supply drop' })

• ok (boolean): did it happen. Branch on this, and nothing else.
• value: the result, or nil.
• err (string): why not, or nil. One of not_ready, no_char, unsupported, not_implemented, bad_argument, no_space, no_funds, not_found, timeout, framework_error, needs_thread, plus no_core and core_too_old from the bridge.

Nothing silently does nothing: a verb the framework cannot do returns false, nil, 'unsupported'. Ask first with Poggy('core.has', { capability = 'money.gold' }) rather than checking the framework's name. A verb marked "thread" in poggycore verbs waits on the framework or the database, so call it from a thread or an event handler. A callback may be passed as a third argument instead of reading the return values.

The manifest

A script loads the one bridge from Poggy Core and depends on it:

fx_version 'cerulean'
game 'rdr3'
rdr3_warning 'I acknowledge that this is a prerelease build of RedM, and I am aware my resources *will* become incompatible once RedM ships.'
lua54 'yes'

version '1.0.0'
poggy_core_min '0.25.0'      -- the oldest Poggy Core with every verb you call

dependency 'poggy_core'
shared_script '@poggy_core/template/poggy.lua'

server_scripts { 'server/main.lua' }
client_scripts { 'client/main.lua' }

poggy_core_min is checked against the Poggy Core that is running. If it is older, the script prints one red line at boot, PoggyReady() returns false, and every call returns false, nil, 'core_too_old'. If your script keeps tables in sql/install.sql, Poggy Core runs it for you when PoggyReady() first passes on the server (see Automatic database setup).

Example

-- server/main.lua
CreateThread(function()
    if not PoggyReady() then return end          -- waits for poggy_core and your tables
    Poggy('storage.register', { id = 'town_safe', opts = { label = 'Town Safe', slots = 60 } })
end)

RegisterNetEvent('my_script:buy', function(item, price)
    local src = source

    local ok, fits = Poggy('inv.canCarry', { src = src, item = item, qty = 1 })
    if not ok or not fits then
        return Poggy('notify', { src = src, text = 'Your satchel is full.', kind = 'error' })
    end

    if not Poggy('money.remove', { src = src, amount = price, currency = 'cash', reason = 'my_script:buy' }) then
        return Poggy('notify', { src = src, text = 'You cannot afford that.', kind = 'error' })
    end

    Poggy('inv.add', { src = src, item = item, qty = 1 })
    Poggy('notify', { src = src, text = 'Purchased.', kind = 'success' })
end)

The verbs

The full list, with what each needs and returns, is poggycore verbs on your server, or shared/sh_verbs.lua in Poggy Core. The main groups:

On-screen prompts and your page's look

• For key prompts, add '@poggy_core/client/lib/prompts.lua' to your client scripts and use PoggyPromptGroup:new(title) and PoggyPrompt:new(controls, text, group), calling group:handleEvents() every frame the group should show.
• A NUI page follows the owner's theme and each player's /poggyui choices with one line, last in its <head>: <script src="https://cfx-nui-poggy_core/ui/hub/theme.js"></script>. Style it with the theme's --pg-* colour tokens.
• Refer to your own resource with GetCurrentResourceName(), never its folder name, so owners may rename the folder.

Troubleshooting#

The console says "standalone" or no framework was found

Run poggycore detect. It probes each framework and says what each answered: not started, an error, or the wrong answer. The usual causes are that the framework core starts after poggy_core in server.cfg (move ensure poggy_core below it), or that ForceFramework is set to the wrong framework. After fixing it, poggycore resolve runs detection again without a restart. On RedEM:RP and RPX this is expected: they are not supported.

A Poggy script will not start, or says poggy_core is too old

Make sure ensure poggy_core comes before every Poggy script. A "needs poggy_core X" line means the script needs a newer Poggy Core than the one running: Poggy Core's own update only takes effect after a server restart (or refresh, ensure poggy_core, ensure <script>).

Something does not work with my framework

In game, run /poggycore test (read-only), then /poggycore selftest. Every verb is listed as PASS, FAIL or SKIP; SKIP means the framework cannot do it and said so. /poggycore selftest full also tests the verbs that change things and puts everything back. Send the FAIL lines when you ask for help.

Updates never install

• Run poggycore update nettest in the console: it checks that the server can reach the feed and explains any failure.
• Check Automatic updates is on (Updates.AutoUpdate), and that the script is started.
• Run poggycore update <script> writetest: it checks that Poggy Core can write into that script's folder.
• A script someone is editing in /poggy is held until the next check.

Scripts are not restarted after an update or a hub save

Add both lines to server.cfg and restart the server:

add_ace resource.poggy_core command.refresh allow
add_ace resource.poggy_core command.ensure allow

An update says it "adds folder(s) this server does not have"

A server script cannot always create folders. Make the folders the console names, by hand, inside that script's folder, then run poggycore update <script> apply.

An update left a .poggyupdate file

The config merge could not be proven safe, so your file was left as it is and the new version was saved beside it. Compare the two, copy across any new settings you want, and delete the .poggyupdate file.

I cannot open /poggy

You need the ACE poggy.settings or to be a framework admin. Add add_ace group.admin poggy.settings allow (and make sure you are in group.admin), or on RSG Core and QBCore RedM grant the framework's admin level in server.cfg. The console names the reason when someone is refused.

The hub says a script is being edited, but nobody is

It is released after Hub.IdleMinutes. To free it at once, run poggycore settings unlock <id> in the console.

A save in /poggy was refused because the file changed

The file was changed on disk (by hand, or by an update) while you had it open. Reload the script in the hub and make the change again.

Where are my old files?

Every file replaced by an update or a hub save is in poggy_core/update_backups/, named by script, date and time.