Home

Free script · v1.0.0

KD Vendingmachine

Immersive, themed vending machines for FiveM. Every machine gets its own realistic interface. Walk up, press the buttons, pay with cash or card, watch your can drop, then reach into the tray and grab it.

ZIP from GitHub · MIT license

Like the script? Give it a ⭐ on GitHub. It costs nothing and helps other people find it.

  • QBox
  • QBCore
  • ESX
  • Standalone
  • ox_inventory
  • ox_target
  • qb-target
  • Lua 5.4
eCola machine: selecting a drink, tapping a card, the can dropping into the tray and the flap opening
The eCola machine. Snacks, coffee, water, Sprunk and the retro cigarette machine each have their own interface.

A unique UI for every machine

It isn't one menu with a different colour. Every machine has its own hardware, its own buttons and its own sounds.

  • See it in the preview at the top

    eCola

    Red soda front, lit sample window, selection buttons, bill acceptor and contactless reader.

    • prop_vend_soda_01
  • The Sprunk machine interface in KD Vendingmachine View larger image

    Sprunk

    Same hardware as eCola, with Sprunk lime branding.

    • prop_vend_soda_02
  • The Raine machine interface in KD Vendingmachine View larger image

    Raine

    A clean, glacier-blue water machine.

    • prop_vend_water_01
  • The Snacks machine interface in KD Vendingmachine View larger image

    Snacks

    Glass-front machine with spiral coils, shelf tags and an A1–D6 keypad. You can also type on your keyboard.

    • prop_vend_snak_01
    • prop_vend_snak_01_tu
  • The Coffee machine interface in KD Vendingmachine View larger image

    Coffee

    Touchscreen: drink, cup size (changes price), sugar and strength, a brewing progress ring, a cup bay with a pour animation and steam.

    • prop_vend_coffe_01
  • The Cigarettes machine interface in KD Vendingmachine View larger image

    Cigarettes

    70s pull-knob machine: wood grain, chase-light marquee, insert coins, then pull a chrome knob.

    • prop_vend_fags_01

What you get

Everything that makes a vending machine feel like a real machine, and everything that keeps your economy safe.

  • Physical animations

    The player walks up and turns to face the machine, presses buttons while the UI is open, and reaches down into the tray for the product. The real prop (can, bottle, chocolate bar, chips, coffee cup, cigarette pack) is in hand and visible to other players.

  • Machine feedback

    LCD/VFD displays, card reader LEDs, a bill sliding into the acceptor, the coil spinning, the product dropping and bouncing in the tray, and a flap you push to take it.

  • Procedural sound effects

    Key beeps, coins, card approval, motor hum, the thunk of the drop, brewing and knob ratchets. Made with Web Audio, so no audio files are shipped.

  • Framework agnostic

    QBox, QBCore, ESX, or standalone with ox_inventory. Detected automatically.

  • Works with your interaction

    ox_target, qb-target, ox_lib text UI or native GTA help text (~INPUT_CONTEXT~). The best one you have is picked.

  • Server authoritative

    Prices, stock, distance, payment methods, carry checks and cooldowns are all validated server-side. If the item can't be added, the money is refunded automatically.

  • Per-machine stock

    Every physical machine has its own stock with automatic restocking. Admins can refill everything with /restockvending.

  • Discord logging

    Purchases and suspicious requests can be logged to a Discord webhook.

  • Extra placements

    Spawn additional machines anywhere from the config.

  • English and Danish

    Both locales are included, and adding your own is easy.

  • Browser dev preview

    Open web/index.html in Chrome or Edge to click through every machine without starting the game.

Requirements

No required dependencies beyond your framework and inventory.

Framework (one of)
qbx_core · qb-core · es_extended · or standalone with ox_inventory
Inventory
ox_inventory, qb-inventory (and forks), or ESX default
Optional
ox_target / qb-target, ox_lib (notifications & text UI)
Server
OneSync enabled (used for server-side distance checks)

Installation

