Sal's Kewl Cards — owner's manual

Overview

Sal's Kewl Cards puts reference material on screen without making anyone alt-tab for it. A card is one page of content a player can pull up mid-scene: a Miranda card, a vitals chart, a fire color-code table, a department SOP, a price list.

Three things make it more than an image viewer:

• Cards can be text, not just images. A text card is typed straight into config.lua. It downloads nothing, stays sharp at any zoom, and you can edit one without opening an image editor.
• Cards are gated by job and grade. Police SOPs stay with police; supervisor material stays with supervisors.
• You can show a card to another player. Hold the Miranda card up to the suspect in front of you and they see it on their screen.

It works on qb-core, Qbox, ESX and standalone. Detection is automatic and there is nothing to configure for it.

Requirements

No database. No permanent server state. Favorites and recents are stored in each player's own FiveM key-value store on their machine.

Installation

1. Drop the folder into your resources/ directory as sals_kewlcards.
2. Add it to server.cfg, after ox_lib:

   ensure ox_lib
   ensure sals_kewlcards

3. Open config.lua and change the jobs on each card to your server's job names. The shipped values — police, sasp, bcso, lspd, safr — are examples, not defaults that will match your server.
4. Restart the server and run /notecards in game.

Upgrading from 1.0

2.0.0 is a rewrite. Your old card entries still work, but two things moved:

