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

<th>
  Arguments
</th>

<th>
  Returns
</th>

<td>
  <code>
    uid
  </code>
</td>

<td>
  Full phone payload.
</td>

<td>
  <code>
    uid
  </code>
</td>

<td>
  Contact UID array.
</td>

<td>
  <code>
    uid
  </code>
  
  , <code>
    contact_uid
  </code>
</td>

<td>
  <code>
    true
  </code>
  
   or <code>
    false
  </code>
  
  .
</td>

<td>
  <code>
    uid
  </code>
  
  , <code>
    contact_uid
  </code>
</td>

<td>
  <code>
    true
  </code>
  
   or <code>
    false
  </code>
  
  .
</td>

<td>
  <code>
    uid
  </code>
</td>

<td>
  Message array.
</td>

<td>
  <code>
    uid
  </code>
  
  , <code>
    other_uid
  </code>
</td>

<td>
  Message array for both participants.
</td>

<td>
  <code>
    from_uid
  </code>
  
  , <code>
    to_uid
  </code>
  
  , <code>
    message
  </code>
  
  , <code>
    timestamp
  </code>
</td>

<td>
  Message JSON.
</td>

<td>
  <code>
    uid
  </code>
  
  , <code>
    message_id
  </code>
</td>

<td>
  <code>
    true
  </code>
  
   or <code>
    false
  </code>
  
  .
</td>

<td>
  <code>
    uid
  </code>
  
  , <code>
    message_id
  </code>
</td>

<td>
  <code>
    true
  </code>
  
   or <code>
    false
  </code>
  
  .
</td>

<td>
  <code>
    uid
  </code>
</td>

<td>
  Email array.
</td>

<td>
  <code>
    from_uid
  </code>
  
  , <code>
    to_uid
  </code>
  
  , <code>
    subject
  </code>
  
  , <code>
    body
  </code>
  
  , <code>
    timestamp
  </code>
</td>

<td>
  Email JSON.
</td>

<td>
  <code>
    uid
  </code>
  
  , <code>
    email_id
  </code>
</td>

<td>
  <code>
    true
  </code>
  
   or <code>
    false
  </code>
  
  .
</td>

<td>
  <code>
    uid
  </code>
  
  , <code>
    email_id
  </code>
</td>

<td>
  <code>
    true
  </code>
  
   or <code>
    false
  </code>
  
  .
</td>

<td>
  <code>
    uid
  </code>
</td>

<td>
  <code>
    OK
  </code>
  
  .
</td>

Command
`phone:init`
`phone:contacts:list`
`phone:contacts:add`
`phone:contacts:remove`
`phone:messages:list`
`phone:messages:thread`
`phone:messages:send`
`phone:messages:mark_read`
`phone:messages:delete`
`phone:emails:list`
`phone:emails:send`
`phone:emails:mark_read`
`phone:emails:delete`
`phone:remove`

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];
};

6.7 KiB Raw Permalink Blame History