> For the complete documentation index, see [llms.txt](https://docs.cuxial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuxial.com/scripts/vehicles/cuxial-chipeo/developers.md).

# Exports & events

Public API of Cuxial Chipeo: server exports to install, remove, damage and read a vehicle's sound system.

Install or remove the equipment from a workshop script, check it from a garage, or read what a car is playing. All exports are server-side and identify the vehicle by its plate.

{% hint style="info" %}
Plates are trimmed and converted to upper case before they are compared, so `' abc 123 '` and `'ABC 123'` are the same vehicle.
{% endhint %}

## Server exports

### IsRadioInstalled

Tells whether a vehicle has the equipment installed.

```lua
exports.cuxial_chipeo:IsRadioInstalled(plate)
```

| Parameter | Type   | Description           |
| --------- | ------ | --------------------- |
| `plate`   | string | Plate of the vehicle. |

**Returns:** `boolean`.

```lua
if exports.cuxial_chipeo:IsRadioInstalled(plate) then
    print('This vehicle has a sound system')
end
```

### InstallRadio

Installs the equipment without the item, the progress bar or any check on the vehicle model.

```lua
exports.cuxial_chipeo:InstallRadio(plate, installedBy)
```

| Parameter     | Type          | Description                                                                                                                                  |
| ------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `plate`       | string        | Plate of the vehicle.                                                                                                                        |
| `installedBy` | string \| nil | Character identifier of the installer. That character can control the radio from outside and remove the equipment, like the owner. Optional. |

**Returns:** `boolean`. `false` when the plate is empty or the vehicle already has equipment.

```lua
local ok = exports.cuxial_chipeo:InstallRadio(plate, citizenid)
```

### UninstallRadio

Removes the equipment, stops what was playing and clears the fried state.

```lua
exports.cuxial_chipeo:UninstallRadio(plate)
```

| Parameter | Type   | Description           |
| --------- | ------ | --------------------- |
| `plate`   | string | Plate of the vehicle. |

**Returns:** `boolean`. `false` when the vehicle had no equipment.

{% hint style="warning" %}
Have the USB stick ejected before calling this export. It returns no item, and a stick left inside stays linked to that plate.
{% endhint %}

```lua
exports.cuxial_chipeo:UninstallRadio(plate)
```

### SetDamaged

Fries or repairs the equipment. A fried system is limited to `overheat.damagedMaxVolume` and `overheat.damagedMaxBass`.

```lua
exports.cuxial_chipeo:SetDamaged(plate, damaged)
```

| Parameter | Type    | Description                                     |
| --------- | ------- | ----------------------------------------------- |
| `plate`   | string  | Plate of the vehicle.                           |
| `damaged` | boolean | `true` fries the equipment, `false` repairs it. |

**Returns:** `boolean`. `false` when the vehicle has no equipment.

```lua
-- Repair for free from your own workshop script
exports.cuxial_chipeo:SetDamaged(plate, false)
```

### GetSession

Returns the playback state of a vehicle.

```lua
local session = exports.cuxial_chipeo:GetSession(plate)
```

| Parameter | Type   | Description           |
| --------- | ------ | --------------------- |
| `plate`   | string | Plate of the vehicle. |

**Returns:** `table | nil`. `nil` when nobody has opened the radio of that vehicle since it spawned.

| Field           | Type          | Description                                                                            |
| --------------- | ------------- | -------------------------------------------------------------------------------------- |
| `plate`         | string        | Plate.                                                                                 |
| `netId`         | number        | Network id of the vehicle.                                                             |
| `model`         | number        | Model hash.                                                                            |
| `url`           | string \| nil | Link being played. `nil` when stopped.                                                 |
| `title`         | string \| nil | Name of the track.                                                                     |
| `playing`       | boolean       | `true` while playing, `false` when paused or stopped.                                  |
| `offset`        | number        | Position of the track, in seconds, at the moment `startedAt` was taken.                |
| `startedAt`     | number        | Server timer, in milliseconds, when playback started or resumed. `0` when not playing. |
| `serverNow`     | number        | Server timer, in milliseconds, when this table was built.                              |
| `volume`        | number        | Current volume. `1.0` is normal.                                                       |
| `maxVolume`     | number        | Volume limit of this model.                                                            |
| `bass`          | number        | Bass level.                                                                            |
| `bassHz`        | number        | Subwoofer cut-off, in Hz.                                                              |
| `punch`         | number        | Punch level.                                                                           |
| `eq`            | number\[]     | Gain of each equalizer band, in dB.                                                    |
| `distance`      | number        | Current range of the sound, in metres.                                                 |
| `maxDistance`   | number        | Range limit of this model.                                                             |
| `damaged`       | boolean       | `true` when the equipment is fried.                                                    |
| `open`          | boolean       | `true` when a door or window was open the last time it was changed from the head unit. |
| `windowsDown`   | number        | Windows rolled down, 0 to 4.                                                           |
| `windowsIntact` | number        | Windows not broken, 0 to 4.                                                            |
| `heat`          | number        | Overheating counter, from 0 to `overheat.seconds`.                                     |
| `pressure`      | number        | Cabin pressure counter, from 0 to `pressure.seconds`.                                  |

```lua
local session = exports.cuxial_chipeo:GetSession(plate)
if session and session.playing then
    local position = session.offset + (session.serverNow - session.startedAt) / 1000
    print(('%s is at second %.0f'):format(session.title, position))
end
```

## State bags

The same data is replicated on the vehicle entity, so a client script can read it without a callback. Treat both as read-only.

| State bag    | Content                                                                                    |
| ------------ | ------------------------------------------------------------------------------------------ |
| `chipeo`     | The table returned by `GetSession`. `nil` when the vehicle has no session.                 |
| `chipeoHeat` | `{ heat, max, pressure }`: overheating counter, its limit, and cabin pressure from 0 to 1. |

```lua
local session = Entity(vehicle).state.chipeo
if session and session.playing then
    print(session.title)
end
```

## Events

Cuxial Chipeo has no public events. The events it registers are internal and can change between versions.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cuxial.com/scripts/vehicles/cuxial-chipeo/developers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.