# Configuration

> Configuration reference for ML Missions

Category: QUESTS SYSTEM · Source: https://miciomods.it/docs/ml-missions-configuration · Last updated: 2026-07-10

## Overview

- `shared/config/config.lua`: General settings, theme, TTS, vehicle keys
- `shared/config/peds.lua`: Ped models available in the creator
- `shared/config/vehicles.lua`: Vehicle models available in the creator
- `shared/config/animations.lua`: Animations selectable in the creator
- `shared/config/weaponlist.lua`: Weapons for enemy NPCs
- `shared/config/props.lua`: Prop models selectable for objectives and optional props
- `shared/heist_presets.lua`: Scripted heist grab presets (trolleys, safes, cash tables)
- `shared/config/zombie_animations.lua`: Zombie-mode movement sets
- `shared/config/minigames/`: Minigame integrations (one file per resource)
- `server/config_server.lua`: ElevenLabs API key, Discord webhooks

Mission and NPC data is managed through the in-game creator and stored in the database.

## General Settings

**shared/config/config.lua**

```lua
Config.Settings = {
    Locale = 'en',
    Debug = false,
    MoveHudCommand = 'movequesthud',
    CreatorCommand = 'missioncreator',
    NearbyPlayerDistance = 10,
    SoundResource = 'xsound',
    GiveVehicleKeys = true,
    RewardsInfo = 'name',          -- 'name' | 'image' | 'combo'
    PlayerNameFormat = 'rp_first', -- 'fivem' | 'rp_first' | 'rp_full'

    KeepOnComplete = {
        Garage      = 'pillboxgarage',
        State       = 1,
        VehicleType = 'car',
    },
}
```

- `Locale`: Language code for translations
- `Debug`: Enables verbose console output
- `MoveHudCommand`: Command to reposition the quest HUD on screen
- `CreatorCommand`: Command to open the in-game mission creator (requires admin permissions)
- `NearbyPlayerDistance`: Max distance in meters to detect nearby players for squad invites
- `SoundResource`: Resource used for TTS audio playback (default: `xsound`)
- `KeepOnComplete`: Destination garage, state and vehicle type used when a `GIVE_VEHICLE` objective has `keepOnComplete = true`. Advanced Parking is auto-detected; no setting needed.
- `GiveVehicleKeys`: Give/remove vehicle keys via `ml_bridge` during vehicle objectives
- `RewardsInfo`: How rewards display in the UI. Options: `'name'` (text only), `'image'` (icon only), `'combo'` (both)
- `PlayerNameFormat`: Player name format. Options: `'fivem'` (Steam/Discord name), `'rp_first'` (RP first name), `'rp_full'` (RP full name)

## Theme

**shared/config/config.lua**

```lua
Config.Theme = 'classic'
-- Config.MainColor = '#c90a47'
-- Config.ThemeBaseColor = '#429ca8'
```

- `Theme`: UI theme. Options: `'classic'`, `'cyberpunk'`, `'wasteland'`, `'fantasy'`, `'noir'`
- `MainColor`: Hex accent color override for buttons and icons. Uncomment to apply. Only affects certain themes.
- `ThemeBaseColor`: Primary background color override. Uncomment to apply. Only affects certain themes.

## TTS (Text-To-Speech)

**shared/config/config.lua**

```lua
Config.TTS = {
    Enabled = true,
    ElevenLabs = {
        DefaultVoiceId = 'Xb7hH8MSUJpSbSDYk0k2',
        ModelId = 'eleven_multilingual_v2',
        Stability = 0.5,
        SimilarityBoost = 0.75,
    }
}
```

**server/config_server.lua**

```lua
Config.TTS.ElevenLabs.ApiKey = 'YOUR_API_KEY'
```

- `Enabled`: Enable/disable TTS globally. When `false`, no API key is needed.
- `DefaultVoiceId`: Default ElevenLabs voice ID. Can be overridden per NPC in the creator.
- `ModelId`: ElevenLabs synthesis model
- `Stability`: Voice stability (0.0-1.0)
- `SimilarityBoost`: Voice similarity boost (0.0-1.0)
- `ApiKey`: ElevenLabs API key (server-side only, never shared with clients)

Generated audio is cached in `cache/tts/` and re-used on every later request. Generation is capped at 50000 characters per player per hour and single lines are cut at 500 characters. Cached lines replay from disk and cost nothing.

### Custom Audio Files

Any voice line can play a local file instead of calling ElevenLabs. In the creator, set the audio source to Custom File and enter the file name. Available for NPC greetings, quest list lines, mission briefings and Talk objectives.

- Place the files in `cache/tts/` inside the resource folder
- Formats: `.mp3`, `.wav`, `.ogg`. A name typed without extension is read as `.mp3`
- Plain file names only (letters, numbers, `-` and `_`), max 2 MB per file

> **INFO:** No API Key Needed
>
> Custom files never call ElevenLabs. Keep `Config.TTS.Enabled = true` so the audio pipeline stays active.

## Skills Integration

**shared/config/config.lua**

```lua
Config.Skills = {
    Enabled       = true,
    Resource      = 'ml_skills',
    MaxXpPerQuest = 5000,
}
```

- `Enabled`: Master switch. When `false`, skill requirements, skill XP and skill unlocks are ignored on every mission
- `Resource`: Name of the skills resource
- `MaxXpPerQuest`: Safety cap on skill XP granted by a single quest completion

