# Player System

The Player System is the core of NOVA Framework. Each connected player has a `NovaPlayer` object that provides a clean OOP API for managing player data.

## Getting a Player

### Server-side

```lua
-- Get player by server ID
local player = Nova.Functions.GetPlayer(source)

-- Get player by identifier
local player = Nova.Functions.GetPlayerByIdentifier('license:abc123')

-- Get all online players
local players = Nova.Functions.GetPlayers()
```

### Via Exports

```lua
-- From any server script
local player = exports['nova_core']:GetPlayer(source)
```

## Player Properties

```lua
local player = Nova.Functions.GetPlayer(source)

-- Basic info
player.source       -- Server ID
player.identifier   -- Unique license identifier
player.charId       -- Character ID
player.name         -- Character first name
player.lastname     -- Character last name
player.fullname     -- First + Last name
player.dob          -- Date of birth
player.nationality  -- Nationality
player.gender       -- 0 = male, 1 = female

-- Economy
player.money        -- Cash on hand
player.bank         -- Bank balance

-- Job
player.job          -- Job name (e.g., 'police')
player.jobGrade     -- Job grade (e.g., 2)
player.jobLabel     -- Job display name (e.g., 'Police')

-- Group/Admin
player.group        -- Admin group (e.g., 'admin', 'user')
```

## Player Methods

### Money

```lua
-- Get money
local cash = player:GetMoney()
local bank = player:GetBank()

-- Add money
player:AddMoney(500)        -- Add cash
player:AddBank(1000)        -- Add to bank

-- Remove money
player:RemoveMoney(200)     -- Remove cash
player:RemoveBank(500)      -- Remove from bank

-- Set money directly
player:SetMoney(5000)
player:SetBank(10000)
```

### Inventory

```lua
-- Get full inventory
local inventory = player:GetInventory()

-- Add item
player:AddItem('bread', 5)          -- Add 5 bread
player:AddItem('weapon_pistol', 1)  -- Add a pistol

-- Remove item
player:RemoveItem('bread', 2)       -- Remove 2 bread

-- Check if has item
local has = player:HasItem('bread')       -- Returns true/false
local count = player:HasItem('bread', true) -- Returns count

-- Get specific item
local item = player:GetItem('bread')
-- Returns: { name = 'bread', count = 5, label = 'Bread', ... }
```

### Job

```lua
-- Get job info
local job = player:GetJob()
-- Returns: { name = 'police', grade = 2, label = 'Police', gradeLabel = 'Sergeant' }

-- Set job
player:SetJob('police', 2)

-- Check job
if player:GetJob().name == 'police' then
    -- Player is police
end
```

### Groups & Permissions

```lua
-- Get group
local group = player:GetGroup()  -- e.g., 'admin'

-- Set group
player:SetGroup('admin')

-- Check permission
local canKick = player:HasPermission('admin.kick')
```

### Status (Hunger/Thirst)

```lua
-- Get status
local hunger = player:GetHunger()   -- 0-100
local thirst = player:GetThirst()   -- 0-100

-- Set status
player:SetHunger(100)
player:SetThirst(100)
```

### Data Persistence

```lua
-- Save player data to database
player:Save()

-- Player data is also auto-saved every Config.AutoSaveInterval seconds
```

## Player Events

```lua
-- Server-side: When a player finishes loading
AddEventHandler('Nova:PlayerLoaded', function(source, player)
    print(player.fullname .. ' has loaded!')
end)

-- Server-side: When a player disconnects
AddEventHandler('Nova:PlayerDropped', function(source, player)
    print(player.fullname .. ' has disconnected')
end)

-- Client-side: When local player is loaded
AddEventHandler('Nova:PlayerLoaded', function(playerData)
    print('My character: ' .. playerData.fullname)
end)
```

## Example: Complete Script

```lua
-- server/main.lua
AddEventHandler('Nova:PlayerLoaded', function(source, player)
    -- Give starter items to new characters
    if player:GetMoney() == Config.DefaultMoney then
        player:AddItem('bread', 10)
        player:AddItem('water', 10)
        Nova.Functions.Notify(source, 'Welcome! You received starter items.', 'success')
    end
end)
```