# Points

The points system lets you define coordinate-based trigger zones. When a player enters, exits, or stays near a point, callbacks fire automatically.

***

## Creating a Point

```lua
local point = KOJA.Client.points.new(properties)
```

### Properties

| Field      | Type             | Required | Description                                                   |
| ---------- | ---------------- | -------- | ------------------------------------------------------------- |
| `coords`   | `vector3`        | Yes      | Centre of the zone                                            |
| `distance` | `number`         | Yes      | Radius in metres                                              |
| `onEnter`  | `function(self)` | No       | Called once when the player enters the zone                   |
| `onExit`   | `function(self)` | No       | Called once when the player exits the zone                    |
| `nearby`   | `function(self)` | No       | Called repeatedly (every \~300 ms) while the player is inside |

Any additional fields you add become properties of the point object and are accessible in callbacks via `self`.

**Returns** `CPoint` — the point object.

***

## Point Object

| Property / Method       | Description                                               |
| ----------------------- | --------------------------------------------------------- |
| `point.id`              | Unique numeric ID                                         |
| `point.coords`          | `vector3` position                                        |
| `point.distance`        | Radius                                                    |
| `point.currentDistance` | Distance from the player right now (only set when nearby) |
| `point.isClosest`       | `true` when this is the closest active point              |
| `point:remove()`        | Removes the point and clears all callbacks                |

***

## Examples

### Simple Enter/Exit

```lua
local atm = KOJA.Client.points.new({
    coords   = vector3(100.0, 200.0, 30.0),
    distance = 2.0,

    onEnter = function(self)
        print('Near ATM')
    end,

    onExit = function(self)
        print('Left ATM')
    end,
})
```

### Recurring Nearby Check

```lua
KOJA.Client.points.new({
    coords   = vector3(100.0, 200.0, 30.0),
    distance = 10.0,

    nearby = function(self)
        -- runs every ~300 ms while the player is within 10 m
        DrawMarker(1, self.coords.x, self.coords.y, self.coords.z, ...)
    end,
})
```

### Custom Properties

```lua
local shop = KOJA.Client.points.new({
    coords    = vector3(25.0, -1335.0, 29.5),
    distance  = 3.0,
    shopType  = 'weapons',   -- custom field

    onEnter = function(self)
        print('Entered shop type:', self.shopType)
    end,
})
```

### Removing a Point

```lua
local point = KOJA.Client.points.new({ ... })

-- later:
point:remove()
```

***

## Static Methods

```lua
-- All registered points
local all = KOJA.Client.points.getAllPoints()

-- Points within their distance radius of the player right now
local nearby = KOJA.Client.points.getNearbyPoints()

-- The single closest point to the player
local closest = KOJA.Client.points.getClosestPoint()
```

***

## SetInterval / ClearInterval

The points module also exposes interval helpers for recurring tasks.

```lua
local id = SetInterval(function()
    -- runs every 1000 ms
end, 1000)

-- Update the interval without stopping it
SetInterval(id, 2000)

-- Stop it
ClearInterval(id)
```

***

## Resource Cleanup

Points created by a resource are automatically removed when that resource stops. No manual cleanup is needed.

## Related pages

- [Callbacks](/koja-lib/api-reference/client-api/callbacks) — koja-lib provides a callback system that lets client scripts request data from the server and vice versa.
- [Inventory](/koja-lib/api-reference/client-api/inventory) — Client-side inventory functions let you check what items the local player has without a server round-trip.
- [DUI](/koja-lib/api-reference/client-api/dui) — DUI (Dynamic UI) allows you to render a web page as a texture on any in-game surface — screens, billboards, laptops, phones, etc.
- [Money](/koja-lib/api-reference/client-api/money) — Retrieve the local player's money balance from the client side via a server callback.
- [Keybinds](/koja-lib/api-reference/client-api/keybinds) — Register persistent key bindings that players can rebind in the GTA V settings menu.
- [Notifications](/koja-lib/api-reference/client-api/notifications) — koja-lib provides two notification interfaces: SendNotify (routes through the configured backend) and LibNotify (built-in koja-lib notification).
- [Client API](/koja-lib/api-reference/client-api) — back to the section overview