Valora Armour

🛡️ Valora Armour

An advanced, original armour system for FiveM that upgrades the standard
“use item → instant 100 armor” into a durability‑driven system of **ballistic
vests, headshot‑absorbing helmets, armor plates and repair kits** — built on
`ox_inventory` + `ox_lib`, fully server‑authoritative and persistent.

Plug & play — the only ox_inventory change is pasting the new `vlr_*` items
into `data/items.lua` (the standard step for any item‑based script). No core
edits, no `data/utility.lua` changes.

✨ Features

Vests with durability — each vest grants a configurable armor value; the
armor you lose to bullets is converted back into the item’s durability
(stored as `ox_inventory` metadata, so it travels with the item).

Hit zones — only torso hits drain the vest; arm/leg hits bypass it
and go to health (GTA‑style). Helmets only react to head hits.

Weapon penetration — per weapon‑group `penetration` + `wear`: a pistol
barely dents the vest, a sniper/AP round bleeds through and tears it up.

Helmets — stop lethal headshots while they have durability
(SetPedSuffersCriticalHits) and reduce the residual headshot damage by tier
(a heavy helmet protects the head far more than a light one), shake the camera on
impact and lose durability per hit until they break.

Job whitelist — restrict any vest/helmet to specific jobs/grades, server‑side.

Armor plates — top up the durability of the vest you’re wearing.

Repair kits — restore durability to your worn vest/helmet (priority order).

Realistic visuals — vest on ped component 9 (overlay over clothes), helmet
on head prop 0; gender‑aware, freemode‑safe, and the outfit/hat underneath is
saved & restored. Live tuning commands included.

Persistence — what you’re wearing and its durability survive relogs
(MySQL); on death the piece is returned to your inventory or lost (per config).

Anti‑cheat aware — equipping/plating/repairing is validated server‑side;
the durability sync path only ever accepts a *decrease*.

Live HUD — a circular “pool” (the helmet silhouette over a colour level
that drains with the percent) showing the helmet's condition only (the native HUD
already shows the armour bar); 8 positions, FiveM‑safe transparency (no
`backdrop-filter`).

Anti‑desync guard — if a clothing menu strips the helmet prop it auto‑unequips
(no invisible headshot protection); the vest overlay is re‑asserted if wiped.

Crafting & repair stations (optional) — `ox_lib` points + context menus
with skill‑checks, ingredient checks and distance/job validation.

i18n — self‑contained, config‑driven locales (English + Serbian included);
set `Config.Locale` to translate every string without touching `ox:locale`.

Framework‑agnostic — auto‑detects ESX / QBCore / QBox / ox_core for the
(optional) identifier & job lookups; works standalone otherwise.

📦 Requirements

`ox_lib` · `ox_inventory` · `oxmysql`  (a framework is optional)

📝 Notes & design choices

- Worn pieces are **removed from the inventory while worn** and returned (with
remaining durability) when taken off / on death (configurable). This keeps the
inventory honest and is what the MySQL table mirrors.

• Visual props are on by default for realism: the vest is drawn on ped
  component 9 (overlay over clothes) and the helmet on head prop 0. Male/female
  drawables are separate, only freemode peds get the visual, and the appearance
  underneath is saved & restored so outfits/hats are never destroyed. Drawable
  ids are pack‑specific — tune them live with `/vlrvest` & `/vlrhelmet`
  
  (`Config.Debug`). Set a piece's `enabled = false` to turn its visual off.

- `vlr_armour` is meant to be your single source of truth for armor. It uses
its own `vlr_*` items and doesn't touch ox_inventory's old `armour`/`heavyarmour`
or Utility slot, so they keep working independently — just stop handing them out
(and disable any framework armor persistence) to avoid two systems fighting over
`SetPedArmour`. Not required for vlr_armour to run.