# Street Races: documentación

> Contrarrelojes en tantos circuitos como quieras, con clasificaciones y avisos de récord a todo el servidor.

- URL: https://xexstudio.com/es/docs/street-races
- Versión: 1.0.0
- Ficha del producto: https://xexstudio.com/es/scripts/street-races
Carreras callejeras contrarreloj para FiveM. Los jugadores se acercan al mostrador de carreras, eligen un circuito y
un vehículo, y corren contra el reloj a través de una línea de checkpoints. Cada circuito tiene su propia
clasificación, y batir un récord se anuncia a todo el servidor. ESX, QBCore y Qbox.

El servidor dirige la carrera: genera el vehículo, arranca y detiene el cronómetro, comprueba cada checkpoint contra
la posición y el tiempo reales del vehículo, y guarda el tiempo. Un cliente modificado no puede enviar un tiempo que
no ha conducido.

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

- **Mostrador de carreras:** un NPC con ox_target o qb-target, o un marker y `[E]` sin recurso de target. Blip en el
  mapa.
- **Cuatro circuitos incluidos:** una vuelta urbana por Hawick y Vinewood, un sprint por el sur de Los Santos, un
  bucle rápido alrededor de los campos petrolíferos y un recorrido todoterreno por el desierto de Grand Senora. Añade
  los tuyos con `/racetool`.
- **Elección de vehículo:** cada circuito tiene su propia lista de vehículos. El servidor genera el que elige el
  jugador.
- **Cuenta atrás, HUD y pantalla de meta:** 3-2-1-GO, un cronómetro en marcha con el contador de checkpoints, y una
  pantalla de meta con el tiempo, la mejor marca personal y el récord del circuito.
- **Clasificaciones:** top 10 por circuito con nombres de personaje, tu mejor tiempo y el récord de cada circuito, y
  el número de récords que tienes.
- **Modo fantasma:** los corredores no colisionan con otros jugadores y estos los ven translúcidos.
- **Recompensas opcionales:** dinero por un récord, una mejor marca personal o cualquier llegada a meta, con tiempo de
  espera y límite por hora. Desactivadas por defecto.
- **Hooks y eventos** para pases de batalla, analíticas o permisos, sin editar el recurso.
- **Optimizado:** sin hilos mientras nadie corre y sin consultas a la base de datos durante una carrera hasta la meta.
  El NPC del mostrador solo existe mientras un jugador está cerca de él.
- 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

## Instalación

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

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

## Cómo funciona

1. **En el mostrador** el jugador abre el menú, elige un circuito y un vehículo.
2. **El servidor genera el vehículo** en la línea de salida y coloca al jugador dentro.
3. **Cuenta atrás.** El vehículo se mantiene inmóvil hasta el GO. El cronómetro arranca en el servidor en ese momento.
4. **Los checkpoints** se muestran de uno en uno con una ruta GPS. Cada uno se comprueba en el servidor antes de que
   aparezca el siguiente.
5. **Meta.** El servidor detiene el cronómetro y guarda el tiempo si es el mejor del jugador. El jugador vuelve al
   mostrador y ve la pantalla de meta.

Una carrera termina antes de tiempo si el vehículo queda destrozado, el jugador muere, sale del vehículo durante
demasiado tiempo (10 s por defecto), escribe `/cancelrace` o se desconecta. El vehículo siempre se elimina.

`/races` abre el menú en cualquier lugar para ver circuitos y clasificaciones. Las carreras solo empiezan en el
mostrador.

## Configuración

| Archivo | Qué contiene |
| --- | --- |
| `config.lua` | Todos los ajustes (tabla siguiente) |
| `data/tracks.lua` | Circuitos: línea de salida, vehículos, checkpoints |
| `locales/<locale>.json` | Todos los textos: notificaciones, menú, HUD y nombres de los circuitos |
| `bridge/server.lua` | Framework, dinero, nombres de personaje, llaves de vehículo, combustible |
| `bridge/client.lua` | Notificaciones, recurso de target, recursos de combustible del lado del cliente |

| Ajuste | Qué hace |
| --- | --- |
| `Config.Framework` | `auto`, o fuerza `esx` / `qb` / `qbox` |
| `Config.Target` | `auto`, `ox_target`, `qb-target` o `none` (marker y `[E]`) |
| `Config.Desk` | Posición, modelo y escenario del NPC, radio de salida y blip |
| `Config.Marker` | Marker mostrado en el mostrador cuando no tiene NPC |
| `Config.Commands` | Comandos de menú y de cancelación. `nil` desactiva uno |
| `Config.Admin` | Ace y nombres de los comandos de administración |
| `Config.UI` | Nombre de marca y color de acento |
| `Config.Checkpoint` | Tipo, tamaño y color del checkpoint y color del blip |
| `Config.Race` | Cuenta atrás, modo fantasma, tiempo permitido fuera del vehículo, colores del vehículo, prefijo de matrícula y las comprobaciones del servidor (velocidad máxima, margen del checkpoint, radio de salida, límites de tiempo) |
| `Config.Leaderboard` | Entradas mostradas por circuito, anuncios de récord |
| `Config.Rewards` | Dinero por llegada a meta, mejor marca personal y récord, cuenta, tiempo de espera y límite por hora |
| `Config.Hooks` | Funciones llamadas por el servidor (consulta Para desarrolladores) |

### Circuitos

