Lee las estadísticas de un jugador, concede membresías, mueve el dinero de un negocio o reacciona a un entrenamiento desde tus propios recursos.

En todos los exports, cid es el identificador de personaje que usa tu framework, y los ids de negocio y de zona son los números que muestran los editores de staff.

Exports de servidor · jugadores

GetStats

Devuelve los niveles y la XP de un jugador conectado.

local stats = exports.cuxial_gym:GetStats(source)

Devuelve: { strength = { level, xp }, agility = { level, xp } }, o nil si el jugador no está cargado.

local stats = exports.cuxial_gym:GetStats(source)
if stats and stats.strength.level >= 25 then
    -- tiene fuerza para cargar la caja
end

AddStatXp

Suma XP a una estadística de un jugador conectado.

local levels = exports.cuxial_gym:AddStatXp(source, stat, xp)

Parámetro	Tipo	Descripción
source	number	Id de servidor del jugador.
stat	string	'strength' o 'agility'.
xp	number	XP que se suma. Tiene que ser mayor que 0.

Devuelve: number. Niveles ganados; 0 si no se sumó nada.

exports.cuxial_gym:AddStatXp(source, 'agility', 150)

GetFatigue

Devuelve la fatiga actual de cada parte del cuerpo de un jugador conectado.

local fatigue = exports.cuxial_gym:GetFatigue(source)

Devuelve: table<string, number> por parte del cuerpo (chest, shoulders, back, arms, abs, thighs, calves), o nil.

GrantMembership

Da a un jugador un pase para una zona. Funciona con personajes desconectados.

local ok, reason = exports.cuxial_gym:GrantMembership(target, zoneId, days, packageId)

Parámetro	Tipo	Descripción
target	number | string	Id de servidor, o cid del personaje.
zoneId	number	Zona del pase.
days	number	Duración, de 1 a 3650.
packageId	number	Opcional. Paquete con el que queda registrado el pase.

Devuelve: boolean y, si falla, un motivo: 'not_ready', 'unknown_zone', 'invalid_days' o 'player_not_found'.

exports.cuxial_gym:GrantMembership(source, 1, 30)

RevokeMembership

Quita a un jugador el pase de una zona.

local ok, reason = exports.cuxial_gym:RevokeMembership(target, zoneId)

Devuelve: boolean y, si falla, 'not_ready', 'unknown_zone', 'player_not_found' o 'no_membership'.

GetMembership

Devuelve el pase activo de un jugador en una zona.

local pass = exports.cuxial_gym:GetMembership(target, zoneId)

Devuelve: { zoneId, businessId, packageId, expiresAt, purchasedAt, secondsLeft }, o nil si no hay pase activo. Las fechas son marcas Unix en segundos.

