# API

## Events

### World interact

```lua
rcore_banners:server:worldInteract
```

* All data related to placing or removing banners will be sent via this event, along with any relevant information.
* Side: server
* Usage:

```lua
AddEventHandler('rcore_banners:server:worldInteract', function(bannerId, playerId, actionType, locationType)
    -- bannerId: DB-ID of banner.
    -- playerId: Player which has done some interaction in world.
    -- actionType: Which task has player done currently: [ADDED_BANNER, REMOVED_BANNER]
    -- locationType: When the interaction has happened? [WORLD, BILLBOARD]
end)
```

### Work stations

```
rcore_banners:server:Stations
```

* All data related to business stations, if any changes, there will be sent to this event.
* Side: server
* Usage:

```lua
AddEventHandler('rcore_banners:server:Stations', function(businessName, playerId, stationIdx, stationState, changeState, data)
    -- businessName: Name of business of which change is related to
    -- playerId: Player which has done some interaction at work station.
    -- stationIdx: Unique of station where the changes happened.
    -- stationState: What happend to station: [UPDATED_STATION, STARTED_PRODUCTION]
    -- changeState: Informational string change.
    -- data: Any relevant extra data that are associated with stationState / change state.
end)
```

### AddBannerIntoSystem

```
exports.rcore_banners:AddBannerIntoSystem
```

* Allow to create own banner from your own resource to defined into banners
* Side: server
* Type: export
* Usage:

```lua
local state, statusCode = exports.rcore_banners:AddBannerIntoSystem({
    banner_name = 'banner_name', -- Name of the banner
    banner_type = 'custom', -- Type needs to be custom!
    banner_image = 'banner_image_url' -- Link to your banner image (Accepting only: image/png, image/jpg image/gif)
})

if state then
    print('Banner was defined into rcore_banners resource')
end
```

### AddBannerToPlayerInventory

```
exports.rcore_banners:AddBannerToPlayerInventory
```

* Allow to give banner item, which exist in the banners resource via export.
* Side: server
* Type: export
* Usage:

```lua
local playerId = 1
local amount = 10
local bannerName = 'rcore_banners'

local itemState, itemStatusCode = exports.rcore_banners:AddBannerToPlayerInventory(playerId, amount, {
    banner_name = bannerName,
})

if itemState then
    print('Banner item was added to the player')
end
```

### Billboards

```
rcore_banners:server:Billboards
```

* All data related to billboards, if any changes, there will be sent to this event.
* Side: server
* Usage:

```lua
AddEventHandler('rcore_banners:server:Billboards', function(session)
    -- session - Array of data related to billboard changes

    -- Example session structure:
    -- session = {
    --     initiator: playerId,                          -- Player initiating the action
    --     initiatorName: GetPlayerName(playerId),       -- Name of the player initiating the action
    --     billboardId: billboardId,                     -- ID of the billboard involved in the action
    --     owner: owner,                                 -- Owner of the billboard (business/faction)
    --     action: 'buyBillboard',                       -- Type of action: [buyBillboard, sellBillboard, setBillboardImage, transferBillboard]
    
    --     data: {
    --         -- Specific dynamic data related to the action
    --         -- For example, if action is 'sellBillboard'
    --         sellPrice: sellPrice,                    -- Selling price of the billboard
    --         targetSociety: targetSociety,            -- Target business to sell the billboard to
    --         targetSocietyCut: targetSocietyCut,      -- Cut for the target business from the sale
    --         ownedBusinessReturn: ownedBusinessReturn  -- Return amount for the owned business
    --     }
    --     OR
    --     data: {
    --         -- Specific dynamic data related to the action
    --         -- For example, if action is 'setBillboardImage'
    --         side: side,                               -- Side of the billboard (if applicable A or B)
    --         banner_name: data['banner_name'],         -- Name of the banner
    --         banner_image: data['banner_image']        -- URL or data of the new billboard image
    --     }
    -- }

    -- Handle the changes based on the action type
    if session.action == 'buyBillboard' then
        -- Handle buy billboard logic
    elseif session.action == 'sellBillboard' then
        -- Handle sell billboard logic
    elseif session.action == 'setBillboardImage' then
        -- Handle set billboard image logic

        local side = session.data.side
        local bannerName = session.data.banner_name
        local bannerImage = session.data.banner_image
    elseif session.action == 'transferBillboard' then
        -- Handle transfer billboard logic
    end
end)
```


---

# 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://documentation.rcore.cz/paid-resources/rcore_banners/api.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.