> For the complete documentation index, see [llms.txt](https://izzyshop-1.gitbook.io/izzyshop-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://izzyshop-1.gitbook.io/izzyshop-docs/izzyshop-resources/izzy-dancing/configuration.md).

# Configuration

### Configuration (`shared/config.lua`)

#### `Config.Locale`

UI language. Files in `locales/`.

| Code | Language   |
| ---- | ---------- |
| `en` | English    |
| `tr` | Turkish    |
| `de` | German     |
| `fr` | French     |
| `es` | Spanish    |
| `pt` | Portuguese |
| `pl` | Polish     |
| `nl` | Dutch      |
| `it` | Italian    |
| `ru` | Russian    |

Missing translation keys fall back to English.

#### `Config.Notify`

Notification system for in-game alerts.

| Value                                                      | Description                              |
| ---------------------------------------------------------- | ---------------------------------------- |
| `auto`                                                     | First detected notify resource on server |
| `ox_lib`, `okoknotify`, `mythic_notify`, `esx`, `qb`, etc. | Force specific system                    |
| `custom`                                                   | Your function in `client/core.lua`       |
| `native`                                                   | GTA default feed                         |

#### `Config.Mugshots`

| Key           | Description                                     |
| ------------- | ----------------------------------------------- |
| `Enable`      | Show player headshots in lobby UI               |
| `Transparent` | Remove background (slower, needs MugShotBase64) |
| `Cache`       | Reuse captures while in same lobby              |

#### `Config.Admin`

Controls who can use **Create Lobby** when `Open = true`.

| Key          | Description                               |
| ------------ | ----------------------------------------- |
| `Open`       | `false` = everyone · `true` = admins only |
| `licenses`   | F8 identifier allowlist                   |
| `esx.groups` | ESX group names                           |
| `qb.groups`  | QBCore / QBX permission names             |

#### `Config.Commands`

Each action: `CreateLobby`, `DeleteLobby`, `EndGame`.

```lua
CreateLobby = {
    Enable = true,
    Command = { Enable = true, Name = 'createlobby' },
    Item = { Enable = false, Name = 'dancing_remote', RemoveOnUse = false },
},
```

* **Command** — chat command
* **Item** — usable inventory item (see `items.txt`)
* Enable command only, item only, or both

| Default command  | Action                    |
| ---------------- | ------------------------- |
| `/createlobby`   | Open create lobby menu    |
| `/deletelobby`   | Delete your lobby (owner) |
| `/finishdancing` | End active game (owner)   |

#### `Config.CashAsItem`

For servers where cash is an inventory item instead of account money.

```lua
CashAsItem = {
    Enable = false,
    Name = "cash",
},
```

#### `Config.Prop`

Manual dance floor placement.

| Key                    | Default           | Description                         |
| ---------------------- | ----------------- | ----------------------------------- |
| `Model`                | `flank_carpet_01` | Carpet prop (needs stream)          |
| `ModelTimeout`         | `15000`           | Model load timeout (ms)             |
| `Spacing`              | `1.7`             | Distance between player mats (m)    |
| `InteractionDistance`  | `3.0`             | **E** key range for dynamic lobbies |
| `PlacementDistance`    | `10.0`            | Raycast distance when placing       |
| `PlacementMaxDistance` | `15.0`            | Max place distance from player      |
| `RotationSpeed`        | `15.0`            | Degrees per scroll step             |
| `PreviewAlpha`         | `200`             | Preview transparency (0–255)        |

**Placement controls:** `E` place · `BACKSPACE` cancel · scroll / arrows rotate

#### `Config.Dances`

Animations when rhythm game starts. One random entry per game.

**Emote command** (needs rpemotes / scully\_emotemenu):

```lua
{ command = "dance" },
```

**Native GTA anim** (no emote script):

```lua
{ dict = "anim@amb@nightclub@...", anim = "high_center" },
```

Use **either** `command` **or** `dict` + `anim` per entry.

#### `Config.Speaker`

Speaker prop for **xsound** positional audio.

```lua
Speaker = {
    Model = 'h4_prop_battle_club_speaker_med',
    Offset = { x = -1.5, y = 0.0 },
},
```

#### `Config.Game`

| Key                 | Description                                          |
| ------------------- | ---------------------------------------------------- |
| `UseIcName`         | `true` = character name in UI · `false` = Steam name |
| `Keys`              | Characters that can appear in rhythm rounds          |
| `TimeBetweenRounds` | Delay between rounds (ms)                            |
| `Difficulty`        | Per-difficulty settings                              |

### **Difficulty fields:**

| Field        | Meaning                                 |
| ------------ | --------------------------------------- |
| `Time`       | Key fall duration (ms) — lower = faster |
| `BoxCount`   | Keys per round                          |
| `RoundCount` | Total rounds                            |

### Default presets:

| Difficulty | Time | Boxes | Rounds |
| ---------- | ---- | ----- | ------ |
| easy       | 4000 | 3     | 8      |
| medium     | 2500 | 3     | 10     |
| hard       | 2000 | 3     | 15     |

**Elimination:** wrong key or timeout → eliminated. Last player(s) standing win. Winner receives **bet × total players**.

#### `Config.Music`

| Key        | Description                        |
| ---------- | ---------------------------------- |
| `Distance` | Hear range from speaker (m)        |
| `Volume`   | `0.0` – `1.0`                      |
| `Types`    | Music categories with YouTube URLs |

If lobby **Music URL** is empty, a random URL from selected **Music Type** is used at game start.

#### `Config.Target`

**ox\_target** / **qb-target** on dance carpets.

```lua
Target = {
    Enable = false,
    Name = 'ox_target',        -- or 'qb-target'
    Icon = 'fas fa-music',
    Distance = 2.5,
    UseKeyInteraction = true,    -- false = target only, no E hint
},
```

| Target option        | When                       |
| -------------------- | -------------------------- |
| Open Control Panel   | Active lobby on this floor |
| Create Dancing Lobby | Empty static floor         |

### Static Dance Floors

Permanent props spawned at map coordinates. Props **stay after** lobby/game ends.

#### Global settings

```lua
StaticLocations = {
    Enable = true,
    RequireStaticForCreate = false,
    CreateDistance = 5.0,   -- reserved (not used in code yet)
    ...
},
```

| Key                      | Description                                                                    |
| ------------------------ | ------------------------------------------------------------------------------ |
| `Enable`                 | Spawn fixed floors on resource start                                           |
| `RequireStaticForCreate` | `true` = lobbies **only** at static spots (no manual `/createlobby` placement) |
| `CreateDistance`         | Documented but **not wired** — use per-location `interactionDistance` instead  |

#### Per-location entry

```lua
{
    id = 'beach_dance_floor',
    label = 'Beach Dance Floor',
    center = vector3(-1840.7262, -1214.5122, 13.0172),
    heading = 240.2563,
    maxPlayers = 9,
    interactionDistance = 5.0,

    -- Optional map blip (per location)
    blip = {
        Enable = true,
        Sprite = 93,
        Color = 27,
        Scale = 0.7,
    },

    -- Optional opening hours (nightclub mode)
    openingHours = {
        Enable = false,   -- false = 24/7 open
        Open = 22,        -- 22:00
        Close = 6,        -- 06:00 (overnight OK: 22→6)
    },
},
```

| Field                 | Description                            |
| --------------------- | -------------------------------------- |
| `id`                  | Unique string (required)               |
| `label`               | Display name (blip / logs)             |
| `center`              | Grid center `vector3`                  |
| `heading`             | Floor rotation (degrees)               |
| `maxPlayers`          | Carpet count & max lobby size          |
| `interactionDistance` | **E** / proximity range for this spot  |
| `propModel`           | Override carpet model                  |
| `speakerModel`        | Override speaker model                 |
| `spacing`             | Override carpet spacing                |
| `speakerOffset`       | Override `{ x, y }` speaker offset     |
| `blip`                | Per-location map blip                  |
| `openingHours`        | Time lock for **creating** new lobbies |

**Opening hours behavior:**

* `Enable = false` → always open for new lobbies
* `Enable = true` → create blocked outside hours; shows *"Closed — Opens 22:00 - 06:00"*
* Active lobby on closed floor → panel still works until lobby ends

**Interaction at static floor:**

* No lobby → **E** = Create Dancing Lobby
* Active lobby → **E** = Open Control Panel

Only **one lobby per static spot** at a time.

### Discord Webhooks (`shared/webhook.lua`)

**Only paste URLs here.** Branding and embed layout are fixed in `server/discord.lua`.

```lua
Webhooks = {
    LobbyCreated = '',
    PlayerJoined = '',
    GameStarted = '',
    GameWinner = '',
    PlayerDisconnect = '',
    OwnerDisconnect = '',
    LobbyDeleted = '',
}
```

Leave `''` to disable that log type.

#### Fixed branding (not configurable)

| Setting            | Value                        |
| ------------------ | ---------------------------- |
| Webhook username   | `Izzy Shop`                  |
| Avatar & thumbnail | tqdev logo URL               |
| Footer             | `DD.MM.YYYY HH:MM:SS -tqdev` |

#### What each webhook logs

| Key                | Trigger               | Details included                                   |
| ------------------ | --------------------- | -------------------------------------------------- |
| `LobbyCreated`     | Owner creates lobby   | Owner, bet, max players, password, location        |
| `PlayerJoined`     | Player accepts invite | Player, owner, fee paid, pot, player count         |
| `GameStarted`      | Owner starts game     | All participants, pot, difficulty, music, location |
| `GameWinner`       | Game ends with winner | Winner, prize, all players, location               |
| `PlayerDisconnect` | Member disconnects    | Player, owner, reason, during-game flag, pot       |
| `OwnerDisconnect`  | Owner disconnects     | Owner, reason, affected members                    |
| `LobbyDeleted`     | Owner deletes lobby   | Owner, bet, player count, game state               |

Each player line includes: **display name**, **server ID**, **Discord mention**, **license**.

### Commands & Items

#### Commands (default)

| Command          | Who             | Action                 |
| ---------------- | --------------- | ---------------------- |
| `/createlobby`   | Allowed players | Open create lobby menu |
| `/deletelobby`   | Lobby owner     | Delete lobby & refund  |
| `/finishdancing` | Lobby owner     | Force end game         |

#### Items

See **`items.txt`** for ox\_inventory, QB, QS, ESX SQL examples.

Default item: `dancing_remote` — opens create lobby when `Config.Commands.CreateLobby.Item.Enable = true`.

### Gameplay Flow

```
/createlobby OR static floor [E]
        ↓
   Create lobby menu (bet, password, players)
        ↓
   Payment deducted (cash → bank fallback)
        ↓
   Manual placement OR static floor bind
        ↓
   Control panel [E] — invite, settings, members
        ↓
   Start game — music plays, dance anim, rhythm UI
        ↓
   Rounds — correct = survive, wrong/timeout = eliminated
        ↓
   Winner — receives pot, Discord log, props cleanup
```

#### Lobby roles

| Role        | Can do                                           |
| ----------- | ------------------------------------------------ |
| **Owner**   | Invite, kick, settings, start game, delete lobby |
| **Member**  | View lobby, leave, play rhythm game              |
| **Visitor** | Near floor with active lobby — view invites tab  |

#### Money

* Create lobby: owner pays bet upfront
* Join lobby: member pays bet on accept
* Price change: members re-charged or kicked if insufficient funds
* Delete / disconnect before game: refunds issued
* Winner: `bet × player_count` added to cash

### Locales

Files: `locales/{code}.lua`

Structure:

```lua
Translations = {
    notifications = { ... },
    ui = { ... },
    print = { ... },
}
```

Use `%{name}`, `%{amount}`, etc. for placeholders.

To add a language: copy `en.lua`, translate, add file to `locales/`, add code to `Config.Locale` comment list.

### Inventory Items (`items.txt`)

Full copy-paste examples for:

* ox\_inventory
* qb-core / qb-inventory
* qs-inventory
* ESX SQL
* codem-inventory

Includes `dancing_remote` image path hints and give commands.

### Troubleshooting

#### Dance floor prop not loading

* Ensure `izzy-dancing-stream` is started **before** `izzy-dancing`
* Check `Config.Prop.Model` matches stream resource
* Increase `Config.Prop.ModelTimeout`

#### No music during game

* Install & start **xsound**
* Check YouTube URL is valid or set Music Type with URLs in config

#### Mugshots not showing

* Start **MugShotBase64**
* Set `Config.Mugshots.Enable = true`

#### E key not showing at static floor

* Stand on/near carpets (uses `interactionDistance`, default 5.0 on beach)
* Check `StaticLocations.Enable = true`
* If `openingHours.Enable = true` and outside hours — create blocked (closed message shown)

#### Target not working

* `Config.Target.Enable = true`
* `ox_target` or `qb-target` must be running
* Match `Config.Target.Name` to your target resource

#### Discord webhooks not sending

* Paste full webhook URL in `shared/webhook.lua`
* URL must start with `https://discord.com/api/webhooks/`
* Empty string = that log type disabled


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://izzyshop-1.gitbook.io/izzyshop-docs/izzyshop-resources/izzy-dancing/configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.