# Commands

***

## 📋 Command Overview

Koja-Crafting provides two admin commands for managing player progression and blueprints:

| Command         | Purpose                   | Permission | Usage                 |
| --------------- | ------------------------- | ---------- | --------------------- |
| `/addblueprint` | Grant blueprint to player | Admin      | `[playerID] [item]`   |
| `/addexp`       | Give experience to player | Admin      | `[playerID] [amount]` |

***

## 🔐 Permission System

### Who Can Use Commands?

Commands are restricted to players with admin permissions. Access is controlled by `Config.AdminGroups`:

```lua
-- In shared/config.lua
Config.AdminGroups = { 'admin', 'owner', 'superadmin', 'god' }
```

How it works:

* Script checks player's job/group from framework (ESX/QBCore)
* If player's group matches any in `Config.AdminGroups`, command executes
* If no match, player receives permission denied message

Configuration Examples:

```lua
-- ESX Standard
Config.AdminGroups = { 'admin', 'superadmin', 'owner' }

-- QBCore Standard
Config.AdminGroups = { 'admin', 'god' }

-- Custom Setup
Config.AdminGroups = { 'moderator', 'admin', 'developer', 'owner' }

-- Restricted (Owners only)
Config.AdminGroups = { 'owner' }
```

For detailed permission setup, see [Admin Permissions](https://docs.kojascripts.eu/new/crafting/configuration/broken-reference).

***

## 🔷 Add Blueprint Command

### Command Syntax

```bash
/addblueprint [playerID] [blueprintItem]
```

***

### Parameters

| Parameter       | Type   | Description                     | Required |
| --------------- | ------ | ------------------------------- | -------- |
| `playerID`      | Number | Target player's server ID       | ✅ Yes    |
| `blueprintItem` | String | Blueprint item name from config | ✅ Yes    |

***

### What It Does

{% stepper %}
{% step %}
Grants a special blueprint to the specified player.
{% endstep %}

{% step %}
Saves blueprint to player's database record (`koja-crafting` table).
{% endstep %}

{% step %}
Unlocks the corresponding item in crafting menu (if level requirement met).
{% endstep %}

{% step %}
Sends notification to the player.
{% endstep %}

{% step %}
Persists through server restarts and player disconnects.
{% endstep %}
{% endstepper %}

***

### Blueprint Configuration

In `shared/config.lua`:

```lua
blueprints = {
    {
        respname = 'parachute',
        name = 'Parachute',
        category = 'advanced',
        image = './images/parachute.webp',
        blueprintItem = 'parachute_blueprint',  -- ← This is what you use in command
        craftingTime = 120,
        requiredLevel = 4,
        resources = {
            { name = 'cloth', amount = 10 },
            { name = 'rope', amount = 5 }
        },
        exp = 150
    }
}
```

Command to give:

```bash
/addblueprint 1 parachute_blueprint
```

***

### Error Messages

<details>

<summary>Blueprint Command — Error Messages</summary>

| Error                          | Cause                      | Solution                               |
| ------------------------------ | -------------------------- | -------------------------------------- |
| "No permissions!"              | Not admin                  | Add your group to `Config.AdminGroups` |
| "Invalid player ID"            | Player offline or wrong ID | Check player is online with `/players` |
| "Blueprint not found"          | Wrong blueprint name       | Check `blueprintItem` in config        |
| "Player already has blueprint" | Duplicate                  | No action needed (already unlocked)    |

</details>

***

## 📊 Add Experience Command

### Command Syntax

```bash
/addexp [playerID] [amount]
```

***

### Parameters

| Parameter  | Type   | Description               | Required |
| ---------- | ------ | ------------------------- | -------- |
| `playerID` | Number | Target player's server ID | ✅ Yes    |
| `amount`   | Number | XP amount to add          | ✅ Yes    |

***

### What It Does

{% stepper %}
{% step %}
Adds specified XP to player's current experience.
{% endstep %}

{% step %}
Automatically calculates if player levels up.
{% endstep %}

{% step %}
Handles multiple level-ups in one command.
{% endstep %}

{% step %}
Saves progress to database immediately.
{% endstep %}

{% step %}
Notifies player of new level/XP.
{% endstep %}

{% step %}
Unlocks items if new level requirement met.
{% endstep %}
{% endstepper %}

***

### Error Messages

<details>

<summary>AddExp Command — Error Messages</summary>

| Error               | Cause            | Solution                          |
| ------------------- | ---------------- | --------------------------------- |
| "No permissions!"   | Not admin        | Add group to `Config.AdminGroups` |
| "Invalid player ID" | Wrong ID/offline | Verify with `/players`            |
| "Invalid amount"    | Negative/zero    | Use positive number               |
| "Command error"     | Framework issue  | Check koja-lib is running         |

</details>

***

## 🛠️ Console vs In-Game

### Running from Server Console

Commands can also be executed from server console:

```bash
# In server console (txAdmin, etc.)
addexp 1 500
addblueprint 5 weapon_blueprint
```

Note: When running from console (source = 0), permission checks are bypassed.

***

## 📊 Command Reference Table

| Command         | Syntax          | Permission | Purpose         | Persistent |
| --------------- | --------------- | ---------- | --------------- | ---------- |
| `/addblueprint` | `[id] [item]`   | Admin      | Grant blueprint | ✅ Yes      |
| `/addexp`       | `[id] [amount]` | Admin      | Give XP         | ✅ Yes      |

***

## 📚 Related Documentation

* For permission setup, see [Admin Permissions](https://docs.kojascripts.eu/new/crafting/configuration/broken-reference)
* For XP system details, see [Player Progression](https://docs.kojascripts.eu/new/crafting/configuration/broken-reference)
* For blueprint configuration, see [Crafting Stations](https://docs.kojascripts.eu/new/crafting/configuration/broken-reference)
* For server setup, see [Server Settings](https://docs.kojascripts.eu/new/crafting/configuration/broken-reference)