# Multicharacter

### v1.0.2 — Major Rewrite (04/07/2026)

> This release is a near-complete overhaul of the resource. Configuration, architecture, UI, and internals have all been reworked. **Read the migration notes before updating.**

***

#### New Features

**Framework & Setup**

* **Automatic framework detection** — Set `Config.Framework = "auto"` and the resource detects ESX, QBox, QBCore, or Standalone at runtime. No more manual switching.
* **QBox (`qbx_core`) support** — Full native support added alongside ESX and QBCore.
* **Standalone mode** — The resource can now run without any framework.
* **ESX character identifier prefix** — New `Config.Prefix` option (e.g. `char1`, `char2`) for ESX-based servers.

**Configuration & Presets**

* **`config_presets.lua`** — New dedicated presets file. Choose from multiple built-in ped position sets (`preset_fixedPos_1`, `preset_fixedPos_2`, `preset_fixedPos_3`) or use `preset_lastPosition` to spawn characters at their last saved coordinates.
* **Last Position preset** — Characters can now be showcased at their real in-world last position during selection.
* **Spawn Point images** — Each spawn location now supports an `image` URL shown in the spawn selector UI.
* **`Config.NewCharacter`** — Fully configurable character creation scene: set player animation, officer NPC model/animation/prop, and camera independently.
* **Instant relog** — `Config.Relog.instant = true` skips the relog wait screen entirely.
* **Upload system** — `Config.Upload` lets you route mugshot uploads to a Discord webhook or FiveManage.
* **Particle effect on slot select** (Beta) — `Config.ParticleOnSelect` plays a configurable particle effect when selecting a character slot.

**Character Selection & Spawn**

* **"Last Known Location" spawn option** — Players can spawn back at their last position, with street name displayed in the UI.
* **Character avatars via native headshots** — Avatar images are now generated with `RegisterPedheadshot` directly — no external resource required.
* **Character disable / enable** — Admins can now disable specific character slots per player without deleting them. Disabled characters are visually marked in the UI.
* **Street name auto-detection** — Last known location resolves to a readable street name pulled from game data.

**Admin Panel**

* **Live theme switching via state bags** — Theme changes from the admin panel apply instantly to all clients without a reload.
* **Overhauled permission system** — `Config.AdminPanel.permission` now uses a key-value table (`["admin"] = true`) instead of a group array. Finer-grained control.
* **Active slot codes visible** — Admin panel now shows all currently active redeemable slot codes.

**Camera System**

* **Full cinematic camera rewrite** — Camera is now an OOP class (`lib.class`). Supports smooth transitions, depth-of-field, cinematic relog zoom-out effect with screen effects and sound.
* **Relog camera animation** — On relog, the camera zooms out from the player's current position with layered sound effects and transition animations.
* **Per-spawn-location camera overrides** — Spawn locations optionally accept a custom `cam` block (`pos`, `rot`, `fov`) to override the default camera behavior.

**Localization**

* **New languages added** — Spanish (`es`), French (`fr`), Brazilian Portuguese (`pt-br`) added alongside the existing English and Italian.
* **Full locale key overhaul** — All strings reorganized under a namespaced `ui.*` structure for better maintainability.

**Sound & UI**

* **New sound effect** — `element_hover.mp3` added for hover interactions.
* **Redesigned character creation UI** — Themed as a "Federal Identification Entry" form. New placeholders, labels, watermarks, and flow.
* **Redesigned spawn selector** — Now shows region, description, image thumbnails, and "Last Known Location" with street name.
* **Welcome messages** — Distinct "Welcome!" and "Welcome back!" messages based on whether the player is new.

***

#### Improvements

* **OOP architecture** — `Login`, `Camera`, `Spotlight`, and `Framework` are all now proper `lib.class` instances. Cleaner code, better encapsulation, no global state leaks.
* **Memory management** — `collectgarbage("collect")` called on cleanup and spotlight deactivation. Character headshot handles are properly unregistered on reset.
* **Cleaner database schema** — Tables renamed to `ars_user_slots`, `ars_multi_codes`, `ars_multi_settings`. Old `multiconfig` table replaced with a simpler settings table.
* **Spawnmanager safety** — `exports.spawnmanager:setAutoSpawn(false)` is now wrapped in `pcall` to prevent crashes if spawnmanager is missing.
* **Admin panel command renamed** — From `multipanel` to `charpanel` (configurable via `Config.AdminPanel.command`).
* **Removed camera-per-slot bloat** — PosPeds no longer require `camPos`, `camRot`, `camZoom` per slot. Camera auto-calculates position from ped coords.
* **Bridge restructure** — Bridge files moved from `bridge/esx/` and `bridge/qbcore/` to `resource/bridge/` for a cleaner directory layout.
* **Locale restructure** — Moved from `shared/locales/` to `locales/translations/` with a main loader at `locales/main.lua`.

***

#### Bug Fixes

* **Typo fixed: `SpootLight` → `SpotLight`** — Config key, variable names, and all internal references corrected.
* **Typo fixed: `spawnSelelected` → `spawnSelected`** — Promise variable renamed.
* **Admin permission check hardened** — Old version had a fragile group-array check; new version uses a simple boolean lookup.
* **Spawn selector back button** — "Go Back" from spawn selector now correctly reinitializes the character selection screen.
* **Duplicate `dependency '/assetpacks'`** — Removed triple-duplicate entry from `fxmanifest.lua`.

***

#### Removed

| Removed                                                                   | Reason                                                 |
| ------------------------------------------------------------------------- | ------------------------------------------------------ |
| `MugShotBase64` dependency                                                | Replaced by native `RegisterPedheadshot`               |
| `shared/Theme.lua`                                                        | Themes managed client-side via state bags              |
| `Config.SpawnClothes`                                                     | No longer used in new character creation flow          |
| `Config.Appearance` / `Config.CustomAppearance` / `Config.SetPedClothing` | Appearance handling moved to framework bridge          |
| `Config.UseBackgroundMugshot`                                             | No longer applicable                                   |
| `Config.StartingCamPos`                                                   | Replaced by `Config.NewCharacter.cam`                  |
| `Config.PosPeds[n].camPos/camRot/camZoom`                                 | Camera auto-calculated from ped position               |
| `multiconfig` database table                                              | Replaced by `ars_multi_settings`                       |
| `shared/Config.lua` & `shared/Theme.lua` paths                            | Config now at root: `config.lua`, `config_presets.lua` |

***

#### Migration Notes

> **Do not drop-in replace the old resource.** Configuration structure has changed significantly.

1. **Rename your config** — The old `shared/Config.lua` does not map 1:1 to the new `config.lua`. Recreate your settings using the new file as a base.
2. **Database** — The new version creates new tables on startup. Old tables (`ars_multicharacter`, `multiconfig`, `ars_multicharacter-codes`) are not automatically migrated.
3. **Remove `MugShotBase64`** — It is no longer a dependency. Remove it from your server if it was only used by this resource.
4. **Update admin command** — The admin panel command changed from `multipanel` to `charpanel` (or whatever you set in `Config.AdminPanel.command`).
5. **Spawn points format changed** — The new preset format uses `id`, `region`, `desc`, `coords`, `image`. Update any custom spawn points accordingly.
6. **Locale keys changed** — If you customized translations, all keys have been reorganized. Re-apply your changes to the new `locales/translations/` files.


---

# 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://docs.arius-scripts.com/site/changelog/changelogs/multicharacter.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.