```lua
{
    id = 'docks',                          -- stored with every time: don't rename it once it has times
    label = 'Docks Sprint',                -- nil = locale key track_docks
    description = 'Through the port.',     -- nil = locale key track_docks_desc
    start = vec4(1000.0, -3000.0, 5.9, 90.0),
    vehicles = {
        { model = 'sultan', label = 'Sultan' },
        { model = 'bati', label = 'Bati 801', type = 'bike' }, -- type for anything that isn't a car
    },
    checkpoints = {
        vec3(900.0, -3000.0, 5.9),
        vec3(800.0, -2950.0, 5.9),         -- the last one is the finish line
    },
},
```

Para hacer una vuelta completa, termina la lista con la posición de salida. Pon `enabled = false` para ocultar un
circuito y conservar sus tiempos.

### Añadir circuitos en el juego

Los administradores pueden ejecutar `/racetool start` en la línea de salida (dentro del vehículo, mirando en el
sentido de la carrera) y `/racetool cp` en cada checkpoint. Cada uno imprime una línea lista para pegar en
`data/tracks.lua` y la copia al portapapeles.

### Recompensas

```lua
Config.Rewards = {
    enabled = true,
    account = 'bank',
    finish = 0,
    personalBest = 500,
    record = 1500,
    cooldown = 300,
    maxPerHour = 4,
}
```

Solo se paga la recompensa más alta que corresponda. Las recompensas provienen de tiempos medidos por el servidor,
así que no se pueden farmear con un cliente modificado. Mantenlas moderadas: cualquiera que conduzca un circuito lo
bastante bien cobra.

### Llaves, combustible y notificaciones

`bridge/server.lua` entrega las llaves con `qbx_vehiclekeys` o `qb-vehiclekeys` y pone combustible para `ox_fuel`.
`bridge/client.lua` cubre LegacyFuel, cdn-fuel y ps-fuel, y envía las notificaciones a través de `lib.notify`.
Sustitúyelos ahí por tus propios recursos.

### Comandos de administración

| Comando | Qué hace |
| --- | --- |
| `/racesreset <track>` | Borra la clasificación de un circuito |
| `/racesstats` | Imprime los pilotos y el récord de cada circuito (consola del servidor y F8) |
| `/racetool cp \| start` | Imprime coordenadas para `data/tracks.lua` |

Están restringidos a `group.admin`. Cámbialo en `Config.Admin.ace`.

## Para desarrolladores

```lua
exports.xex_races:IsRacing(source) -- server
```

| Evento (servidor, local) | Argumentos |
| --- | --- |
| `xex_races:raceStarted` | `source, trackId, model` (cuando arranca el cronómetro) |
| `xex_races:raceFinished` | `source, trackId, timeMs, isPersonalBest, isRecord` |
| `xex_races:suspicious` | `source, reason, details` (`out_of_order`, `impossible_speed`, `bad_start`, `too_short`) |

```lua
AddEventHandler('xex_races:raceFinished', function(source, trackId, timeMs, isPersonalBest, isRecord)
    -- battle pass progress, logs, analytics...
end)
```

`Config.Hooks` hace lo mismo desde la configuración, más una comprobación antes de que empiece una carrera:

```lua
Config.Hooks = {
    canStart = function(source, trackId, model)
        return true -- false = the player can't start this race
    end,
    onRaceFinished = function(source, data)
        -- data = { track, time, vehicle, personalBest, record, reward }
    end,
}
```

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

## Seguridad

Los jugadores solo piden empezar una carrera y dicen a qué checkpoint han llegado. El servidor:

- solo inicia carreras cerca del mostrador, con un circuito y un vehículo de `data/tracks.lua`;
- genera el vehículo por sí mismo y arranca el cronómetro solo cuando el jugador está sentado en él en la línea de
  salida;
- acepta los checkpoints solo en orden, solo cuando el vehículo está en el checkpoint, y solo si el tiempo desde el
  anterior es posible a `Config.Race.maxSpeed` (un teletransporte termina la carrera y dispara
  `xex_races:suspicious`);
- mide el tiempo por sí mismo y cierra la carrera antes de guardarla, de modo que una carrera solo puede terminar una
  vez;
- paga las recompensas (si están activadas) a partir de ese tiempo, con tiempo de espera y límite por hora.

## Preguntas frecuentes

**¿Pueden los jugadores correr con sus propios vehículos?**
No. Las carreras usan vehículos generados por el servidor, para que el vehículo y el tiempo se puedan comprobar.

**¿Pueden correr varios jugadores a la vez?**
Sí, cada uno con su propio vehículo y su propio cronómetro. Dos jugadores no pueden empezar el mismo circuito mientras
el primer vehículo sigue en la línea de salida; el segundo espera un momento.

**¿Hay carreras multijugador (jugadores unos contra otros)?**
No en la 1.0. Cada carrera es una contrarreloj; la clasificación es la competición.

**¿Cómo reinicio un circuito?**
`/racesreset <track id>`. Para reiniciarlo todo, vacía la tabla `xex_race_times`.

**He renombrado el id de un circuito y sus tiempos han desaparecido.**
Los tiempos se guardan por id. Vuelve a poner el id antiguo o actualiza `track_id` en la base de datos.

**¿Por qué el menú dice que tengo que ir al mostrador?**
`/races` muestra los circuitos y las clasificaciones en cualquier lugar, pero las carreras solo empiezan en el
mostrador.

## Licencia

MIT. Úsalo, modifícalo y compártelo; conserva el aviso de copyright. Consulta LICENSE.
