Generic Handles
Generic Handles is the software that powers Nanite Systems horns, handles, and other gripping devices. It is also available as a redistributable SDK for third-party handle creators.
The main purpose of Generic Handles is to allow a unit's user to easily pick up and reposition the unit, including by placing it on furniture or into an attractive pose for displaying. Over time the Handles feature set has expanded, and also includes an interface for accessing the unit's wardrobe and a system for multi-person posing, called "uses."
This document will explain how to get the most out of your Handles, and is aimed mainly at individual consumers. For assistance in using the redistributable SDK, see the document "! How to use NS Generic Handle Firmware", which was included with your purchase.
As some units may have multiple sets of handles, not all handle attachments will appear as "handles" in the unit's devices list. For example, NS-branded horns appear as "horns," and the NS Executive Handle appears as the singular "handle" instead. Additionally, the software will adapt to be used in other anatomy, and third-party creators may create items such as "antlers," "hair," "tail," or "ears" to take advantage of this. On the local console HUD included with Companion and the ATOS/CX OSD, most of these will be consolidated into a single entry.
Access to the handles is achieved by touching them, or equivalently using devices > handle device name > access. (See section above to determine the device name.) While the unit is on, local access is required, subject to consent if the unit is running Companion or Clockwork. There are no access restrictions when the unit is powered down.
To move a unit by force, choose the "Carry..." option from the main menu. It will move at your side until released by accessing the same menu and choosing "Release". You may not intercede if the unit is already being carried by someone else.
To seat a unit on a nearby object, choose "Place..." instead of "Release" while the unit is being carried. This option is not available until the unit has been picked up.
To pose a unit, choose the "Pose..." option from the main menu. This will present an alphabetized list of animations installed in the handles for your perusal. New poses can be added by the unit simply by dropping them into the handles, as long as they do not begin with an underscore, which is reserved for non-pose animations, such as multi-person uses and the carrying animation. Once posed, the unit cannot move until it has been released.
The handles will search for a notecard named "_poses" and parse this for vertical offsets. For example, a poses notecard with the contents:
will automatically raise the unit by 0.05 m (5 cm) when in the "belly" or "bracelets" poses. Live adjustments are not currently supported.
The "Use..." option on the main menu grants access to a poseball rezzing system. It is only visible if the notecard "_uses" exists. This uses the following format:
For example:
Offset and rotations are specified using LSL vectors and rotations. Animation names should (but are not strictly required to) begin with an underscore to hide them from listing under the "Pose..." menu. Arousal is generated using the unit's current sensitivity levels on a generic stimulation surface (See TESI protocol documentation; values as high as 10 may be necessary to trigger TESI if the unit has no arousal when the use begins.
When the unit is placed into a use, it will automatically sit on the first (zeroth) poseball. The poseballs will be automatically de-rezzed when the unit stands.
So where is it? The uses feature is still undergoing development and is not yet intended to be a main draw of the Generic Handles code. The animations we used for testing during development have an unusually protectionist licensing agreement (the final sales price of the item must be increased for every animation included) so we have chosen not to include example uses.
If it has not been deleted, the dresser interface allows access to a chat-link-based #RLV browser where you can add and remove attachments and other clothing items from the unit's outfit using its inventory system.
Important: The RLV restriction sendchat prevents use of chat links. If you experience difficulty using chat link browsing, make sure you do not have this restriction active. It is commonly enforced by gag devices, such as Companion's vox output pipe. In most versions with this feature, it can be found under the "cortex" menu with the name "gag mode" or "chat forwarding." Ensure it is disabled, or chat link usage will not be possible. Users do not need RLV enabled to take advantage of chat link menus, although Linden Lab has identified them as a phishing hazard and may remove them in the distant future.
The dresser is highly flexible and allows browsing of both the entire #RLV folder structure and a segregated subsection under the unit's RLV path, which defaults to "~NS" but can be changed in the _oem file. By default, the dresser will search for a folder called "dresser" inside this location. For units with multiple controller setups, it may be of use to keep a variety of different directories under different RLV paths by using distinct _oem files.
If the unit already has a folder hierarchy you wish to browse, then it is unlikely any modifications to it will be necessary. However, for best results, we recommend using the following methods:
By default the handles menu will automatically populate itself with extra options, such as "Tug", "Yank", and "Nibble". These are purely for your amusement and have no significance whatsoever.
Handles can also be operated through the system command line, both by the unit itself and by an interested user. Take note of the handle device name under the unit's devices menu (as described earlier in this document); the system command name will be <device>, e.g. @handles for typical handles via self-command access or /1un horns for local command access on a unit with horns named "Unit".
<device> dress [add|remove <folder>]
Opens the dresser interface. If add or remove is specified, adds/removes the specified folder under the root path.
<device> carry|yank
Picks up the unit if possible. yanking is more interesting.
<device> pose <animation>
Starts a pose.
<device> use <use_name>
Starts a use (multi-avatar pose with poseballs).
<device> unpose
Releases the unit from poses (not uses, seats, or carrying).
<device> seat <chair>
Seats the unit on a chair with <chair> as its UUID.
<device> stand
Stands the unit up and releases it from poses.
<device> release
As stand, but also de-rezzes poseballs created for uses.
The main purpose of Generic Handles is to allow a unit's user to easily pick up and reposition the unit, including by placing it on furniture or into an attractive pose for displaying. Over time the Handles feature set has expanded, and also includes an interface for accessing the unit's wardrobe and a system for multi-person posing, called "uses."
Getting started
This document will explain how to get the most out of your Handles, and is aimed mainly at individual consumers. For assistance in using the redistributable SDK, see the document "! How to use NS Generic Handle Firmware", which was included with your purchase.
The handle device name
As some units may have multiple sets of handles, not all handle attachments will appear as "handles" in the unit's devices list. For example, NS-branded horns appear as "horns," and the NS Executive Handle appears as the singular "handle" instead. Additionally, the software will adapt to be used in other anatomy, and third-party creators may create items such as "antlers," "hair," "tail," or "ears" to take advantage of this. On the local console HUD included with Companion and the ATOS/CX OSD, most of these will be consolidated into a single entry.
Handles access
Access to the handles is achieved by touching them, or equivalently using devices > handle device name > access. (See section above to determine the device name.) While the unit is on, local access is required, subject to consent if the unit is running Companion or Clockwork. There are no access restrictions when the unit is powered down.
Carrying and seating
To move a unit by force, choose the "Carry..." option from the main menu. It will move at your side until released by accessing the same menu and choosing "Release". You may not intercede if the unit is already being carried by someone else.
To seat a unit on a nearby object, choose "Place..." instead of "Release" while the unit is being carried. This option is not available until the unit has been picked up.
Posing
To pose a unit, choose the "Pose..." option from the main menu. This will present an alphabetized list of animations installed in the handles for your perusal. New poses can be added by the unit simply by dropping them into the handles, as long as they do not begin with an underscore, which is reserved for non-pose animations, such as multi-person uses and the carrying animation. Once posed, the unit cannot move until it has been released.
Position adjustments
The handles will search for a notecard named "_poses" and parse this for vertical offsets. For example, a poses notecard with the contents:
default: 0
belly: 5
bracelets: 5
belly: 5
bracelets: 5
will automatically raise the unit by 0.05 m (5 cm) when in the "belly" or "bracelets" poses. Live adjustments are not currently supported.
Uses
The "Use..." option on the main menu grants access to a poseball rezzing system. It is only visible if the notecard "_uses" exists. This uses the following format:
<use name>: <anim 0>,<offset 0>,<rotation 0>,<arousal 0>[,<anim 1>,...]
For example:
arch: _arch-f,<0,0,1>,<0,0,0,1>,1,_arch-m,<-1,0,0>,<0,0,0,1>,1
deep: _deep-f,<0,0,0>,<0,0,0,1>,2,_deep-m,<0,0,0>,<0,0,0,1>,1
deep: _deep-f,<0,0,0>,<0,0,0,1>,2,_deep-m,<0,0,0>,<0,0,0,1>,1
Offset and rotations are specified using LSL vectors and rotations. Animation names should (but are not strictly required to) begin with an underscore to hide them from listing under the "Pose..." menu. Arousal is generated using the unit's current sensitivity levels on a generic stimulation surface (See TESI protocol documentation; values as high as 10 may be necessary to trigger TESI if the unit has no arousal when the use begins.
When the unit is placed into a use, it will automatically sit on the first (zeroth) poseball. The poseballs will be automatically de-rezzed when the unit stands.
So where is it? The uses feature is still undergoing development and is not yet intended to be a main draw of the Generic Handles code. The animations we used for testing during development have an unusually protectionist licensing agreement (the final sales price of the item must be increased for every animation included) so we have chosen not to include example uses.
Dressing
If it has not been deleted, the dresser interface allows access to a chat-link-based #RLV browser where you can add and remove attachments and other clothing items from the unit's outfit using its inventory system.
Important: The RLV restriction sendchat prevents use of chat links. If you experience difficulty using chat link browsing, make sure you do not have this restriction active. It is commonly enforced by gag devices, such as Companion's vox output pipe. In most versions with this feature, it can be found under the "cortex" menu with the name "gag mode" or "chat forwarding." Ensure it is disabled, or chat link usage will not be possible. Users do not need RLV enabled to take advantage of chat link menus, although Linden Lab has identified them as a phishing hazard and may remove them in the distant future.
The dresser is highly flexible and allows browsing of both the entire #RLV folder structure and a segregated subsection under the unit's RLV path, which defaults to "~NS" but can be changed in the _oem file. By default, the dresser will search for a folder called "dresser" inside this location. For units with multiple controller setups, it may be of use to keep a variety of different directories under different RLV paths by using distinct _oem files.
Setting up the directory hierarchy for the dresser
If the unit already has a folder hierarchy you wish to browse, then it is unlikely any modifications to it will be necessary. However, for best results, we recommend using the following methods:
- Do not expect to find any empty folders in your hierarchy using the dresser. Folders which are empty and folders which contain only empty folders ("barren" folders) are invisible to the dresser. Because of this, customers are often confused when testing the dresser for the first time.
- Folders must be nested at least one level deep. Make categories for your outfit folders. The dresser will not work if you only have one level of folders.
- The dresser was designed for use with RLVa (Catznip's reimplementation of the RLV API) and may malfunction when used with "original" RestrainedLove viewers, such as Marine Kelley's viewer or Cool VL. Modern viewers such as Firestorm, Black Dragon, and even Singularity will function as expected.
- Create new outfits by pasting links, not items. This can be done by copying entries from the Current Outfit or My Outfits folders, or by right-clicking in your inventory and choosing "Paste as Link" rather than copying or moving real assets. Using inventory links will ensure that your viewer's outfit manager never desynchronizes with your #RLV folders.
- Don't use extra punctuation (most commonly +, >, or \) in folder names. The dresser will add "(browse)" links whenever there are subfolders, and always forces the effect of the "+" option (add instead of replace).
- Do use "(nostrip)" or "(no strip)" at the end of folders that hold body parts. This is a reliable way to prevent other RLV devices from removing them when inappropriate. For best results, put this tag on the actual folder holding the body parts, not the #RLV subfolder that contains only links.
- The dresser will hide folders that start with a period (.), underscore (_) or tilde (~). As implied above, the "(nostrip)" tag can be used on any folder in your inventory, so the period notation is not strictly necessary. Folders prefixed with underscores are assumed to be set up for sequences with the Nanite Systems EmergenceXL conversion tank.
- Avoid folder names containing forward slashes (/). This can cause problems when going up a level in the browser, as RLV and RLVa use forward slashes as path separators. (For example, a folder called "~NS" inside "#RLV" is called "#RLV/~NS".)
- Make use of topical folders like "Outfits", "Accessories", "Hair", "Bodies", and so forth. A single folder with many children is much more likely to cause memory problems in the dresser (and in other #RLV browsers) than a balanced hierarchy.
Emotes
By default the handles menu will automatically populate itself with extra options, such as "Tug", "Yank", and "Nibble". These are purely for your amusement and have no significance whatsoever.
Command-line reference
Handles can also be operated through the system command line, both by the unit itself and by an interested user. Take note of the handle device name under the unit's devices menu (as described earlier in this document); the system command name will be <device>, e.g. @handles for typical handles via self-command access or /1un horns for local command access on a unit with horns named "Unit".
<device> dress [add|remove <folder>]
Opens the dresser interface. If add or remove is specified, adds/removes the specified folder under the root path.
<device> carry|yank
Picks up the unit if possible. yanking is more interesting.
<device> pose <animation>
Starts a pose.
<device> use <use_name>
Starts a use (multi-avatar pose with poseballs).
<device> unpose
Releases the unit from poses (not uses, seats, or carrying).
<device> seat <chair>
Seats the unit on a chair with <chair> as its UUID.
<device> stand
Stands the unit up and releases it from poses.
<device> release
As stand, but also de-rezzes poseballs created for uses.