The Four Screens#

Claw Machine has four interfaces, and each one opens from the cabinet or a command:

Screen	Opened with	What it is for
Start dialog	`E` at a cabinet	The machine's name, price per drop, payment method, prizes left and your balance. Choose how many drops to buy, see the total, and press Play.
Game HUD	While playing	Credits left, prizes in the machine, the aim timer and prizes won this session, plus the current phase and the win or miss banner. The leaderboard is shown here too.
Owner panel	`E` on a machine for sale, `G` on your own	Buy a machine, or run one you own: price, till, restock, statistics and resale.
Creator	`/clawcreator`	Admins place, edit, restock, teleport to and delete machines, and put them up for sale.

How a Run Plays#

Walk up to a cabinet and press E (or use the target, if enabled). Choose how many drops you want — 1 by default, up to 10 — and pay for all of them up front. They are used one after another, and the session ends when they run out. A machine set to a price of 0 shows Free.

The camera blends into the cabinet, the player's hand takes the joystick, a light comes on inside the glass and the claw parks in a corner. It plays like a real arcade crane game: one pass per axis. Hold to run the rail out; let go and that axis is locked for good.

Step	Control	What happens
1. Depth	Hold the arrow shown	The claw runs along the rail. Let go and the depth is set.
2. Side	Hold the arrow shown	The same on the other axis.
3. Drop	`SPACE`	The claw descends onto the pile, the jaws close, and it lifts and travels to the chute.
Any time	`BACKSPACE`	Leave the machine. A confirmation appears, and the aim timer pauses while it is open.

The on-screen buttons always show the next key. A gamepad works too, with rumble when the jaws land, catch and win. You have 30 seconds to aim; when the timer runs out the claw drops on its own. The player cannot be hurt during a run, and walking away from the cabinet ends the session.

Winning#

A good aim does not guarantee a prize. Every prize has a grip value: the jaws roll against it when they close, and again while carrying it to the chute. A prize can slip out mid-travel — that is intentional, and it is why the harder prizes pay more. When the jaws close on a prize and miss, it gets a small shove, so the player can see the claw really touched it.

When a prize reaches the chute it drops into the tray, the player reaches in and takes it, and the reward — cash, items or both — is handed over. Hard prizes play a rarer win stinger. The prize is gone from the machine for everybody.

Other players can watch. Everyone nearby sees the claw move and the prize ride it in real time, and wherever the pile settles after a run is saved, so the next player finds it exactly as it was left. Only one player can use a machine at a time.

The Cabinets#

Four cabinets ship with the script, each with its own claw, jaw animation and calibrated interior. They are streamed by clawmachine-assets and picked per machine in the creator.

Id	Name	Cabinet / claw model
`claw_01`	Foxy Catcher Machine	`custom_claw_machine_01` / `custom_claw_04`
`claw_02`	Lucky Claw Machine	`custom_claw_machine_02` / `custom_claw_02`
`claw_03`	Next Level Claw Machine	`custom_claw_machine_03` / `custom_claw_03`
`claw_04`	Twin Frame Machine	`custom_claw_machine_04` / `custom_claw_04`

Cabinets are solid by default; set Config.SolidCabinets = false if one blocks a doorway. They spawn within 45 metres of a player (Config.StreamDistance).

Placing a Machine#

Run /clawcreator (ace command.clawcreator). The left column lists every placed machine with a search box; press + to start a new one. The form has these sections:

Section	What you set there
Machine Info	The name shown in the start dialog.
Cabinet	Which of the four cabinets and claws it uses.
Pricing	The price per drop and whether it is paid in cash or from the bank. A price of 0 is free to play.
Prizes	Tick the prizes the cabinet is filled with — up to 16 types, including the defaults that every machine carries. Each shows its grip.
Ball rewards	What each ticked prize pays on this machine only: an amount of money, up to five items from your inventory's item list, or both. Use default goes back to the catalog's reward.
Placement	Press Select to place the cabinet in the world (see below).
For sale	Put the machine up for sale and set its purchase price (45,000 suggested). While it is for sale it is out of service and any player can buy it.

Placement closes the window and shows a ghost of the cabinet — with its claw — following where you aim:

Key	Does
`Mouse`	Aim where the cabinet goes.
`Z` / `X`	Rotate (hold).
`Mouse wheel`	Raise or lower in 5 cm steps.
`Left click`	Confirm the placement.
`BACKSPACE`	Cancel.

