> For the complete documentation index, see [llms.txt](https://dirkscripts.gitbook.io/dirkscripts-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dirkscripts.gitbook.io/dirkscripts-documentation/resources/dirk-lib/devtools.md).

# DevTools

{% hint style="info" %}
Client Module
{% endhint %}

A suite of in-game developer tools accessible via the `/devtools` command or individually by their own slash commands. Tools are registered with the `DevTool` class and can be extended with custom entries.

## /devtools

Opens a context menu listing all registered dev tools alphabetically.

## Built-in Tools

### /vector4

Copies your current position and heading as a `vector4(x, y, z, heading)` to the clipboard.

### /vector3

Copies your current position as a `vector3(x, y, z)` to the clipboard.

### /vector2

Copies your current position as a `vector2(x, y)` to the clipboard.

### /camPos

Copies the camera position and rotation to the clipboard.

### /getPosition

Interactive point placement tool. Place one or multiple points with a visual marker, then copies the coordinates to the clipboard.

**Controls:** `E` add point, `G` cancel, `B` delete last point, `LMB` confirm all (multi mode).

### /placeEntity

Interactive entity placement tool with rotation controls. Spawns an entity, lets you position it, then copies the final position and rotation to the clipboard.

### /polygonCreator

Interactive polygon point creator with adjustable height. Place points to define a polygon boundary, then copies the formatted points to the clipboard.

**Controls:** `E` add point, `G` cancel, `B` delete last, `↑`/`↓` adjust height, `LMB` confirm.

### /viewModels

Toggles the display of nearby object model names and health as 3D text above each prop.

***

## DevTool API

### DevTool.register

Register a custom dev tool.

```lua
DevTool.register('myTool', {
    label = 'My Tool',
    description = 'Does something useful',
    icon = 'wrench',
    action = function()
        print('Tool activated')
    end,
    command = true, -- also registers /myTool command
})
```

| Property    | Type     | Required | Description                              |
| ----------- | -------- | -------- | ---------------------------------------- |
| label       | string   | yes      | Display label in menu                    |
| description | string   | yes      | Description text                         |
| icon        | string   | yes      | Icon name                                |
| action      | function | yes      | Function to run when selected            |
| command     | boolean  | no       | Also register as a `/name` slash command |

### DevTool.get

Get a registered dev tool by name.

```lua
local tool = DevTool.get('myTool')
```

### DevTool.getAll

Get all registered dev tools.

```lua
local tools = DevTool.getAll()
```

### DevTool.delete

Remove a registered dev tool.

```lua
DevTool.delete('myTool')
```

***

## Exported Functions

### lib.getPosition

Interactive point placement. Returns placed coordinate(s) or `false` if cancelled.

```lua
local pos = lib.getPosition()                    -- single point → vector3
local positions = lib.getPosition(true)          -- multiple points → formatted string
local bounded = lib.getPosition(true, 50.0)      -- max 50 units from start
local inZone = lib.getPosition(false, polyTable) -- constrained to polygon
```

| Parameter | Type            | Required | Description                                                           |
| --------- | --------------- | -------- | --------------------------------------------------------------------- |
| multiple  | boolean         | no       | Collect multiple points before confirming                             |
| bounds    | table \| number | no       | Polygon table for boundary check, or max distance from starting point |

**Returns:** `vector3` (single), `string` (multiple, formatted), or `false` (cancelled)

### lib.placeEntity

Interactive entity placement.

```lua
local result = lib.placeEntity('object', 'prop_bench_01a', 50.0, true)
if result then
    print(result.pos, result.rot)
end
```

| Parameter   | Type            | Required | Description                         |
| ----------- | --------------- | -------- | ----------------------------------- |
| \_type      | string          | yes      | `'object'`, `'vehicle'`, or `'ped'` |
| model\_name | string          | yes      | Model name to spawn                 |
| bounds      | number \| table | no       | Distance or polygon constraint      |
| networked   | boolean         | no       | Create a networked entity           |

**Returns:** `{ rot: vector3, pos: vector4 }` or `false` if cancelled. Also copies to clipboard.

### lib.createPolygon

Interactive polygon creation.

```lua
local polygon = lib.createPolygon()
if polygon then
    print(polygon) -- formatted point string
end
```

| Parameter | Type            | Required | Description         |
| --------- | --------------- | -------- | ------------------- |
| bounds    | table \| number | no       | Boundary constraint |

**Returns:** `string` (formatted polygon points) or `false` if cancelled.