User:Rev Eponym/nPose
nPose documentation
 |
Warning: If you're reading this, it is unofficial. Testing and composition only! |
nPose is a system for coordinating animations between several avatars seated on the same object (linkset), such as a couch or bed, as well as rezzable, coordinated props. Unlike previous systems, nPose does not use poseballs to accomplish this.
nPose Quick Start
Are you familiar with Second Life building methods, prim inventories, and such? Have you set up a posing system using another type such as MLP or XPose? Here's the most basic process:
- Rez the object you're going to set up with nPose.
Ideally, the object's root prim should be empty. - Copy the nPose core scripts into the object: Core, Menu, Dialog, Slave
- Copy the nPose Adjuster Prim into the object
- Copy the animation files you want to use into the object
- Create and copy in notecards that define poses for the animations (see that section below)
- Reset scripts in the object
- Set up positions:
- Sit on the nPose object to access the menu
- Click the Admin button
- Choose Adjust from the submenu
- The Adjuster object will appear
- Edit the Adjuster and position it where you want your avatar to be sitting, relative to the object
- The Adjuster will say its position in local chat each time it moves
- Copy the appropriate line of text from the chat window
- Edit the notecard for the animation pose, and replace the existing text with the Adjuster's location info
- Save the position notecard
- Click Stop Adjust from the Admin menu
- Repeat this process for each animation pose
- This will enable animations on an object that will seat one avatar only. Read on for deeper detail.
Configuration notecards
Animations for seated avatars are activated by buttons in the nPose menu. To create those buttons, nPose needs a notecard for every pose (an animation or group of animations) that contains the animation name, and position/rotation information for each avatar pose.
A very basic nPose notecard might be named 'SET:Meditate', and its contents would like this:
ANIM|meditation|<0.0, 0.0, 0.0>|<0.0, 0.0, 0.0>
nPose needs the notecard to be present, even without correct position information, otherwise the pose will not appear on the menus. The notation here is very important:
- Each line begins with a command in all caps
- A vertical pipe ('|' - shift-backslash) acts as a separator between all elements
- The animation name must be exactly the same as the file in the object
(to copy the name, use rightclick-Rename in the Contents box to select, then Ctrl-C and Return) - The position must be a Euler (XYZ) vector, separated by commas and enclosed in carets ('<>')
- The rotation must also be a Euler vector, like that seen in the SL Edit controls
- There can be other parameters after this, but these are the minimum necessary
With the very basic information above in a notecard named 'SET:Meditate', the user of a sitting avatar will see 'Meditate' on the nPose menu, and when that button is selected, the avatar will be posed in the animation at the center coordinates of the object. Obviously, the position information needs to be something other than zero, and relative to the object. That's where the Adjuster comes in.
Using the Adjuster
The Adjuster is nPose's built-in 'smart prim' tool, used to determine the relative position and rotation of an animation. It's a rezzable object which looks like a three-dimensional axis, similar to that seen in SL's building tools.
Using the basic prim Edit tools, the Adjuster can be manipulated and the seated avatar will move in response. The Adjuster will call out its position in local chat each time it is moved, and this information can be copied and pasted into the configuration notecard.
Notecards in nPose
Notecards provide the link between the nPose scripts and the animation files, as well as enabling a variety of other custom functions.
Notecard types
nPose uses different types of notecards to define its customized menu functions. Each of these notecards has its type spelled out in capitals at the beginning of its name, like so: style="text-size:75%;" style="background:#E8F1F8;"
| Notecard Type | Function | ... | Example name |
|---|---|---|---|
| DEFAULT | Animations | .. | DEFAULT:Sitting |
| SET | Animations, grouping categories of poses | .. | SET:Lounging |
| BTN | Script messaging | .. | BTN:Colors |
| SEQ | Sequences of Sets | .. | SEQ:Line Dance |
 |