Press Save Machine and the cabinet appears for everyone, stocked and ready. Pick a machine in the list to edit it: Reposition, Restock now, teleport to it, or delete it. Changing a machine's prizes, cabinet or position re-deals the prizes inside; changing only its name or price keeps the pile as it is.

Hardcoded machines#

Machines listed in Config.Machines load on every start and are read-only — useful for fixed locations nobody should touch in game:

lua

Config.Machines = {
    { coords = vec3(-1652.1, -1060.3, 13.15), heading = 145.0,
      label = 'Vespucci Arcade', machineModel = 'claw_01',
      price = 100, paymentMethod = 'money', -- or 'bank'
      prizes = { 'gacha_green', 'gacha_red' } },
}

Prizes and Rewards#

The prize catalog lives in Config.Prizes.catalog. What ships:

Prize	Grip	Win chance	Pays
Green Gacha Ball	0.70	~27.9%	$160
Red Gacha Ball	0.60	~20.5%	$260
Blue Gacha Ball	0.50	~14.3%	$440
Yellow Gacha Ball	0.40	~9.1%	$800
Plush Toy 01 – 08	0.45	~11.5%	`peluche_01` … `peluche_08` item

Adding your own prize#

Any prop on your server can be a prize. Add an entry to the catalog and it appears in the creator:

lua

{ id = 'teddy',             -- internal key, never rename it once machines use it
  model = 'prop_bear_01',   -- any prop on your server
  label = 'Teddy Bear',     -- shown in the creator and the win message
  grip = 0.45,              -- 0 = impossible to catch, 1 = always
  color = '#f472b6',        -- dot colour in the creator
  count = 1,                -- optional: always stock exactly this many
  rare = true,              -- optional: play the rare win stinger
  reward = { item = 'teddy_bear', amount = 1 } },

A reward can be { money = 250 }, { item = 'teddy_bear', amount = 1 }, a list { items = { { name = 'teddy_bear', amount = 1 }, ... } }, or money and items at once. Money is paid as cash. If the prop does not exist on your server, that prize is skipped with a console warning instead of breaking the machine. A prize with no reward at all pays Config.Rewards.fallback ($160).

How a machine is stocked#

Config.Prizes.defaults lists prizes stocked in every cabinet, ticked or not — the eight plush toys sit there, one of each. Empty the list to pick them per machine instead.

Prizes with a fixed count go in first and are spread through the whole pile rather than buried at the bottom. The rest share what is left, capped by perMachine (24), maxTotal (120) and maxPerColor (4). With the defaults, a four-colour cabinet holds 8 plush + 16 balls — around 150 drops of stock. Nothing is ever spawned over the chute hole.

An unowned machine refills itself 15 seconds after its last prize is won. An owned machine waits for its owner to pay for the restock.

Player-Owned Machines#

With Config.Ownership.enabled = true, a machine up for sale shows [E] - Buy machine with its price, and nobody can play it until it is bought. A machine goes up for sale from the creator's For sale section, or automatically when placed if defaultForSale is on. The purchase is paid from the bank, and a player may own up to two machines.

Once bought, the owner presses G at the cabinet to open the panel:

Action	Detail
Price per drop	Anything within `priceLimits` — 100 to 300 by default.
Collect	Takes the till: every play minus the city's 20% commission.
Restock	Refills the machine to full. Costs `restockCost` (200) per missing prize, paid by the owner.
Statistics	Prizes won and total revenue.
Sell machine	Refunds 60% of the purchase price plus whatever is in the till, and puts the machine back up for sale.

Admins can open the G panel of any owned machine, release one from its owner with /clawclearowner while standing at it, and change the sale state and price from the creator. Ownership, the till and the statistics are saved in the database.

The Economy#

The odds of winning a prize on one drop are:

lua

chance = catchChance × carryChance × grip²
       = 0.95        × 0.60        × grip²

With the shipped catalog that averages ~18% wins and ~58 back for every drop. The default balance is built around a price of 100 per drop:

Per drop	Amount
Player pays	100
Player gets back (average)	~58
City commission (20%)	20
Owner receives	80
Owner pays in restock	~36
Owner keeps	~44

A 45,000 machine pays for itself in about 1,000 drops, and the money created as prizes (~58) almost exactly matches what the commission and restocking burn (~56) — so the machines do not inflate your economy.

