Documentation
Learn how the script works, explore its main features, and discover how to configure and use everything with ease.
Walk up and press E (or use ox_target if enabled). If the machine charges, the price is taken when the song starts.
The song list is grouped into setlists — songs ordered by difficulty and sliced into named sets of six, with your clear progress shown per set. Each row shows the length, note count, level and your best run.
Where | Control | What happens |
|---|---|---|
Song list | Up / Down | Move through the setlists |
Song list | Left / Right | Change difficulty: easy, normal, hard |
Song list |
| Open the guitar shop |
Song list | Enter | Confirm the track and go to the mode picker |
Mode | Up / Down, Enter | Single, Duo or Versus |
Venue | Up / Down, Enter | Which stage you perform at |
Any screen | Backspace | Back a step, or leave the machine |
Settings holds three tabs: your profile (match history and accuracy), the ranking (top players), and keybinds — fret keys are rebound here and saved per player on their own machine, not on the server.
Five lanes, five frets. The defaults are A S D F G, with Space for Star Power. Notes are graded PERFECT / GREAT / GOOD / BAD / MISS on how close to the beat you hit them.
The rock meter starts at 50 and moves with every note. Hit well and it fills; miss and it drains. Empty it and you are booed off stage and the run ends there — turn that off with Config.Gameplay.life.failEnabled.
Star Power banks up as you clear 16-note phrases. Once the meter is at least half full, Space fires it: the score multiplier doubles on top of your streak multiplier, the stage lights turn white-blue and the crowd comes up, for up to 26 seconds of a full meter.
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 the scores add into one team total |
Versus | 2 pads | Both play the full chart. Higher score wins. Get booed off and you lose outright |
Duo and Versus start with an invite: the host picks the song and the mode, the other pad gets a prompt and has 30 seconds to accept.
Results show the grade, accuracy, longest streak, the note breakdown and whether you beat your own record or the server's. A new server record is announced to everyone. Then the level-up screen pays out the XP and shop points.
18 tracks, all royalty-free, each with easy / normal / hard charts already written in the SQL file.
There are no .chart files to find. The resource analyses the audio and writes the notes itself:
Decode the audio.
Spectral analysis (FFT).
Detect onsets — where things actually hit in the track.
Track the beat and settle on a tempo.
Place notes against that grid, at a density set per difficulty.
Save the chart to the database.
This runs once per song, in the player's NUI, the first time anyone picks a track with no chart yet — with a progress overlay while it works. Everyone afterwards reads the stored chart.
The song list marks these with First play will analyze this song.
Difficulty | Max notes/sec | Min gap | Chords |
|---|---|---|---|
easy | 2.20 | 330 ms | none |
normal | 3.20 | 165 ms | 6 % |
hard | 5.50 | 95 ms | 22 % |
Set Config.Beatmap.autoGenerate = false and songs without a stored chart are simply unplayable instead of generating one.
Put the file in the resource's songs/ folder. Either layout works:
songs/My-Song.mp3 → id "My-Song"
songs/my_song/song.mp3 → id "my_song"mp3, ogg and wav are supported.
Restart the resource. Files are served by the manifest, so a new one is not visible until then.
Open /guitarmusic, type the folder or file name, press Detect, fill in the name and artist, and import it.
Names with spaces, accents or symbols are renamed to something servable automatically when the resource stops —
Más allá.mp3becomesM_s_all_.mp3. Give your files clean names and you avoid the surprise.
Field | What it does |
|---|---|
Name / Artist | What the song list shows |
BPM | Set by hand and it is treated as authoritative for the chart |
Difficulties | Which of easy / normal / hard the song offers |
Play window | Start and end points on the waveform — trim a long intro or outro. Only editable once the song has a chart |
Preview | Start and length of the clip that plays while the song is highlighted |
Cover URL | Artwork, by link |
Generate / Regenerate rewrites the chart from scratch.
Delete on a file-based song does not remove anything. 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 regenerate it. The audio file is untouched.
A song added from a link has no file to keep, so deleting it removes it outright. Adding the link again brings it back as a new song.
/guitarmusic → Add from YouTube. Paste a link and press Add.
Nothing is downloaded. The video is the audio: it plays through YouTube's own embedded player inside the NUI. The resource only asks YouTube for the title and channel to fill in the name and artist.
youtube.com/watch, youtu.be, /embed/, /shorts/ and /live/ links are all accepted.
Because there is no audio file to analyse, the tempo has to be set by ear before a chart can be built.
Press play and tap along with the beat — the button, or the space bar.
Keep tapping. How long you tap for matters far more than how accurate any single tap is.
Watch the end drift: how far the song's last notes could land from the music. Under 50 ms is solid; past 150 ms the chart ends out of time.
Landing on half or double the real tempo is harmless — the buttons fix it.
If the panel says your tapping matches a whole-number tempo, take it exactly. That removes the drift entirely.
If you already know the exact BPM, type it. It beats tapping every time.
Then Generate the chart and the song is playable like any other.
These songs stream from YouTube on each player's client. They depend on the video staying up and on the player being able to reach YouTube — a video later made private or deleted stops working. Files in
songs/have neither problem.
Some videos cannot be embedded at all. Those are flagged, and their tempo cannot be set here.
Run /guitarcreator (requires the command.guitarcreator ACE). The panel lets you:
Place a machine — a ghost preview follows your aim. Rotate it, raise or lower it, and confirm.
Name it.
Pick 1 or 2 player pads. One pad is solo only; two pads enable Duo and Versus.
Set the price and the payment method — cash or bank. Zero is free to play.
Tick which modes players may start there.
Teleport to or delete any placed machine from the list.
Everything placed this way is stored in the database and loads on every start.
Machines listed in Config.Machines load on start and are not editable in game:
Config.Machines = {
{ coords = vec3(-1652.1, -1060.3, 13.15), heading = 145.0,
label = 'Vespucci Arcade',
players = 2,
price = 250, paymentMethod = 'money',
allowedModes = { 'solo', 'duo', 'versus' } },
}Config.Pads holds the standing spots as offsets from the cabinet — one entry for 1-player machines, two for 2-player ones.
They are calibrated for the shipped cabinet. If you swap Config.MachineModel for your own prop, re-measure them with /guitarpad.
With Config.Stage.enabled = true (the default), the performing player doesn't watch the cabinet — they watch themselves on stage. A clone of their ped is spawned at the venue holding their equipped guitar, and the camera cuts between framed shots in time with the music.
Five venues ship: National (stadium), Vinewood, Pier 46, Cube Plaza and Theme Park Pier. The player picks one before the song starts; in Duo and Versus the host's choice is used.
Adding a venue is one line:
{ id = 'mystage', label = 'My Venue', coords = vec4(0.0, 0.0, 70.0, 180.0) },If your locale files define stages.mystage, that translation is shown instead of label.
Camera — a list of shots, offsets and angles relative to the performer, cycled every 8 beats with an FOV punch on the beat. Frame your own with /guitarcam.
Lights — a truss of sweeping beams over the stage, key lights on the performer, and flashes over the crowd, all moving on the beat and changing colour every two bars. While Star Power burns, the palette switches to white-blue and everything gets brighter.
Crowd — spectator peds placed per venue, each with a model and an action: partying, cheering, air guitar, filming on a phone. Place your own with /guitarcrowd.
Mood — the stage forces night (23:00 by default) and applies a cinematic timecycle so the lights read properly. Both are switchable.
Because every camera shot is an offset from the performer, a new venue needs no camera work. The crowd is per-venue and does need placing.
Turn Config.Stage.enabled off and everyone plays on the cabinet camera instead.
Every run pays out XP (raises your level) and points (spent in the shop). Both are calculated on the server from the notes hit, the stars earned, whether you cleared the song and whether you full-comboed it — then scaled by difficulty and mode:
Multiplier | easy | normal | hard |
|---|---|---|---|
Difficulty | 1.0 | 1.35 | 1.8 |
Multiplier | solo | duo | versus |
|---|---|---|---|
Mode | 1.0 | 1.1 | 1.25 |
Get booed off stage and you still keep a share — 35 % of the XP and 25 % of the points.
The level curve runs to 50 by default, and a single run is capped at 25,000 XP and 4,000 points, so nothing can be farmed in one go.
Opened with T from the song list. Seven guitars ship, each gated by level and price:
Guitar | Level | Price |
|---|---|---|
Pawnshop Special | 1 | free |
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 |
The equipped guitar is what you carry on the stage and what everyone else sees on your ped at the cabinet.
{
id = 'my_guitar', -- internal key, 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 = { … } },
stage = { model = `my_guitar_prop`, bone = 24817, placement = { … } },
},machine is what others see at the cabinet, stage is what you see on the venue clone — usually the same.
Do not guess the placement offsets — tune them in game with /guitarplace.
Artwork goes in web/src/assets/guitars/ and is bundled at build time, so a new image needs a UI rebuild followed by a resource restart.
/guitarprogress info <serverId|me>
/guitarprogress points <serverId> <amount>
/guitarprogress xp <serverId> <amount>
/guitarprogress level <serverId> <level>Requires the same ACE permission as the creator. The player is told their progress was changed by an admin.
In milliseconds either side of the beat:
Judgment | Window | Score weight | Rock meter |
|---|---|---|---|
PERFECT | 45 ms | 1.0 | +2.0 |
GREAT | 90 ms | 0.75 | +1.0 |
GOOD | 135 ms | 0.4 | 0 |
BAD | 180 ms | 0.1 | −4.0 |
MISS | — | 0 | −8.0 |
score = 1000 × judgment weight × streak multiplier × star power
The streak multiplier steps up every 10 notes — x2 at 10, x3 at 20, x4 at 30 — and caps at x4. Star Power doubles whatever that comes to while it burns.
SSS | SS | S | A | B | C |
|---|---|---|---|---|---|
99 % | 97 % | 94 % | 88 % | 80 % | 70 % |
If hits feel late or early, Config.Gameplay.audioOffsetMs is the dial. It ships at -90 — push it more negative if notes register late. This is per-server, not per-player.
Everything you are meant to change is in config/main.lua.
The camera shot lists, the light rig, the crowd placements and the guitar offsets are calibrated against the venues and props the resource ships with. They are editable, but edit them with the in-game editors rather than by hand — every value is a local offset, and guessing them will not go well.
Option | Default | What it does |
|---|---|---|
|
| UI language. 41 included |
|
|
|
|
| Metres at which the prompt appears |
|
| Metres at which cabinets spawn and despawn |
|
| The cabinet prop |
|
| Starting fret keys — players rebind their own |
Option | Default | What it does |
|---|---|---|
|
| Count-in before the song starts |
|
| How long a note takes to travel down the lane. Lower = faster and harder to read |
|
| Audio latency compensation |
|
| The player cannot be hurt during a run |
|
| Walk this far away and the session ends |
| start 50, fail on | The rock meter, and whether you can be booed off |
| on, 16-note phrases | Phrase length, gain, burn time, threshold, multiplier |
Option | Default | What it does |
|---|---|---|
|
|
|
| 5 venues | Where performances happen |
|
| Beats between camera cuts |
|
| Spacing and camera pull-back for two performers |
| on | Truss, beams, key lights, palettes and Star Power colours |
| on | Ped models, actions and per-venue placements |
| on, | Forces night at the venue |
Option | Default | What it does |
|---|---|---|
|
| Master switch for levels and points |
|
| Level ceiling |
| 25000 / 4000 | Hard cap on one run's payout |
|
| The shop panel |
|
| Key that opens it from the song list |
| 7 entries | The shop catalog |
Option | Default | What it does |
|---|---|---|
|
| How long a Duo/Versus invite stands |
|
| Rows in the ranking |
|
| Announce new server records to everyone |
|
| Turn this off on a live server |
All of these are gated behind Config.Debug.enabled. Each one prints a paste-ready block to the F8 console — paste it over the matching entry in config/main.lua.
Command | What it edits |
|---|---|
| Where players stand at the cabinet |
| The guitar's offset and rotation on the ped |
| The performance shot list |
| Spectator placement per venue |
| Toggles autoplay — the game plays the next song itself |
| Prints every loaded machine to the console |
/guitarpad — stand near a machine. Arrows move, Q/E rotate, Shift/Ctrl change height, TAB switches between pad 1 and 2, ENTER prints, Backspace exits. Dummy peds show you exactly what a player at each spot will look like.
/guitarplace — WASD and the wheel move the camera, arrows move the prop on screen, PgUp/PgDn change depth, R/T rotate on the current axis, C changes the axis, V toggles pivot rings, 1/2/3 flip 180°, Q/E change the bone, Z changes the step size, G resets.
/guitarcam — WASD move, Space/Ctrl up and down, Shift for fast, wheel changes FOV, TAB/Q/E switch shot, R adds a shot here, X deletes one, F reverts the view. Run it during a song and the edits apply live to the running performance.
/guitarcrowd — WASD fly, mouse to aim, left click places a ped, Q/E change model, R/T change action, 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. A stand-in guitarist marks where the performer will be.
The framework glue lives in custom/, and every file there is open and meant to be edited.
File | What you can change |
|---|---|
| Identifier, money in/out, player name. Only money is used — the machines charge to play |
|
|
| The ox_target registration. Swap it for qb-target here |
| The pad editor and autoplay toggle |
| Server-side hooks |
locales/*.json — 41 languages included. Set Config.Locale to the one you want.
To edit or add one, copy the English file, translate the values, and name the file after your locale code. Locale files are read at runtime: a resource restart is enough, no rebuild needed.
Two things beyond plain UI strings are translatable:
Venue names go under stages.<id>, and override the label in the config.
Setlist names are select.tier_1 through select.tier_7. The list is scanned upwards until a number is missing, so adding tier_8 and beyond works with no code change (up to 60). With more sets than names, the names cycle and get numbered — OPENING LICKS 2, and so on.