# CodexCore

***

### 🔰 Setup & Exports

#### Resource Order

Add in `server.cfg`:

```cfg
ensure codex_core
# ensure your modules after this (e.g. codex_trustlevel)
```

#### fxmanifest.lua

**Exports (Client)**

* `getLibClient`
* `CodexAPIsInit`
* `Progressbar`

**Exports (Server)**

* `getLibServer`

#### Config

`config.lua` selects target framework and SQL driver.

CodexCore maps calls internally so your module code remains **framework‑neutral**.

***

### 🤝 Client Library — CodexCore

#### Get Library

```lua
local CodexCore = exports['codex_core']:getLibClient()
```

Returns the CodexCore client facade.

***

#### Core Functions

**`CodexCore.RequestCoreAPI()`**

Returns the underlying framework client object.

> ⚠️ Use only if CodexCore does not already provide an abstraction.

```lua
local Core = CodexCore.RequestCoreAPI()
```

***

**`CodexCore.IsLoaded()`**

Checks whether the local player is fully loaded.

```lua
if not CodexCore.IsLoaded() then return end
```

***

**`CodexCore.GetCharacterIdentifier()`**

Returns a unique character identifier.

***

**`CodexCore.GetJob()` / `CodexCore.GetJobGrade()`**

Returns current job name and grade.

***

**`CodexCore.GetMoney()` / `CodexCore.GetGold()`**

Returns mapped balances.

***

**`CodexCore.GetGroup()`**

Returns permission group (e.g., `admin`, `user`).

***

### 🔁 RPC Callback (Client → Server)

#### `CodexCore.TriggerServerCallback(name, cb, ...)`

| Parameter | Type     | Description                        |
| --------- | -------- | ---------------------------------- |
| `name`    | string   | Callback name registered on server |
| `cb`      | function | Receives result from server        |
| `...`     | varargs  | Arguments forwarded                |

```lua
CodexCore.TriggerServerCallback('trust:get', function(level)
  print('Trust level =', level)
end, CodexCore.GetCharacterIdentifier())
```

***

### 🧰 Utility — AddBlipForCoords

```lua
local blip = CodexCore.AddBlipForCoords(
  123.4, 456.7, 78.9,
  `blip_shop`,
  'Black Market',
  `BLIP_MODIFIER_MP_COLOR_1`
)
```

***

### 🗯️ Client Sub‑APIs — CodexAPIsInit

```lua
local CodexAPIs = exports['codex_core']:CodexAPIsInit()
```

Provides:

* `Prompt`
* `Blip`
* `Render`
* `Buttons`
* `Peds`
* `Objects`

***

## ⭐ Prompts API

#### Overview

Create grouped interaction prompts supporting:\
`click`, `hold`, `customhold`, `mash`, `timed`

***

#### Setup Prompt Group

```lua
local group = Prompt:SetupPromptGroup('CratePickup')
```

***

#### Register Prompt

```lua
local grab = group:RegisterPrompt(
  'Pick Up Crate',
  Codex.Keys['E'],
  true, true, true,
  'hold',
  { timedeventhash = 'MEDIUM_TIMED_EVENT' }
)
```

***

#### Prompt Loop Example

```lua
CreateThread(function()
  while true do Wait(0)
    group:ShowGroup('Hold [E] to pick up')
    if grab:HasCompleted(true) then
      TriggerEvent('codex-core:notification', '📦 Crate picked up!', 2500, 'success')
      break
    end
  end
end)
```

***

## 🗯️ Blips API

#### Create Blip

```lua
local drop = Blip:SetBlip('Drop-Off', `blip_shop`, 0.3, 250.0, 400.0, 50.0)
Blip:AddBlipModifier(drop, `BLIP_MODIFIER_JOB`):ApplyModifier()
```

#### Radius

```lua
local area = Blip:SetRadius(-1282792512, 30.0, 250.0, 400.0, 50.0)
```

***

## ⭐ Buttons API

```lua
local BTN = CodexAPIs.Buttons:Create(0, `INPUT_JUMP`, false, 300, 1000, {
  OnTotalRepeatedPress = function(cnt)
    if cnt >= 3 then
      TriggerEvent('codex-core:notification', '👟 Triple‑jump!', 2000, 'inform')
    end
  end
}, true)
```

***

## 📍 Render API

#### Example — 3D Text

```lua
CodexAPIs.Render:Draw3DText(
  vector3(123.0, 456.0, 78.0),
  'Interact',
  0.6,
  {r=255,g=255,b=255,a=255},
  1,
  3
)
```

***

## 🧶 Objects API

