Pon, retira y lee sanciones desde tus propios recursos, como un menú de administración o un panel web. La API son cinco exports de servidor; el script no expone eventos públicos.

Todos los exports funcionan con el personaje conectado (se aplica al momento) o desconectado (se guarda y se aplica al entrar). Los personajes se identifican por citizenid; en ESX es el identificador del personaje.

Valores de retorno

Los cuatro exports de escritura devuelven dos valores:

Valor	Tipo	Descripción
ok	boolean	true si el cambio se ha guardado.
detail	string	Si va bien, 'online' u 'offline'. Si falla, el motivo en el idioma del servidor, por ejemplo «Datos no válidos», «El jugador ya tiene una sanción activa», «No se encontró al jugador o la sanción» o «Error interno».

El parámetro opcional admin es una tabla { name = string, identifier = string } que se guarda con la sanción y se muestra en el panel y en los registros. Sin él, la sanción figura como puesta desde el panel.

Cada sanción puesta, retirada o cumplida mediante un export se anuncia y se registra igual que una puesta por comando.

Exports de servidor

AddCommunityService

Pone tareas comunitarias a un personaje. Si ya tiene servicios comunitarios, las tareas se suman y el motivo se añade al anterior. Se rechaza mientras el personaje esté en la cárcel.

local ok, detail = exports.cuxial_cmservices:AddCommunityService(citizenid, amount, reason, admin)

Parámetro	Tipo	Descripción
citizenid	string	Id del personaje.
amount	number	Tareas a poner, de 1 a comserv.maxApiTasks. Los decimales se redondean hacia abajo.
reason	string	Motivo. Obligatorio; se corta a admin.reasonMax caracteres.
admin	table	Opcional. Quién pone la sanción.

Devuelve: boolean, string.

local ok, detail = exports.cuxial_cmservices:AddCommunityService('ABC12345', 10, 'Conducción temeraria', {
    name = 'Panel web',
    identifier = 'web',
})
if not ok then print(detail) end

RemoveCommunityService

Retira los servicios comunitarios de un personaje. Un jugador conectado va al punto de salida, o de vuelta a la cárcel si también tiene tiempo de cárcel.

local ok, detail = exports.cuxial_cmservices:RemoveCommunityService(citizenid, admin)

Parámetro	Tipo	Descripción
citizenid	string	Id del personaje.
admin	table	Opcional. Quién la retira.

Devuelve: boolean, string. Falla con «No se encontró al jugador o la sanción» si el personaje no tiene servicios comunitarios.

AddJail

Envía a un personaje a la cárcel administrativa. Se rechaza si ya está en la cárcel. Si el personaje tiene servicios comunitarios, primero cumple la cárcel y después sigue con las comunitarias donde las dejó.

local ok, detail = exports.cuxial_cmservices:AddJail(citizenid, minutes, reason, admin)

Parámetro	Tipo	Descripción
citizenid	string	Id del personaje.
minutes	number	Minutos, de 1 a jail.maxMinutes. Los decimales se redondean hacia abajo.
reason	string	Motivo. Obligatorio; se corta a admin.reasonMax caracteres.
admin	table	Opcional. Quién pone la sanción.

Devuelve: boolean, string.

RemoveJail

Libera a un personaje de la cárcel. Un jugador conectado va al punto de salida de la cárcel, o a la zona de comunitarias si aún le quedan tareas.

local ok, detail = exports.cuxial_cmservices:RemoveJail(citizenid, admin)

Parámetro	Tipo	Descripción
citizenid	string	Id del personaje.
admin	table	Opcional. Quién la retira.

Devuelve: boolean, string. Falla con «No se encontró al jugador o la sanción» si el personaje no está en la cárcel.

GetPlayerPunishment

Devuelve las sanciones activas de un personaje.

local punishment = exports.cuxial_cmservices:GetPlayerPunishment(player, kind)

Parámetro	Tipo	Descripción
player	number | string | table	Id de servidor de un jugador conectado, un citizenid, o una tabla de jugador con citizenid (o PlayerData.citizenid).
kind	string	Opcional. 'comserv' o 'jail'.

Devuelve:

kind	Devuelve
'comserv' o 'jail'	La sanción de ese tipo, o false.
sin indicar	{ comserv = sanción?, jail = sanción? }, o false si no tiene ninguna.

Una sanción es una tabla con estos campos:

Campo	Tipo	Descripción
done	number	Tareas hechas o minutos cumplidos.
total	number	Tareas puestas o minutos totales.
reason	string	Motivo.
start	number	Hora Unix en que se puso la sanción.
admin	table	Quién la puso: name e identifier.

local jail = exports.cuxial_cmservices:GetPlayerPunishment(source, 'jail')
if jail then
    print(('Quedan %d minutos'):format(jail.total - jail.done))
end