Important: The type name must be in all caps, with no spaces, with a colon(':') before the rest of the name. Without this, the scripts won't be able to find the notecards, and the item will not appear in the menu. |
- DEFAULT
- Used as the default pose set when nPose is initialized, and there can be only one with this type. Otherwise, it's the same as SET below. If no DEFAULT notecard is included in the contents of the nPose object, nPose will use the first SET notecard in the contents (alphabetically) as the DEFAULT.
- SET
- Used to define a group of animations which will appear in the nPose menu with the name after the colon in the notecard name. The notecard contains one line for each sitter, listing animation name and position. There can also be other lines, for functions that will be triggered along with the animation set. The Notecard commands section defines the different function types available.
- The SET notecard type can also be used to define submenus of animations, using the notecard name. See #Submenus below for details
- BTN
- Used for internal functions, or to send messages to other scripts within the linkset or to rezzed props.
- SEQ
- Used to setup sequences of pose sets. It communicates to the modified Rygel sequencer script. Details are provided later.
Notecard commands
Each line of a notecard begins with a command in all caps, similar to notecard type names. Supported commands are as follows:
| Command | Function | Data format |
|---|---|---|
| ANIM | Animation name, position and rotation | ANIM|animation-name|<xyz position>|<xyz rotation> |
| LINKMSG | Message to other scripts | LINKMSG|number|string|key |
| SATMSG | Script message activated when an avatar sits | SATMSG|number|string|key |
| NOSATMSG | Script message activated when an avatar stands (unsits) | NOSATMSG|number|string|key |
| PROP | Rezzes a prop in the position specified | PROP|prop-name|<xyz position>|<xyz rotation> |
- ANIM
- Provides information for activating and positioning an avatar animation.
- LINKMSG
- Provides information to be sent to other scripts in the nPose object, activated when the menu button for this pose is selected. This can activate other script functions and activate plug-in scripts. In LINKMSG lines, you may include the substitute %AVKEY% string, which will be replaced with the avatar key of the person who clicked the button (if applicable). This way, link-message-driven plugins can respond to individual users.
- SATMSG
- Same as LINKMSG, but activated specifically when an avatar sits.
- NOTSATMSG
- Same as LINKMSG, but activated specifically when an avatar moves or stands.
- PROP
- Provides information for positioning and activating rezzable props.
Submenus can be created simply by using identical keywords in the names of SET notecards. The submenu name must appear after 'SET:' in the notecard name, and before the button name, with a colon (:) in between.
For example, a series of one-, two-, and three-avatar poses for sitting around could be grouped under the submenu 'Lounging', and the notecards for each would be named as follows:
SET:Lounging:Solo SET:Lounging:Conversation SET:Lounging:Tea Party
The result would be a button in the main nPose menu called 'Lounging', and three buttons on the submenu named 'Solo' 'Conversation' and 'Tea Party'.
- ChangeSeat
- When a multiple-pose animation set is active, this button shows the other positions available. Clicking an empty position will place your avatar in that position; when that position is occupied, avatar positions will be swapped.
- Sync
- Restarts the animations in a set, so that avatar animations will be in sync.
- Offset
- Activates the position adjustment menu for your avatar. These settings are saved in script memory for your avatar, until the scripts are reset or nPose is restarted.
- -> or <-
- 'Next page' or 'Previous page' button, active when a menu has more than 12 buttons.
- ^ (up caret)
- 'Up' menu button, goes back to the previous menu from a submenu.
The admin menu is only available to the owner of the nPose object. The 'Admin' button will bring up a submenu with the following buttons:
- Adjust
- Rezzes the adjuster prim used to edit the position of the seat positions.
- StopAdjust
- Removes the adjuster prim.
- PosDump
- 'Dumps' the positions of avatars and props in the current pose into local chat. This text can be copied into SET notecards.
- Unsit
- Brings up a submenu with the names of all seated avatars. Click the name of the avatar and they will be unseated.
- Options
- Activates the Options submenu, with the following commands:
- Menuonsit
- Brings up a submenu to allow the option of having a menu pop up when an authorized avatar sits on the nPose object to be turned on or off.
- ToDefault
- Clicking this button will bring up a submenu to turn on or turn off the option of having nPose return to the DEFAULT pose when all seated Avatars have stood.
- Permit
- Brings up a submenu for restricting permissions for who can use the nPose object. The current setting will be displayed at the top of the Permit menu. The buttons on this submenu are:
- Public
- Permissions set so that anyone is allowed to use the nPose menus.
- Locked
- Permissions set so that only the owner is allowed to use the nPose menus.
- Group
- Permissions set so that anyone with their active group set to the same as the nPose object is allowed to use the nPose menus.