# 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.