# 📏 Five Lua Scale - Advanced 3D Ruler & Biometric Ped Scale System

---

## 🌐 [EN] English Documentation

### 📌 Overview

**Five Lua Scale** is a high-performance, biometric ped scaling script designed for FiveM servers (QBCore & ESX). It enables players and administrators to adjust character physical height and weight proportions with real-time visual feedback, an interactive **3D in-game ruler (cetvel)**, orbital camera controls, and a sleek **Admin Management Dashboard**.

---

### ✨ Key Features

- **Interactive 3D Ruler (Cetvel)**:

  - Renders a live 3D holographic laser ruler directly beside the character.

  - Precise millimeter & centimeter measurement lines.

  - Configurable **MIN indicator line & text badge** to prevent unrealistic character shrinking.

- **360° Free Orbital Camera**:

  - Left-click drag to rotate camera around ped.

  - Right-click drag for smooth vertical panning (eye-level to full body).

  - Mouse scroll for dynamic zoom in/out.

- **Modern Glassmorphic NUI**:

  - Dual measurement units: **Metric (cm/kg)** and **Imperial (ft-in/lbs)**.

  - 4 One-Click Body Presets: *Slim*, *Normal*, *Heavy*, *Athletic*.

  - Real-time biometric display and instant server-synchronized changes.

- **Multi-Character Architecture**:

  - Saved distinctly per `citizenid` (QBCore) or `identifier` (ESX). Multiple characters belonging to the same player maintain their own distinct body scales without mixing up.

- **Comprehensive Admin Panel (`/allpedscale`)**:

  - Tablet animation upon opening.

  - Live table of all scaled players with real-time online/offline indicators.

  - Search by name, ID, or license.

  - Edit height/weight scale with live update.

  - Reset scale back to default (1.00m).

  - Add players and grant modification rights (by Server ID or offline CitizenID/License).

  - Increment / decrement remaining rights count.

  - Profile Avatars: Steam, Discord bot avatar, Live Ped Mugshot, or Initials.

- **Security & Modularity**:

  - `shared/server_config.lua`: Sensitive keys (**Steam Web API Key**, **Discord Bot Token**) are kept strictly server-side and never sent to clients.

  - `editable/c_framework.lua` & `editable/s_framework.lua`: Open framework adapters supporting **QBCore**, **ESX**, **ox_lib**, custom notifications, and tablet animations.

---

### ⚙️ Configuration Guide

#### 1. Public Configuration (`shared/config.lua`)

| Setting | Type | Description |

| :--- | :--- | :--- |

| `FiveLuaCfg.Framework` | `string` | `'qbcore'` or `'esx'` (Auto-detected if left default). |

| `FiveLuaCfg.NotifyType` | `string` | Notification system: `'qb'`, `'esx'`, `'ox'`, or `'chat'`. |

| `FiveLuaCfg.Locale` | `string` | UI language: `'tr'` (Turkish) or `'en'` (English). Translations in `shared/locales.lua`. |

| `FiveLuaCfg.CommandName` | `string` | Command to open player scale menu (Default: `"pedscale"`). |

| `FiveLuaCfg.AllCommandName` | `string` | Command to open admin dashboard (Default: `"allpedscale"`). |

| `FiveLuaCfg.RestrictedAccess` | `boolean` | `true`: Requires admin permission or granted rights. `false`: Open to all players. |

| `FiveLuaCfg.AllowedIdentifiers` | `table` | List of authorized Steam Hex, Discord ID, License, or FiveM IDs. |

| `FiveLuaCfg.AllowedGroups` | `table` | Server permission groups (e.g. `{"admin", "god"}`). |

| `FiveLuaCfg.ShowMinIndicator` | `boolean` | `true`: Shows red MIN guideline on 3D ruler. `false`: Hides it completely. |

| `FiveLuaCfg.ShowMinText` | `boolean` | `true`: Displays "MIN (1.44M)" badge on ruler. `false`: Only keeps the guideline. |

| `FiveLuaCfg.Limits` | `table` | Min/Max scale limits for Height and Weight. |