```lua
local box = CodexAPIs.Objects:Create(
  'p_package09',
  150.0, 250.0, 45.0,
  90.0,
  true,
  'standard'
)

box:PickupLight(true)
```

***

## 🧍‍♂️ Peds API

```lua
local ped = CodexAPIs.Peds:Create(
  'U_M_M_NbxGeneralStoreOwner_01',
  -300.1, 500.2, 50.0, 180.0
)

ped:SetBlip(`BLIP_STYLE_ENEMY`, 'Guard')
ped:Invincible(true)
ped:SetPedCombatAttributes({ {flag=46, enabled=true} }, 2, 2, 2)
```

***

## 📊 Progressbar

```lua
exports['codex_core']:Progressbar(4000, 'Mixing chemicals...')
```

***

## 👮 Admin Command — `/coords`

Only available if:

```
LocalPlayer.state.Character.Group == 'admin'
```

Copies coordinates to clipboard in formats:

* `vec`
* `vec4`
* `json`
* `xyz`

***

## 💻 Server Library — CodexCore

```lua
local Core = exports['codex_core']:getLibServer()
```

***

### 🗄️ SQL Helper

```lua
local rows = Core.ExecuteSql(
  'SELECT trust FROM trustlevel WHERE identifier=@id',
  { ['@id'] = Core.GetCharacterIdentifier(source) }
)
```

***

### 👤 Player & Character

```lua
local charId = Core.GetCharacterIdentifier(src)
if not charId then return end
```

***

### 👮 Jobs & Groups

```lua
Core.SetJob(src, 'police')
Core.SetJobGrade(src, 0)
```

***

### 💰 Money & Accounts

```lua
if Core.GetAccountMoney(src, 0) >= 25 then
  Core.RemoveAccountMoney(src, 0, 25)
  Core.AddAccountMoney(src, 1, 1)
end
```

***

### 🎒 Inventory

```lua
Core.RegisterUsableItem('lockpick', function(src, item)
  TriggerClientEvent('codex-core:notification', src, '🔓 Using lockpick...', 2000, 'inform')
end)
```

***

### 🔁 Callbacks

#### Server

```lua
Core.RegisterServerCallback('trust:get', function(src, cb, charId)
  local rows = Core.ExecuteSql(
    'SELECT trust FROM trustlevel WHERE char=@c',
    { ['@c']=charId }
  )
  cb(rows[1] and rows[1].trust or 0)
end)
```

#### Client

```lua
CodexCore.TriggerServerCallback('trust:get', function(trust)
  TriggerEvent('codex-core:notification', ('Trust: %d'):format(trust), 2000, 'inform')
end, CodexCore.GetCharacterIdentifier())
```

***

## 🛣️ Events Reference

### Client Events

#### `codex-core:playerLoaded`

```lua
AddEventHandler('codex-core:playerLoaded', function()
  -- init HUD, prompts, etc.
end)
```

***

#### `codex-core:notification`

```lua
TriggerClientEvent(
  'codex-core:notification',
  src,
  '✅ Purchased!',
  2500,
  'success'
)
```

***

### Server Events

#### `codex-core:sendToDiscord`

```lua
TriggerEvent(
  'codex-core:sendToDiscord',
  WEBHOOK,
  'Player Banned',
  ('ID: %s'):format(src),
  16711680
)
```

***

## 🔼 Versioning & Config

* `version.lua` checks latest version and prints changelog
* `config.lua` sets framework and SQL driver

***

## 💪 Best Practices

* Stay **framework‑neutral**
* Use callbacks for sensitive operations
* Always guard DB results
* Secure and rate‑limit critical events
* Pair actions with **notifications + progress bars**

***

## 🔚 End‑to‑End Example — Shop Purchase

### Client

```lua
RegisterNUICallback('buy', function(data, cb)
  TriggerServerEvent('shop:buy', data.item, data.price)
  cb(true)
end)
```

### Server

```lua
local Core = exports['codex_core']:getLibServer()

RegisterNetEvent('shop:buy', function(item, price)
  local src = source

  if Core.GetAccountMoney(src, 0) < price then
    TriggerClientEvent('codex-core:notification', src, '❌ Not enough money!', 2500, 'error')
    return
  end

  if not Core.CanCarryItem(src, item, 1) then
    TriggerClientEvent('codex-core:notification', src, '❌ Inventory full!', 2500, 'error')
    return
  end

  Core.RemoveAccountMoney(src, 0, price)
  Core.AddItem(src, item, 1)

  TriggerClientEvent('codex-core:notification', src, '✅ Purchase successful!', 2500, 'success')
end)
```