> For the complete documentation index, see [llms.txt](https://code-after-sex.gitbook.io/script-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://code-after-sex.gitbook.io/script-documentation/character-creator-and-select-and-apppearance/installation.md). # Installation & Integration `cas-charcreator` is a dual-framework RedM character creator and character selection system that runs on both VORP and RSGCore. It bundles the appearance, barber, and wardrobe stack on top of multicharacter selection. It auto-detects which framework is running at boot. There is no hard framework dependency in `fxmanifest.lua`, so the same folder installs on either kind of server. The only difference between a VORP and an RSG install is a handful of `server.cfg` lines. This installation and configuration guide covers prerequisites, the database tables, framework auto-detection, and the exact `server.cfg` setup for FiveM/RedM servers. > Read this whole page once before you touch `server.cfg`. The stop/ensure lines are framework-specific and the order matters. *** ## Table of contents 1. [How it works (read first)](#1-how-it-works-read-first) 2. [Prerequisites and dependencies](#2-prerequisites-and-dependencies) 3. [Drop in the resource and refresh the NUI](#3-drop-in-the-resource-and-refresh-the-nui) 4. [Database note (no .sql to import)](#4-database-note-no-sql-to-import) 5. [RSG (RSGCore) server.cfg setup](#5-rsg-rsgcore-servercfg-setup) 6. [VORP server.cfg setup](#6-vorp-servercfg-setup) 7. [Framework auto-detection (no manual flag)](#7-framework-auto-detection-no-manual-flag) 8. [First-boot verification checklist](#8-first-boot-verification-checklist) 9. [Troubleshooting (symptom, cause, fix)](#9-troubleshooting-symptom-cause-fix) *** ## 1. How it works (read first) | Fact | Detail | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | Framework | Auto-detected at runtime in `shared/framework.lua` via `GetResourceState('rsg-core')` / `GetResourceState('vorp_core')`. | | Manifest deps | None hard. A hard `vorp_core` dependency would block the resource from starting on an RSG box, so it is intentionally absent. | | NUI | A Vite/React app, prebuilt into `ui/`. The folder ships ready to run. | | Appearance engine | cas applies appearance with its own engine (`CCEngine`). It does not rely on `rsg-appearance`/`vorp_character` to render the ped. | | Character data | Still lives in the framework's existing tables (`players`/`characters`/`playerskins` etc.). cas only adds three tables of its own (see section 4). | | Spawn | On RSG, cas owns the spawn (replaces `rsg-spawn`). On VORP, spawn is handed off through `vorp_core`'s native `vorp:initCharacter`. | The post-create flow is the same on both frameworks: after you create a character you are returned to the SELECT screen (the new character now shows in the roster). Picking a character spawns it at its last saved position, or at `CCConfig.SpawnPoints[1]` for a brand-new first-time character. The spawn picker is off by default (`CCConfig.SpawnSelector = "never"`). ### What is in the download (three resources) cas-charcreator owns the ENTIRE appearance + wardrobe stack on RSG. The package ships THREE resources: * `cas-charcreator` (main): the creator/selector + appearance + barber + wardrobe stack. * `vorp_character` (VORP only): the compat shim that replaces the stock `vorp_character`. * `rsg-appearance` (RSG only): a STUB that REPLACES the stock `rsg-appearance` resource folder (same name). Its manifest declares `provide 'rsg-wardrobe'`, so it also supplies the `rsg-wardrobe` name; there is no separate `rsg-wardrobe` stub, and you DELETE the stock `rsg-wardrobe` folder. On VORP you use `cas-charcreator` + the `vorp_character` shim, and you do NOT use the RSG stub. On RSG you use `cas-charcreator` + the `rsg-appearance` stub (and you delete the stock `rsg-wardrobe` folder), and you do NOT use the `vorp_character` shim. ### Companion resources (open source, on GitHub) The main `cas-charcreator` resource is delivered escrow-encrypted with your purchase. The companion resources are open source and can be downloaded any time from GitHub, so you always have the latest: [**github.com/codeaftersex/cas-charcreator-companions**](https://github.com/codeaftersex/cas-charcreator-companions) That repository holds the `vorp_character` shim (VORP) and the `rsg-appearance` stub (RSGCore). Browse the files directly, or grab the packaged build from the [Releases](https://github.com/codeaftersex/cas-charcreator-companions/releases) tab. *** ## 2. Prerequisites and dependencies ### Common to both frameworks | Dependency | Required? | Notes | | ------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `oxmysql` | Yes | Manifest pulls `@oxmysql/lib/MySQL.lua`. Must start before cas-charcreator. | | `ox_lib` | Yes on RSG | Used for notifications on RSG (it is always present on an RSGCore stack). | | `screenshot-basic` | Optional | Used for live character mugshots, which ship disabled by default (`CCConfig.Mugshot.enabled = false`); the select screen shows a demo portrait until you enable them. If missing, mugshots are skipped (no error). | | MySQL/MariaDB | Yes | Your framework already requires this. cas auto-creates its tables (see section 4). | ### RSG (RSGCore) stack | Resource | Action | Why | | ------------------------------------------ | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `rsg-core` | keep | Detected by auto-detect; provides player data + callbacks. | | `oxmysql`, `ox_lib` | keep | See above. | | `rsg-multicharacter` | stop | cas replaces the multichar selector. | | `rsg-barbers` | stop | cas owns the barber. | | `rsg-appearance` | REPLACE with CAS stub | Replace the stock resource folder with the CAS `rsg-appearance` stub shipped in this package (same name). Do NOT stop it. See section 5. | | `rsg-wardrobe` | DELETE the stock folder | The CAS `rsg-appearance` stub declares `provide 'rsg-wardrobe'`, so it supplies this name. Delete the stock `rsg-wardrobe` folder; there is no separate stub and no `stop` line. See section 5. | | `rsg-hud`, `rsg-essentials`, `rsg-bathing` | keep | They run normally against the `rsg-appearance` stub. | ### VORP stack | Resource | Action | Why | | ------------------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `vorp_core` | keep | Detected by auto-detect; provides character API + `vorp:initCharacter`. | | `vorp_inventory` | keep | Reads clothing via the compat shim; load it after the shim. | | `vorp_character` (stock) | remove/unload | FXServer must load only the cas compat shim named `vorp_character`; keep the stock one out of any scanned or ensured folder (see section 6). | | `vorp_barbershop` | stop | cas owns the barber (or disable cas's barber; pick exactly one, see section 6). | *** ## 3. Drop in the resource and refresh the NUI The `ui/` folder ships prebuilt, so there is nothing to compile for a normal install. 1. Copy the whole `cas-charcreator` folder into your resources tree. Keep it inside a bracketed category folder, for example: ``` resources/[CAS]/cas-charcreator/ ``` 2. The NUI is already built. The manifest serves it via: ```lua ui_page 'ui/index.html' files { 'ui/index.html', 'ui/assets/*', 'ui/fonts/*', 'ui/assets/creator/*', 'ui/assets/select/*', } ``` 3. When you add or replace NUI files (for example, you dropped in a new build of `ui/`), the server must re-index the `files{}` globs. From the live console run a refresh first, then ensure: ``` refresh ensure cas-charcreator ``` > `refresh` makes the server pick up newly added files; `ensure` (re)starts the resource so they are actually served. A bare `restart` without a prior `refresh` will not register brand-new files. *** ## 4. Database note (no .sql to import) There is no `.sql` file to import. On first start cas creates its own three tables automatically (via `oxmysql`): | Table | Key columns | Purpose | | ------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `cas_mugshots` | `charidentifier VARCHAR(60)`, `image LONGTEXT` | Stores live character mugshots (only when mugshots are enabled and `screenshot-basic` is present). | | `cas_player_locale` | `identifier VARCHAR(60)`, `locale VARCHAR(8)` | Per-account language choice; persists across characters and PCs and lets the server localize notifications. | | `outfits` | per-character saved looks | Wardrobe outfits; survives script updates. | Character/appearance data itself is not stored by cas. It is written into the framework's existing tables: * RSG hybrid storage: cas writes the `playerskins` row itself. `playerskins.skin` holds the cas-format skin JSON; `playerskins.clothes` holds the RSG hash format so existing RSG clothing readers interop. (cas writes the row as `(citizenid, skin, clothes)`; there is no `license` column.) * VORP: character + skin data stays in `vorp_character`'s tables; the cas shim proxies reads/writes. Just start the server with a working DB connection and the tables appear. *** ## 5. RSG (RSGCore) server.cfg setup Add this block after your framework resources (`rsg-core`, `oxmysql`, `ox_lib`) have started. Before you boot the server, REPLACE the stock `rsg-appearance` resource folder with the CAS `rsg-appearance` stub shipped in this package (same resource name), and DELETE the stock `rsg-wardrobe` folder. The stub `ensure`s normally (it IS the resource named `rsg-appearance`) and declares `provide 'rsg-wardrobe'`, which supplies the `rsg-wardrobe` name now that the stock folder is gone: ```cfg ## --- cas-charcreator (RSGCore) --------------------------------------------- ## cas replaces the multichar selector and the barber: stop rsg-multicharacter stop rsg-barbers ## NOTE: there are NO stop lines for rsg-appearance or rsg-wardrobe. You REPLACE ## the stock rsg-appearance folder with the CAS stub (same name) and DELETE the ## stock rsg-wardrobe folder; the stub provides the rsg-wardrobe name. (see below) ## cas owns the character creator/selector + spawn + barber: ensure cas-charcreator ## -------------------------------------------------------------------------- ``` ### Why you REPLACE rsg-appearance (and DELETE rsg-wardrobe) Running the stock `rsg-appearance` alongside cas corrupts the player ped, and you cannot simply `stop` it either. Replacing the stock `rsg-appearance` folder with a same-named CAS stub, and deleting the stock `rsg-wardrobe` folder so the stub's `provide 'rsg-wardrobe'` takes effect, is the reliable fix. Why running the stock `rsg-appearance` breaks the ped: * In CitizenFX, `RegisterCommand` is a name-keyed MULTIMAP: it invokes EVERY handler registered for a command name. So on every `loadskin` (after a bath, prison release, radial menu) BOTH cas's `loadskin` and `rsg-appearance`'s `loadskin` fire. * `rsg-appearance` reads the cas-format `playerskins.skin` and applies it through its own rsg-creator-format loaders, producing a broken/garbage ped plus Lua nil-index error spam; the `rsg-appearance:client:ApplyClothes` event also double-applies. * You CANNOT make cas authoritative reliably while the stock `rsg-appearance` runs. Why you cannot just `stop` it: * `rsg-bathing` hard-depends into it: `rsg-bathing` declares `dependency rsg-appearance` and `dependency rsg-wardrobe`. Stopping `rsg-appearance` cascade-stops `rsg-bathing`, after which `rsg-hud` spams `No such export IsBathingActive in resource rsg-bathing`. * A `provide` from another resource does NOT override a real resource that is present under that name. That is exactly why `rsg-appearance` is REPLACED (a real stub keeps the name, so the dependency binds to the stub) while `rsg-wardrobe` is DELETED (with no real resource under that name, the stub's `provide 'rsg-wardrobe'` is what satisfies the dependency). Replacing the stock folders with same-named stubs is the reliable fix: the dependency resolves to the stub, there is no second appearance system, and cas's `loadskin` and `ApplyClothes` are the SOLE handlers. What the stub does: * The `rsg-appearance` stub keeps the `rsg-appearance` name present (so `rsg-bathing`'s `dependency 'rsg-appearance'` resolves and it starts) and answers the read-only exports `rsg-hud` (`IsCothingActive`) and `rsg-essentials` (`GetClothesCurrentComponentHash`, `GetBodyCurrentComponentHash`) call, returning safe values (`false`/`0`). It has NO appearance logic. * The same stub declares `provide 'rsg-wardrobe'`, which supplies the `rsg-wardrobe` name for `rsg-bathing`'s `dependency 'rsg-wardrobe'`. There is no separate `rsg-wardrobe` resource; cas owns the wardrobe, so nothing calls the wardrobe exports. * Keep `rsg-bathing`, `rsg-hud` and `rsg-essentials` running; they work against the stub. > Known cosmetic limitation: with the `rsg-appearance` stub, toggling a bandana off via `rsg-essentials` will not restore the previous neckwear or a male's beard (the stub returns `0`). Cosmetic only; no error. ### What cas owns on RSG * Spawn: cas replaces `rsg-spawn` and fires `RSGCore:Server:OnPlayerLoaded` and `RSGCore:Client:OnPlayerLoaded` itself (in `bridge/cl_rsg.lua`). Those set `isLoggedIn` and boot the HUD / inventory / jobs. (This is why you must not also run `rsg-spawn`.) * Money: forced to cash via `CCConfig.RsgMoney = { [0] = "cash", [1] = "cash", [2] = "cash" }` (VORP's 3 currencies are mapped onto RSG cash). * Slots: per-account character slots come from `CCConfig.RsgMaxCharacters` (default `5`). *** ## 6. VORP server.cfg setup VORP needs no framework-swap stop lines: there is no `rsg-multicharacter` equivalent to stop. Instead, the stock `vorp_character` is replaced by a compat shim. ### 6a. Use a single active `vorp_character` (the cas compat shim) FXServer must load exactly one resource named `vorp_character`, and that one must be the cas compat shim. This shim is included in the download as the `vorp_character` folder (alongside `cas-charcreator`); you do not build it yourself. The principle: FXServer only loads resources that live under a bracketed category folder it scans (for example `resources/[CAS]/`) or that you explicitly `ensure`. Place the cas compat shim where the server will load it, for example: ``` resources/[CAS]/vorp_character/ <-- the ACTIVE cas compat shim ``` The original stock `vorp_character` must NOT be loaded by FXServer. Either delete it, or keep it out of any folder the server scans or ensures. A non-bracketed folder is not auto-scanned, and you must not `ensure` it by name. If both the stock resource and the shim are named `vorp_character` and both are visible to the server, you get a duplicate-resource conflict. The active `vorp_character` (the cas compat shim) proxies `GetPlayerComponent` / `GetAllPlayerComponents` / `GetPlayerSkin` / `OpenOutfitsMenu` to cas-charcreator. It depends on cas-charcreator, so it must be ensured after it. ### 6b. server.cfg block ```cfg ## --- cas-charcreator (VORP) ------------------------------------------------ ## Load order MUST be: vorp_core -> cas-charcreator -> vorp_character(shim) -> vorp_inventory ensure vorp_core ensure cas-charcreator ensure vorp_character ## the [CAS] compat shim (depends on cas-charcreator) ensure vorp_inventory ## cas owns the barber: stop VORP's stock one to avoid double blips/prompts/UI: stop vorp_barbershop ## -------------------------------------------------------------------------- ``` > Barber: pick exactly ONE. Either `stop vorp_barbershop` (recommended, cas owns the barber) or set `CCConfig.Shops.barber.enabled = false` (let VORP's barbershop own it). Running both gives double blips, double prompts and double UI at the same chairs. ### Notes for VORP * Spawn handoff uses `vorp_core`'s native `vorp:initCharacter` (which sets `IsInSession`). The RSG `OnPlayerLoaded` loop bug does not occur on VORP. * CASCADE WARNING: the shim depends on `cas-charcreator`, so never hot-stop `cas-charcreator` alone on a live VORP server, because that kills the shim, which breaks `vorp_inventory` clothing. Restart the whole chain in order instead (`vorp_core` -> `cas-charcreator` -> `vorp_character` -> `vorp_inventory`). *** ## 7. Framework auto-detection (no manual flag) There is nothing to set. Do not look for a "framework = vorp/rsg" config option; it does not exist. * `shared/framework.lua` loads first (it is the first `shared_script`) and decides the framework by `GetResourceState('rsg-core')` / `GetResourceState('vorp_core')`. * Every bridge adapter ships for both frameworks and no-ops unless its framework is active: * client: `bridge/cl_vorp.lua`, `bridge/cl_rsg.lua`, `bridge/shims_rsg.lua` * server: `bridge/sv_vorp.lua`, `bridge/sv_rsg.lua` * The `CCConfig.Rsg*` options in `config.lua` (`RsgMoney`, `RsgMaxCharacters`, and so on) only apply on RSG and are simply ignored on VORP. Just make sure the matching core (`rsg-core` or `vorp_core`) is started before `cas-charcreator` so auto-detect sees it. *** ## 8. First-boot verification checklist Start the server, connect, and watch the server console plus the F8 client console. ### Both frameworks * [ ] `cas-charcreator` starts with no manifest/Lua errors in the server console. * [ ] On first DB connect, tables `cas_mugshots`, `cas_player_locale`, and `outfits` exist (check your DB). No `.sql` import was needed. * [ ] The character SELECT screen renders (cinematic backdrop scene loads). * [ ] Creating a character returns you to the SELECT screen with the new character in the roster. * [ ] Picking a character spawns it (last saved position, or `CCConfig.SpawnPoints[1]` for a brand-new one). * [ ] Barber / clothing / wardrobe prompts appear once at their markers (not doubled). ### RSG only * [ ] `rsg-multicharacter` and `rsg-barbers` are stopped. * [ ] The stock `rsg-appearance` folder was REPLACED by the CAS stub (same name) and the stock `rsg-wardrobe` folder was DELETED; the stub starts normally (no `stop` line for it). * [ ] No `No such export IsBathingActive` spam from `rsg-hud` (that means `rsg-bathing` resolved both hard dependencies, `rsg-appearance` to the stub and `rsg-wardrobe` to the stub's `provide`, and is still alive). * [ ] After spawn the player is fully logged in: HUD/inventory/jobs boot and the session does not bounce back to char-select after about 1 to 2 seconds (confirms cas fired `OnPlayerLoaded`, so `isLoggedIn = true`). * [ ] Money shows as cash. * [ ] A newly created character has its appearance (preview ped is not the default model), which confirms the `playerskins` row was written. * [ ] Deleting a character works (no "You Have Been Kicked For Exploitation"). * [ ] Character age is correct (derived from `charinfo.birthdate`, not `0`). ### VORP only * [ ] Load order in console matches: `vorp_core` -> `cas-charcreator` -> `vorp_character` (shim) -> `vorp_inventory`. * [ ] The original stock `vorp_character` is not listed as started (it is deleted or kept outside any scanned or ensured folder). * [ ] `vorp_barbershop` is stopped (or `CCConfig.Shops.barber.enabled = false`; exactly one). * [ ] `vorp_inventory` clothing reflects the character's worn items (confirms the shim is proxying correctly). * [ ] Spawn completes via `vorp:initCharacter` with no char-select bounce. *** ## 9. Troubleshooting (symptom, cause, fix) | Symptom | Cause | Fix | | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | RSG: select screen black, ped never renders; F8 shows `fade guard kicked in (select)` | Unbounded `repeat-until` loops in `CCEngine.IsPedReadyToRender`/`LoadModel` + no pre-stream on RSG entry. | Fixed in code (bounded loops + `cl_rsg` pre-streams). Ensure you are on the current build. | | RSG: pick char, spawn, about 1 to 2 seconds, black, thrown back to char-select, repeating | cas did not fire `OnPlayerLoaded`, so `isLoggedIn` stayed `false` and the session watchdog looped. | Fixed: cas now fires `RSGCore:Server/Client:OnPlayerLoaded`. Keep `cas-charcreator` after `rsg-core`. | | RSG: `You Have Been Kicked For Exploitation` on character delete | Server coerced the citizenid with `tonumber()` (RSG ids are strings), producing `DeleteCharacter(nil)` and a license mismatch. | Fixed in server code (no more `tonumber` on RSG ids). | | RSG: character age shows `0` | RSGCore drops the custom `charinfo.age` field. | Fixed: age derived from `charinfo.birthdate`. | | RSG: new character has no appearance / preview ped is default | `playerskins` INSERT referenced a non-existent `license` column and failed silently under `pcall`. | Fixed: INSERT is now `(citizenid, skin, clothes)`. | | RSG: ped looks broken/garbage after a bath, prison release or radial menu; Lua nil-index spam | The stock `rsg-appearance` still ran alongside cas; `RegisterCommand` is a multimap, so its `loadskin` fired too and double-applied the cas-format skin through its own loaders. | Replace the stock `rsg-appearance` folder with the CAS stub so cas's `loadskin` and `ApplyClothes` are the SOLE handlers. See section 5. | | RSG: `rsg-hud` spams `No such export IsBathingActive in resource rsg-bathing` | You `stop`ped `rsg-appearance`, so RedM cascade-stopped its hard dependent `rsg-bathing`. | Do not stop it: replace the stock `rsg-appearance` folder with the CAS stub instead, so `rsg-bathing`'s dependency binds to the stub (a `provide` cannot keep a present, stopped `rsg-appearance` alive). The stub also provides the `rsg-wardrobe` name, so delete the stock `rsg-wardrobe` folder. See section 5. | | Either: double barber, two blips / two prompts / two UIs at the same chair | The framework's stock barber (`rsg-barbers` / `vorp_barbershop`) was left enabled alongside cas's. | Stop the stock barber (`stop rsg-barbers` / `stop vorp_barbershop`), or disable cas's via `CCConfig.Shops.barber.enabled = false`; exactly one. | | VORP: `vorp_inventory` clothing breaks after a restart | You hot-stopped `cas-charcreator` alone; the `vorp_character` shim depends on it and died with it. | Never hot-stop cas alone. Restart the chain in order: `vorp_core` -> `cas-charcreator` -> `vorp_character` -> `vorp_inventory`. | | New `ui/` files 404 / old UI keeps showing | Server did not re-index the `files{}` globs. | Run `refresh` then `ensure cas-charcreator`. See section 3. | *** ### Quick reference: config knobs you may touch | `config.lua` key | Default | Meaning | | ------------------------------- | ------------------------------------ | ----------------------------------------------------------------------- | | `CCConfig.DefaultLanguage` | `"en"` | Default/fallback locale (`en, es, de, fr, it, pt, pt-BR, ro`). | | `CCConfig.ForceLanguage` | `nil` | Set a code to force one language server-wide and skip the picker. | | `CCConfig.RsgMoney` | `{[0]="cash",[1]="cash",[2]="cash"}` | RSG-only: maps VORP currency indices to RSG money types. | | `CCConfig.RsgMaxCharacters` | `5` | RSG-only: character slots per account (VORP reads `vorp_core`). | | `CCConfig.Shops.barber.enabled` | `true` | Set `false` to let the framework's stock barber own the barber instead. | > Leave `CCConfig.DevMode = false` in production, because it registers unrestricted player commands. *** ## More resources and support * [Buy CAS Character Creator (escrow)](https://codeaftersex.com/script/character-creator?v=escrow) * [Preview video (YouTube)](https://youtu.be/U8ZZdky3a0I) * [Open-source companions (GitHub)](https://github.com/codeaftersex/cas-charcreator-companions) * [Support Discord](https://discord.gg/codeaftersex) * [All CodeAfterSex scripts](https://www.codeaftersex.com) *** *Part of the* [*CodeAfterSex*](https://codeaftersex.com/) *RedM and FiveM script catalogue. Buy CAS Character Creator:* [*purchase with escrow on CodeAfterSex*](https://codeaftersex.com/script/character-creator?v=escrow)*.* --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://code-after-sex.gitbook.io/script-documentation/character-creator-and-select-and-apppearance/installation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.