forge/docs/PHONE_USAGE_GUIDE.md

Phone Usage Guide

The phone module stores contacts, messages, and emails for each UID. It is a server-extension state module backed by SurrealDB.

Storage Model

{
  "contacts": ["76561198000000000", "field_commander"],
  "messages": [
    {
      "id": "phone-message:sender:receiver:1",
      "from": "sender",
      "to": "receiver",
      "message": "Text body",
      "timestamp": 123.45,
      "read": false
    }
  ],
  "emails": [
    {
      "id": "phone-email:sender:receiver:2",
      "from": "sender",
      "to": "receiver",
      "subject": "Subject",
      "body": "Email body",
      "timestamp": 123.45,
      "read": false
    }
  ]
}

Rules validated by the Rust service:

• UID arguments cannot be empty.
• Message and email bodies cannot be empty.
• Empty email subjects become No subject.
• Player messages and emails cannot target field_commander.
• field_commander can send messages or emails to players.
• Deleting a message or email removes it only from the requesting UID's index.

Commands

Command	Arguments	Returns
phone:init	uid	Full phone payload.
phone:contacts:list	uid	Contact UID array.
phone:contacts:add	uid, contact_uid	true or false.
phone:contacts:remove	uid, contact_uid	true or false.
phone:messages:list	uid	Message array.
phone:messages:thread	uid, other_uid	Message array for both participants.
phone:messages:send	from_uid, to_uid, message, timestamp	Message JSON.
phone:messages:mark_read	uid, message_id	true or false.
phone:messages:delete	uid, message_id	true or false.
phone:emails:list	uid	Email array.
phone:emails:send	from_uid, to_uid, subject, body, timestamp	Email JSON.
phone:emails:mark_read	uid, email_id	true or false.
phone:emails:delete	uid, email_id	true or false.
phone:remove	uid	OK.

Initialize Phone State

phone:init creates phone state if needed and seeds self-contact plus field_commander.

private _result = "forge_server" callExtension ["phone:init", [getPlayerUID player]];
private _payload = _result select 0;

if (_payload find "Error:" == 0) exitWith {
    systemChat format ["Phone init failed: %1", _payload];
};

private _phone = fromJSON _payload;

Send a Message

private _timestamp = str diag_tickTime;

private _result = "forge_server" callExtension ["phone:messages:send", [
    getPlayerUID player,
    _targetUid,
    "Move to checkpoint Alpha.",
    _timestamp
]];

Read a Conversation

private _result = "forge_server" callExtension ["phone:messages:thread", [
    getPlayerUID player,
    _otherUid
]];

private _messages = fromJSON (_result select 0);

Send an Email

private _result = "forge_server" callExtension ["phone:emails:send", [
    getPlayerUID player,
    _targetUid,
    "Supply Request",
    "Requesting resupply at grid 123456.",
    str diag_tickTime
]];

Mark and Delete Records

"forge_server" callExtension ["phone:messages:mark_read", [
    getPlayerUID player,
    _messageId
]];

"forge_server" callExtension ["phone:emails:delete", [
    getPlayerUID player,
    _emailId
]];

Error Handling

private _payload = (_result select 0);
if (_payload find "Error:" == 0) then {
    systemChat format ["Phone error: %1", _payload];
};