| `FiveLuaCfg.PlayerNameType` | `string` | Profile name source in player menu: `'steam'`, `'discord'`, or `'rp'`. |

| `FiveLuaCfg.PlayerAvatarType` | `string` | Profile avatar source in player menu: `'steam'`, `'discord'`, `'mugshot'`, or `'initials'`. |

| `FiveLuaCfg.AdminPanelNameType` | `string` | Profile name source in admin panel: `'steam'`, `'discord'`, or `'rp'`. |

| `FiveLuaCfg.AdminPanelAvatarType` | `string` | Profile avatar source in admin panel: `'steam'`, `'discord'`, or `'initials'`. |

| `FiveLuaCfg.EnableAutoGarageDoors` | `boolean` | `true`: Automatically opens listed gates/doors when ped approaches. `false`: Disabled. |

| `FiveLuaCfg.GarageDoorModels` | `table` | Array of door prop model hashes handled by the automatic door opener. |

#### 2. Sensitive Server Configuration (`shared/server_config.lua`)

```lua

FiveLuaCfg = FiveLuaCfg or {}

-- Steam Web API Key (Get yours from )

FiveLuaCfg.SteamApiKey = "YOUR_STEAM_API_KEY_HERE"

-- Discord Bot Token (Required if Discord avatar/name resolution is used)

FiveLuaCfg.DiscordBotToken = "YOUR_DISCORD_BOT_TOKEN_HERE"

-- Discord Webhook URL (Logs rights grants, admin adjustments, scale changes, resets & dates)

FiveLuaCfg.DiscordWebhook = "YOUR_DISCORD_WEBHOOK_URL_HERE"

```

---

### 🚀 Installation Steps

1. **Move Resource**:

   Place the folder into your server resources:

   `resources/[meslek]/fivelua-pedscale`

2. **Database Import**:

   Import **`fivelua_pedscale.sql`** into your database using HeidiSQL or phpMyAdmin:

   ```sql

   CREATE TABLE IF NOT EXISTS `fivelua_pedscale` (

       `citizenid` varchar(64) NOT NULL,

       `license` varchar(64) DEFAULT NULL,

       `char_name` varchar(100) DEFAULT 'Bilinmiyor',

       `steam_name` varchar(100) DEFAULT 'Bilinmiyor',

       `steam_avatar` varchar(500) DEFAULT NULL,

       `discord_name` varchar(100) DEFAULT 'Bilinmiyor',

       `discord_profile` varchar(255) DEFAULT NULL,

       `discord_avatar` varchar(500) DEFAULT NULL,

       `scale_h` decimal(4,2) DEFAULT 1.00,

       `scale_w` decimal(4,2) DEFAULT 1.00,

       `has_right` tinyint(1) DEFAULT 0,

       `rights_count` int(11) DEFAULT 0,

       `given_by_name` varchar(100) DEFAULT NULL,

       `given_by_license` varchar(64) DEFAULT NULL,

       `created_at` timestamp NULL DEFAULT current_timestamp(),

       `updated_at` timestamp NULL DEFAULT current_timestamp() ON UPDATE current_timestamp(),

       PRIMARY KEY (`citizenid`),

       KEY `idx_license` (`license`)

   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

   ```

3. **Configure Settings**:

   - Open `shared/config.lua` and set your framework, language, limits, and admin identifiers.

   - Open `shared/server_config.lua` and set your **Steam API Key** and **Discord Bot Token**.

4. **Start Resource**:

   Add the start line to your `server.cfg`:

   ```cfg

   ensure fivelua-pedscale

   ```

---

### 🎮 In-Game Commands

- `/pedscale` - Opens personal biometric height and weight adjustment screen.

- `/allpedscale` - Opens Admin Management Panel (Admins only).

---

---

## 🇹🇷 [TR] Türkçe Dokümantasyon

### 📌 Genel Bakış

