> For the complete documentation index, see [llms.txt](https://docs.cuxial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuxial.com/scripts/leisure/cuxial-danceclass/configuration.md).
# Configuration
Every option of Cuxial Dance Class explained: who teaches, zones, fees, difficulties and points.
Everything you can adjust lives in `shared/config.lua`. Restart the resource after any change.
## Instructor · `instructor`
| Option | Type | Default | What it does |
| --------- | ------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode` | string | `'everyone'` | Who can open a class. `'everyone'` = any player, `'job'` = only the jobs in `jobs`, `'ace'` = only players with the permission in `ace`. Any other value works as `'everyone'`. |
| `jobs` | string\[] | example | Job names allowed to teach. Only used with `mode = 'job'`. Replace the example with your own. |
| `ace` | string | `'danceclass.instructor'` | ACE permission required. Only used with `mode = 'ace'`. |
| `command` | string | `'danceclass'` | Name of the command that opens the panel. |
| `keybind` | string \| nil | `nil` | Default key that opens the panel, for example `'F7'`. `nil` = command only. |
| `nextKey` | string \| nil | `'F6'` | Default key the instructor uses to start the class or launch the next dance without opening the panel. `nil` = no key. |
{% hint style="info" %}
`keybind` and `nextKey` are only defaults. Each player can rebind them in the GTA key settings, and FiveM remembers their choice.
{% endhint %}
## Interface and join prompt
| Option | Type | Default | What it does |
| -------------- | ------------ | ------------ | ----------------------------------------------------------------------------------------------- |
| `ui.accent` | string (hex) | configurable | Accent colour of the interface. |
| `joinKey` | number | `38` | Game control that accepts a class with a fee when you step into its zone. `38` is E. |
| `joinPromptMs` | number | `12000` | Milliseconds the fee prompt stays on screen. |
## Rooms · `rooms`
| Option | Type | Default | What it does |
| ----------------- | -------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `anywhere` | boolean | `true` | `true` lets instructors open a class anywhere. `false` only allows classes whose zone centre is inside a studio from `studios`. |
| `studios` | table\[] | `{}` | Dance studios. Each entry: `name`, `coords` (vector3), `radius` in metres (25 if omitted) and `blip` (`true` shows it on the map). |
| `blip` | table | `sprite = 480`, `color = 8`, `scale = 0.7` | Look of the studio blips. |
| `maxStudents` | number | `8` | Highest capacity an instructor can pick for a class. |
| `joinMargin` | number | `6.0` | Extra metres around the zone accepted when the server checks that a student is really there. Also the range of the nearby class list in the panel. |
| `fee` | table | see below | Entry fee settings. |
| `refundIfNoRound` | boolean | `true` | `true` returns the fee to a student who leaves, is kicked or sees the class closed before any dance has started. `false` never refunds. |
### Class zone · `rooms.zone`
The instructor draws the zone with the zone creator of Cuxial Bridge.
| Option | Type | Default | What it does |
| -------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `minPoints` | number | `3` | Minimum points of the polygon. |
| `maxPoints` | number | `12` | Maximum points. Extra points are ignored. |
| `maxRadius` | number | `40.0` | Largest distance in metres from the centre of the zone to its farthest point. A bigger zone is rejected. |
| `maxThickness` | number | `12.0` | Maximum height of the zone, in metres. |
| `height` | number | `4.0` | Height the creator starts with. |
| `debug` | boolean | `false` | `true` draws every class zone in the world, for testing. |
Two classes cannot overlap. A zone drawn too close to an open class is rejected.
### Entry fee · `rooms.fee`
| Option | Type | Default | What it does |
| --------- | ------- | -------- | -------------------------------------------------------------------------------------- |
| `enabled` | boolean | `true` | `true` lets instructors charge a fee. `false` makes every class free. |
| `account` | string | `'bank'` | Account the fee is taken from and paid into. Use an account name your framework knows. |
| `min` | number | `0` | Lowest fee an instructor can set. |
| `max` | number | `5000` | Highest fee an instructor can set. |
The fee goes straight from the student to the instructor when the student joins. Refunds are paid from the instructor's account.
## Class · `class`
| Option | Type | Default | What it does |
| ------------------ | ------ | ------- | ------------------------------------------------------------------------------------ |
| `countdownSeconds` | number | `3` | Countdown before each dance. |
| `roundSeconds` | number | `30` | Length of each dance. |
| `maxRounds` | number | `12` | Dances per class. Also the most dances an instructor can pick for the list. |
| `resultsHoldMs` | number | `6000` | Milliseconds the results table of a dance stays on screen. |
| `classEndHoldMs` | number | `9000` | Milliseconds the final podium stays on screen. |
| `missesToFall` | number | `3` | Misses in a row that make the character fall. |
| `fallMs` | number | `2500` | Milliseconds on the ground. |
| `fallGraceMs` | number | `1000` | Milliseconds after getting up during which misses do not count towards another fall. |
| `stumbleMs` | number | `900` | Length of the stumble shown on a single miss. |
| `minStudents` | number | `1` | Students needed to start a dance. |
{% hint style="info" %}
Students can only join before the first dance. Once the class has started, the zone tells newcomers it is already under way.
{% endhint %}
## Difficulties · `difficulties`
Three levels are included: `easy`, `normal` and `hard`. `difficultyOrder` sets the order in which they appear in the panel.
| Field | Type | What it does |
| ---------------- | --------- | -------------------------------------------------------------------------------------------------------- |
| `label` | string | Name shown on the class cards. |
| `noteIntervalMs` | number | Base gap between notes. Lower is faster. |
| `perfectMs` | number | Timing window, in milliseconds either side of the note, for a Perfect. |
| `goodMs` | number | Timing window for a Good. Outside it, the note is a miss. |
| `pointsBase` | number | Points of a dance with every note Perfect, before the streak bonus. |
| `keys` | string\[] | Keys used by the level. Valid values: `'W'`, `'A'`, `'S'`, `'D'`, `'UP'`, `'DOWN'`, `'LEFT'`, `'RIGHT'`. |
| Level | `noteIntervalMs` | `perfectMs` | `goodMs` | `pointsBase` | Keys |
| -------- | ---------------- | ----------- | -------- | ------------ | --------------------- |
| `easy` | `950` | `100` | `220` | `3` | W A S D |
| `normal` | `700` | `80` | `180` | `4` | W A S D + up, down |
| `hard` | `480` | `65` | `140` | `6` | W A S D + four arrows |
## Points · `points`
At the end of each dance the script works out the accuracy of every student and turns it into points. With Cuxial Gym running, those points raise the skill in `skill`.
| Option | Type | Default | What it does |
| ----------------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------------- |
| `skill` | string | `'Stamina'` | Gym skill that goes up. Use a name Cuxial Gym accepts, such as `'Stamina'`, `'Strength'` or `'Running'`. |
| `perfect` | number | `1.0` | Weight of a Perfect in the accuracy. |
| `good` | number | `0.6` | Weight of a Good. |
| `minAccuracy` | number | `0.25` | Accuracy below which a dance gives no points. From 0 to 1. |
| `streakBonusPer` | number | `0.02` | Bonus for each hit of the best streak. |
| `streakBonusMax` | number | `0.3` | Cap of the streak bonus. |
| `maxPerRound` | number | `6` | Most points a student can earn in one dance. |
| `maxPerClass` | number | `24` | Most points a student can earn in one class. |
| `instructorPerStudent` | number | `1` | Points the instructor earns for each student who reaches `minAccuracy`. |
| `instructorMaxPerRound` | number | `3` | Most points the instructor can earn in one dance. |
Points of a dance = `pointsBase` × accuracy × (1 + streak bonus), rounded and limited by `maxPerRound`.
## Dances · `playlists`
One list of dances per difficulty, used when the instructor leaves the class on random. Each entry is the command of a dance from the Cuxial Emotes catalog.
* A command that does not exist in the catalog is skipped.
* An empty list picks at random from the whole catalog.
* A dance is not repeated until every dance of the list has been used.
The instructor can always pick specific dances in the panel, for the whole class or for the next dance only.
## Ranks · `ranks`
Titles shown in each player's history, by total points earned as a student and as an instructor.
| Field | Type | What it does |
| -------- | ------ | -------------------------------- |
| `points` | number | Points needed to reach the rank. |
| `label` | string | Name of the rank. |
Keep the list sorted from fewest to most points, starting at `0`.
## Security · `security`
| Option | Type | Default | What it does |
| -------------------- | ------ | ------- | ------------------------------------------------------------------------------- |
| `maxEventsPerSecond` | number | `30` | Notes per second the server accepts from one player. Anything above is dropped. |
## Common changes
### Only a job can teach
{% code title="shared/config.lua" %}
```lua
instructor = {
mode = 'job',
jobs = { 'dancer' },
-- the rest stays the same
},
```
{% endcode %}
### Classes only inside a studio
{% code title="shared/config.lua" %}
```lua
rooms = {
anywhere = false,
studios = {
{ name = 'Dance Studio', coords = vector3(0.0, 0.0, 0.0), radius = 25.0, blip = true },
},
-- the rest stays the same
},
```
{% endcode %}
### Free classes
{% code title="shared/config.lua" %}
```lua
fee = { enabled = false, account = 'bank', min = 0, max = 5000 },
```
{% endcode %}
### Texts in your language
The difficulty and rank names are written in `shared/config.lua`. Set them in the language of your server.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.cuxial.com/scripts/leisure/cuxial-danceclass/configuration.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.