From download to a working machine in a couple of minutes.

  1. Download

    Download the ZIP and extract it.

    Download for free
  2. Drop it in resources

    Rename the folder to kd-vendingmachine and drop it into your resources folder.

  3. Add the items

    Add the items to your inventory. See the table below.

  4. Ensure the resource

    Add it to your server.cfg after your framework, inventory and target:

    cfg
    ensure kd-vendingmachine
  5. Admin access (optional)

    Give admins the restock permission:

    cfg
    add_ace group.admin kdvending.admin allow
  6. Restart

    Restart your server. The console prints this, and any item missing from your inventory is listed in a warning:

    console
    [kd-vendingmachine] v1.0.0 loaded · framework: qbox · inventory: ox_inventory

Items

The default config sells ~30 items. Ready-to-paste definitions are in the /install folder.

InventoryFileWhere it goes
ox_inventory (QBox / ESX / standalone)install/ox_inventory.luaox_inventory/data/items.lua. Includes consume anims, props and status values.
qb-inventoryinstall/qb-core.luaqb-core/shared/items.lua
ESX default inventoryinstall/esx.sqlRun against your database

Already have water, coffee, sandwich or lighter? Skip those. You can also change any machine to sell your existing items. Just edit the name field in the config.

Running it on your server?

Like the script? Give it a ⭐ on GitHub. It costs nothing and helps other people find it.

Star on GitHub

Configuration

There are two config files. One is shared with clients, the other stays on the server.

FileContentsSent to clients?
config/config.luaMachines, items, prices, UI, animations, interactionYes
config/server.luaWebhook, max distance, admin ace, loggingNo

General

lua
Config.Locale      = 'en'     -- 'en' | 'da'
Config.Framework   = 'auto'   -- 'auto' | 'qbox' | 'qbcore' | 'esx' | 'standalone'
Config.Inventory   = 'auto'   -- 'auto' | 'ox_inventory' | 'framework'
Config.Interaction = 'auto'   -- 'auto' | 'ox_target' | 'qb-target' | 'textui' | 'native'
Config.Notify      = 'auto'   -- 'auto' | 'ox_lib' | 'framework' | 'native'

Config.InteractDistance = 1.6
Config.AlignPlayer      = true   -- walk up to the machine before the UI opens
Config.NetworkedProps   = true   -- others can see the product in your hand
Config.Cooldown         = 1500   -- ms between purchases (server enforced)

Payment & stock

lua
Config.Payment = { cash = true, bank = true }   -- default, override per machine

Config.Stock = {
    enabled        = true,
    default        = 12,   -- per slot, override with `stock = n` on an item
    restockMinutes = 30,
}

Stock is tracked per physical machine: two eCola machines side by side each have their own stock.

Interface

lua
Config.UI = {
    currency    = '$',
    sound       = true,
    volume      = 0.35,
    showBalance = true,      -- show cash / bank under the payment modules
    autoTake    = 8000,      -- auto-grab after X ms if the player doesn't click the tray (0 = off)
    images      = 'drawn',   -- 'drawn' | 'inventory' | 'nui://my-images/%s.png'
}
imagesResult
'drawn'Stylised CSS products (cans, bottles, bars, chips, cups, packs) coloured per item. Works with zero setup and matches the machine art.
'inventory'Uses your inventory's item images (ox / qb / ps / lj inventory auto-detected). Falls back to drawn if an image is missing.
custom stringAny URL template containing %s (replaced with the item name).

Adding or editing a machine

lua
Config.Machines.mymachine = {
    label     = 'Energy Machine',          -- target label / notifications
    brand     = 'Junk',                    -- printed on the machine
    tagline   = 'The quick fix',
    layout    = 'soda',                    -- 'soda' | 'glass' | 'coffee' | 'retro'
    theme     = 'sprunk',                  -- 'ecola' | 'sprunk' | 'raine' | 'snack' | 'coffee' | 'redwood'
    models    = { 'prop_vend_soda_02' },   -- each model can only belong to one machine
    animation = 'tray_low',                -- key from Config.Animations
    icon      = 'fa-solid fa-bolt',
    payment   = { cash = true, bank = false },   -- optional
    items = {
        {
            name   = 'junk_energy',  -- inventory item
            label  = 'Junk Energy',
            price  = 6,
            kind   = 'can',          -- drawn shape: can | bottle | bar | bag | candy | cup | pack
            color  = '#1b1b1b',      -- main colour
            accent = '#b6ff00',      -- label / stripe colour
            prop   = 'can',          -- hand prop, key from Config.Props
            stock  = 20,             -- optional
            -- image    = 'https://...',          -- optional, overrides Config.UI.images
            -- metadata = { quality = 100 },      -- optional, ox_inventory metadata
        },
    },
}

