# Hunting: documentación

> Caza con cebo en la que el servidor decide qué se genera, de quién es y cuánto paga.

- URL: https://xexstudio.com/es/docs/hunting
- Versión: 1.0.0
- Ficha del producto: https://xexstudio.com/es/scripts/hunting
Caza con cebo en la que el servidor lo decide todo. Cada animal pertenece al cazador que puso el cebo, y cada piel
se comprueba por dueño, distancia, salud y causa de la muerte antes de pagarla. Niveles de cazador, una licencia de
caza con examen teórico, un diario de cazador y un puma a partir del nivel 5. ESX, QBCore y Qbox.

## Requisitos

- [ox_lib](https://github.com/overextended/ox_lib) y [oxmysql](https://github.com/overextended/oxmysql)
- OneSync
- Un framework: **ESX** (con `esx_license` para la licencia de caza), **QBCore** o **Qbox**
- Un inventario: **ox_inventory**, **qb-inventory** (o un fork con los mismos exports) o el inventario de ESX
- Opcional: **ox_target** o **qb-target** (sin uno de ellos, la cabaña usa un marker y un aviso `[E]`)
- Opcional: [Weapon Licenses](https://xexstudio.com/scripts/weapon-licenses) para exigir una licencia de armas antes de la licencia de caza

## Instalación

1. Copia `xex_hunting` en tu carpeta de recursos.
2. Añade los objetos:
   - **ox_inventory:** copia `install/ox_inventory.lua` en `ox_inventory/data/items.lua`. Deja el cebo y el cuchillo
     sin `consume`: xex_hunting retira el cebo por su cuenta, en el servidor.
   - **qb-inventory:** copia `install/qb-inventory.lua` en `qb-core/shared/items.lua` y, en `config.lua`, usa
     `weapon_musket` y `shotgun_ammo` en `Config.Shop`.
   - **Inventario de ESX:** ejecuta la parte de objetos de `install/esx.sql`.
   - **Imágenes de los objetos:** copia `install/images/*.png` a `ox_inventory/web/images/` (o `qb-inventory/html/images/`).
3. **Solo ESX:** ejecuta la línea de la licencia de `install/esx.sql` (añade el tipo de licencia `hunting`).
4. Añade a `server.cfg` después de tu framework, inventario, ox_lib y oxmysql:
   ```cfg
   ensure xex_hunting
   ```
5. Idioma: `setr ox:locale en` (o `es`).

La tabla de progreso (`xex_hunting_progress`) se crea en el primer arranque.

## Cómo se juega

1. Aprueba el examen de la licencia y después compra cebo, un cuchillo y un arma de caza en la cabaña (por defecto
   cerca de Paleto Forest, de camino al Mount Chiliad). El diario muestra una lista de comprobación con lo que aún te
   falta.
2. Usa el cebo dentro de una zona de caza y espera cerca de él. El servidor hace una tirada por un animal cada pocos
   segundos.
3. El animal camina hacia el cebo. Si te acercas demasiado, huye; el puma, en cambio, ataca.
4. Abátelo con un arma de caza (mosquete, rifle de precisión o rifle de francotirador por defecto) y usa el cuchillo
   junto a él.
5. Vende pieles, colmillos y carne en la cabaña. Cada nivel añade una bonificación al precio.

El diario (habla con el cazador) muestra el nivel del cazador, la XP, las cacerías, la lista de comprobación, los
precios de venta y el equipo (con las imágenes de objetos de tu inventario), los animales, las armas permitidas y la
tabla de niveles.

## Configuración

Todo está en `config.lua`:

| Ajuste | Qué hace |
| --- | --- |
| `Config.Framework` / `Config.Inventory` / `Config.Target` | `auto`, o fuerza uno |
| `Config.Account` | Cuenta para ventas, recompensas y compras |
| `Config.Items` | Nombres de los objetos cebo y cuchillo |
| `Config.Weapons` | Armas que cuentan como muerte limpia (una especie puede sobrescribirlo) |
| `Config.Hunt` | Zonas y quién las ve en el mapa, tiempos, probabilidad de spawn y distancias, límites, blip, animación del cebo, herramienta y prop |
| `Config.Species` | Animales: modelo, XP, peso de spawn, nivel, zonas, recompensas, imagen del diario |
| `Config.Levels` | XP por nivel y bonificación de venta |
| `Config.License` | Licencia de caza: activada/desactivada, precio, examen teórico (preguntas, respuestas necesarias), requisito de licencia de armas |
| `Config.Lodge` | Posición de la cabaña, NPC, blip y qué compra |
| `Config.Shop` | Equipo que se vende en la cabaña y qué objetos requieren licencia |
| `Config.Buyers` | Lugares adicionales que compran objetos (un carnicero, un perista...) |
| `Config.UI` | Título y subtítulo del diario, color de acento e imágenes de los objetos |
| `Config.Hooks` | Funciones llamadas por el servidor (ver más abajo) |

Las zonas de caza se dibujan en el mapa por defecto para los jugadores con licencia de caza
(`Config.Hunt.zoneBlips.show`: `'license'`, `'always'` o `'never'`). El diario también las lista, y al hacer clic en
una se fija el GPS.

Los textos están en `locales/*.json`, incluidos los nombres y descripciones de los animales y los títulos de nivel.
Las preguntas del examen están en `questions/<locale>.lua` (cargado solo en el servidor; las respuestas se barajan en
cada examen). Las zonas de caza son códigos de zona de GTA; sus límites están en `data/zones.lua` (comprobados en el
servidor).

### Añadir un animal

Añade una entrada a `Config.Species` con su modelo de ped y después `species_<name>` y `species_<name>_desc` en los
locales. La imagen es opcional: ponla en `ui/art/` y establece `image`.

### Armas

`WEAPON_PRECISIONRIFLE` necesita la build 2699 del juego o una más reciente (`sv_enforceGameBuild 2699`). En builds
anteriores, quítala de `Config.Weapons` y `Config.Shop`.

### ESX sin ox_inventory

Las armas van al loadout. El objeto de munición del mosquete no existe ahí: quítalo de `Config.Shop` o sustitúyelo
por el objeto de munición que use tu servidor.

## Para desarrolladores

```lua
-- server
exports.xex_hunting:GetProfile(source)        -- { xp, hunts, level, title, bonus, species = { deer = 4, ... } }
exports.xex_hunting:GetLevel(source)          -- 1..10
exports.xex_hunting:HasHuntingLicense(source) -- boolean
exports.xex_hunting:IsHunting(source)         -- boolean
exports.xex_hunting:AddXp(source, amount)     -- reward hunting XP from another script

AddEventHandler('xex_hunting:huntCompleted', function(source, data)
    -- data = { species = 'deer', xp = 100, level = 3, leveledUp = false, zone = 'MTCHIL' }
end)
```

`Config.Hooks` te permite conectar otros recursos sin editar el código:

```lua
Config.Hooks.canSpawnPrey = function(source, modelHash, species)
    return true -- false = skip this species (e.g. an anti-cheat that blocks networked peds)
end

Config.Hooks.onHuntCompleted = function(source, data)
    -- battle pass, daily missions, analytics...
end
```

`bridge/server.lua`, `bridge/inventory.lua` y `bridge/client.lua` están abiertos: adáptalos si usas otro framework,
sistema de licencias, inventario, target o recurso de notificaciones.

## Seguridad

- El servidor abre la cacería cuando se usa el cebo, mide cuánto se tarda en colocarlo y solo entonces lo retira.
- El servidor elige la especie y el lugar. El cliente del cazador crea el animal (para que su IA y su cadáver
  coincidan con lo que ve el cazador) y el servidor solo lo acepta si el modelo, el dueño, la posición y el mundo
  coinciden.
- Al despiezar se comprueba, en el servidor: que la cacería es tuya, que el animal es el asignado a ella, que está
  muerto, que se abatió con un arma permitida, que estás junto a él y que tienes el cuchillo. El tiempo se mide en el
  servidor.
- Las recompensas se entregan una a una y se marcan: un inventario lleno o un guardado fallido se pueden reintentar
  sin recibir nada dos veces. La XP se guarda una vez por cacería.
- El examen de la licencia se elige, se baraja y se corrige en el servidor; el cliente nunca recibe las respuestas
  correctas, la tasa se cobra al empezar y abandonar a mitad del examen gasta el intento.
- Los precios, los objetos y las licencias salen de la configuración del servidor. Comprar, vender y sacar la
  licencia comprueban que estás en la cabaña. Nada de lo que envía el cliente decide un precio ni una cantidad.
- Salir, morir, desconectarse o cambiar de personaje termina tus cacerías y elimina sus animales.