**Five Lua Scale**, FiveM sunucuları (QBCore & ESX) için geliştirilmiş, yüksek performanslı ve biyometrik karakter boy/kilo ölçeklendirme scriptidir. Oyuncuların ve yöneticilerin karakter boyutlarını canlı görsel geri bildirim, oyun içi interaktif **3D lazer cetvel**, serbest orbital kamera kontrolleri ve gelişmiş bir **Yönetici Paneli** ile ayarlamasını sağlar.

---

### ✨ Öne Çıkan Özellikler

- **İnteraktif 3D Lazer Cetvel**:

  - Karakterin yanında 3D lazer cetvel oluşturur.

  - Milimetrik ve santimetrik hassas ölçüm çizgileri.

  - Karakterin aşırı küçültülmesini engelleyen ve konfigürasyondan açılıp kapatılabilen **kırmızı MIN gösterge çizgisi ve metin kutucuğu**.

- **360° Serbest Orbital Kamera**:

  - Sol tık + sürükle: Ped etrafında kamerayı döndürme.

  - Sağ tık + sürükle: Yukarı/aşağı dikey kamera kaydırma (göz hizasından ayaklara kadar).

  - Mouse tekerleği: Pürüzsüz yakınlaşma / uzaklaşma (zoom).

- **Modern Glassmorphic NUI Arayüzü**:

  - İki ölçü birimi: **Metrik (cm/kg)** ve **İmperial (ft-in/lbs)**.

  - 4 Tek Tıkla Hazır Vücut Tipi: *Zayıf*, *Normal*, *Kilolu*, *Atletik*.

  - Anlık biyometrik göstergeler ve sunucuyla senkronize gerçek zamanlı ped matrisi.

- **Çoklu Karakter Desteği**:

  - Ölçekler oyuncunun `citizenid` (QBCore) veya `identifier` (ESX) kimliğine kaydedilir. Aynı oyuncunun 1. ve 2. karakterleri birbirine karışmaz, her karakterin boyu bağımsız kalır.

- **Kapsamlı Yönetici Paneli (`/allpedscale`)**:

  - Panel açıldığında tablet animasyonu ve prop kullanımı.

  - Oyuncu listesi, arama motoru (İsim, ID, Lisans) ve çevrimiçi/çevrimdışı durumu.

  - Canlı boy & kilo ölçek düzenleme ve sunucuya anında senkronize etme.

  - Oyuncunun ölçeğini tek tıkla varsayılana (1.00m) sıfırlama.

  - ID veya lisans girerek oyuncu ekleme ve düzenleme hakkı tanımlama.

  - Kalan hak sayısını artırma / azaltma.

  - Profil Avatarları: Steam, Discord bot avatarı, Canlı Ped Mugshot veya İnisiyaller.

- **Güvenlik ve Modülerlik**:

  - `shared/server_config.lua`: **Steam Web API Key** ve **Discord Bot Token** istemcilere (client) gönderilmez, sunucu tarafında güvenle saklanır.

  - `editable/c_framework.lua` & `editable/s_framework.lua`: Açık framework köprüsü (**QBCore**, **ESX**, **ox_lib**, özel bildirimler ve tablet animasyonu).

---

### ⚙️ Ayarlar & Konfigürasyon

#### 1. Genel Konfigürasyon (`shared/config.lua`)

| Ayar | Tip | Açıklama |

| :--- | :--- | :--- |

| `FiveLuaCfg.Framework` | `string` | `'qbcore'` veya `'esx'` (Varsayılan olarak otomatik algılanır). |

| `FiveLuaCfg.NotifyType` | `string` | Bildirim türü: `'qb'`, `'esx'`, `'ox'` veya `'chat'`. |

| `FiveLuaCfg.Locale` | `string` | Dil seçeneği: `'tr'` (Türkçe) veya `'en'` (İngilizce). Çeviriler `shared/locales.lua` dosyasındadır. |

| `FiveLuaCfg.CommandName` | `string` | Oyuncu ölçek menüsü komutu (Varsayılan: `"pedscale"`). |

| `FiveLuaCfg.AllCommandName` | `string` | Yönetici paneli komutu (Varsayılan: `"allpedscale"`). |

