Message:/restraints:

Message:
The purpose of this message is to allow the Core to notify Devices of restrictions the unit is under - for example, if it is unable to move, unable to think, unable to see, and so on. This allows the Device to react accordingly: it might not respond to clicks or menu buttons from a unit that is unable to move, or might provide fewer or less informative messages to a unit whose vision or thinking are impaired. The Device may also have as part of its purpose indicating the status of the unit (e.g. a diagnostic console), in which case, it needs to know that status.

Note that some Cores may also use this message to indicate that a unit simply isn't using the specified abilties.

Usage
A Core capable of sending a message should also be able to reply to   by sending a  message.

Note: This is possibly the most complicated thing in the whole ORIX protocol, and therefore the most likely to be inadequate. Feedback on this message is particularly valuable.

Parameters
This one is complicated.

Every ORIX Core capable of placing any restrictions on a unit should define a hierarchy of restrictions. For example, a Core might use the following hierarchy:
 * system
 * power
 * charge (to recharge its power system)
 * draw (to use power from its power system)
 * move
 * travel
 * teleport
 * fly
 * run
 * walk
 * touch
 * fartouch
 * neartouch
 * alltouch
 * move
 * use (to use devices it may be near or holding)
 * useattached (to use devices attached to it)
 * pose (to change its animation)
 * speak
 * volume
 * clarity
 * speed
 * sense
 * see
 * hear
 * names
 * hovertext
 * think
 * reason
 * emotion
 * memory
 * selfuse
 * selfprogram (to alter its own programming)
 * selfcontrol (to operate its own controls)

At the highest level of the taxonomy, the unit may be completely shut down - that is, incapable of doing anything at all. This could be indicated as. Or it may be completely unrestricted, which could be indicated as. Or it could have some other intermediate value defined by the core. (For clarity, such a value should not be numeric - it would be weird for "2" to be a level of restriction between "0" and "1". Where intermediate values are useful, it is suggested that they begin with a letter, like "E1" or "partial".)

The specific value ("0", "1", "E1", 'or "partial" in these examples) given to the  item indicates that all other items below it in the hierarchy also have the same value. We don't even have to know what all of those items are - we know that they are all fully restricted, or all fully unrestricted, or whatever "E1" or "partial" might mean.

Alternatively, a unit's motor system may be shut down, making it incapable of any movement, and its speech may also be garbled. This can be indicated using a JSON hierarchical object as

{"system": {"move":"0", "speak": {"clarity":"G5"} } }

A device designed for this Core would recognize each of those values. A device designed for a different core with a different hierarchy of restrictions might understand only "system", but it would still be able to understand that the unit is partially restricted. A slightly more knowledgeable device could further tell that the unit cannot move, and that its speech is partially limited - or even that it is the clarity of its speech that is limited, even if it does not specifically know what "G5" means - it knows that it isn't 0 (completely restricted) or 1 (completely unrestricted), and can decide for itself what to do about that.

Values ending in "~" may be used to indicate that the specified limitation is a voluntary restriction. In other words, a unit whose Core reports  is unable to move (perhaps frozen with a control, or being interfered with by electromagnetic interference), while a unit whose Core reports   is voluntarily remaining motionless, but could likely decide to move again without any outside intervention.

Conveniently, ORIX messages use JSON. So the system described above can send:

/restraints:{"system": {"move":0, "speak": {"clarity":"G5"} } }

to let all nearby devices know that its ability to move and speak clearly has just been impaired.

One more wrinkle needs to be addressed. The message above says nothing about the unit's ability to think. There's nothing wrong with that, but if a Device has requested a full reporting of all restraints the unit is under, this is insufficient. The additional keyword "other" can be used for this purpose:

/restraints:{"system": {"move":0, "speak": {"clarity":"G5", "other":1}, "other": 1 } }

This now clearly indicates that the unit's ability to do anything "other" than move or speak is unrestricted, and all aspect of its speech "other" than clarity are unimpaired. This could be done a little more concisely by placing the "other" indicator at the top level, as in:

/restraints:{"system": {"move":0, "speak": {"clarity":"G5"} }, "other":1 }

This indicates that there are no other restraints in play "other" than movement and clarity of speech.


 * system
 * Indicates the level of restraint of the entire system. See above discussion for details.


 * other
 * Indicates the level of restraint of any subsystems not otherwise specified.

Expected Action by Device
Entirely Device-dependent.

Response(s) Expected
None.

Examples
See above