Documentation
How Claw Machine plays and how to run it: controls, grip and win odds, placing machines with /clawcreator, prizes and rewards, player-owned machines, the economy, the leaderboard, the full config and calibrating your own cabinet.
Claw Machine has four interfaces, and each one opens from the cabinet or a command:
Screen | Opened with | What it is for |
|---|---|---|
Start dialog |
| 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 |
| Buy a machine, or run one you own: price, till, restock, statistics and resale. |
Creator |
| Admins place, edit, restock, teleport to and delete machines, and put them up for sale. |
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 |
| The claw descends onto the pile, the jaws close, and it lifts and travels to the chute. |
Any time |
| 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.
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.
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 |
|---|---|---|
| Foxy Catcher Machine |
|
| Lucky Claw Machine |
|
| Next Level Claw Machine |
|
| Twin Frame Machine |
|
Cabinets are solid by default; set Config.SolidCabinets = false if one blocks a doorway. They spawn within 45 metres of a player (Config.StreamDistance).
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 |
|---|---|
| Aim where the cabinet goes. |
| Rotate (hold). |
| Raise or lower in 5 cm steps. |
| Confirm the placement. |
| 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.
Machines listed in Config.Machines load on every start and are read-only — useful for fixed locations nobody should touch in game:
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' } },
}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% |
|
Any prop on your server can be a prize. Add an entry to the catalog and it appears in the creator:
{ 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).
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.
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 |
Collect | Takes the till: every play minus the city's 20% commission. |
Restock | Refills the machine to full. Costs |
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 odds of winning a prize on one drop are:
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.
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.
Everything below is in config/main.lua and takes effect after a resource restart.
Option | Default | What it does |
|---|---|---|
| 'en' | Language of the interface and notifications. |
| auto | Force |
| false |
|
| 1.8 | Metres at which the prompt appears. |
| 45.0 | Metres at which cabinets spawn and despawn. |
| true |
|
| E / BACKSPACE | Interact and cancel, as GTA control ids. |
| — | Interface sounds: click, cancel, coin, motor, drop, win, lose. |
| on | The light inside the glass while somebody plays: colour, range, intensity and position. |
Option | Default | What it does |
|---|---|---|
| 10 | Most drops a player may buy at once. |
| 1 | Drops pre-selected in the start dialog. |
Option | Default | What it does |
|---|---|---|
| 16 | Different prize types one machine may hold, defaults included. |
| 8 plush | Prizes stocked in every machine regardless of the creator. |
Option | Default | What it does |
|---|---|---|
| true | Master switch for payouts. |
|
| Paid when a prize has no reward at all. |
Option | Default | What it does |
|---|---|---|
| true | Turn player ownership off entirely. |
| 'bank' | Account used to buy, sell, restock and collect. |
Option | Default | What it does |
|---|---|---|
| 'clawcreator' | Command that opens the creator. |
| 'command.clawcreator' | Ace permission for the creator and admin actions. |
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 |
|---|---|
| The box inside the glass the claw travels through and prizes sit in. |
| Where the claw parks. |
| The lowest point the claw may reach, and the floor the pile rests on. |
| Where the claw releases a prize, and the hole under it — no prize is ever spawned there. |
| The tray where the won prize lands. |
| The play camera: position, target, fov, and how much it follows the claw. |
| Where the player stands (w is the heading) and how the hand sits on the joystick. |
| The jaw open/close clip, and how far the jaws come down over a prize before closing. |
| Optional override of |
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.
Marks the box inside the glass and derives the rest of the machine from it. Start here.
/clawlimit sets how low the claw goes and where the pile rests. /clawchute marks the hole where a prize counts as won.
/clawtune adjusts clawRest, chute and the remaining offsets with a live preview. /clawraise moves the whole interior up or down at once.
/clawcam places the play camera while you look through it. /clawstand places the player and their hand on the joystick.
/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.
aimTimeMs30000 |
Time to aim before the claw drops on its own. 0 = no limit. |
| 3.0 | Walk this far away and the session ends. |
| true | The player cannot be hurt during a run. |
| 0.95 | Odds of the jaws grabbing a prize, times its grip. |
| 0.60 | Odds of not dropping it on the way, times its grip. |
| true | Refill a machine once it runs out. |
| 15000 | Wait before that refill. |
| false |
|
perMachine24 |
Prizes spawned when a machine is stocked. |
| 120 | Hard ceiling per machine. |
| 4 | Copies of the same prize type per machine (fixed counts ignore it). |
| 12 prizes | Every prize the creator offers. |
giveItem
true |
|
| 'auto' | Force an inventory resource name if detection picks the wrong one. |
| 5 | Different items one prize may hand out. |
defaultForSalefalse |
New machines go up for sale on their own. |
| 45000 | Purchase price suggested in the creator. |
| 2 | Machines one player may own. 0 = no limit. |
| 0.20 | Cut of every play kept by the city. |
| true | Owners may sell the machine back. |
| 0.6 | Share of the purchase price refunded. |
| 100 – 300 | Range an owner may charge per drop. |
| 200 | What the owner pays per missing prize. |
| 47 / 'G' | Key that opens the owner panel, and the letter shown in the prompt. |
Config.Leaderboardon, top 10 |
The ranking of prizes won. |
| empty | Read-only hardcoded machines. |
| true | The calibration commands and debug output. Turn it off on a live server. |