> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roadshop.org/llms.txt
> Use this file to discover all available pages before exploring further.

# RoadPhone Fold

> Configure the foldable phone included with RoadPhone Pro

<Info>
  **RoadPhone Fold is included with RoadPhone Pro.** It uses the same `roadphone` resource, apps, data and exports. No separate Fold purchase or second phone resource is required.
</Info>

## Configure the Fold item

Keep the resource named `roadphone`. Add the Fold item to your inventory's item definitions and shops, then configure its name in `config.lua`:

```lua config.lua theme={null}
Config.FoldableItems = { 'phone_fold' }
Config.FoldKey = ''
Config.FoldProps = {
    closed = { model = 'roadphone_fold_closed' },
    open = { model = 'roadphone_fold_open' },
}
```

| Setting                         | Purpose                                                                                                 |
| ------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `Config.FoldableItems`          | Item names that open as Fold. Automatically merged into RoadPhone's internal `Config.Items` list.       |
| `Config.FoldKey`                | Default keyboard binding. Empty means unbound; players assign a key in the game's key-binding settings. |
| `Config.FoldProps.closed.model` | Closed phone prop.                                                                                      |
| `Config.FoldProps.open.model`   | Unfolded phone prop.                                                                                    |

Automatic registration inside RoadPhone does **not** create an inventory item definition or put the item in a shop. Use your existing Pro inventory integration. Each device needs its own slot when using metadata.

## Fold and unfold

1. Use the Fold item from the inventory to select the correct device.
2. Click the hinge button, run `/roadphone_fold`, or use the assigned key.
3. The interface changes width and the model held by the character switches between the closed and open props.

The command only acts while a Fold phone is open. It does not open the phone or convert a regular Pro item.

| Mode                         | Saved state                                                                    |
| ---------------------------- | ------------------------------------------------------------------------------ |
| `Config.UseMetadata = true`  | `phone_settings.unfolded` on the selected item; follows the phone when traded. |
| `Config.UseMetadata = false` | Client KVP `roadphone_unfolded`; shared between that client's Fold devices.    |

Fold selection uses the configured `phone_fold` item name. Metadata mode controls per-item data and fold-state persistence.

## Apps on the wider screen

Fold uses the existing Pro apps and account sessions. Unfolding does not create a second number or app installation.

* **List and detail panes:** Notes, Reminders and DarkChat keep navigation beside the selected content.
* **Sidebars and navigation rails:** Clock, Calls, Taxi, Music, Connect, Wave, Bank and Loop adapt their navigation.
* **Wider layouts:** Messages, Contacts, Mail, Gallery, Settings, Calendar, Maps, Weather, Garage, Wallet, Events, Eats and other adapted apps use the extra space.
* **Compatibility layout:** Apps without a Fold layout, including the current custom-app route, remain in a centered phone-width column.

The home screen retains its four-column app grid and compact dock. An unfolded Fold does not use the regular phone's landscape rotation.

## Included 3D props

Keep these shipped files when updating:

```text theme={null}
stream/prop/roadphone_fold_closed.ydr
stream/prop/roadphone_fold_open.ydr
stream/prop/roadphone_fold.ytyp
```

The supplied manifest loads the model definitions. Each `Config.FoldProps` entry may also specify `offset` and `rotation`; otherwise the normal phone attachment defaults apply.

With `Config.UsePhoneProps = false`, the closed phone uses the standard game phone prop. The unfolded model still uses `Config.FoldProps.open`.

## Integration and exports

Use the same [client](/roadphonepro/api/client), [server](/roadphonepro/api/server) and [metadata exports](/roadphonepro/api/metadata) as Pro. See the [complete export index](/roadphonepro/api/exports).

Trigger the normal fold action from a **client** resource:

```lua theme={null}
ExecuteCommand('roadphone_fold')
```

Read the saved setting from a **server** resource:

```lua theme={null}
local settings = exports['roadphone']:GetPhoneSettingsFromMetadata(source)
local savedUnfolded = settings ~= nil
    and (settings.unfolded == true or settings.unfolded == 1)
```

This reads persisted settings, not live device state. Writing `UpdatePhoneSettings(source, { unfolded = true })` changes saved settings; it does not animate the UI or immediately swap the held prop.

There are currently **no public Fold-specific Lua exports**. `GetPhoneDevice`, `IsFoldDeviceActive`, `ResolvePhoneDevice` and `SetPhoneUnfolded` are internal functions. Do not call them through `exports['roadphone']`.

Likewise, `getPhoneProp(itemName)` maps regular item/colour variants; it does not expose the active Fold prop or open/closed state.

## Troubleshooting

| Symptom                      | Check                                                                                                                       |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| A normal phone opens         | Use the `phone_fold` item and check that it is listed in `Config.FoldableItems`, including on Jaksam.                       |
| The fold key does nothing    | Assign a key, open the Fold phone, then try `/roadphone_fold`.                                                              |
| The unfolded prop is missing | Check both YDR files, the YTYP, manifest and model names. Restart the resource after updating assets.                       |
| The wrong phone data appears | Use the exact inventory slot. Custom inventory hooks should use [OnPhoneItemUsed](/roadphonepro/api/metadata#item-helpers). |
| An app stays narrow          | It uses the compatibility layout until a dedicated Fold layout is available.                                                |