Skill requirements, XP rewards and skill unlocks are set per mission in the creator. Everything stays silent when `ml_skills` is not running.

## Permissions

**shared/config/config.lua**

```lua
Config.Permissions = {
    Creator = {
        useDefaultAdmins = true,
        ace = {
            'ml_missions.creator',
            'admin', 'god', 'superadmin', 'command',
            'group.admin', 'group.superadmin',
        },
    },
    LiveActions = {
        useDefaultAdmins = true,
        ace = {
            'ml_missions.admin',
            'admin', 'god', 'superadmin',
            'group.admin', 'group.superadmin',
        },
    },
}
```

- `Creator`: Opens the creator command, edits missions and NPCs, and views the Live Missions tab
- `LiveActions`: Force complete, force fail and teleport to leader from the Live Missions tab. When the whole block is removed it falls back to `Creator`
- `useDefaultAdmins`: Also accept the framework admin groups resolved by `Bridge.HasPermission`
- `ace`: ACE permissions accepted for the tier. Matching any single entry is enough

## Vehicle Keys

**shared/config/config.lua**

```lua
Config.VehicleKeys = {
    Give = function(vehicle, plate)
        if not Config.Settings.GiveVehicleKeys then return end
        Bridge.GiveVehicleKey(vehicle, plate)
    end,
    Remove = function(vehicle, plate)
        if not Config.Settings.GiveVehicleKeys then return end
        Bridge.RemoveVehicleKey(vehicle, plate)
    end
}
```

Called automatically during vehicle objectives. Override these functions if your vehicle keys system is not supported by `ml_bridge`. Only active when `Config.Settings.GiveVehicleKeys = true`.

## Minigames

Defined in `shared/config/minigames/`. Each file registers entries in `Config.AvailableMiniGames`. Selected per-objective in the creator.

Supported resources:

- `ox_lib`: Always available
- `bl_ui`: Optional
- `mgc`: Optional
- `bd`: Optional
- `ultra_voltlab`: Optional
- `utk_fingerprint`: Optional

**Adding a custom minigame**

**shared/config/minigames/my_game.lua**

```lua
Config.AvailableMiniGames["my_custom_game"] = {
    label = "My Custom Game",
    Start = function(params)
        local success = exports['my-minigames']:StartGame('hard')
        return success
    end
}
```

The `Start` function must return `true` (pass) or `false` (fail).

## Shared Config Files

### Ped Models

**shared/config/peds.lua**

```lua
pedModelList = {
    'a_f_m_beach_01', 'a_f_y_bevhills_01',
    'a_m_m_afriamer_01', 'a_m_y_acult_01',
    -- Add your own ped models at the bottom
}
```

- `model`: GTA ped model name
- `label`: Display name in the creator dropdown

### Vehicle Models

**shared/config/vehicles.lua**

```lua
carModelList = {
    'adder', 'autarch', 'banshee2', 'sultan', 'kuruma',
    -- Add your own vehicle spawn names at the bottom
}
```

- `model`: GTA vehicle spawn name
- `label`: Display name in the creator dropdown

### Animations

**shared/config/animations.lua**

```lua
AnimationsList = {
    { Label = 'Mechanic (Ground)', Animation = 'base', Dictionary = 'amb@world_human_vehicle_mechanic@male@base' },
}
```

- `Label`: Display name in the creator
- `Animation`: Animation clip name
- `Dictionary`: Animation dictionary

## Discord Webhooks

**server/config_server.lua**

```lua
Config.DiscordWebhook = {
    CompleteObjective = 'INSERT_WEBHOOK_LINK_HERE',
    StartQuests       = 'INSERT_WEBHOOK_LINK_HERE',
    Allobjective      = 'INSERT_WEBHOOK_LINK_HERE',
    Turnin            = 'INSERT_WEBHOOK_LINK_HERE',
    QuestsExploit     = 'INSERT_WEBHOOK_LINK_HERE',
    FailedAll         = 'INSERT_WEBHOOK_LINK_HERE',
    MissionEdit       = 'INSERT_WEBHOOK_LINK_HERE',
    MissionDelete     = 'INSERT_WEBHOOK_LINK_HERE',
    MissionTest       = 'INSERT_WEBHOOK_LINK_HERE',
    OneTimeTurnin     = 'INSERT_WEBHOOK_LINK_HERE',
    NpcEdit           = 'INSERT_WEBHOOK_LINK_HERE',
    NpcDelete         = 'INSERT_WEBHOOK_LINK_HERE',
    SquadActions      = 'INSERT_WEBHOOK_LINK_HERE',
    RewardClaimed     = 'INSERT_WEBHOOK_LINK_HERE',
    AdminAction       = 'INSERT_WEBHOOK_LINK_HERE',
}
```

- `CompleteObjective`: Player completes an objective
- `StartQuests`: Quest started
- `Allobjective`: All objectives completed
- `Turnin`: Quest turned in
- `QuestsExploit`: Suspicious activity detected
- `FailedAll`: Quest failed
- `MissionEdit` / `MissionDelete`: Creator changes
- `MissionTest`: Test mission launched
- `OneTimeTurnin`: One-time quest completed
- `NpcEdit` / `NpcDelete`: NPC changes
- `SquadActions`: Squad lifecycle events
- `RewardClaimed`: Rewards distributed

Leave any webhook as `INSERT_WEBHOOK_LINK_HERE` to disable that log entirely.