| `FiveLuaCfg.RestrictedAccess` | `boolean` | `true`: Hak veya admin yetkisi gerekir. `false`: Herkes kullanabilir. |

| `FiveLuaCfg.AllowedIdentifiers` | `table` | Yetkili Steam Hex, Discord ID, License veya FiveM ID listesi. |

| `FiveLuaCfg.AllowedGroups` | `table` | Sunucu yetki grupları (Örn: `{"admin", "god"}`). |

| `FiveLuaCfg.ShowMinIndicator` | `boolean` | `true`: Cetveldeki kırmızı MIN çizgisini açar. `false`: Tamamen gizler. |

| `FiveLuaCfg.ShowMinText` | `boolean` | `true`: Cetveldeki "MIN (1.44M)" yazısını gösterir. `false`: Sadece çizgiyi bırakır. |

| `FiveLuaCfg.Limits` | `table` | Minimum ve maksimum boy/kilo ölçek sınırları. |

| `FiveLuaCfg.PlayerNameType` | `string` | Oyuncu menüsü profil isim kaynağı: `'steam'`, `'discord'` veya `'rp'`. |

| `FiveLuaCfg.PlayerAvatarType` | `string` | Oyuncu menüsü profil avatar kaynağı: `'steam'`, `'discord'`, `'mugshot'` veya `'initials'`. |

| `FiveLuaCfg.AdminPanelNameType` | `string` | Yönetici paneli isim kaynağı: `'steam'`, `'discord'` veya `'rp'`. |

| `FiveLuaCfg.AdminPanelAvatarType` | `string` | Yönetici paneli avatar kaynağı: `'steam'`, `'discord'` veya `'initials'`. |

| `FiveLuaCfg.EnableAutoGarageDoors` | `boolean` | `true`: Ped yaklaştığında listedeki garaj kapılarını otomatik açar. `false`: Devre dışı. |

| `FiveLuaCfg.GarageDoorModels` | `table` | Otomatik açılacak garaj kapısı prop model hash listesi. |

#### 2. Hassas Sunucu Konfigürasyonu (`shared/server_config.lua`)

```lua

FiveLuaCfg = FiveLuaCfg or {}

-- Steam Web API Anahtarı ( adresinden temin edilir)

FiveLuaCfg.SteamApiKey = "STEAM_API_KEYINIZ_BURAYA"

-- Discord Bot Token (Profilde Discord avatar/ismi kullanılacaksa gereklidir)

FiveLuaCfg.DiscordBotToken = "DISCORD_BOT_TOKENINIZ_BURAYA"

-- Discord Webhook Günlüğü (Kime hak verildi, hangi admin verdi, boy/kilo düzenlemeleri, sıfırlamalar ve tarihler)

FiveLuaCfg.DiscordWebhook = "DISCORD_WEBHOOK_URLNIZ_BURAYA"

```

---

### 🚀 Kurulum Adımları

1. **Dosyaları Yükleyin**:

   Klasörü sunucunuzun `resources` dizinine taşıyın:

   `resources/[meslek]/fivelua-pedscale`

2. **Veritabanı Kurulumu**:

   Paket içerisindeki **`fivelua_pedscale.sql`** dosyasını veritabanınıza (HeidiSQL veya phpMyAdmin) okutun.

3. **Ayarları Yapılandırın**:

   - `shared/config.lua` dosyasından dil, framework, sınırlar ve yetkili ID'leri ayarlayın.

   - `shared/server_config.lua` dosyasından **Steam API Key** ve **Discord Bot Token** bilgilerinizi girin.

4. **Sunucu Başlatma**:

   `server.cfg` dosyanıza şu satırı ekleyin:

   ```cfg

   ensure fivelua-pedscale

   ```

---

### 🎮 Oyun İçi Komutlar

- `/pedscale` - Karakter boy ve kilo ölçeklendirme arayüzünü açar.

- `/allpedscale` - Yönetici Yönetim Panelini açar (Sadece yetkili yöneticiler).

---