Puppetry Network Control

Category:Puppetry
Puppetry Server
Communication
This document is intended for developers and people that want to understand
some of the technology used in Second Life so the viewers and region simulator
can share Puppetry animation. It assumes the reader has some knowledge of C++
programming, http and what's happening inside Second Life. See How Puppetry Works for more information.
Puppetry Viewer and Server
The Second Life viewer communicates with region servers through two
mechanisms. The first is the "Puppetry" capability (also referenced as a cap)
to exchange information with the server about the feature. This is the same
mechanism used by many other systems, and allows the viewer to detect, start,
stop and control Puppetry functionality. The actual information to animate your
and other avatars is sent in the AgentAnimation and the AvatarAnimation
messages. These messages will have bone position and rotation data to pose the
avatar.
The Puppetry Capability
The Puppetry capability may be requested from a viewer. Requesting this cap
upon connection to a region enables puppetry messages and services between the
viewer and the simulator. The name for the cap is `Puppetry` and should be requested when connecting to a
region along with all other capabilities. If the simulator supports puppetry it
will respond with a URL that can be used to access the services. If there is no
response for "Puppetry", the server does not support it.
Getting the Current State of
Puppetry
Issuing an HTTP GET to the puppetry cap queries the current state of
puppetry. The response is an LLSD map with the following fields.
Boolean 	When this value is **true**the viewer has indicated to the simulator that it will be transmitting real-time puppetry data to the simulator. If this value is **false**, the simulator will discard any puppetry data received from a viewer.Default: True
Boolean 	This controls whether the viewer will receive puppetry events from other transmitting viewers. When the value is true the simulator will append puppetry events to the AvatarAnimation messages sent as part of the interest list updates every frame.Default: True
Boolean 	
Integer 	Puppetry events are collected and send in blocks. This is the size of the largest collection of events that may be transmitted.Default: 255
Real 	The simulator only transmits puppetry events to avatars within a certain range of the viewer. By default, this range is 25 meters.Default: 25
Array of UUIDs	List of agents that have been explicitly
 subscribed to. Subscribed agents ignore the range limit.Default: empty
Array of UUIDs	List of agents that have been explicitly muted. Muted agents will never send puppetry information.Default: empty
Setting Parameters and
Puppetry Behavior
Puppetry behavior is modified by POSTing to the puppetry cap. If the
parameters are successfully changed the simulator will respond with a body
identical to the HTTP get with the new parameters. When changing parameters,
only those you wish to change are included in the posted LLSD body. Omitted
parameters are left unchanged.
Transmitting, Receiving, and
Local vs. Remote Echo
In order to transmit or receive puppetry data to the simulator the viewer
must turn it on by posting a message to the puppetry cap. Setting transmit to
true will allow the viewer to send realtime puppetry events to the simulator.
Setting receive to true will allow the simulator to send puppetry events
produced by other avatars to the viewer.
Normally, the simulator relays puppetry events to other agents within range
and does not echo them back to the sender. Setting `echo_back` to true changes this behavior
and the simulator will send the events back to the agent that produced them.
Type 	Description
Boolean	Controls whether the agent may transmit Puppetry data to the simulator. **true**: The simulator will accept and forward Puppetry events from this agent. **false**: The simulator will discard any Puppetry events sent from this agent.
Boolean	Controls whether this agent will receive Puppetry events from other avatars. **true**: The agent will receive Puppetry events as part of the AvatarAnimation message from the simulator during an interest list update. **false**: The agent will not receive Puppetry events from other avatars.
Boolean	Controls whether the agent will receive an echo of their own Puppetry events from the simulator. **true**: This agent's Puppetry events are echoed back as part of the interest list update. **false**: This agent does not receive their own Puppetry events.
Puppetry Range
By default an agent will only receive events from agents that are within 25
meters of their avatar position. To change the default range include a `range` value in the posted body with the
new value.
FieldName	Type	Description
Range 	Real	Maximum range for puppetry data. Agents outside of this range will not exchange puppetry information.
Subscriptions and Muting
A viewer may also request that puppetry data be sent from certain agents
that may be out of range. To do this include an array of the Agent IDs that the
viewer would like to subscribe to in the post body under the `subscribe` key. To cancel a subscription,
post the agent IDs in an array called `unsubscribe`.
A viewer may subscribe to at most 10 other agents at a time.
Muted agents will never send puppetry information to the viewer. Muting and
unmuting is done by posting arrays of agent IDs to the simulator using the `mute` and `unmute` keys. A viewer may mute up to 100 other agents at
a time.
Field Name 	Type 	Description
subscribe 	Array of UUIDs	Explicitly subscribes to agents in the list. Subscribed agents will transmit puppetry data even when out of range.
unsubscribe	Array of UUIDs	Removes agents from the explicitly subscribed list.
mute 	Array of UUIDs	Explicitly mute puppetry information from the listed avatars.
unmute 	Array of UUIDs	Remove avatars from the mute list.
Realtime Avatar Puppetry
The simulator receives and forwards puppetry events through the optional
PhysicalAvatarEventList block in the AgentAnimation and the AvatarAnimation
messages. The simulator will forward any received puppetry events to eligible
agents on the next frame as part of the interest list update. The simulator
will only process the most recent 5 puppetry event blocks, discarding older
blocks in favor of newer ones.
Sending Puppetry Events to
the Simulator
Puppetry events are sent to the server by packing them together into
PhysicalAvatarEventList blocks and sending those blocks to the simulator as
part of an AgentAnimation message. An event block may never be larger than the `event_size` value returned from the
puppetry cap. Data sent beyond this threshold will be truncated. The viewer may
send multiple blocks and multiple AgentAnimation message as frequently as they
like. However the stream is lossy when overloaded; the simulator will discard
older event blocks in favor of new ones.
Receiving Puppetry Events
from the Simulator
The simulator sends puppetry events to receiving simulators in one or more
optional PhysicalAvatarEventList in an AvatarAnimation message. These blocks
should be decoded by the receiving viewer and fed into the inverse kinematics
(IK) system to animate the avatar. The simulator will never send more than one
AvatarAnimation message per frame. If there is insufficient space in the the
message the oldest event blocks will be dropped.
PhysicalAvatarEventList
Packing Format
The puppetry event block consists of a series of events that are to be
replayed by viewers through the IK system.
*32 bit: timestamp for the event
*16 bit: number of joint events to follow
*32 bit: size of event block.
*repeating blocks:
**16 bit: Joint ID
** 8 bit: Event mask flag
*** 0x01 = position is packed (three floats: xyz)
*** 0x02 = reserved for: position is in parent frame when set (currently always in root-frame)
*** 0x04 = orientation is packed (three floats: imaginary xyz part of quaternion xyzw, where w is always positive)
*** 0x08 = orientation is in parent frame when set (else in root-frame)
*** 0x10 = reserved for: scale is packed (three floats: xyz), but not yet supported
*** 0x20 = reserved, unused
*** 0x40 = reserved, unused
*** 0x80 = "disable constraint"
**variable data as per mask: [12 bytes position] | [12 bytes orientation]
***future update will change this to be 6 bytes, F32 values packed to 16 bits