> 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/free/carmarket/zones.md).

# Zones

Market zones define **where players can list and buy vehicles**. Each zone has an NPC, a blip, and a set of parking slot boxes (where vehicles are physically displayed for sale).

## Structure

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

```lua
Config.Zones = {
    {
        id = "zone1",
        coords = vector4(-2187.8787, -409.0271, 13.1511, 231.3093),
        distance = 1.5,
        name = "Mark",
        blip = {
            sprite = 1,
            colour = 1,
            scale = 1.0,
            display = 4,
        },
        npc = {
            name = "Mark",
            hash = 0x18CE57D0,
            scenario = "WORLD_HUMAN_CLIPBOARD",
            target = {
                icon = "fas fa-shopping-basket",
                label = "Mark - Car Market",
                distance = 2.0,
                key = 38,
            },
        },
        CarMarketBoxes = {
            { id = 'zone1_slot1', coords = vec3(-2160.43, -402.35, 13.39), size = vec3(3, 5, 3), rotation = 82.9 },
            { id = 'zone1_slot2', coords = vec3(-2159.97, -396.41, 13.39), size = vec3(3, 5, 3), rotation = 82.9 },
            { id = 'zone1_slot3', coords = vec3(-2158.71, -390.22, 13.39), size = vec3(3, 5, 3), rotation = 82.9 },
        },
    },
    -- more zones...
}
```

{% endcode %}

## Fields

| Field            | Type      | Purpose                                                        |
| ---------------- | --------- | -------------------------------------------------------------- |
| `id`             | `string`  | **Unique** identifier (referenced in DB, slot ownership, etc.) |
| `coords`         | `vector4` | NPC position + heading                                         |
| `distance`       | `number`  | Interaction radius (meters)                                    |
| `name`           | `string`  | Display name (shown in UI)                                     |
| `blip`           | `table`   | Standard FiveM blip config                                     |
| `npc`            | `table`   | Ped model + scenario + targeting config                        |
| `CarMarketBoxes` | `table[]` | Slot boxes where listed vehicles spawn                         |

### CarMarketBoxes

Each box represents one **physical slot** in the world.

| Field      | Type     | Purpose                                               |
| ---------- | -------- | ----------------------------------------------------- |
| `id`       | `string` | Unique slot ID — players buy individual slots by this |
| `coords`   | `vec3`   | World position of the slot                            |
| `size`     | `vec3`   | Bounding box used for proximity checks                |
| `rotation` | `number` | Heading the vehicle spawns with                       |

{% hint style="info" %}
Slot `id`s must be **globally unique**, not just within a zone. Default convention is `<zoneId>_slot<N>`.
{% endhint %}

## Adding a new zone

{% stepper %}
{% step %}

### Pick coords in-game

Use `/copycoords` from `koja-lib` or any dev tool to grab `vector4` for the NPC spawn.
{% endstep %}

{% step %}

### Add the zone entry

Append a new table to `Config.Zones` with a unique `id`.
{% endstep %}

{% step %}

### Place slot boxes

Walk around the parking area and place 3–10 `CarMarketBoxes`. Each `coords` should be the **center** of where a parked car will sit.

{% hint style="warning" %}
Slot boxes within 1.5m of each other will be flagged as "occupied" if either has a car — keep them spaced out.
{% endhint %}
{% endstep %}

{% step %}

### Restart and test

`refresh` and `restart koja-carmarket`. The blip + NPC should appear at the new zone.
{% endstep %}
{% endstepper %}

## Default zones shipped

| Zone ID | Name         | Location                      |
| ------- | ------------ | ----------------------------- |
| `zone1` | Mark         | Mark's car shop, near La Mesa |
| `zone2` | Legion       | Legion Square                 |
| `zone3` | Sandy Shores | Sandy Shores                  |
| `zone4` | Lotnisko     | LSIA airport area             |
| `zone5` | Paleto       | Paleto Bay                    |

Feel free to remove or replace any of them — they're examples.