# CodeRanch - cMulticharacter

## Requirements

* **VORP Core** framework
* **cBase** resource (language system)
* **weathersync** resource
* **oxmysql**

## Installation

1. Place `cMulticharacter` in your resources folder
2. Ensure `cBase` starts before this resource
3. Add `ensure cMulticharacter` to your server.cfg
4. Restart the server (first launch requires full restart, not script restart)

## Configuration (config.lua)

### General

| Setting                             | Default | Description                                            |
| ----------------------------------- | ------: | ------------------------------------------------------ |
| `Config.DevMode`                    | `false` | Enable to allow script restart without server restart  |
| `Config.MinAge`                     |    `18` | Minimum age for character creation                     |
| `Config.ServerYear`                 |  `1899` | Game year, used to calculate age from birth year       |
| `Config.EnableMusic`                |  `true` | Enable/disable background music on character selection |
| `Config.ReloadCharCommand`          |  `"rc"` | Command to reload character appearance                 |
| `Config.AllowPlayerDeleteCharacter` |  `true` | Allow players to delete their characters               |

### Background Music

* Set `Config.EnableMusic = true` to enable
* Place your audio file as `music.mp3` in the resource root folder
* The file name **must** be `music.mp3`
* Players can mute music from the settings menu (saved to localStorage)
* Recommended: keep the file size small for faster loading

### Clothing Command Animation

```lua
Config.clothingCommandAnimation = {
    dict = "mech_inventory@apply_lotion",
    anim = "both_hands",
    duration = 3000,
}
```

This animation plays when using clothing toggle commands (/hat, /shirt, /coat, /undress, /dress etc).

### Creator Spawn

```lua
Config.creator_spawn = {
    ped = vector4(x, y, z, heading),
    camera = { x, y, z, rotx, roty, rotz, fov },
}
```

Where the character creator ped spawns and where the camera looks.

### Spawn Selector

```lua
Config.SpawnSelectorCamera = {
    zPlus1 = 50.0,        -- first camera height
    zPlus2 = 30.0,        -- final camera height
    cam1Time = 2000,       -- first transition (ms)
    cam2Time = 1500,       -- second transition (ms)
    fov = 110.0,           -- field of view
    shakeType = "HAND_SHAKE",
    shakeAmplitude = 0.12, -- 0.0 = no shake, 1.0 = max
}
```

### Spawn Locations

```lua
Config.SpawnLocations = {
    {
        name = "Saint Denis",
        description = "Description text here.",
        highlights = { "Saint Denis", "words to highlight in orange" },
        image = "saintdenis",          -- must match an image import in SpawnSelector.vue
        position = vector3(x, y, z),
        heading = 90.0,
    },
}
```

### Clothing Commands

```lua
Config.commands = {
    Hat = { command = "hat" },
    Shirt = { command = "shirt" },
    -- etc.
}
```

Each entry registers a toggle command (e.g. `/hat` to put on/take off hat).

## Localization (shared/locales.lua)

Language is automatically detected from cBase (`Config.LangPreference` in cBase config).

Supported languages: `en`, `tr`, `ar`, `fr`, `it`, `es`

Each locale has two sections:

* **Root keys** - Backend strings (prompts, spinner text, menu labels)
* **`ui` subtable** - NUI/Vue strings (buttons, labels, popups)

To add a new language, copy `Locales['en']` and translate all values.

## Shop System (config\_shops.lua)

### Shop Types

Each shop location can have multiple shop types:

* `CLOTHING` - Clothing items with tints/palettes
* `HAIR` - Hair, beard, eyebrows
* `MAKEUP` - Lipstick, blush, eyeliner, shadow, foundation

### Prices

```lua
ConfigShops.Prices = {
    clothing = { Hat = { price = 10 }, ... },
    hair = { Hair = { price = 10 }, ... },
    makeup = { lipsticks = { price = 10 }, ... },
}
```

Extra pricing for specific items:

```lua
CoatClosed = {
    price = 10,
    extra = {
        { comp = 33333333, price = 20, currency = 0 }
    }
}
```

## Database

The script automatically adds a `nationality` column to the `characters` table on first start.

Outfits are stored in the `outfits` table (created by VORP Core).

## UI Controls

| Key   | Action           |
| ----- | ---------------- |
| W / S | Camera up/down   |
| A / D | Rotate character |

### Settings (Character Selection)

* **Streamer Mode** - Hides character info (saved to localStorage)
* **Time** - Change time of day (weathersync)
* **Weather** - Change weather (weathersync)
* **Mute Music** - Toggle background music (saved to localStorage)
* **Filter Mode** - Cinematic bars + photo filters
* **Filter Type** - Cycle through photo mode filters

## Credits

Built with VORP Framework