Documentation
How Guitar Pro plays and how to run it: song list, Single/Duo/Versus, scoring and Star Power, generating charts from mp3, placing machines, the cinematic stage, guitars, levels and every config option.
Guitar Pro has a player side and an admin side, and it helps to know which is which from the start:
Side | Opened with | What it is for |
|---|---|---|
The cabinet | E at a machine, or ox_target | Everything a player does: the song list, the modes, the venue, the game itself, results, the shop and their settings. |
The admin panel |
|
/guitarmusicTwo tabs in one window: Machines, to place and edit cabinets, and Music, to tune and generate songs. Needs the |
Machines and songs live in the database and are edited in game. The rules of the game — hit windows, scoring, the stage, the shop — live in
config/main.luaand take a resource restart.
Walk up to a cabinet and press E (or use ox_target if you enabled it). The player is placed on a free pad and the song list opens. It is grouped into setlists of six songs — OPENING LICKS, AXE-GRINDERS, THRASH AND BURN and on — each showing how many of its songs you have cleared. Every row shows the length, the note count, the level of the chart and your best run on it.
Where | Key | What happens |
|---|---|---|
Song list | ↑ ↓ | Move through the songs. The highlighted one plays a preview. |
Song list | ← → | Change difficulty: easy, normal, hard. |
Song list | Enter | Confirm the track and go to the mode picker. |
Song list | Tab | The scoreboard: top scores on this song, and the server's longest combos and best accuracy. |
Song list | S | Settings: profile, ranking and keybinds. |
Song list | T | The guitar shop. |
Mode | ↑ ↓, Enter | Single, Duo or Versus. |
Venue | ← →, Enter | Which stage to perform on. Each venue is previewed live as you browse. |
Any screen | Backspace / Esc | Back a step, or leave the machine. |
Settings holds three tabs: the profile (the last 30 runs and your accuracy), the ranking (top players), and keybinds. The fret keys and Star Power are rebound there — R resets them — and are saved on the player's own game, not on the server, so each player keeps their layout on every machine.
If the machine charges, the price is taken when the song starts. Walk more than a few metres away from the cabinet and the session closes on its own. While playing, the player cannot be hurt.
Mode | Needs | How it works |
|---|---|---|
Single | 1 pad | One player, the whole chart. |
Duo | 2 pads | Co-op. The chart is split down the fretboard — pad 1 plays green, red and yellow, pad 2 plays blue and orange — and both scores add up into one team total. The rock meter is shared: if one player is booed off, the team is. |
Versus | 2 pads | Both play the full chart of the same song, with the rival's score live on screen. The higher score wins; a tie goes to accuracy, then to the longest streak. Get booed off, or quit, and you lose outright. |
Duo and Versus start with an invite: the host picks the song, the difficulty, the mode and the venue, and the player on the other pad gets a prompt with 30 seconds to accept. On a paid machine both players pay when the invite is accepted. On a two-pad machine, only one player browses the song list at a time; the other waits for them to finish choosing.
Five lanes, five frets. The default keys are A S D F G — green, red, yellow, blue, orange — with Space for Star Power. A count-in plays over 5-4-3-2-1, then the notes come down the highway in time with the song. Backspace during a song asks whether to quit; a quit run is not saved.
Every note is graded on how close to the beat it was hit, in milliseconds either side:
Judgment | Window | Score weight | Rock meter |
|---|---|---|---|
PERFECT | 45 ms | 1.0 | +2 |
GREAT | 90 ms | 0.75 | +1 |
GOOD | 135 ms | 0.4 | 0 |
BAD | 180 ms | 0.1 | −4 |
MISS | — | 0 | −8 |
score per note = 1000 × judgment weight × streak multiplier × Star PowerThe streak multiplier steps up every 10 notes in a row — x2 at 10, x3 at 20, x4 at 30 — and caps at x4. A miss resets it.
The rock meter starts at 50 out of 100 and moves with every note, by the amounts above. Empty it and the player is booed off stage and the run ends there — switch that off with Config.Gameplay.life.failEnabled.
Star Power banks a quarter of its meter for every 16-note phrase cleared. Once the meter is at least half full, Space fires it: the score doubles on top of the streak multiplier, the stage lights turn white-blue, the crowd roars, and a full meter burns for 26 seconds. Saving it for the densest part of a song is how records are set.
Every cleared run gets a grade from its accuracy, and a booed-off run gets an F:
SSS | SS | S | A | B | C | D |
|---|---|---|---|---|---|---|
99% | 97% | 94% | 88% | 80% | 70% | below |
It also earns up to five stars — one each at 50%, 65%, 78%, 88% and 95% accuracy — and stars pay out XP and points. A failed run earns none.
The results screen shows the grade, accuracy, longest streak, notes hit and the PERFECT-to-MISS breakdown, and whether the run beat your personal best or the server record. A new server record is announced to everyone on the server. Then the level-up screen pays out XP and points. From results, Enter goes back to the song list and G retries the same song.
A cleared run always outranks a failed one as a personal best, and only cleared runs can set a server record. The server checks every result before saving it — a run with more notes than the chart, a score above what the chart allows, or a finish faster than the song is thrown out and pays nothing.
18 royalty-free tracks ship in songs/, each with easy, normal and hard charts already written in database/sql.sql. Every song is an audio file in that folder: nothing is streamed or loaded from the internet, and the game only ever plays files the resource serves itself.
There are no chart files to find. When an admin presses Generate, the music manager analyses the audio and writes the notes itself, with a progress overlay naming each step:
Decoding audio.
Spectral analysis (FFT).
Detecting onsets — where things actually hit in the track.
Tracking beats and settling on a tempo.
Placing notes against that grid, at the density of each difficulty.
Saving the chart to the database.
It runs once per song, in the admin's game — the server does no audio work. From then on everyone reads the stored chart, and players at a machine see the new song appear in their list immediately. Each difficulty is rated with a level from its notes per second, its tempo and its length.
Difficulty | Max notes / second | Min gap | Chords |
|---|---|---|---|
easy | 2.20 | 330 ms | none |
normal | 3.20 | 165 ms | 6% |
hard | 5.50 | 95 ms | 22% |
The density is Config.Beatmap.difficulties. A change only affects charts generated after it — press Regenerate on the songs you want re-cut. Tracks with steady percussion chart best; ambient, rubato and loose live recordings give the beat tracker little to lock onto.
mp3, ogg and wav are supported, and either layout works — the file name or the folder name becomes the song's id:
songs/My-Song.mp3 → id "My-Song"
songs/my_song/song.mp3 → id "my_song"Use letters, numbers, _ and - only. Names with spaces, accents or symbols are renamed automatically the next time the resource stops — Más allá.mp3 becomes Mas_alla.mp3.
The folder is scanned once at boot and the files are served by the resource, so a new one is not visible until then.
The song is listed as not generated. Select it, fill in the name and artist, tick the difficulties it should offer and press Generate. When the overlay finishes, the song is playable on every machine.
Select any song in the music manager to edit it:
Field | What it does |
|---|---|
Name / Artist | What the song list shows. The list is ordered by name. |
BPM | The tempo the stage grooves to — lights, camera cuts and the beat lines on the highway. The tempo measured from the chart is shown beside it with a USE button. Type your own and it is kept as yours, to two decimals. |
Start / End | The play window, set on a waveform with Set as start and Set as end — trim a long intro or an outro so the run is just the song. AUTO plays to the end of the track. Editable once the song has a chart. |
Difficulties | Which of easy, normal and hard the song offers. At least one stays on. |
The preview that plays in the song list is the first 30 seconds of the play window. Save Changes applies at once; Regenerate rewrites the chart from scratch.
Delete does not remove anything from disk: the chart is dropped, the song goes back to not generated and leaves the in-game list, but it stays in the music manager so you can generate it again. To remove a song for good, delete its audio file and restart.
/guitarcreator opens the Machines tab: every placed cabinet in a searchable list, and a form on the right. Press + for a new one, then Select under Placement. The window closes and a see-through ghost of the cabinet follows where you aim:
Key | Does |
|---|---|
Mouse | Aim — the ghost sits on whatever surface you look at. |
Z / X (hold) | Rotate. |
Mouse wheel | Raise or lower it, 5 cm per notch. |
Left click | Confirm the position. |
Backspace | Cancel. |
Back in the form, fill in the rest and press Save Machine. The cabinet appears for everyone immediately and is stored in guitar_machines.
Section | What you set there |
|---|---|
Machine Info | The machine's name. |
Players | 1 pad — solo only — or 2 pads, which enables Duo and Versus. |
Pricing | The price to start a song, and whether it comes from cash or the bank. 0 is free to play. |
Game Modes | Which of Single, Duo and Versus may be started at this machine. |
Placement | Where it stands. On an existing machine, Reposition moves it. |
Select a machine in the list to edit it, Teleport to it, or Delete it. Editing or deleting a machine ends any song being played on it. Cabinets placed by qs-arcades are not listed — they belong to that resource.
Machines listed in Config.Machines load on every start and are not stored in the database — useful for a map that always ships with its cabinets:
Config.Machines = {
{
coords = vec3(-1652.1, -1060.3, 13.15), heading = 145.0,
label = 'Vespucci Arcade',
players = 2,
price = 250, paymentMethod = 'money', -- 'money' (cash) or 'bank'
allowedModes = { 'solo', 'duo', 'versus' },
},
}Config.Pads holds the standing spots as offsets from the cabinet — one entry for one-pad machines, two for two-pad ones. They are calibrated for the shipped cabinet. If you swap Config.MachineModel for your own prop, re-measure them with /guitarpad (see In-Game Editors below).
With Config.Stage.enabled = true (the default), the player performing does not watch the cabinet — they watch themselves. A clone of their character is placed at the venue holding their equipped guitar, and the camera cuts between framed shots in time with the music. Everything on the stage exists only on the performer's screen, so it never disturbs anyone else; the rest of the server sees the real character at the cabinet, guitar on a strap, cycling through performance animations that get wilder as the streak grows.
Venue | Id |
|---|---|
National (stadium) — the default |
|
Vinewood |
|
Pier 46 |
|
Cube Plaza |
|
Theme Park Pier |
|
The player picks a venue before the song starts; in Duo and Versus the host's choice is used, and the two performers stand side by side. Adding a venue is one line in Config.Stage.stages:
{ id = 'mystage', label = 'My Venue', coords = vec4(0.0, 0.0, 70.0, 180.0) },The coordinates are where the performer stands and the way they face. If your locale files define stages.mystage, that translation is shown instead of label.
Part | How it works |
|---|---|
Camera | An opening sweep around the performer, then 15 shots cycled every 8 beats with a field-of-view punch on the beat. Every shot is an offset from the performer, so a new venue needs no camera work. |
Lights | A truss of six sweeping beams over the stage, key lights on the performer and flashes out over the crowd, all moving on the beat and changing colour every two beats. Star Power switches to a brighter white-blue palette. |
Crowd | Spectators placed per venue, each with a model and an action — partying, cheering, dancing, air guitar, filming on a phone, drinking. The National and Vinewood ship with full crowds. |
Mood | Night is forced at the venue (23:00) and a cinematic colour grade is applied so the lights read properly. Weather-sync resources are paused for the performer and restored afterwards. |
Turn Config.Stage.enabled off and everyone plays on the cabinet camera in Config.Camera instead — fixed, front, side or dynamic.
Every saved run pays out XP, which raises the player's level, and points, which are spent in the shop. Both are calculated on the server from the notes hit, the stars earned, whether the song was cleared and whether it was full-combo'd, then scaled by difficulty and mode:
Pays | Per note | Per star | Clear | Full combo | When booed off |
|---|---|---|---|---|---|
XP | 2 | 140 | 300 | 600 | 35% kept |
Points | 0.45 | 45 | 70 | 180 | 25% kept |
The total is multiplied by the difficulty — easy ×1.0, normal ×1.35, hard ×1.8 — and the mode — Single ×1.0, Duo ×1.1, Versus ×1.25. One run is capped at 25,000 XP and 4,000 points, so nothing can be farmed in a single go. The level curve starts at 1,200 XP and grows 14% per level, up to level 50.
Opened with T from the song list. Seven guitars ship, each gated by a level and a price in points:
Guitar | Level | Price |
|---|---|---|
Pawnshop Special | 1 | Free — everyone starts with it |
House Axe | 2 | 1,500 |
Rust Riot | 5 | 4,500 |
High Roller | 8 | 8,000 |
Black Sermon | 12 | 12,000 |
Bootleg Queen | 20 | 22,000 |
Last Encore | 30 | 38,000 |
A bought guitar is strapped on straight away, and any owned guitar can be equipped later. The equipped guitar is what the player carries on stage and what everyone else sees on them at the cabinet.
Copy an entry in Config.Guitars and change it:
{
id = 'my_guitar', -- never rename it once players own it
label = 'My Guitar',
blurb = 'shop.blurb_my_guitar', -- a locale key, or plain text
price = 5000,
level = 6,
image = 'my_guitar.png',
machine = { model = `my_guitar_prop`, bone = 24817,
placement = { x = 0.015, y = 0.280, z = 0.100, rx = 9.6, ry = 15.2, rz = 188.7 } },
stage = { model = `my_guitar_prop`, bone = 24817,
placement = { x = 0.015, y = 0.280, z = 0.100, rx = 9.6, ry = 15.2, rz = 188.7 } },
},machine is what others see at the cabinet and stage is what the performer sees on the venue clone — usually the same. The first entry with a price of 0 is the free starter. Do not guess the placement offsets: tune them in game with /guitarplace. A guitar whose artwork is not part of the interface shows a NO ARTWORK card in the shop and works normally.
To adjust a player's level, XP or points by hand, use /guitarprogress — see Commands and Exports.
The camera shots, the crowd, the standing spots and the guitar offsets in config/main.lua are local offsets calibrated against the shipped venues and props. They are editable, but edit them with these tools rather than by hand. Each one prints a paste-ready block to the F8 console — paste it over the matching entry in the config and restart.
Command | What it edits |
|---|---|
| Where players stand at the cabinet → |
| The guitar's offset and rotation on the character → |
| The performance shot list → |
| The spectators of each venue → |
| Toggles autoplay — the game plays the next song by itself, handy to watch a venue or a chart. |
| Prints every loaded machine to the F8 console. |
Stand within 15 m of a machine. Stand-in characters show exactly where a player at each spot will be. Arrows move, Q / E rotate, Shift / Ctrl change height, TAB switches between pad 1 and 2, ENTER prints, Backspace exits.
WASD and the wheel move the camera, the arrows move the prop on screen, PgUp / PgDn change depth, R / T rotate on the current axis, C changes the axis, V toggles the pivot rings, 1 / 2 / 3 flip 180°, Q / E change the bone, Z changes the step size, G resets, ENTER prints, Backspace cancels. The shipped guitars are already tuned; base-game props generally need it.
WASD move, Space / Ctrl up and down, Shift for speed, the wheel changes the field of view, TAB / Q / E switch shot, R adds a shot here, X deletes one, F reverts the view, ENTER prints, Backspace exits. Run it during a song and the edits apply live to the running performance.
WASD fly, Space / Ctrl up and down, the mouse aims, left click places a spectator, Q / E change the model, R / T change the action, the wheel turns them, Z faces them at the stage, X removes the nearest, G clears the venue, TAB moves to the next venue, ENTER prints every venue, Backspace exits. A stand-in guitarist marks where the performer will be.
Every option lives in config/main.lua and takes effect after a resource restart.
Option | Default | What it does |
|---|---|---|
| 'en' | Interface and notification language. 41 included. |
| auto | Set only if detection is wrong: 'esx', 'qb' or 'standalone'. |
| false | true = interact through ox_target instead of the [E] prompt. |
| 2.2 | Metres at which the prompt appears. |
| 60.0 | Metres at which cabinets spawn for a player. |
| guitar_pro_machine_01 | The cabinet prop. |
| — | Where players stand, for one- and two-pad machines. |
| E / Backspace | Interact and cancel, as GTA control ids. |
| A S D F G + Space | Starting fret keys. Players rebind their own. |
| — | Interface sound cues, including the click on every note hit. |
Option | Default | What it does |
|---|---|---|
| 4000 | Count-in before the song starts. |
| 1500 | How long a note takes to travel down the lane. Lower is faster and harder to read. |
Option | Default | What it does |
|---|---|---|
| true | Allow charts to be generated from the audio. false = only songs with a stored chart can be played. |
| easy / normal / hard | Note density, minimum gap and chord rate per difficulty. |
Option | Default | What it does |
|---|---|---|
| true | false = play on the cabinet camera instead. |
| 'stadium' | The venue preselected in the picker. |
Option | Default | What it does |
|---|---|---|
| true | Master switch for levels, points and the shop. |
| 50 | The level ceiling. |
Option | Default | What it does |
|---|---|---|
| dynamic | The cabinet camera, used only when the stage is off. |
| on, 8 / 20 | Performance animations, and the streaks at which they escalate. |
|
-90 |
Audio latency compensation. More negative if hits register late. |
| true | The player cannot be hurt during a run. |
| 4.0 | Walk this far from the cabinet and the session ends. |
| off | Fades the interface while frets are held. |
| 45 / 90 / 135 / 180 | Hit windows in milliseconds. |
| start 50, fail on | The rock meter, its gains and losses, and whether you can be booed off. |
| base 1000, x4 cap | Base score, judgment weights and the streak steps. |
| on, 16-note phrases | Phrase length, gain per phrase, burn time, activation threshold and multiplier. |
| SSS … C | Minimum accuracy per grade. |
|
5 venues |
Where performances happen. |
| 8 / 1300 | Beats between camera cuts, and the glide time between shots. |
| 0.7 / 1.28 | Spacing between two performers, and how far the camera pulls back to frame both. |
| — | The opening sweep around the performer: distance, height, aim and angle. |
| 15 shots | The shot list. Edit with /guitarcam. |
| on | The truss, beams, key lights, crowd flashes, brightness, palettes and Star Power colours. |
| on | Spectator models, actions and the placements per venue. Edit with /guitarcrowd. |
| true / 23 | Forces night for the performer. |
| 'MP_Powerplay_blend' / 0.6 | The cinematic colour grade. '' disables it. |
|
1200 / 1.14 |
XP for the first level and how fast it grows. |
| — | What a run pays per note and per star, the clear and full-combo bonuses, and the share kept when booed off. |
| — | Payout multipliers. |
| 25000 / 4000 | Hard cap on one run's XP and points. |
| 'guitarprogress' | The admin adjustment command, and its permission. |
| on, T | The shop panel and the key that opens it from the song list. |
| — | The fallback guitar, used before a profile has loaded. |
| 7 entries | The shop catalogue. |
| 30000 | How long a Duo or Versus invite stands. |
| 400 | How often the partner's score is synced. |
| 10 | Rows in each ranking. |
| true | Announce new server records to everyone. |
| 'guitarcreator' | Command and permission for the machine creator, plus the ghost's rotate speed and height step. |
| 'guitarmusic' | Command and permission for the music manager. |
| empty | Machines loaded from the config on every start. |
| enabled | The in-game editors and their command names. Turn it off on a live server. |