> For the complete documentation index, see [llms.txt](https://docs.ak4y.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ak4y.com/scripts/ak4y-multicharacter-v3/events.md).

# Events

#### Give XP (server-sided)

```lua
local success = exports['ak4y-multicharacter-v3']:GiveXp(source, amount) --return true of false
```

| Parameter | Type   | Description                |
| --------- | ------ | -------------------------- |
| source    | number | The player id              |
| amount    | number | The amount you want to add |

#### Get Level (server-sided)

```lua
local playerLevel = exports['ak4y-multicharacter-v3']:GetLevel(source)
```

| Parameter | Type   | Description   |
| --------- | ------ | ------------- |
| source    | number | The player id |

Example Usage;

```lua
print("Player is level: " .. playerLevel)
```

#### Client-side Events Triggered

```lua
ak4y-multicharacter-v3:LevelUp (newLevel, oldLevel) - When player levels up
```

```lua
ak4y-multicharacter-v3:XpIncrease (xpGained, totalXp, currentLevel) - When XP increases
```

#### Notes;

* The system automatically handles database creation if a player doesn't have an XP record
* Level is calculated as: floor(XP / Config.NeedXpForLevel) + 1
* Minimum level is always 1
* XP can be negative, but this is not recommended
* The system works with both QB and ESX frameworks
* All XP operations are automatically saved to the database