• Images live in nui/images/, not nui/stream/. Copy your own artwork into the new folder. (A folder named stream is FiveM's convention for streamed game assets, which notecards are not.)
• The menu command is /notecards, not /notecardmenu. Both command names are set in Config.Commands if you would rather keep the old one.

Cards also gained category, order, text and images fields. All four are optional — a 1.0-style card with just title, image, description and jobs still loads.

If a card is misconfigured, the resource says so in the client console at startup, names the card, and says whether the problem was missing content or a rejected filename. It does not fail silently.

Player guide

This is the part to paste into your server rules or a Discord channel.

Keybind

The menu is bindable and ships unbound, so players choose their own key in Settings → Key Bindings → FiveM → Open the notecard menu. To preset one for everybody, put a key name in Config.Keybind.

In the viewer

Writing cards

Every card is one entry in Config.Notecards. The key is the shortcut players type with /shownotecard, so keep it short and lowercase.

Text cards

Start here. A text card needs no artwork, downloads nothing, and stays sharp at any zoom level:

['callsigns'] = {
    title       = 'Callsign Format',
    description = 'How to build your unit number.',
    category    = 'general',
    order       = 10,
    jobs        = {},
    text        = [=[
# Format

- **1-ADAM-12** — district, unit type, beat
- Supervisors use **S** in the unit slot

Say your full callsign on first contact, short form after.
]=],
},

The markup is deliberately tiny:

Nothing else is interpreted. Lines wrapped in your editor rejoin into one paragraph, so you can keep config.lua tidy without changing how a card reads.

Image cards

Put the file in nui/images/ and name it in the card:

['usecodes'] = {
    title       = 'Use of Force',
    description = 'Continuum and reporting thresholds.',
    category    = 'law',
    order       = 20,
    image       = 'usecodes.webp',
    jobs        = { 'police', 'bcso' },
},

Multi-page cards

Swap image for images and the viewer grows page controls and arrow-key navigation:

images = { 'pursuit_p1.webp', 'pursuit_p2.webp' },

Every field

Job & grade permissions

The jobs field takes three shapes.

jobs = nil                       -- everyone, including civilians
jobs = {}                        -- everyone
jobs = { 'police', 'sasp' }      -- those jobs, any grade
jobs = { police = 3, sasp = 3 }  -- those jobs, grade 3 or higher

The last form is how you keep supervisor material with supervisors. The number is a minimum: police = 3 means grade 3 and everything above it.

Grades are read from whatever your framework reports — qb and Qbox nest it as job.grade.level, ESX gives a plain number, and both are normalized to the same thing before the check runs.

Showing a card to a player

This is the feature that makes the resource a scene tool rather than a reference binder. Two ways in:

• The people icon in the viewer shows the card to the nearest player within range.
• /showcardto <id> <name> targets a specific player by server ID.

The receiving player sees the card with a banner naming who showed it to them. They can close it themselves, or set Config.Present.Duration to close it automatically after a number of milliseconds.

What the server checks

Every present request is validated on the server, against state the server owns rather than anything the sending client claimed:

• The card exists in your config. The client sends a card key, never an image path, so nothing a client says can put an arbitrary file on someone else's screen.
• The presenter's job passes that card's own gate — resolved server-side. Turn this off with Config.Present.RequireJob = false if you want any player to be able to hand any card around.
• The distance between the two characters is within Config.Present.Distance, measured from the server's own entity positions.
• A per-player cooldown (Config.Present.Cooldown) so the feature cannot be used to spam someone's screen.

Set Config.Present.Enabled = false to turn the whole feature off.

Categories, favorites & search

Categories

Cards group into categories so the menu stays usable past a dozen or so. Define them in Config.Categories:

Config.Categories = {
    { id = 'law',     label = 'Law Enforcement', icon = 'shield-halved',     order = 10 },
    { id = 'fire',    label = 'Fire',            icon = 'fire-extinguisher', order = 20 },
    { id = 'ems',     label = 'EMS',             icon = 'briefcase-medical', order = 30 },
    { id = 'general', label = 'General',         icon = 'book',              order = 99 },
}

Icons are Font Awesome names, the same set ox_lib uses. A category with no cards the player may open is hidden rather than shown empty. If a player ends up with exactly one category and no favorites or recents, the menu skips the middle step and lists the cards directly.

Favorites and recents

Players pin cards with the star in the viewer, and the last few they opened appear under Recently Used. Both are stored per player on their own machine and survive a reconnect. Both are pruned automatically when a card is renamed or removed, and both respect the job gate — a pinned card the player no longer has access to simply stops appearing.

Caps are Config.Favorites.Max and Config.Recent.Max. Set Enabled = false on either to remove it from the menu.

Search

Search appears once a player can see Config.Search.MinCards cards, so a small catalog does not carry a search box it does not need. It matches on title, description and shortcut, and only ever returns cards that player is allowed to open.

Card artwork

WebP, PNG and JPG all work. WebP is worth using: every player downloads every card image when they join, whether or not their job can open it.

Two rules for artwork you draw yourself:

• 1000px wide or more. The viewer zooms up to 4x, and zoom can only enlarge detail that is in the file. The three cards that ship with the resource are 1000×600.
• Plain filenames. Letters, digits, dots, dashes and underscores only — no folders, no spaces. Anything else is rejected at startup and the console says which card and why.

If a card is mostly words, do not draw it at all. Make it a text card: sharp at every zoom level, zero download, and editable in the same file as the rest of your config.

Optional inventory item

Off by default. Turn it on only after adding the item to your inventory resource:

Config.Inventory = {
    Enabled = true,
    Item    = 'notecard_binder',
}

On qb-core, Qbox and ESX the useable item is registered for you. On ox_inventory, items are driven from its own items.lua — point the item's client.export at sals_kewlcards.openMenu.

Configuration reference

Exports

For driving the viewer from another resource — a CAD, a phone, a training script.

Client

exports.sals_kewlcards:openMenu()
exports.sals_kewlcards:openCard('miranda')   -- honors the job gate; returns a boolean
exports.sals_kewlcards:isOpen()              -- boolean

openCard returns false and shows nothing if the key is unknown or the player's job does not allow it.

Server

exports.sals_kewlcards:showCard(playerId, 'miranda', 'Dispatch')

Puts a card on a player's screen with a banner naming the third argument as the sender. Returns a boolean. This is the admin/system path and does not apply the job gate — it is for your own trusted resources, not for player input.

What the job gate does

Worth being plain about, because it decides what belongs on a card.

Image cards are ordinary web assets. Every player who joins downloads every image the resource ships, whether or not their job can open it. The jobs field decides what the menu offers a player and what the server will let them present to somebody else. It does not stop a determined player from finding the file.

For reference material — rights cards, protocol charts, code tables — that is the right trade, and it is what this resource is for. But do not put anything on a card that you would mind any player seeing.

Text cards behave the same way: they live in config.lua, which is delivered to clients as part of the resource.

Translating

No player-facing string is hardcoded. locales/en.lua is the baseline; copy it, translate the values, and point Config.Locale at the new file:

Locales['fr'] = {
    ['menu_title']     = 'Fiches',
    ['none_available'] = 'Aucune fiche disponible pour votre metier.',
    -- ...
}

Anything you leave out falls back to English rather than showing a blank, so a partial translation is safe to ship. Card title and description text lives in config.lua with the cards themselves, not in the locale file.

Troubleshooting

Support

Support, release news and coupon codes are on Discord. Purchases are handled by Tebex, who own the checkout, billing support and refunds. The resource ships with its own README and CHANGELOG — the CHANGELOG calls out breaking config changes explicitly.

All pricing is on the main site.