local pass = exports.cuxial_gym:GetMembership(source, 1)
if pass then print(('quedan %d horas'):format(pass.secondsLeft // 3600)) end

Exports de servidor · negocios

Lectura

Export	Devuelve
GetBusinessInfo(id)	{ id, name, type, logo, color, funds, level, xp, maxXp, ownerName }, o nil. type es siempre 'gym'.
GetBusiness(id)	Copia completa del negocio, tal como la muestra el panel del negocio, o nil.
GetAllBusinesses()	Tabla de copias por id de negocio.
GetBusinessesByType(kind)	La misma tabla cuando kind es 'gym'; vacía en otro caso.
GetBusinessFunds(id)	number. 0 si el negocio no existe.
GetBusinessLevel(id)	{ level, xp, maxXp }, o nil.
GetEmployees(id)	Lista de { identifier, name, avatar, grade, minutesWorked, repsHelped, pendingBonus, totalBonus }.
GetEmployeeCount(id)	number.
GetWarehouse(id)	Lista de { name, stock, enabled }.
GetWarehouseStock(id, item)	number.
GetBusinessInteractionPoints(id)	Lista de { id, scope, ownerId, mode, model, coords, rotation, radius, actions }.
GetBusinessMetadata(id)	Copia de los metadatos del negocio, o nil.

local info = exports.cuxial_gym:GetBusinessInfo(1)
if info then print(info.name, info.funds, info.level) end

Miembros

Export	Devuelve
GetPlayerBusinesses(cid)	number[]. Ids de los negocios a los que pertenece el personaje.
IsPlayerInBusiness(cid, id)	boolean.
IsPlayerOwner(cid, id)	boolean.
GetPlayerRole(cid, id)	string. Identificador del rango, o nil.
HasPermission(cid, id, permission)	boolean.

permission es uno de 'manage_company', 'manage_employees', 'manage_permissions', 'manage_warehouse', 'manage_finances', 'manage_sellers', 'pay_bonuses', 'transfer_ownership', o su posición en esa lista (de 1 a 8).

if exports.cuxial_gym:HasPermission(cid, 1, 'manage_finances') then
    -- puede tocar el dinero
end

HirePlayer

Añade un personaje a un negocio sin oferta previa.

local ok = exports.cuxial_gym:HirePlayer(id, cid, name, grade)

Parámetro	Tipo	Descripción
id	number	Id del negocio.
cid	string	Identificador del personaje.
name	string	Nombre que aparece en la lista de empleados.
grade	string	Opcional. Identificador del rango; 'employee' por defecto.

Devuelve: boolean. false si el personaje ya trabaja ahí, el rango no existe o el negocio no tiene plazas de empleado libres.

FirePlayer

local ok = exports.cuxial_gym:FirePlayer(id, cid)

Devuelve: boolean. false si el personaje no está en el negocio.

Dinero

Export	Qué hace
AddBusinessIncome(id, amount, reason, source)	Registra un ingreso. Cuenta para impuestos, XP del negocio y misiones. reason y source son opcionales.
DepositToBusiness(id, amount, source)	Añade fondos como depósito. source es opcional.
WithdrawFromBusiness(id, amount, source)	Saca fondos. Falla si no hay suficiente.

Los tres devuelven boolean. amount es un número entero mayor que 0. source, si se indica, es el jugador que queda como autor de la transacción.

Estos exports solo cambian los fondos del negocio. No dan ni quitan dinero a ningún jugador: eso hazlo en tu propio código.

if exports.cuxial_gym:AddBusinessIncome(1, 2500, 'Clase privada', source) then
    -- cobra al jugador aquí
end

Stock, XP y metadatos

Export	Qué hace
AddWarehouseStock(id, item, amount)	Añade unidades de un item al almacén.
RemoveWarehouseStock(id, item, amount)	Quita unidades. Falla si no hay suficientes.
AddBusinessXP(id, amount)	Suma XP al negocio.
SetBusinessMetadata(id, key, value)	Define una clave de los metadatos. nil la borra.

Los cuatro devuelven boolean.

SetBusinessMetadata acepta solo estas claves, con estos tipos: workArea (table), workerLevels (table), membership (table), incomeTax (number), xpRate (number), helperRepsPerMinigame (number) y callCooldownUntil (number).

Exports de cliente

Export	Devuelve	Qué hace
IsExercising()	boolean	Si el jugador local está en una serie.
IsHelping()	boolean	Si el jugador local está ayudando a alguien.
OpenGymPanel(zoneId)	boolean	Abre el panel del gimnasio de una zona. El jugador tiene que estar cerca de un punto del menú del gimnasio de esa zona.
OpenBusinessPanel(id)	boolean	Abre el panel del negocio. Sin id, abre el negocio del jugador o una lista para elegir.
CloseBusinessPanel()	boolean	Lo cierra.
IsBusinessPanelOpen()	boolean	Si el panel del negocio está abierto.
GetCurrentBusinessId()	number | nil	Id del negocio que muestra el panel abierto.
IsInBusiness(id)	boolean	Si el jugador local es personal de ese negocio.

if exports.cuxial_gym:IsExercising() then return end

UseGizmo

Deja al jugador mover y rotar una entidad con el gizmo de colocación, y espera a que confirme o cancele.

local result = exports.cuxial_gym:UseGizmo(entity, { camera = true })

Parámetro	Tipo	Descripción
entity	number	Entidad que se coloca.
opts.camera	boolean	Opcional. true usa la cámara de colocación de gizmo.

Devuelve: { position = vector3, rotation = vector3, cancelled = boolean }, o nil si la entidad no existe.

local result = exports.cuxial_gym:UseGizmo(prop)
if result and not result.cancelled then
    print(result.position, result.rotation)
end

Eventos de servidor

Se lanzan solo en el servidor. Escúchalos con AddEventHandler.

Evento	Parámetros	Cuándo
cuxial_gym:exerciseStarted	source, ctx	Un jugador empieza una serie.
cuxial_gym:exerciseFinished	source, ctx	Una serie termina, por el motivo que sea.
cuxial_gym:statLevelUp	source, data	Un jugador sube de nivel. data es { strength, agility, gained = { strength, agility } }.
cuxial_gym:stockChanged	businessId, item, stock	Cambia el stock de un item en un almacén.

Campos de ctx:

Campo	Tipo	Descripción
exerciseId	string	Ejercicio, como en data/exercises.lua.
eqId	string	Equipo.
zoneId	number | false	Zona; false en un modelo global.
zoneName	string | false	Nombre de la zona.
businessId	number | false	Negocio dueño de la zona.
bodyPart	string	Parte del cuerpo principal que se entrena.
maxReps	number	Límite de repeticiones del ejercicio; 0 es sin límite.
global	boolean	true en un prop del mapa fuera de cualquier zona.
reps	number	Repeticiones hechas. Solo al terminar.
freeReps	number	Repeticiones extra conseguidas. Solo al terminar.
levels	table	Niveles ganados: { strength, agility }. Solo al terminar.
durationMs	number	Duración de la serie. Solo al terminar.
reason	string	Por qué terminó: esc_cancel, minigame_fail, max_reps, fatigue_overload, too_far, config_stop, anim_failed, server_ended o resource_stop. Solo al terminar.

AddEventHandler('cuxial_gym:exerciseFinished', function(source, ctx)
    if ctx.reps >= 20 then
        -- premia una serie larga
    end
end)

Hooks

Dos archivos quedan abiertos para tu código: server/hooks.lua y client/hooks.lua. Rellena el cuerpo de cada función; un error dentro de un hook se captura y se muestra en la consola.

Servidor

Hook	Se llama	Retorno
hooks.onPlayerLoaded(src, cid, stats)	Se cargan los datos de gimnasio de un personaje.	Ninguno
hooks.onStatLevelUp(src, cid, stats)	El jugador sube de nivel.	Ninguno
hooks.canStartExercise(src, ctx)	Antes de empezar una serie.	false la bloquea. Un segundo valor indica la clave de idioma del mensaje que se muestra.
hooks.onExerciseStarted(src, ctx)	Empieza una serie.	Ninguno
hooks.onExerciseFinished(src, ctx)	Termina una serie.	Ninguno

stats es { strength = { level, xp }, agility = { level, xp } }. ctx es la misma tabla que en los eventos.

server/hooks.lua

function hooks.canStartExercise(src, ctx)
    -- no se entrena fuera del mundo principal
    if GetPlayerRoutingBucket(src) ~= 0 then
        return false
    end
    return true
end

Cliente

Hook	Se llama	Retorno
hooks.onExerciseRep(data)	Después de cada repetición del jugador local.	false termina la serie.

data es { exerciseId, eqId, zoneId, reps, freeReps, maxReps, bodyPart }.

State bags

Los define el servidor en cada jugador y se replican a los clientes. Son de solo lectura: un cambio hecho desde un cliente se revierte.

State bag	Valor
gymStats	{ strength, agility } con los niveles actuales.
gymExercise	{ zoneId, eqId, exerciseId, anchor, coords, businessId, helper } mientras entrena; nil si no.
gymHelping	{ owner, eqId } mientras ayuda; nil si no.

local levels = Player(source).state.gymStats

Exports de compatibilidad

Para recursos escritos contra un sistema de habilidades con Strength, Stamina y Running. Están disponibles como exports.cuxial_gym y como exports.CuxialGym.

Export	Qué hace
AddSkillToPlayer(source, skill, amount)	Suma amount puntos a una habilidad. Cada punto vale compat.xpPerPoint de XP de la estadística asignada en compat.skills. Devuelve boolean.
GetPlayerSkills(source)	Devuelve { Strength, Stamina, Running } de 0 a 100, escalado desde los niveles de las estadísticas.
MaxAllSkills	Función de item para ox_inventory: al usar el item, las dos estadísticas suben al nivel máximo.

exports.CuxialGym:AddSkillToPlayer(source, 'Strength', 2)

Un item de ejemplo que usa MaxAllSkills:

ox_inventory/data/items.lua

['gym_master_pill'] = {
    label = 'Master pill',
    weight = 10,
    consume = 1,
    server = { export = 'cuxial_gym.MaxAllSkills' },
},