# events

***

## Client → Server

### `moh_carplay:syncmusic`

Triggered by the client when a player performs any action in the CarPlay UI. The server validates the request and forwards the event to all passengers.

```lua
TriggerServerEvent("moh_carplay:syncmusic", peds, vehNet, data)
```

#### Arguments

| Argument | Type     | Description                                           |
| -------- | -------- | ----------------------------------------------------- |
| `peds`   | `table`  | Array of server IDs for all current vehicle occupants |
| `vehNet` | `number` | Network ID of the vehicle                             |
| `data`   | `table`  | Action payload (see data structure below)             |

#### Server validation

Before forwarding, the server checks:

1. The vehicle entity exists (`veh ~= 0`).
2. The player who triggered the event is actually inside that vehicle.

If either check fails, the event is dropped and a warning is printed to the server console:

```lua
[CarPlay] Player 12 sent syncmusic but is not in vehicle 456 — ignored.
```

***

## Server → Client

### `moh_carplay:playsound`

Sent by the server to each passenger after a validated `syncmusic` event.

```lua
TriggerClientEvent("moh_carplay:playsound", playerId, data)
```

#### Data payload

| Field       | Type     | Required           | Description                                               |
| ----------- | -------- | ------------------ | --------------------------------------------------------- |
| `event`     | `string` | ✅                  | Action type (see table below)                             |
| `veh`       | `number` | ✅                  | Network ID of the vehicle                                 |
| `vehStr`    | `string` | ✅                  | String version of the network ID                          |
| `link`      | `string` | ✅ for `url`        | Direct audio URL                                          |
| `songName`  | `string` | ✅ for `url`        | Song name in `"Title by Artist"` format                   |
| `thumbnail` | `string` | ❌                  | Album art URL                                             |
| `vol`       | `number` | ✅ for `setVolume`  | New volume level (0–100, converted to 0.0–1.0 internally) |
| `newTime`   | `number` | ✅ for `selectTime` | Seek target in seconds                                    |

#### Event types

| `event` value   | Description                                                       |
| --------------- | ----------------------------------------------------------------- |
| `url`           | Stop any current playback and stream a new URL from the beginning |
| `pause`         | Pause current playback and save state to statebag                 |
| `resume`        | Resume paused playback                                            |
| `resetPlayback` | Destroy the sound and clear `currentSong` from the statebag       |
| `setVolume`     | Change volume and persist it to the statebag                      |
| `selectTime`    | Seek to a specific timestamp                                      |
| `restartSong`   | Seek back to position 0                                           |

***

## NUI → Client callbacks

These are internal callbacks between the CarPlay HTML UI and the Lua client.

### `closeCarPlay`

Called when the player closes the UI.

```lua
RegisterNUICallback("closeCarPlay", function(data, cb)
    SetNuiFocus(false, false)
    cb("ok")
end)
```

### `callback`

Called when the player performs any action inside the UI (play, pause, seek, volume, etc.). The client forwards the action to the server via `moh_carplay:syncmusic`.

```lua
RegisterNUICallback("callback", function(data, cb)
    -- data.veh    = vehicle network ID
    -- data.event  = action type
    -- ...
end)
```

***

## NUI messages (Client → UI)

The client sends these messages to the HTML interface via `SendNUIMessage`.

| Event             | When sent                      | Payload fields                                |
| ----------------- | ------------------------------ | --------------------------------------------- |
| `openCarPlay`     | Player opens the UI            | `veh`, `vehIdStr`, `currentSong`              |
| `playbackStarted` | A song begins playing          | `link`, `thumbnail`, `title`, `author`, `vol` |
| `updateTime`      | Every loop tick                | `time.currentTime`, `time.totalDuration`      |
| `resetPlayback`   | Song ends or is stopped        | *(none)*                                      |
| `setPicPaused`    | Player leaves vehicle mid-song | *(none)*                                      |


---

# Agent Instructions: 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:

```
GET https://mohssins.gitbook.io/mohscriptsdocs/moh-carplay/events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.