# nova\_core

The core resource of the NOVA Framework. Provides the foundation for all other scripts: player management, jobs, economy, callbacks, permissions, vehicle keys, weather/time sync, and database operations.

## Features

* **Player System** — Modern OOP player objects with character info, jobs, gangs, metadata
* **Job System** — Configurable jobs with grades, duty toggle, salary
* **Gang System** — Gang/group integration
* **Economy** — Cash, bank, and black\_money management
* **Callbacks** — Server-client callback system
* **Permissions** — O(1) permission cache with auth-gated exports
* **Vehicle Keys** — Key management for vehicle ownership
* **Weather & Time Sync** — Synchronized weather and time across all players
* **Needs System** — Hunger and thirst metabolism
* **World Control** — NPC density, traffic control
* **Localization** — Portuguese and English support
* **Database** — oxmysql integration with optimized queries

## Exports

### Shared Exports

| Export      | Returns | Description                     |
| ----------- | ------- | ------------------------------- |
| `GetObject` | table   | Get the core framework object   |
| `GetConfig` | table   | Get the framework configuration |
| `GetItems`  | table   | Get all registered items        |

### Server Exports

| Export                 | Parameters                  | Returns | Description                         |
| ---------------------- | --------------------------- | ------- | ----------------------------------- |
| `IsFrameworkReady`     | —                           | boolean | Check if framework is initialized   |
| `GetPlayer`            | `source`                    | Player  | Get player object by server ID      |
| `GetPlayerByCitizenId` | `citizenid`                 | Player  | Get player by citizen ID            |
| `GetPlayers`           | —                           | table   | Get all loaded players              |
| `IsPlayerLoaded`       | `source`                    | boolean | Check if player is loaded           |
| `AddPlayerMoney`       | `source`, `type`, `amount`  | boolean | Add money (cash/bank/black\_money)  |
| `RemovePlayerMoney`    | `source`, `type`, `amount`  | boolean | Remove money                        |
| `SetPlayerInventory`   | `source`, `inventory`       | —       | Set player inventory data           |
| `SetPlayerSkin`        | `source`, `skin`            | —       | Set player appearance               |
| `SavePlayer`           | `source`                    | —       | Force save player data              |
| `SetPlayerMetadata`    | `source`, `key`, `value`    | —       | Set metadata (hunger, thirst, etc.) |
| `LoginPlayer`          | `source`, `citizenid`       | —       | Load character                      |
| `LogoutPlayer`         | `source`                    | —       | Save and unload character           |
| `CreateCallback`       | `name`, `handler`           | —       | Register a server callback          |
| `Notify`               | `source`, `message`, `type` | —       | Send notification                   |
| `HasPermission`        | `source`, `permission`      | boolean | Check permission                    |
| `HasPermissionNode`    | `source`, `node`            | boolean | Check permission node               |
| `IsAdmin`              | `source`                    | boolean | Check admin status                  |
| `GetJobs`              | —                           | table   | Get all registered jobs             |
| `GetGangs`             | —                           | table   | Get all registered gangs            |
| `GiveKeys`             | `source`, `plate`           | —       | Give vehicle keys                   |
| `RemoveKeys`           | `source`, `plate`           | —       | Remove vehicle keys                 |
| `HasKeys`              | `source`, `plate`           | boolean | Check if player has keys            |
| `GetCurrentWeather`    | —                           | string  | Get current weather                 |
| `GetCurrentTime`       | —                           | table   | Get current time                    |
| `SetWeather`           | `weather`                   | —       | Set weather                         |
| `SetTime`              | `hour`, `minute`            | —       | Set time                            |

### Client Exports

| Export             | Parameters              | Returns | Description                     |
| ------------------ | ----------------------- | ------- | ------------------------------- |
| `IsFrameworkReady` | —                       | boolean | Check if framework is ready     |
| `IsPlayerLoaded`   | —                       | boolean | Check if local player is loaded |
| `GetPlayerData`    | —                       | table   | Get local player data           |
| `TriggerCallback`  | `name`, `cb`, `...args` | —       | Trigger a server callback       |
| `ClientNotify`     | `message`, `type`       | —       | Show local notification         |
| `HasKey`           | `plate`                 | boolean | Check if player has vehicle key |
| `GetMyKeys`        | —                       | table   | Get all vehicle keys            |

## Configuration

Main configuration in `config/main.lua`:

```lua
NovaConfig = {
    DefaultMoney = { cash = 5000, bank = 10000, black_money = 0 },
    DefaultJob = { name = 'desempregado', grade = 0 },
    DefaultGang = { name = 'none', grade = 0 },
    HungerRate = 0.5,          -- Hunger decrease per minute
    ThirstRate = 0.8,          -- Thirst decrease per minute
    SaveInterval = 300,         -- Auto-save every 5 minutes
    MaxPlayers = 64,
}
```

## Dependencies

* **oxmysql** — Database operations

## Notes

* All server exports validate the source player before executing
* Money operations are atomic and validated server-side
* The permission system uses an O(1) lookup cache
* Weather and time sync runs on a configurable interval
* Player data auto-saves periodically and on disconnect

## Security

* All server exports validate the caller before executing
* Internal event names and database schema are not disclosed for security purposes
* The permission system uses O(1) lookup cache with server-side validation