# 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](broken://pages/0ff54406511996995fbec6d1b4c286b8efe5150b).

***

## 🔷 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](broken://pages/0ff54406511996995fbec6d1b4c286b8efe5150b)
* For XP system details, see [Player Progression](broken://pages/95958ee66962d26442d85824ccdc24b3caeeb41c)
* For blueprint configuration, see [Crafting Stations](broken://pages/fc34b22896c5ea7fffc5d364bba13e50425dfafc)
* For server setup, see [Server Settings](broken://pages/6dafbcd21c1067ed064e072bdf327dfe4bdf61ef)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kojascripts.eu/new/crafting/configuration/commands.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.