> 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/koja-lib/api-reference/client-api/points.md).

# 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.


---

# 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.kojascripts.eu/koja-lib/api-reference/client-api/points.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.