Coffee-style machines can have sizes that multiply the price (validated server-side):

lua
sizes = {
    { label = 'S', name = 'Small',  multiplier = 1.0 },
    { label = 'M', name = 'Medium', multiplier = 1.25 },
    { label = 'L', name = 'Large',  multiplier = 1.5 },
},

Animations

Every machine uses an animation preset. You can tweak them or add your own. Hand props live in Config.Props and are referenced by name from items. Invalid models are skipped with a console warning, so nothing breaks.

lua
Config.Animations.tray_low = {
    align  = vec3(0.0, -0.78, 0.0),   -- where the player stands (machines face -Y)
    browse = { dict = 'anim@heists@keypad@', clip = 'idle_a', flag = 49 },        -- loop while UI is open
    press  = { dict = 'anim@heists@keypad@', clip = 'exit',   flag = 48 },        -- confirm purchase
    grab   = { dict = 'pickup_object', clip = 'pickup_low', flag = 0,
               propAt = 0.36,   -- anim phase where the product appears in the hand
               stopAt = 0.92,   -- anim phase where the grab ends
               hold   = 900 },  -- ms the product stays in hand afterwards
}

Extra placements

lua
Config.Placements = {
    { machine = 'coffee', coords = vec4(-1199.61, -884.82, 12.81, 124.0) },
    { machine = 'snacks', coords = vec4(441.32, -979.64, 29.69, 180.0), model = 'prop_vend_snak_01_tu' },
}

API

Exports and events, so you can build on it from your own scripts.

Client exports

lua
-- Open the UI for a machine entity (e.g. from your own target / interaction script)
exports['kd-vendingmachine']:OpenMachine(entity)

-- Is the UI currently open?
local open = exports['kd-vendingmachine']:IsOpen()

-- Force close (the player still grabs anything they paid for)
exports['kd-vendingmachine']:CloseMachine()

Server exports

lua
-- Refill every machine
exports['kd-vendingmachine']:Restock()

-- Current stock of a specific machine
local stock = exports['kd-vendingmachine']:GetStock('ecola', vec3(x, y, z))

Server events

lua
-- Fired after every successful purchase
AddEventHandler('kd-vendingmachine:purchased', function(source, data)
    -- data.machine, data.item, data.price, data.payment, data.coords
end)

Commands

CommandPermissionDescription
/restockvendingkdvending.admin (or server console)Refill every machine

Security

The client never decides anything that matters. For every purchase the server:

  • checks the player is within ServerConfig.MaxDistance of the machine
  • verifies the item belongs to that machine and takes the price from the config, never from the client
  • validates the payment method and cup size
  • checks stock, inventory space and balance
  • removes the money first, then adds the item, and refunds if adding the item fails
  • enforces a per-player cooldown
  • logs anything suspicious to the console and, optionally, a Discord webhook

FAQ

The most common questions. Missing an answer? Ask on Discord.

Nothing happens when I target a machine

Make sure kd-vendingmachine starts after your target resource. With Config.Debug = true the F8 console prints which interaction mode was picked.

"Not enough money" / "You cannot carry that" even though I can

Check that the item exists in your inventory. Missing items are listed on resource start. Unknown items fail the carry check.

The player doesn't line up with the machine

Adjust align in the animation preset. y is the distance in front of the machine (negative = in front). You can also disable walking up with Config.AlignPlayer = false.

Can I use my own vending machine props / MLO machines?

Yes. Add the model name to a machine's models list, or create a new machine entry. Any prop works.

Does the UI work without internet (fonts)?

Fonts load from Google Fonts. Without internet the UI falls back to system fonts and still works.

Can I modify it and use it on my server?

Yes. It is MIT licensed: use it, modify it, ship it. Credit is appreciated but not required.

Ready for a drink?

Free and open source under the MIT license. Use it, modify it, ship it. Need something custom? Ask on Discord. Like the script? Give it a ⭐ on GitHub. It costs nothing and helps other people find it.