If you change the price, the commission or the payouts, that balance moves with them. Below 100 per drop players farm the machine; above 300 nobody plays. The easiest global dial is Config.Gameplay.carryChance: raising it makes every prize easier without touching the catalog.

The Leaderboard#

Every run is counted per player: prizes won and runs played. The top 10 (Config.Leaderboard.topLimit) are shown in the game interface along with the player's own score. When somebody passes the best total on the server, everyone gets a notification that they now hold the claw machine record. Turn it off with Config.Leaderboard.enabled = false.

Configuration Reference#

Everything below is in config/main.lua and takes effect after a resource restart.

General

Option	Default	What it does
`Config.Locale`	'en'	Language of the interface and notifications.
`Config.Framework`	auto	Force `'esx'`, `'qb'` or `'standalone'` only if detection is wrong.
`Config.UseTarget`	false	`true` plays through ox_target instead of the `[E]` prompt.
`Config.InteractDistance`	1.8	Metres at which the prompt appears.
`Config.StreamDistance`	45.0	Metres at which cabinets spawn and despawn.
`Config.SolidCabinets`	true	`false` makes cabinets walk-through.
`Config.Keys`	E / BACKSPACE	Interact and cancel, as GTA control ids.
`Config.Sounds`	—	Interface sounds: click, cancel, coin, motor, drop, win, lose.
`Config.BinLight`	on	The light inside the glass while somebody plays: colour, range, intensity and position.

Gameplay — Config.Gameplay

Option	Default	What it does
`maxCredits`	10	Most drops a player may buy at once.
`defaultCredits`	1	Drops pre-selected in the start dialog.
`aimTimeMs`	30000	Time to aim before the claw drops on its own. 0 = no limit.
`autoCloseDistance`	3.0	Walk this far away and the session ends.
`invincibleWhilePlaying`	true	The player cannot be hurt during a run.
`catchChance`	0.95	Odds of the jaws grabbing a prize, times its grip.
`carryChance`	0.60	Odds of not dropping it on the way, times its grip.
`autoRestock`	true	Refill a machine once it runs out.
`restockDelayMs`	15000	Wait before that refill.
`autoRestockOwned`	false	`true` also refills owned machines for free.

Prizes — Config.Prizes

Option	Default	What it does
`maxPerMachine`	16	Different prize types one machine may hold, defaults included.
`defaults`	8 plush	Prizes stocked in every machine regardless of the creator.
`perMachine`	24	Prizes spawned when a machine is stocked.
`maxTotal`	120	Hard ceiling per machine.
`maxPerColor`	4	Copies of the same prize type per machine (fixed counts ignore it).
`catalog`	12 prizes	Every prize the creator offers.

Rewards — Config.Rewards

Option	Default	What it does
`enabled`	true	Master switch for payouts.
`fallback`	`{ money = 160 }`	Paid when a prize has no reward at all.
`giveItem`	true	`false` pays money only and ignores items.
`inventory`	'auto'	Force an inventory resource name if detection picks the wrong one.
`maxItemsPerPrize`	5	Different items one prize may hand out.

Ownership — Config.Ownership

Option	Default	What it does
`enabled`	true	Turn player ownership off entirely.
`account`	'bank'	Account used to buy, sell, restock and collect.
`defaultForSale`	false	New machines go up for sale on their own.
`defaultPurchasePrice`	45000	Purchase price suggested in the creator.
`maxPerPlayer`	2	Machines one player may own. 0 = no limit.
`commission`	0.20	Cut of every play kept by the city.
`allowResale`	true	Owners may sell the machine back.
`resaleRefund`	0.6	Share of the purchase price refunded.
`priceLimits`	100 – 300	Range an owner may charge per drop.
`restockCost`	200	What the owner pays per missing prize.
`manageKey` / `manageKeyLabel`	47 / 'G'	Key that opens the owner panel, and the letter shown in the prompt.

Creator, leaderboard and debug

Option	Default	What it does
`Config.Creator.command`	'clawcreator'	Command that opens the creator.
`Config.Creator.permission`	'command.clawcreator'	Ace permission for the creator and admin actions.
`Config.Leaderboard`	on, top 10	The ranking of prizes won.
`Config.Machines`	empty	Read-only hardcoded machines.
`Config.Debug.enabled`	true	The calibration commands and debug output. Turn it off on a live server.

Adding Your Own Cabinet#

