Network Protocol

There are two networked components - the “user interface” which consists of the end user web interface, as well as any in world HTML extensions (inventory display). The user interface can be called with GET or POST methods, uses HTML over HTTP along with cookies in some places.

This page does not document the above, the internals for the web interface are mostly beyond the scope of this documentation.

Instead this page focuses on the object/hud communications, that which connects SL LSL scripts to the system.

The protocol format for this communication is JSON encoding over HTTP POST, this is the same wether the server or client initiates the connection.

Note that all requests should result in a 200 OK HTTP status, this doesn't mean the command completed, merely that it was fully processed, the contents of the response should be examined for success details. Any non 200 HTTP status should cause that server to be marked as faulty for a period of time and no further requests should be submitted to it. There are two public entry point servers, and the system automatically switches between them when one becomes faulty, resubmitting requests that error (see supplied Comms.lsl library for reference implementation).

There are some standard fields present in all requests/responses, documented first, then further detail is provided on individual API calls.

Unless otherwise stated these are all key-value pairs in the JSON.

These values may appear in any server response or inbound HTTP

• error - if this value is present and not blank the user should be informed of the appropriate error message and discard the request/response
• terminate - if set the script should shut down entirely.
• shutdown - only applies to scripts that have HTTP-in (a listener / callback URL), the control of the character has been supersceeded (logged in elsewhere). The “shutdown” message is sent as a cursory notice to all URLs that are being purged / replaced at the server end, you'll need to restart the session with the server to process any further commands
• say - a message to 'say' locally (for results of public relevance, roll output, etc). Parameter 'sayas' (optional) to say “as” this user (rename object, /me does, etc)
• message - some kind of success message to display (client objects are not supposed to be particularly advanced (libcomms.lsl assumes llOwnerSay for these. message is processed normally via LINK)
• open - open the web page - used by the HUD only as a callback from the page request being processed. SL is slow to load pages, so if we open the panel when we load the page, it shows old stuff, so instead we call back from the eventual HTTP request the panel generates to “show” the panel properly…
• close - close the web panel - used by the HUD when the user clicks a “close” link in the panel as a callback from the server
• openurl - llOpenURL with this stuff. url=url, description=description
• ping - return with incommand pong (?)

The Region and Object Owner and Name are read from the HTTP headers

Mandatory

• developerkey - your unique developer key. You MUST carefully protect this, if it is compromised and abused it will be revoked, which will give you a bit of a nightmare. Similarly you shouldn't allow foreign scripts to be inserted if you're using the provided comms.lsl as it just trusts link messages.
• command - name of a command to run, parameters will depend on the command, below.
• runasavatar - Commands will be run in the context of the objects owner, this is usually appropriate for HUDs and attachments, however rezzed objects will need to set this to the user interacting. Please note that for every request from second life, the object, objects owner and developer key used to authenticate are logged independantly of the “actor” set here, abuse of this command will get you quickly blacklisted :) Know /why/ you need this.
• runascharacter - similar
• runasnocharacter - wipes character info from the state - set to any STRING
• callback
• command
• cookie
• developerkey
• digest
• interface
• objectkey
• protocol
• runasnocharacter
• timestamp
• url

The entire API is now defined by the Java “Commands” interface, documentation ought to be generated from there dynamically. [https://gphud.coagulate.net/app/introspection/api/ GPHUD API (Introspection)]

• incommand - “runtemplate”
• args - number of arguments for this command
• invoke - command to invoke
• (ping)
• autoattach
• broadcast
• disseminate
• effectN
• error
• eventmessage1
• eventmessage2
• forcereconnect
• hudcolor
• hudreplace
• hudtext
• incommand
• incommand
• instancename
• instancestatus
• legacymenu
• leveltext
• lineN???
• logincommand
• logincomplete
• message
• messageN
• messagecount
• messageto
• mode
• motd
• name
• opencmd
• openurl
• parcelonly
• qbNtexture
• qbbalance
• radar
• reboot
• rebootserver
• registered?
• rpchannel
• say
• sayN
• sayashud
• sayashudN
• servergive
• setlogo
• shutdown
• sizeratio
• teleport
• terminate
• titlercolor
• titlertext
• titlerz
• uixmenus
• zone
• zonemessage
• zoning

Each argument is specified as follows, with N being replaced by its positional index, starting at zero

• arg'n'name - name to set value to
• arg'n'type - one of SELECT, TEXTBOX
• arg'n'description - description of the argument to put in the question

• arg'n'button'm' - buttons for the dialog - m=0-11