TODO: Move some parts over to the main spec, for the place commands

Entities like persons or places provide 3 interfaces to issue user commands, which are described here.


To let a person entity do something a _request_do_command_method_here has to be sent to it. For example the _enter command lets your person entity enter a place. To do that via the _request_do interface you have to send a packet with the method _request_do_enter to it:

 :_source      psyc://
 :_target      psyc://
 :_place       @dev

You should use the _request_do interface for clients with graphical user interface, automatons or similar applications, where those commands are mostly 'hardwired'. If you have to process arbitrary user input (command line commands) it is recommended to use the interfaces described below.


For places the command requests differ as you have to leave out the _do in the method name.


All user commands can also be issued via the _request_execute interface. The advantage of this interface is, that clients don't have to map commands to protocol methods themselves, but instead send the command to the destination entity as they are (eg. a place or person).

The above example as _request_execute command looks like this:

 :_source      psyc://
 :_target      psyc://
 enter @dev

The method is _request_execute and the command is, along with its arguments, put into the body. But without any leading command characters, which have to be interpreted by the client.


Whenever you want to implement a thin client you can use the _request_input method. It allows the clients to shift all command processing to the person entity. The PSYC variable _focus is used here to focus the command to a specific entity, which for example can be a place:

 :_target                psyc://host.tld/~nick
 :_focus                 psyc://
 /kick eviluser

Standard Person Commands

These are the commands PSYC person entities may want to implement:

_request_do...related variablesequivalent command
This command lets the person entity do a chat action, like _request_do_action_hug would virtually hug someone.
_add_friend_nick_person or _person, _trustee/friend
_cast_method, _amount_friendivity/cast (= /friendcast)
_clear_friend_nick_person or _person/cancel
_enter_home(too psyced specific)/home
_examine_person _trustee _tag _format/examine /surf
_invite_person _focus/invite
_list_peers/show *
_list_peers_JSON/show data
_message_person, _group/tell and /
This sends a message to either a _person or a _group.
_presence_degree_mood _degree_availability
_degree_automation _description_presence
/availability /mood and many more
_remove_friend_nick_person or _person/unfriend
Generates a _status_storage with _application variables.
_set_key _value/set
_show_log_amount _match _parameter/lastlog
Stores all variables of the _application family in the entity storage. SHOULD also handle profile settings.

Presence with PSYC clients

In PSYC, clients are in charge of setting and resetting presence states on behalf of their users. That means, that a client will probably want to transmit a _request_do_presence soon after logging in and before logging out using _request_do_quit. Quitting does not automatically send offline presence. This only happens when the client loses contact to the server abnormally.

Place command requests

_request...variablesequivalent command
_nick_nick_local (masquerade)/nick
_show_log_match _amount _parameter/history

The _target MUST be aimed at a place (consider however, places potentially provide differing choices of methods). If your request is to be performed on behalf of an identity not identical to the source (typically the case for a client or external tool) you need to provide a _source_identification.


As replies to _request_do, _request_execute and _request_input any method from one of the method families can be expected. Use packet tags to detect whether a request failed or to get the reply of the request.