# nova\_multicharacter

NOVA Framework advanced multicharacter system. Provides a cinematic character selection and creation experience with visual effects, background music, and rich customization.

## Features

* **Character List** — View and select existing characters
* **Create Character** — Create new characters with name, date of birth, gender
* **Delete Character** — Remove characters (configurable)
* **Multiple Slots** — Configurable character slots per player
* **Cinematic Mode** — Camera effects and animations during selection
* **Background Music** — Ambient music during character selection
* **Visual Effects** — Screen effects and weather/time settings
* **Localization** — Portuguese language support
* **Performance Mode** — Reduced effects for lower-end systems
* **Starter Items** — Configurable items given to new characters
* **Last Location** — Option to spawn at last known location

## Configuration

Edit `config.lua`:

```lua
Config.Debug = false
Config.Lang = 'pt'
Config.PerformanceMode = false

Config.CleanZone = true             -- Clean NPCs/vehicles in spawn area
Config.HideRadar = true
Config.DeleteButton = true          -- Show delete character button

Config.DefaultSlots = 3             -- Default character slots
Config.PlayersNumberOfCharacters = {
    -- ['license:xxx'] = 5,         -- Override slots per player
}

Config.DefaultSpawn = vector4(-74.64, -818.89, 326.18, 0.0)

Config.BackgroundMusic = {
    enabled = true,
    volume = 0.3,
    file = 'music.ogg',
}

Config.CinematicMode = {
    enabled = true,
    bars = true,
    letterbox = true,
}

Config.Effects = {
    blur = true,
    vignette = true,
}

Config.Animation = {
    dict = 'anim@heists@heist_corona@team_idles@male_a',
    clip = 'idle',
}

Config.TimeSettings = {
    hour = 20,
    minute = 0,
    weather = 'CLEAR',
}

Config.Dob = {
    minAge = 18,
    maxAge = 80,
}

Config.StarterItems = {
    { name = 'bread', amount = 5 },
    { name = 'water', amount = 5 },
    { name = 'phone', amount = 1 },
}

Config.NoSpawnMenuOnlyLastLocation = false
Config.NewPlayerNoApartmentStartCoords = vector4(-1045.0, -2750.0, 21.3, 326.0)
```

### Configuration Options

| Option            | Type    | Description                            |
| ----------------- | ------- | -------------------------------------- |
| `DefaultSlots`    | number  | Character slots per player             |
| `DefaultSpawn`    | vector4 | Spawn position during selection        |
| `BackgroundMusic` | table   | Music settings (enabled, volume, file) |
| `CinematicMode`   | table   | Camera/letterbox effects               |
| `Effects`         | table   | Visual effects (blur, vignette)        |
| `TimeSettings`    | table   | Time/weather during selection          |
| `StarterItems`    | table   | Items given to new characters          |
| `PerformanceMode` | boolean | Disable heavy effects                  |
| `DeleteButton`    | boolean | Allow character deletion               |

## How It Works

1. Player connects and triggers the multicharacter screen
2. Cinematic effects activate (camera, music, weather)
3. Existing characters are displayed with their appearance loaded on the ped
4. Player selects a character or creates a new one
5. On creation, the `nova_creator` is optionally called for appearance
6. Starter items are given to new characters
7. Player spawns at last location or default spawn

## Pages

The NUI supports optional link pages:

```lua
Config.Pages = {
    Credits = { enabled = true, url = '' },
    Store = { enabled = true, url = '' },
}
```

## Dependencies

* **nova\_core** — Player/character data, login/logout flow
* **oxmysql** — Database operations

## Notes

* This is the **premium** version of multicharacter, replacing `nova_multichar` (free)
* Supports HUD integration via `Config.CustomHud`
* Character appearance is loaded from the database
* The NUI features a modern dark theme with smooth transitions
* Background music loops during character selection and stops on spawn