> For the complete documentation index, see [llms.txt](https://docs.privalo.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.privalo.dev/scripts/essentials/peds-menu/config.md).

# CONFIG

#### 2.1 Ajustes base

| Clave                | Por defecto | Descripción                                      |
| -------------------- | ----------- | ------------------------------------------------ |
| `PVConfig.Framework` | `'auto'`    | `auto` \| `qbx` \| `qb` \| `esx` \| `standalone` |
| `PVConfig.Locale`    | `'es'`      | Idioma (`locales/<x>.json`)                      |
| `PVConfig.Debug`     | `false`     | Prints extra en consola                          |

#### 2.2 Comandos

| Clave           | Por defecto   | Descripción               |
| --------------- | ------------- | ------------------------- |
| `PlayerCommand` | `'peds'`      | Comando del jugador       |
| `AdminCommand`  | `'pedsadmin'` | Comando de staff          |
| `ResetCommand`  | `'resetped'`  | Restablecer ped inmediato |

#### 2.3 Permisos admin

| Clave               | Por defecto       | Descripción                                               |
| ------------------- | ----------------- | --------------------------------------------------------- |
| `AdminAce`          | `'pv_peds.admin'` | ACE del panel admin                                       |
| `AutoGrantAdminAce` | `true`            | Auto-otorga a los `AdminGroups` al iniciar                |
| `AdminGroups`       | `{ 'admin' }`     | Grupos considerados admin (`group.admin`, `group.mod`...) |

> Los admins pueden **abrir** el editor y **aplicar cualquier ped** (bypass en `PV_CanUsePed`), pero su **catálogo de `/peds`** sigue mostrando solo lo que tienen asignado. Sin doble juego: para probar un ped ajeno usan el editor.

#### 2.4 Comportamiento

| Clave                    | Por defecto | Descripción                                                             |
| ------------------------ | ----------- | ----------------------------------------------------------------------- |
| `PersistBetweenSessions` | `true`      | Restaura el último ped usado al reconectar                              |
| `ApplyDefaultVariation`  | `true`      | Aplica componentes por defecto al cambiar skin (evita "player desnudo") |
| `PreservePlayerData`     | `true`      | Mantiene salud, armadura, arma, vehículo y posición                     |

#### 2.5 UI

| Clave        | Por defecto | Descripción                         |
| ------------ | ----------- | ----------------------------------- |
| `UI.accent`  | `#7c5cff`   | Color principal (morado)            |
| `UI.accent2` | `#22d3ee`   | Color secundario (cian)             |
| `UI.logo`    | `nil`       | URL de logo opcional en la cabecera |

#### 2.6 Categorías iniciales

Solo se importan si `pv_peds_categories` está vacía. Después el staff las gestiona desde el juego:

```lua
PVConfig.DefaultCategories = {
    { id = 'civil',     label = 'Civiles',    icon = 'user',      ord = 1 },
    { id = 'servicios', label = 'Servicios',  icon = 'briefcase', ord = 2 },
    { id = 'especial',  label = 'Especiales', icon = 'star',      ord = 3 },
    { id = 'animales',  label = 'Animales',   icon = 'paw',       ord = 4 },
    { id = 'evento',    label = 'Eventos',    icon = 'ghost',     ord = 5 },
}
```

#### 2.7 Tipos de permisos

Cada ped guarda `permission_type` + `permission_value` + `extra_citizens`.

| Tipo        | `permission_value` (ejemplo) | Quién lo puede usar                    |
| ----------- | ---------------------------- | -------------------------------------- |
| `job`       | `police,ambulance`           | Players con job en la lista (CSV)      |
| `ace`       | `pv_peds.staff`              | Players con ese ACE                    |
| `group`     | `admin,mod`                  | Players en `group.admin` o `group.mod` |
| `citizenid` | `ABC12345,XYZ99999`          | Solo esos citizen IDs concretos        |

**`extra_citizens`** (CSV independiente): permite dar acceso a jugadores concretos *además* del filtro del tipo. Ejemplo: un ped `permission_type='job'` con `permission_value='police'` y `extra_citizens='JEFE123'` → lo pueden usar todos los polis **y** ese citizen específico aunque no sea poli.

> Nota: en versiones anteriores existía `everyone`. Se removió porque provocaba abuso silencioso. Un ped sin filtro válido = nadie tiene acceso (salvo admin).

#### 2.8 Peds de ejemplo (seed)

Se insertan solo si la tabla `pv_peds_defs` está vacía:

```lua
PVConfig.SeedPeds = {
    { label = 'Traje elegante F',     model = 'a_f_y_business_02', category = 'civil',     icon = 'user' },
    { label = 'Chef',                 model = 's_m_m_chemsec_01',  category = 'servicios', icon = 'utensils' },
    { label = 'Guardia de seguridad', model = 's_m_m_security_01', category = 'servicios', icon = 'shield' },
    { label = 'Bigfoot',              model = 'ig_orleans',        category = 'especial',  icon = 'ghost' },
}
```

Después el staff crea/edita todo desde `/pedsadmin` y asigna permisos.

### 3. Uso in-game

#### 3.1 Jugador — `/peds`

| Acción                | Cómo                                                          |
| --------------------- | ------------------------------------------------------------- |
| Abrir                 | Comando `/peds`                                               |
| Filtrar por categoría | Click en el sidebar izquierdo (con contadores por categoría)  |
| Buscar                | Barra superior del sidebar (busca en label y model)           |
| Aplicar ped           | Click en la card → skin cambia al momento                     |
| Ver ped actual        | Bloque destacado abajo del sidebar                            |
| Restablecer           | Botón "Restablecer" o `/resetped` → vuelve al ped por defecto |

**El jugador solo ve los peds a los que tiene permiso.** El filtrado se hace en servidor (`catalogForMe`), así que no hay forma de "hackear" para ver lo que no le corresponde. El grid muestra:

* Avatar circular con gradiente (icono FA del ped)
* Label + modelo (`mono`) + badge de categoría
* Botón "Usar" (o ✓ si es el ped actual)

#### 3.2 Staff — `/pedsadmin`

**Sidebar**

* Categorías con contador de peds por cada una.
* Lista de peds bajo cada categoría (los inactivos se marcan).
* `+ Nuevo ped` — abre editor limpio.
* `+ Nueva categoría` — dialog NUI con id / label / icon.

**Editor por pestañas**

| Pestaña               | Contenido                                                                                                                                                |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Información**       | Label, modelo, categoría, icono FA, descripción, activo/inactivo                                                                                         |
| **Permisos**          | Selector de tipo + input de valor + ayuda contextual del formato esperado                                                                                |
| **Extra / Asignados** | Buscador de jugadores para añadirlos al CSV `extra_citizens`. Debajo, lista de quién tiene actualmente **este ped aplicado** (con estado online/offline) |

**Buscador de jugadores** (útil en varias pestañas):

* Por `source id` numérico (ej: `1`, `24`) — busca solo si está online.
* Por `citizenid` exacto (ej: `ABC12345`).
* Por `license` (LIKE parcial).
* Por **nombre IC** (busca en `charinfo.firstname`, `lastname`, o concatenación) → hasta 25 resultados con badge online/offline.

**Acciones del editor**

* **Vista previa** — cambia tu skin al modelo del draft para probarlo (sin guardar).
* **Guardar** — persiste en DB y dispara `catalogDirty` a **todos los clientes** → refresh inteligente por rol.
* **Eliminar** — pide confirmación con dialog NUI.

#### 3.3 Reset y estado

Cuando cambias de ped, se **preservan**:

* Salud (`SetEntityHealth`).
* Armadura (`SetPedArmour`).
* Arma equipada actual (`GiveWeaponToPed` con 100 balas).
* Posición y heading (o el vehículo/asiento si estabas dentro).

El nuevo `applyPed` **espera activamente** a que el ped realmente cambie (loop de hasta 20 x 50 ms = 1 s). Si el modelo es pesado o custom y tarda en cargar, ya no se pierde el `SetPedDefaultComponentVariation` posterior (bug clásico en peds custom que salían invisibles).

Si `PersistBetweenSessions` está activo, al reconectar el cliente pregunta al server "¿tenía yo un ped guardado?" y lo aplica al momento del spawn.

#### 3.4 Ver quién tiene un ped puesto

En el editor, pestaña **Asignados**, aparece la lista de citizen IDs que actualmente tienen ese ped **aplicado y guardado**. Cada fila muestra:

* Nombre IC (resuelto vía DB).
* CitizenID.
* Estado online (verde) / offline (gris).

Útil para auditar peds sensibles ("¿quién tiene el modelo del alcalde?").


---

# 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://docs.privalo.dev/scripts/essentials/peds-menu/config.md?ask=<question>&goal=<endgoal>
```

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