# 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.

***

## 🔷 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

:::steps
### Step 1

Grants a special blueprint to the specified player.


### Step 2

Saves blueprint to player's database record (`koja-crafting` table).


### Step 3

Unlocks the corresponding item in crafting menu (if level requirement met).


### Step 4

Sends notification to the player.


### Step 5

Persists through server restarts and player disconnects.
:::

***

### 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

:::steps
### Step 1

Adds specified XP to player's current experience.


### Step 2

Automatically calculates if player levels up.


### Step 3

Handles multiple level-ups in one command.


### Step 4

Saves progress to database immediately.


### Step 5

Notifies player of new level/XP.


### Step 6

Unlocks items if new level requirement met.
:::

***

### 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
* For XP system details, see [Player Progression](/new/crafting/configuration/player-progression-settings)
* For blueprint configuration, see [Crafting Stations](/new/crafting/configuration/crafting-stations-settings)
* For server setup, see [Server Settings](/new/crafting/configuration/server-settings)

## Related pages

- [General Settings](/new/crafting/configuration/general-settings) — This page covers the basic configuration options for Koja-Crafting that control debug mode, language, and player behavior.
- [Server Settings](/new/crafting/configuration/server-settings) — This page covers server-side configuration options including database management, crafting recovery, and shared table functionality.
- [Images Settings](/new/crafting/configuration/images-settings) — This page explains how to configure item images, add custom graphics, and manage image paths in Koja-Crafting.
- [Player Progression Settings](/new/crafting/configuration/player-progression-settings) — This page covers the player progression system including levels, experience points, and how to configure the leveling system in Koja-Crafting.
- [Admin Settings](/new/crafting/configuration/admin-settings) — This page covers admin permission configuration and available admin commands for managing Koja-Crafting.
- [Interaction Settings](/new/crafting/configuration/interaction-settings) — This page covers how players interact with crafting stations - either through key press or target system (ox\_target,qb-target,).
- [Configuration](/new/crafting/configuration) — back to the section overview