The four cabinets that ship are already calibrated. To use your own cabinet prop, copy an entry in Config.MachineModels, give it a new id, label, model and clawModel, and measure it in game — do not guess the numbers by hand. Every value is a local offset from the cabinet origin (x = right, y = forward, z = up), so the same numbers work at any position and heading.

Value	What it is
`bin`	The box inside the glass the claw travels through and prizes sit in.
`clawRest`	Where the claw parks.
`clawFloorZ` / `binFloorZ`	The lowest point the claw may reach, and the floor the pile rests on.
`chute` / `chuteArea`	Where the claw releases a prize, and the hole under it — no prize is ever spawned there.
`payout`	The tray where the won prize lands.
`camera`	The play camera: position, target, fov, and how much it follows the claw.
`stand` / `handIk`	Where the player stands (w is the heading) and how the hand sits on the joystick.
`clawAnim` / `contactOverlap`	The jaw open/close clip, and how far the jaws come down over a prize before closing.
`light`	Optional override of `Config.BinLight` for this cabinet.

With Config.Debug.enabled = true, place one machine with your cabinet, stand next to it and work through the calibration commands. Each one prints a paste-ready block to the F8 console — paste it over the matching entry in Config.MachineModels and restart.

Mark the glass — /clawzone
Marks the box inside the glass and derives the rest of the machine from it. Start here.
Set the limits — /clawlimit and /clawchute
/clawlimit sets how low the claw goes and where the pile rests. /clawchute marks the hole where a prize counts as won.
Fine-tune — /clawtune and /clawraise
/clawtune adjusts clawRest, chute and the remaining offsets with a live preview. /clawraise moves the whole interior up or down at once.
Frame the player — /clawcam and /clawstand
/clawcam places the play camera while you look through it. /clawstand places the player and their hand on the joystick.
Check it — /clawrestock and /clawshow
/clawrestock re-deals the prizes into the new interior, /clawshow win or /clawshow lose previews the end of a run, and a real run confirms the grab.

While editing: the arrow keys move X/Y, Shift / Ctrl move Z, TAB cycles the value being edited, ENTER prints, BACKSPACE exits, and holding SPACE switches to coarse steps. The full list is in Commands and Exports.

If a cabinet's geometry changes after machines were placed with it, the saved piles no longer fit inside the glass. The script notices on the next start and re-stocks those machines on its own.

The Four Screens#

How a Run Plays#

Winning#

The Cabinets#

Placing a Machine#

Hardcoded machines#

Prizes and Rewards#

Adding your own prize#

How a machine is stocked#

Player-Owned Machines#

The Economy#

The Leaderboard#

Configuration Reference#

Adding Your Own Cabinet#

Mark the glass — /clawzone

Set the limits — /clawlimit and /clawchute

Fine-tune — /clawtune and /clawraise

Frame the player — /clawcam and /clawstand

Check it — /clawrestock and /clawshow

The Four Screens#

How a Run Plays#

Winning#

The Cabinets#

Placing a Machine#

Hardcoded machines#

Prizes and Rewards#

Adding your own prize#

How a machine is stocked#

Player-Owned Machines#

The Economy#

The Leaderboard#

Configuration Reference#

Adding Your Own Cabinet#

Mark the glass — /clawzone

Set the limits — /clawlimit and /clawchute

Fine-tune — /clawtune and /clawraise

Frame the player — /clawcam and /clawstand

Check it — /clawrestock and /clawshow

The Four Screens#

How a Run Plays#

Winning#

The Cabinets#

Placing a Machine#

Hardcoded machines#

Prizes and Rewards#

Adding your own prize#

How a machine is stocked#

Player-Owned Machines#

The Economy#

The Leaderboard#

Configuration Reference#

Adding Your Own Cabinet#

Mark the glass — /clawzone

Set the limits — /clawlimit and /clawchute

Fine-tune — /clawtune and /clawraise

Frame the player — /clawcam and /clawstand

Check it — /clawrestock and /clawshow

The Four Screens#

How a Run Plays#

Winning#

The Cabinets#

Placing a Machine#

Hardcoded machines#

Prizes and Rewards#

Adding your own prize#

How a machine is stocked#

Player-Owned Machines#

The Economy#

The Leaderboard#

Configuration Reference#

Adding Your Own Cabinet#

Mark the glass — /clawzone

Set the limits — /clawlimit and /clawchute

Fine-tune — /clawtune and /clawraise

Frame the player — /clawcam and /clawstand

Check it — /clawrestock and /clawshow