forge/docus/dist/raw/client-addons/phone.md

Client Phone Usage Guide

The client phone addon provides the in-game phone UI for contacts, SMS messages, email, and local utility apps such as notes, calendar events, world clocks, and alarms.

Open Phone UI

call forge_client_phone_fnc_openUI;

The phone UI creates RscPhone, loads ui/_site/index.html, and routes browser alerts through forge_client_phone_fnc_handleUIEvents.

State Ownership

Contacts, messages, and emails are server-owned and requested through the server phone addon.

Local utility app state is stored in profileNamespace:

• notes
• calendar events
• world clocks
• alarms
• theme/preferences

Phone Class

forge_client_phone_fnc_initClass creates GVAR(PhoneClass).

The phone class currently owns local notes, events, and settings helpers. Contacts, messages, and emails continue to use server-backed request/response events.

Browser Events

Session and Preferences

<th>
  Client behavior
</th>

<td>
  Send player UID to browser with <code>
    setPlayerUid
  </code>
  
  .
</td>

<td>
  Send saved light/dark theme to browser.
</td>

<td>
  Save theme preference to <code>
    profileNamespace
  </code>
  
  .
</td>

Event
phone::get::player
phone::get::theme
phone::set::theme

Contacts

<th>
  Client behavior
</th>

<td>
  Load cached contacts and request server refresh.
</td>

<td>
  Request contacts from server.
</td>

<td>
  Add contact by phone number.
</td>

<td>
  Add contact by phone number.
</td>

<td>
  Add contact by email.
</td>

<td>
  Remove contact by UID.
</td>

Event
phone::get::contacts
phone::refresh::contacts
phone::add::contact
phone::add::contact::by::phone
phone::add::contact::by::email
phone::remove::contact

Messages

<th>
  Client behavior
</th>

<td>
  Request messages from server.
</td>

<td>
  Request thread with another UID.
</td>

<td>
  Send SMS through server.
</td>

<td>
  Mark message read on server.
</td>

<td>
  Delete message on server.
</td>

Event
phone::get::messages
phone::get::message::thread
phone::send::message
phone::mark::message::read
phone::delete::message

Email

<th>
  Client behavior
</th>

<td>
  Request emails from server.
</td>

<td>
  Send email through server.
</td>

<td>
  Mark email read on server.
</td>

<td>
  Delete email on server.
</td>

Event
phone::get::emails
phone::send::email
phone::mark::email::read
phone::delete::email

Local Utility Apps

<th>
  Client behavior
</th>

<td>
  Load local notes.
</td>

<td>
  Save local note.
</td>

<td>
  Delete local note.
</td>

<td>
  Load local calendar events.
</td>

<td>
  Save local calendar event.
</td>

<td>
  Delete local calendar event.
</td>

<td>
  Load local world clocks.
</td>

<td>
  Save local world clock.
</td>

<td>
  Delete local world clock.
</td>

<td>
  Load local alarms.
</td>

<td>
  Save local alarm.
</td>

<td>
  Delete local alarm.
</td>

<td>
  Toggle local alarm enabled state.
</td>

Event
phone::get::notes
phone::save::note
phone::delete::note
phone::get::events
phone::save::event
phone::delete::event
phone::get::clocks
phone::save::clock
phone::delete::clock
phone::get::alarms
phone::save::alarm
phone::delete::alarm
phone::toggle::alarm

Usage Rules

• Send contact, message, and email mutations to the server phone addon.
• Keep local-only utility apps in profileNamespace until they are migrated to server-backed storage.
• Do not treat local phone utility state as shared multiplayer state.
• Validate required UID, phone, email, subject, and message fields before sending server requests.

Related Guides

• Phone Usage Guide
• Client Notifications Usage Guide