> For the complete documentation index, see [llms.txt](https://petrisservices.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://petrisservices.gitbook.io/docs/scripts/capture-the-area/usage.md).

# Usage

### Command

> <mark style="color:blue;">**/startcapturethearea**</mark> <mark style="color:purple;">zonename</mark>

{% hint style="info" %}
You can use it from the <mark style="background-color:green;">console</mark> or <mark style="background-color:orange;">in-game</mark> if you have the <mark style="color:red;">permissions</mark> you've set in <mark style="color:purple;">IsAllowedToStart()</mark> configurable open function.
{% endhint %}

### Exports

#### Start Event Out Of Schedule (Server-Sided)

```lua
exports["petris-capturethearea"]:StartEvent() -- For Random Area Selection

exports["petris-capturethearea"]:StartEvent("AreaName") -- For Specific Area
```

#### Check If Player Is Capturing (Client-Sided)

```lua
exports["petris-capturethearea"]:IsPlayerCapturing()
```

#### Check If Player Is In Zone (Client-Sided)

```lua
exports["petris-capturethearea"]:IsPlayerInZone()
```

### Weekly Schedule Configuration

```lua
Schedule = {
        ['Monday'] = {
            {zone = "House", hour = 14, minute = 0}, -- 14:00 - 2:00PM
            {zone = "random", hour = 18, minute = 30}, -- 18:30 - 6:30PM
        },
        ['Tuesday'] = {
            {zone = "House", hour = 14, minute = 0}, -- 14:00 - 2:00PM
            {zone = "random", hour = 18, minute = 30}, -- 18:30 - 6:30PM
        },
        ['Wednesday'] = {
            {zone = "House", hour = 14, minute = 0}, -- 14:00 - 2:00PM
            {zone = "random", hour = 18, minute = 30}, -- 18:30 - 6:30PM
        },
        ['Thursday'] = {
            {zone = "House", hour = 14, minute = 0}, -- 14:00 - 2:00PM
            {zone = "random", hour = 18, minute = 30}, -- 18:30 - 6:30PM
        },
        ['Friday'] = {
            {zone = "House", hour = 14, minute = 0}, -- 14:00 - 2:00PM
            {zone = "random", hour = 18, minute = 30}, -- 18:30 - 6:30PM
        },
        ['Saturday'] = {
            {zone = "House", hour = 14, minute = 0}, -- 14:00 - 2:00PM
            {zone = "random", hour = 18, minute = 30}, -- 18:30 - 6:30PM
        },
        ['Sunday'] = {
            {zone = "House", hour = 14, minute = 0}, -- 14:00 - 2:00PM
            {zone = "random", hour = 18, minute = 30}, -- 18:30 - 6:30PM
        }
    },
```

{% hint style="info" %} <mark style="color:purple;">In the zone value</mark>, you can either set <mark style="color:orange;">"random"</mark> to let the script select one of your configured zones or the name of a specific zone of your configured zones.
{% endhint %}

### Areas/Zones Configuration

<pre class="language-lua"><code class="lang-lua">Zones = {
        ["House"] = {
            ["Area"] = { -- INFO: /pzcreate: to start a polyzone creation, /pzadd to add a point in the polyzone, /pzfinish to finish the creation of the polyzone.
                vector2(3275.9729003906, 5182.8525390625),
                vector2(3286.1896972656, 5196.1513671875),
                vector2(3288.8740234375, 5197.8774414063),
                vector2(3307.4431152344, 5200.8916015625),
                vector2(3333.015625, 5181.2436523438),
                vector2(3315.8989257813, 5158.84765625),
                vector2(3312.8894042969, 5160.7846679688),
                vector2(3309.7436523438, 5156.7666015625)
            },
            ["Blip"] = {
                Coords = vector3(3305.22,5178.94,17.16)
            },
            ["Settings"] = {
                visible = true,
                minZ = 17.0, 
                maxZ = 37.0,
            },
            ["Duration"] = 2, -- INFO: Duration in minutes.
            ["Bucket"] = 1, -- INFO: Use 0 if you don't want an exclusive area bucket.
<strong>            ["ViewDistance"] = 100.0, -- INFO: View distance to see the zone if setted to be visible.
</strong>            ["Rewards"] = { -- INFO: You can add any types, names and amount of rewards as the reward function is open source and you can handle freely the function.
                {type = "item", name = "bread", amount = 5},
                {type = "weapon", name = "WEAPON_PISTOL", amount = 50},
                {type = "money", name = "black_money", amount = 1000}
            }
        }
    },
</code></pre>

{% hint style="info" %} <mark style="color:purple;">In order to create a zone properly</mark>, you must create a polyzone via [PolyZone ](https://github.com/mkafrin/PolyZone)script.\
\ <mark style="color:green;">**/pzcreate**</mark> : To start the creation of a zone.\ <mark style="color:yellow;">**/pzadd**</mark> : To add points of a zone. (Better use zone corners for points)\ <mark style="color:red;">**/pzfinish**</mark> : To finish the zone. After that, a text file will be generated in the same location where your server.cfg is located at.
{% endhint %}

### Open Framework Functions

{% code fullWidth="false" %}

```lua
Functions = {
        TriggerCronTask = function(h, m) -- INFO: ESX Cron is used here. Change it if you're using something else.
            TriggerEvent('cron:runAt', h, m, StartCaptureTheArea)
        end,
        RewardPlayer = function(playerId, reward) -- INFO: In this function, you can handle any type of rewards the capturer will receive.
            -- ESX EXAMPLE
            if reward.type == 'item' then
                local xPlayer = Config.Framework.GetPlayerFromId(playerId)
                xPlayer.addInventoryItem(reward.name, reward.amount)
            end
        end,
        GetPlayerGroup = function(playerId) -- INFO: This is used to avoid capturing being paused by friends 
            -- ESX EXAMPLE
            local xPlayer = Config.Framework.GetPlayerFromId(playerId)
            return xPlayer.job.name
        end,
        SendNotificationToPlayer = function(playerId, text)
            -- ESX EXAMPLE
            TriggerClientEvent('esx:showNotification', playerId, text)
        end,
        Announcement = function(text)
            -- ESX EXAMPLE (Notification)
            -- RECOMMENDATION: It would be better if you replace the notification with a chat message instead.
            TriggerClientEvent('esx:showNotification', -1, text)
        end,
        IsStaff = function(playerId)
            -- ESX EXAMPLE
            local xPlayer = Config.Framework.GetPlayerFromId(playerId)
            if xPlayer.getGroup() ~= 'user' then
                return true
            end
            return false
        end,
        IsAllowedToStart = function(playerId)
            -- ESX EXAMPLE
            local xPlayer = Config.Framework.GetPlayerFromId(playerId)
            if xPlayer.getGroup() == 'superadmin' then
                return true
            end
            return false
        end
    }
```

{% endcode %}

{% hint style="info" %}
We've added <mark style="color:orange;">ESX functionality</mark> as it's the most popular framework right now, <mark style="color:green;">but you can use any framework</mark> and make the script work.\
\
If you need extra assistance, please don't hesitate to open a ticket on my [Discord Server.](https://discord.gg/x4487hW9FC)
{% endhint %}