Documentation
Install Dance Machine on your FiveM server: requirements, server.cfg load order, the automatic database and shipped charts, admin ACE permissions and config.
Before installing Dance Machine, make sure your server meets the minimum requirements. Four things are mandatory — one of them ships with the script; everything else is optional and picked up on its own.
Requirement | Status | Notes |
|---|---|---|
OneSync | Required | The resource will not start without it. |
| Required |
Database access. The tables create themselves.
| Required | Callbacks, notifications and shared helpers. |
| Required | Included in the download. Streams the arcade cabinet and the backdrop shown behind the song menu. |
Framework | Optional |
|
| Optional | Only when |
| Optional | Styled notifications, and its HUD is hidden while a player is at the machine. |
| Optional | A styled 3D prompt over the machine instead of plain drawn text. |
Every optional integration degrades silently. If a resource is missing, the script falls back to its own prompt, notifications and HUD handling — nothing errors. Integrations has the details.
After purchasing Dance Machine, the resource is automatically linked to your CFX Portal account.
Sign in to the CFX Portal using the same account used during checkout, open Granted Assets, and download Dance Machine.
After extracting the download, you should have these two folders:
qs-dancemachine/
├── config/ -- what you may edit
├── custom/ -- framework bridges (editable)
├── client/custom/ -- prompt, notifications, target, weather sync, debug tools (editable)
├── locales/ -- 41 languages
├── songs/ -- the 19 shipped tracks; your own go here too
├── database/ -- sql.sql: the tables and the shipped charts
└── web/ -- the interface
dancemachine-assets/
└── stream/ -- the arcade cabinet and the menu backdropKeep both folder names as shipped. Other resources — Arcade Creator among them — reach the script through
exports['qs-dancemachine'], and the update check looks it up by name. The cabinet only exists whiledancemachine-assetsis running.
Move both folders into your server's resources directory. They can live anywhere inside it, including a category folder:
resources/
└── [qs]/
├── qs-dancemachine/
└── dancemachine-assets/Then open your server.cfg and make sure every dependency — and everything you want detected — starts before Dance Machine:
ensure oxmysql
ensure ox_lib
# Framework
ensure es_extended
# ensure qb-core
# ensure qbx_core
# Optional
ensure ox_target
ensure qs-interface
ensure qs-textui
ensure dancemachine-assets
ensure qs-dancemachineThe loading order matters. The framework is detected the moment the resource starts, so a framework that starts afterwards is not found and the machines run standalone — which means nobody is charged to play.
Dance Machine creates its four tables on first start. There is nothing you must run for the script to work:
Table | Holds |
|---|---|
| Every machine placed with the creator: position, name, pads, price, payment method and allowed modes. |
| Each song's details and its generated chart. |
| Each player's best run per song and difficulty — the source of every record and ranking. |
| Each player's recent runs, for the profile. The last 40 per player are kept. |
What the automatic setup cannot do is write the charts of the 19 shipped tracks. Those live in database/sql.sql. Import it once — with phpMyAdmin, HeidiSQL, DBeaver or any database manager — and every shipped song is playable the moment the server starts. Skip it and the songs still appear in the Music Manager, marked not generated, until you generate each one.
Updating from an older version? Earlier releases stored a machine's position in separate
cx,cy,czandheadingcolumns. The first start moves every row into the newcoordscolumn on its own and prints how many it migrated. Your machines, songs and scores are kept.
Placing machines (/dancecreator) and managing songs (/dancemusic) are behind an ACE permission, command.dancecreator by default. Anybody without it is told they do not have permission.
Give the permission to a group and put your staff in that group, in server.cfg:
add_ace group.admin command.dancecreator allow
add_principal identifier.license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx group.adminA group that already has the whole command ace — add_ace group.admin command allow, as most server configs and txAdmin set up — already includes it.
Both panels read their permission from config/main.lua, so you can give music and machines to different people:
Config.Creator = {
command = 'dancecreator',
permission = 'dancemachine.machines',
-- ...
}
Config.Music = {
command = 'dancemusic',
permission = 'dancemachine.music',
}add_ace group.admin dancemachine.machines allow
add_ace group.dj dancemachine.music allowEverything is configured in one file, config/main.lua, and every section is commented. Machines and songs are not configured there — they are managed in game.
Section | Contents |
|---|---|
| The language, and the framework (auto-detected). |
| ox_target or the proximity prompt, how close a player must stand (2.2 m), and how far away cabinets are spawned (60 m). |
| The cabinet model, and where the players stand on it for one and two pads. |
| The interact key, the default lane keys players start with, and the interface sounds. |
| Countdown, note speed, audio latency, hit windows, the life bar, the score formula and the grade thresholds. |
| How dense each generated difficulty is. |
| The cinematic stages and their cameras, the machine-view camera used when stages are off, and the dance moves. |
| The dancer shown behind the song menu. |
| How long an invitation waits, how often scores are shared, the size of the top lists and record announcements. |
| The admin commands and their permissions, and machines defined in the file instead of in game. |
| The testing and calibration commands. |
The values worth reviewing first:
Config.Locale = 'en' -- 41 languages, see Integrations
Config.UseTarget = false -- true = ox_target on the cabinet
Config.MachineModel = `qs_arcade_dance_machine_02` -- or qs_arcade_dance_machine_01
Config.Gameplay.audioOffsetMs = -90 -- more negative if hits feel late
Config.Creator.permission = 'command.dancecreator'
Config.Music.permission = 'command.dancecreator'
Config.Debug.enabled = false -- keep it off on a live serverRestart your server and read the console. A healthy start looks like this:
[qs-dancemachine:INFO] Locale loaded: en (13 keys)
[qs-dancemachine:INFO] Server framework loaded: esx
[qs-dancemachine:INFO] Loaded 19 song(s) (scanned once at boot)
[qs-dancemachine:INFO] Loaded 0 dance machine(s) from SQL.
[qs-dancemachine:INFO] Started - framework: esxframework: standalone on a server that runs ESX, QBCore or Qbox means the framework started after Dance Machine — move it above ensure qs-dancemachine. A yellow WARN line about songs is explained in Common Errors.
Then join your server and work through the first loop:
Type /dancecreator, press +, give it a name, press Select under Placement, aim the ghost cabinet at the floor and left-click. Press Save Machine and it appears for everybody.
Walk up to the cabinet and press E. Pick a track with the arrows, press ENTER twice, choose a stage and press Start. Hit the notes with W A S and ↑ → ↓.
/dancemusic lists every song the server found. From there, Usage covers adding your own music.
From here on only one thing needs a restart: adding new audio files to
songs/. Machines, song details and charts are all edited in game and reach every player immediately.