# 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


---

# Agent Instructions: 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:

```
GET https://coderanch-redm-store.gitbook.io/coderanch-redm-store-docs/coderanch-cmulticharacter.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.