> For the complete documentation index, see [llms.txt](https://docs.kojascripts.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kojascripts.eu/new/crafting/configuration/api.md).

# API

***

## 🖥️ Server Exports

Exports allow other resources to interact with Koja-Crafting directly.

### AddExp Export

**Purpose**: Add experience points to a player programmatically from another resource.

#### Syntax

```lua
exports['koja-crafting']:AddExp(data)
```

#### Parameters

```lua
data = {
    identifier = 'steam:110000XXXXXXXX',  -- Player identifier (optional if playerId provided)
    playerId = 1,                         -- Server ID (optional if identifier provided)
    exp = 100                             -- Amount of XP to add
}
```

| Parameter    | Type   | Required     | Description                                |
| ------------ | ------ | ------------ | ------------------------------------------ |
| `identifier` | String | ⭕ Optional\* | Player's identifier (steam, license, etc.) |
| `playerId`   | Number | ⭕ Optional\* | Player's server ID                         |
| `exp`        | Number | ✅ Required   | Experience points to add                   |

\*One of `identifier` or `playerId` must be provided.

#### Examples

Example 1: Add XP by Player ID

{% code title="example.lua" %}

```lua
-- From your custom resource
exports['koja-crafting']:AddExp({
    playerId = 5,
    exp = 100
})
```

{% endcode %}

Example 2: Add XP by Identifier

{% code title="example.lua" %}

```lua
-- From your custom resource
local playerIdentifier = 'license:6435325123456789'
exports['koja-crafting']:AddExp({
    identifier = playerIdentifier,
    exp = 250
})
```

{% endcode %}

Example 3: Quest Reward

{% code title="quest.lua" %}

```lua
-- In your quest system
function CompleteQuest(playerId, questId)
    -- Your quest completion logic
    
    -- Reward crafting XP
    if questId == 'master_crafter_quest' then
        exports['koja-crafting']:AddExp({
            playerId = playerId,
            exp = 500
        })
    end
end
```

{% endcode %}

Example 4: Job Payout Bonus

{% code title="job.lua" %}

```lua
-- In your job script
RegisterServerEvent('myjob:completeMission')
AddEventHandler('myjob:completeMission', function()
    local source = source
    
    -- Normal job payout
    GivePlayerMoney(source, 5000)
    
    -- Bonus crafting XP
    exports['koja-crafting']:AddExp({
        playerId = source,
        exp = 50
    })
end)
```

{% endcode %}

#### How It Works

1. ✅ Validates player exists in database
2. ➕ Adds XP to player's current total
3. 📈 Automatically calculates level-ups
4. 💾 Saves to database
5. 📢 Notifies player if online

***

### AddBlueprint Export

**Purpose**: Grant a blueprint to a player programmatically from another resource.

#### Syntax

```lua
exports['koja-crafting']:AddBlueprint(identifier, blueprintName)
```

#### Parameters

| Parameter       | Type   | Required | Description                                 |
| --------------- | ------ | -------- | ------------------------------------------- |
| `identifier`    | String | ✅ Yes    | Player's identifier                         |
| `blueprintName` | String | ✅ Yes    | Blueprint item respname (not blueprintItem) |

⚠️ **Important**: Use the item's `respname`, not the `blueprintItem` name!

#### Examples

Example 1: Basic Usage

{% code title="example.lua" %}

```lua
-- From your custom resource
local playerIdentifier = 'license:64376347656789'
exports['koja-crafting']:AddBlueprint(playerIdentifier, 'parachute')
```

{% endcode %}

Example 2: Event Reward

{% code title="example.lua" %}

```lua
-- Event winner gets special blueprint
RegisterServerEvent('myevent:playerWon')
AddEventHandler('myevent:playerWon', function()
    local source = source
    local identifier = GetPlayerIdentifier(source, 0)
    
    exports['koja-crafting']:AddBlueprint(identifier, 'legendary_item')
end)
```

{% endcode %}

Example 3: Shop Purchase

{% code title="shop.lua" %}

```lua
-- In your shop script
function PurchaseBlueprint(playerId, blueprintName, price)
    local identifier = GetPlayerIdentifier(playerId, 0)
    
    if RemovePlayerMoney(playerId, price) then
        exports['koja-crafting']:AddBlueprint(identifier, blueprintName)
        TriggerClientEvent('chat:addMessage', playerId, {
            args = { '[Shop]', 'Blueprint purchased!' }
        })
    end
end
```

{% endcode %}

#### Blueprint Configuration Reference

In your `Config.Craftings`:

{% code title="config.lua" %}

```lua
blueprints = {
    {
        respname = 'parachute',              -- ← Use this in AddBlueprint()
        name = 'Parachute',
        blueprintItem = 'parachute_blueprint', -- ← NOT this
        -- ...
    }
}
```

{% endcode %}

{% hint style="warning" %}
Remember that player can use the item from inventory in ui to learn an blueprint!
{% endhint %}

***

### Place Crafting

**Purpose**: Enter placement mode for portable crafting station.

**Direction**: Server → Client

**When Triggered**:

* Player uses portable crafting item

#### Usage

```lua
-- Server-side
TriggerClientEvent('koja-crafting:client:placeCrafting', playerId, craftingType)
```

#### Parameters

| Parameter      | Type   | Description                      |
| -------------- | ------ | -------------------------------- |
| `playerId`     | Number | Player to trigger placement mode |
| `craftingType` | String | Crafting station type/ID         |
|                |        |                                  |

### <mark style="color:$info;">Using the export in inventory to place a station.</mark>

### OX-INVENTORY

Item definition (ox\_inventory/data/items.lua)

```lua
['weaponcrafting'] = {
  label = 'Weapon Crafting',
  weight = 10,
  craftingType = 'weapon_crafting',
  server = {
    export = 'koja-crafting.place_crafting' -- see bridge below
  }
},
```

### ESX

In **ESX**, you register the item as usable:

```lua
-- server.lua
ESX.RegisterUsableItem('weaponcrafting', function(playerId)
  local xPlayer = ESX.GetPlayerFromId(playerId)
  if not xPlayer then return end

  -- optional: remove item after use
  xPlayer.removeInventoryItem('weaponcrafting', 1)

  -- place crafting station
  exports['koja-crafting']:place_crafting({
    src = xPlayer.source,
    type = 'weapon_crafting',
  })
end)
```

### QB-CORE

In **QB**, create a useable item:

```lua
-- server.lua
QBCore.Functions.CreateUseableItem('weaponcrafting', function(source, item)
    local Player = QBCore.Functions.GetPlayer(source)
    if not Player then return end
    if not Player.Functions.GetItemByName(item.name) then return end

    -- optional: remove item
    Player.Functions.RemoveItem('weaponcrafting', 1)

    -- place crafting station
    exports['koja-crafting']:place_crafting({
        src = source,
        type = 'weapon_crafting',
    })
end)
```

***

## 🔄 Callbacks

Server callbacks for retrieving data.

### koja-crafting:server:checkForBlueprints

**Purpose**: Check player's inventory for blueprint items and automatically unlock them.

**Direction**: Client → Server

**Returns**: Result data with success status and blueprints found.

#### Usage

```lua
-- Client-side
KojaLib.Client.TriggerServerCallback('koja-crafting:server:checkForBlueprints', {}, function(result)
    if result.success then
        print('Blueprints found: ' .. result.blueprintsFound)
        print('Message: ' .. result.message)
    end
end)
```

#### Response Structure

```lua
{
    success = true,                    -- Boolean: Operation success
    message = 'Found 2 new blueprints!', -- String: Result message
    inventory = { ... },               -- Table: Updated inventory
    blueprintsFound = 2                -- Number: Count of new blueprints
}
```

#### Example Integration

{% code title="inventory.lua" %}

```lua
-- In your inventory script
RegisterCommand('checkblueprints', function()
    KojaLib.Client.TriggerServerCallback('koja-crafting:server:checkForBlueprints', {}, function(result)
        if result.success and result.blueprintsFound > 0 then
            ShowNotification('You discovered ' .. result.blueprintsFound .. ' new blueprints!')
        else
            ShowNotification('No new blueprints found.')
        end
    end)
end)
```

{% endcode %}

***

## 🔨 Integration Examples

### Example 1: Quest System Integration

Scenario: Give crafting XP and blueprint as quest reward.

{% code title="quest\_integration.lua" %}

```lua
-- In your quest script (server-side)
RegisterServerEvent('myquest:complete')
AddEventHandler('myquest:complete', function(questId)
    local source = source
    local identifier = GetPlayerIdentifier(source, 0)
    
    if questId == 'blacksmith_apprentice' then
        -- Give crafting XP
        exports['koja-crafting']:AddExp({
            playerId = source,
            exp = 250
        })
        
        -- Give weapon blueprint
        exports['koja-crafting']:AddBlueprint(identifier, 'advanced_weapon')
        
        -- Quest completion message
        TriggerClientEvent('chat:addMessage', source, {
            args = { '[Quest]', 'Crafting skills improved! Blueprint unlocked!' }
        })
    end
end)
```

{% endcode %}

***

## 📚 Related Documentation

* For command usage, see [Commands](broken://pages/0e6ece82256083bf42cd9a7b25d7a0a23d65f57f)
* For player progression details, see [Player Progression](broken://pages/4cab851ea84423a90a1b15aa48e7266fb2c30f98)
* For blueprint configuration, see [Crafting Stations](broken://pages/f456d4c63ebcdd2a50d34776bad5a3d7e3dcf189)
* For server setup, see [Server Settings](broken://pages/165d3835257c8a926c1239cfbd662f1df0c71b1b)

***

## 🆘 Getting Help with Integration

If you need help integrating Koja-Crafting with your scripts:

1. **Check examples above** for similar use cases
2. **Enable debug mode** to see what's happening
3. **Test with simple exports first** before complex integration
4. **Visit Discord**: <https://discord.gg/kojascripts>
5. **Read documentation**: <https://docs.kojascripts.eu>

***

Happy integrating! 🔌

*Remember: Koja-Crafting is designed to be easily integrated with other resources. Use exports for direct control, and events for dynamic updates.*