# Arm Wrestling: documentación

> Pulsos contra cualquier jugador en una mesa o un barril, con resistencia, apuestas, ranking y torneos.

- URL: https://xexstudio.com/es/docs/arm-wrestling
- Versión: 1.0.0
- Ficha del producto: https://xexstudio.com/es/scripts/arm-wrestling
Pulsos para FiveM. Dos jugadores se encuentran en una mesa o un barril, uno desafía al otro y empujan con las
animaciones de pulsos del propio juego. La resistencia convierte el pulso en un duelo de ritmo y no de machacar la
tecla, los jugadores pueden apostar dinero del juego y cada pulso clasificatorio mueve una puntuación que alimenta un
ranking del servidor. ESX, QBCore y Qbox.

El servidor dirige el pulso: cuenta y limita los empujes, aplica la resistencia, mueve el brazo, decide el ganador,
paga la apuesta y guarda el resultado. Un cliente modificado no puede ganar un pulso que no ha jugado.

Creado por [XeX](https://xexstudio.com). Las capturas y el resto de scripts de XeX están en
[xexstudio.com](https://xexstudio.com/scripts).

## Características

- **Mesas en cualquier sitio:** props que ya existen en el mapa (por defecto la mesa de pulsos y los barriles de
  madera) con ox_target o qb-target, además de mesas que colocas en la configuración con un blip en el mapa. Sin
  recurso de target, `[E]` en las mesas colocadas.
- **Desafiar y aceptar:** elige a un jugador que esté en la mesa, indica una apuesta o juega un pulso amistoso, y el
  rival acepta o rechaza.
- **Resistencia:** cada empuje gasta resistencia y los empujes con cansancio son más débiles. Un ritmo constante
  mantiene toda la fuerza; una ráfaga gana terreno unos segundos y te deja débil. Las dos barras de resistencia están
  en pantalla, así que puedes atacar cuando el rival está cansado.
- **Apuestas con dinero del juego:** las dos cantidades se cobran al aceptar el desafío y el ganador se lleva el
  bote. Los empates y los pulsos cancelados se reembolsan. Rendirse, alejarse o desconectarse durante un pulso lo
  pierde.
- **Ranking por puntuación con divisiones:** cada jugador tiene una puntuación y una división (bronce, plata, oro,
  diamante), y el número uno es el campeón. Ganar a un jugador más fuerte da más puntos que ganar a uno más débil, y
  la tarjeta de resultado celebra un ascenso. El ranking muestra puntuación, victorias y derrotas, mejor racha de
  victorias y victoria más rápida.
- **Temporadas mensuales y salón de la fama:** el primer día de cada mes los 3 primeros pasan al salón de la fama y
  empieza una temporada nueva. La mejor racha y la victoria más rápida se conservan como récords históricos.
- **Ranking en la pared:** el top 5 de la temporada y el último campeón pintados en una pared junto a la mesa (sin
  props).
- **Espectadores:** los jugadores alrededor de la mesa ven el pulso en directo: los dos nombres, el brazo, las barras
  de resistencia y el bote.
- **Torneos:** eliminación directa en una mesa para 4, 8 o 16 jugadores, con cabezas de serie según la puntuación,
  pases directos, una cuota de inscripción que forma el bote, cuadro en directo, combates convocados por el servidor y
  victorias por incomparecencia para quien no se presenta. Los ganadores pasan al salón de la fama.
- **HUD del pulso y tarjeta de resultado:** posición del brazo, tiempo restante, las dos barras de resistencia, bote y
  el cambio de puntuación al terminar.
- **Hooks y eventos** para habilidades, pases de batalla, analíticas o permisos, sin editar el recurso.
- **Optimizado:** sin hilos mientras nadie juega y una escritura en la base de datos por pulso clasificatorio. Las
  mesas colocadas solo existen mientras un jugador está cerca.
- Inglés y español.

## Requisitos

- [ox_lib](https://github.com/overextended/ox_lib) y [oxmysql](https://github.com/overextended/oxmysql)
- Un framework: **ESX**, **QBCore** o **Qbox**
- OneSync (activado por defecto en los servidores actuales)
- Opcional: ox_target o qb-target (necesario para usar props que ya están en el mapa)

## Instalación

1. Pon `xex_armwrestling` en tu carpeta de recursos.
2. Añádelo a `server.cfg` después de tu framework, ox_lib y oxmysql:
   ```cfg
   ensure xex_armwrestling
   ```
3. Configura el idioma con `setr ox:locale en` (o `es`).

La tabla `xex_armwrestling` se crea al arrancar. Si tu usuario de base de datos no puede crear tablas, ejecuta
`install/armwrestling.sql`.

## Cómo funciona

1. **En la mesa** un jugador elige "Arm wrestle" y escoge a uno de los jugadores que están junto a ella.
2. **Apuesta.** El retador indica una cantidad (0 para un pulso amistoso). El rival la ve y acepta o rechaza.
3. **Se cobran las dos cantidades**, los dos jugadores se colocan en la mesa y empieza una cuenta atrás.
4. **Empuje.** Pulsa la tecla de empujar. El brazo se mueve hacia quien empuja con más fuerza; el pulso termina cuando
   llega a un lado, o a los 45 segundos a favor de quien vaya por delante.
5. **Resultado.** El ganador se lleva el bote y un pulso clasificatorio actualiza las dos puntuaciones.

Mantén pulsada la tecla de rendirse durante un segundo para abandonar. Durante la cuenta atrás cancela el pulso y
reembolsa las apuestas; una vez empezado cuenta como derrota. Si un jugador cae derribado, el pulso se cancela y los
dos recuperan su dinero.

### Resistencia

Con los valores por defecto, un jugador mantiene toda la fuerza a unos 5 o 6 empujes por segundo. Más rápido que eso
vacía la barra en tres o cuatro segundos, y los empujes con la barra vacía valen un 30 %. Machacar la tecla lo más
rápido posible pierde, por tanto, contra un jugador constante a lo largo de un pulso completo; la habilidad está en
cuándo gastar la ráfaga.

### Ranking

Las puntuaciones empiezan en 1000 y funcionan como las del ajedrez: los puntos que gana un jugador son los que pierde
el otro, y la cantidad depende de la diferencia entre ambos (16 entre iguales, hasta 32). Para mantenerlo limpio:

- los pulsos de menos de `Config.Ranking.minDuration` segundos no puntúan;
- los mismos dos jugadores solo tienen `Config.Ranking.pairLimit` pulsos clasificatorios por hora (se pueden jugar
  más, sin puntuar);
- un jugador aparece en el ranking tras `Config.Ranking.minMatches` pulsos.

El HUD muestra si el pulso es clasificatorio antes de empezar.

## Configuración

| Archivo | Qué contiene |
| --- | --- |
| `config.lua` | Todos los ajustes (tabla de abajo) |
| `locales/<locale>.json` | Todos los textos: notificaciones, menús, HUD y ranking |
| `bridge/server.lua` | Framework, dinero, nombres de personaje, comprobación de derribo |
| `bridge/client.lua` | Notificaciones, recurso de target, comprobación de derribo |

| Ajuste | Qué hace |
| --- | --- |
| `Config.Framework` | `auto`, o fuerza `esx` / `qb` / `qbox` |
| `Config.Target` | `auto`, `ox_target`, `qb-target` o `none` (`[E]` en las mesas colocadas) |
| `Config.Controls` | Teclas de empujar y rendirse con la etiqueta que se muestra en el HUD |
| `Config.Models` | Props que pueden usar los jugadores, si cuentan todos los del mapa y cómo se colocan los jugadores |
| `Config.Tables` | Mesas colocadas por el script: posición, modelo, blip y un panel de ranking opcional en una pared |
| `Config.Match` | Distancias, tiempo de invitación, cuenta atrás, duración del pulso, tamaño del empuje, punto de victoria y límite de empujes |
| `Config.Stamina` | Activada o no, coste por empuje, recuperación por segundo y fuerza sin resistencia |
| `Config.Bets` | Activadas o no, cuenta y apuesta máxima |
| `Config.Ranking` | Activado o no, tamaño, puntuación inicial, puntos por pulso, las reglas anteriores, divisiones y temporadas |
| `Config.Spectators` | Activados o no y a qué distancia deben estar los jugadores para ver un pulso |
| `Config.Tournaments` | Activados o no, quién puede organizar, tamaños, tiempo de inscripción, límite de entradas, comisión del bote, tiempo de convocatoria y distancias |
| `Config.WallBoard` | Distancia a la que se dibujan los paneles de ranking en la pared y cada cuánto se refrescan |
| `Config.UI` | Nombre de marca y color de acento |
| `Config.Admin` | Ace y nombre del comando de reinicio |
| `Config.Hooks` | Funciones a las que llama el servidor (ver Para desarrolladores) |

### Props y mesas

```lua
Config.Models = {
    prop_arm_wrestle_01 = { world = true, aligned = true, axis = 0.0, offset = vec3(0.0, 0.0, 0.0) },
    prop_wooden_barrel = { world = true, aligned = false, offset = vec3(0.0, 0.0, 0.0) },
}

Config.Tables = {
    { coords = vec4(-1226.8, -1557.87, 3.19, 303.77), model = 'prop_arm_wrestle_01', blip = true },
}
```

- `world = true` permite a los jugadores usar todos los props de ese modelo del mapa. Ponlo en `false` para permitir
  solo las mesas que colocas tú.
- `aligned = true` es para props con dos lados: los jugadores se colocan a lo largo del eje del propio prop. Si acaban
  enfrentados a través de la mesa en lugar de a lo largo, pon `axis = 90.0`.
- `offset` mueve el centro de la escena si las manos no se encuentran sobre el prop (x a la derecha del retador, y
  hacia el rival, z hacia arriba).

Para añadir cualquier otro prop (una mesa de bar, una caja), indica su modelo y ajusta `offset` en el juego.

### Panel de ranking en la pared

Cada mesa de `Config.Tables` puede mostrar el ranking de la temporada en una pared cercana. Colócate delante de la
pared, mírala y ejecuta `/armwrestlingboard`: la línea se imprime en F8 y se copia al portapapeles. Pégala en la mesa:

```lua
Config.Tables = {
    { coords = vec4(-1226.8, -1557.87, 3.19, 303.77), model = 'prop_arm_wrestle_01', blip = true,
      board = { coords = vec4(-1205.10, -1559.80, 6.20, 215.0), width = 1.6 } },
}
```

### Torneos

1. **Organizar:** en la mesa, elige "Tournament" y rellena un nombre, el tamaño (4, 8 o 16) y la cuota de inscripción
   (0 para uno gratuito). Por defecto solo organizan los administradores; pon `Config.Tournaments.host = 'everyone'`
   para que pueda hacerlo cualquier jugador.
2. **Inscripción:** los jugadores alrededor de la mesa reciben el aviso y se inscriben desde la misma opción,
   pagando la cuota. Pueden salirse y recuperarla hasta que acabe la inscripción.
3. **Cuadro:** cuando el torneo se llena o termina el tiempo de inscripción (con al menos `minPlayers`), los
   jugadores se ordenan por puntuación. Los mejores cabezas de serie pasan directos cuando el número de plazas no es
   una potencia de dos.
4. **Combates:** el servidor convoca cada combate. Los dos jugadores tienen `callSeconds` para acudir a la mesa; quien
   no está pierde por incomparecencia. Un empate o un pulso cancelado se vuelve a jugar. Los desafíos normales esperan
   mientras tanto.
5. **Campeón:** el ganador se lleva el bote (menos `cut`) y queda guardado en el salón de la fama.

Cualquiera puede abrir el cuadro en directo desde la mesa. Un jugador que se desconecta durante la inscripción sale
del torneo y su cuota se queda en el bote.

### Temporadas y divisiones

Las temporadas siguen el mes natural. Cuando acaba un mes, los `Config.Ranking.hallSize` mejores jugadores de la
temporada se guardan en el salón de la fama y todas las puntuaciones, victorias y derrotas vuelven a empezar; la
pantalla del ranking tiene una pestaña con las últimas `hallSeasons` temporadas. Pon `Config.Ranking.seasons = false`
para un ranking sin fin. Las divisiones son umbrales de puntuación en `Config.Ranking.divisions` (nombre, puntuación
mínima y color); añádelas, quítalas o renómbralas con libertad.

### Comandos de administración

`/armwrestlingreset` borra todo el ranking y `/armwrestlingboard` imprime las coordenadas de un panel de ranking en la
pared. Los dos están restringidos a `group.admin`; cámbialo en `Config.Admin.ace`.

## Para desarrolladores

```lua
exports.xex_armwrestling:IsWrestling(source)   -- server
exports.xex_armwrestling:GetStats(identifier)  -- server: { rating, wins, losses, streak, best_streak, fastest, rank, needed }
```

| Evento (servidor, local) | Argumentos |
| --- | --- |
| `xex_armwrestling:matchFinished` | `data` = `{ winner, loser, players, reason, duration, bet, ranked }` |
| `xex_armwrestling:tournamentFinished` | `data` = `{ id, name, winner, runnerUp, players, pot, prize }` |

`winner` y `loser` son ids de servidor (`nil` en un empate), `reason` es `pin`, `time` o `forfeit` y `duration` está
en milisegundos.

```lua
AddEventHandler('xex_armwrestling:matchFinished', function(data)
    -- battle pass progress, logs, analytics...
end)
```

`Config.Hooks` hace lo mismo desde la configuración, además de una comprobación de permisos y un multiplicador de
fuerza:

```lua
Config.Hooks = {
    canPlay = function(source)
        return true -- false = this player can't arm wrestle right now
    end,
    power = function(source)
        return 1.0 -- multiplier of every push, clamped between 0.5 and 1.5 (e.g. a gym skill)
    end,
    onMatchFinished = function(data) end,
    onTournamentFinished = function(data) end, -- same data as the tournamentFinished event
}
```

Mantén el código específico de tu servidor en tu propio recurso y escucha el evento: así las actualizaciones de
xex_armwrestling nunca lo sobrescriben.

## Seguridad

Los jugadores solo piden desafiar a alguien, responden a un desafío e indican cuántas veces han pulsado. El servidor:

- acepta solo props incluidos en `Config.Models` y, para los modelos que no se pueden usar en todas partes, solo en
  una mesa de `Config.Tables`; los dos jugadores deben estar de verdad en la mesa y la mesa debe estar libre;
- cobra las dos cantidades antes de empezar el pulso, o ninguna, y las paga o reembolsa exactamente una vez;
- acepta como máximo `Config.Match.maxPressRate` empujes por segundo de cada jugador, envíe lo que envíe el cliente;
- aplica por sí mismo la resistencia y la fuerza, mueve el brazo y decide el ganador y el tiempo;
- termina el pulso si un jugador se va, se aleja o se desconecta, y nunca puntúa pulsos demasiado cortos ni repetidos
  con demasiada frecuencia entre los mismos dos jugadores.

## Preguntas frecuentes

**¿Necesito un recurso de target?**
Solo para usar props que ya están en el mapa. Las mesas de `Config.Tables` también funcionan con `[E]`.

**¿Puedo desactivar las apuestas o el ranking?**
Sí: `Config.Bets.enabled = false` y `Config.Ranking.enabled = false`.

**¿Un personaje más fuerte empuja con más fuerza?**
No por defecto. Devuelve un multiplicador desde `Config.Hooks.power` para conectar tus propias habilidades o tu
recurso de gimnasio.

**Los jugadores se colocan en el sitio equivocado en mi mesa.**
Ajusta `axis` y `offset` de ese modelo en `Config.Models`.

**¿Cómo reinicio el ranking?**
`/armwrestlingreset`, o vacía la tabla `xex_armwrestling`. Con las temporadas activadas, también empieza de nuevo
cada mes.

**¿Puede mirar la gente?**
Sí. Cualquiera que esté a menos de `Config.Spectators.distance` de un pulso lo ve en directo; pon `enabled = false`
para desactivarlo.

## Licencia

MIT. Úsalo, cámbialo y compártelo; conserva el aviso de copyright. Consulta LICENSE.
