> For the complete documentation index, see [llms.txt](https://docs.lostdev.store/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lostdev.store/territories/integration.md).

# Integration

This page covers everything you need to integrate another script with **ld\_territories** — querying territory data, and hooking into capture outcomes and reward delivery. Everything else (NUI communication, internal client/server sync) is implementation detail and not meant to be used from other resources.

## Exports

All exports run on the **server**. Call them from another server-side script with `exports['ld_territories']:FunctionName(...)`.

| Export                    | Signature                          | Description                                                                |
| ------------------------- | ---------------------------------- | -------------------------------------------------------------------------- |
| `GetTerritory`            | `(territoryId) -> table\|nil`      | Full state of one territory (owner, progress, state, coords, radius, ...). |
| `GetTerritories`          | `() -> table<string, table>`       | State of every territory, keyed by territory id.                           |
| `GetTerritoryOwner`       | `(territoryId) -> string\|nil`     | Identifier of the current owning faction, or `nil` if unowned.             |
| `IsPlayerInsideTerritory` | `(source, territoryId) -> boolean` | Whether a player is currently inside a given territory.                    |
| `IsTerritoryContested`    | `(territoryId) -> boolean`         | Whether a territory is currently contested by more than one faction.       |

### Example

```lua
local territory = exports['ld_territories']:GetTerritory('grove')

if territory then
    print(('%s is owned by: %s (%.1f%% control)'):format(
        territory.label, territory.owner or 'nobody', territory.progress))
end

if exports['ld_territories']:IsPlayerInsideTerritory(source, 'grove') then
    -- give a bonus, block an action, trigger a scene, etc.
end
```

## Reward events (required if you use per-territory rewards)

If you configure `money`, `items`, `experience`, or a `custom` reward in `config/territories.lua` for any territory, **you must handle these events yourself** — ld\_territories does not touch your framework's money/inventory system directly, so it stays compatible with any economy or inventory setup.

| Event                           | Payload                                 | When it fires                             |
| ------------------------------- | --------------------------------------- | ----------------------------------------- |
| `territories:reward:money`      | `source, amount, territoryId`           | A capturing player earned a money reward. |
| `territories:reward:item`       | `source, itemName, amount, territoryId` | A capturing player earned an item reward. |
| `territories:reward:experience` | `source, amount, territoryId`           | A capturing player earned an XP reward.   |

### Example (server-side, in your own script)

```lua
AddEventHandler('territories:reward:money', function(source, amount, territoryId)
    -- e.g. for qbx_core:
    local player = exports.qbx_core:GetPlayer(source)
    if player then
        player.Functions.AddMoney('cash', amount, 'territory-reward')
    end
end)

AddEventHandler('territories:reward:item', function(source, itemName, amount, territoryId)
    exports.ox_inventory:AddItem(source, itemName, amount)
end)
```

## Optional: reacting to territory outcomes

If another script needs to react whenever a territory changes hands (e.g. announce it, trigger a mission, adjust another system), you can listen for these **server-side** events. They fire once per outcome, regardless of how many players are online.

| Event                          | Payload                           | Fires when                                                                    |
| ------------------------------ | --------------------------------- | ----------------------------------------------------------------------------- |
| `territories:ownerChanged`     | `territoryId, newOwner, oldOwner` | A territory's owner changes (capture, admin override, or the owner loses it). |
| `territories:captureCompleted` | `territoryId, newOwner, oldOwner` | A capture finishes successfully.                                              |
| `territories:contested`        | `territoryId, contestedFactions`  | A territory becomes contested.                                                |
| `territories:cooldownStarted`  | `territoryId, duration`           | A territory enters cooldown after a capture.                                  |
| `territories:cooldownEnded`    | `territoryId`                     | A territory's cooldown ends.                                                  |

### Example

```lua
AddEventHandler('territories:ownerChanged', function(territoryId, newOwner, oldOwner)
    if newOwner then
        TriggerEvent('my-script:announce', ('%s just took %s!'):format(newOwner, territoryId))
    end
end)
```

{% hint style="info" %}
These are all standard server-side `TriggerEvent`s — any resource can listen to them with `AddEventHandler`, no extra setup required.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.lostdev.store/territories/integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.