Battery positioning
Traditionally, batteries remained docked at a user-specified position behind the avatar and moved along the Z axis of the spine attachment point when inserted. This was generally practical for most uses, but was incompatible with chest-mounted controllers and controllers mounted at an angle.
With our third-generation batteries, released in January 2017, the battery firmware was updated to include a new auto-positioning feature, introduced during Companion 8.3. This mechanism is designed to simplify the lives of those who use multiple controllers. When the battery is inserted, the controller will tell it the correct X/Y/Z offsets to use in order to line up properly with the battery socket.
By the time auto-positioning was introduced to the public, the company was already aware of the attachment point overloading problem, in which multiple attachments on the same point greatly increased the odds that, during region crossing or inter-region teleportation, one or more attachments would be dropped during the limited time window afforded to the simulators in which to transfer avatar data. As a result, the theoretically trivial task of setting the coordinates of the battery and socket equal to one another was not directly possible, as it became standard convention to attach the battery to the Spine attachment point and the controller to the Chest attachment point.
The Spine and Chest have different coordinate systems; specifically, the Chest is rotated 180° around the horizontal axis. Additionally, the attachment points are not rooted at the same location, or even a constant distance from one another: instead, the Spine and Chest have a distance along the Z (depth) axis which is a function of the avatar's shape, particularly the gender, body thickness, and shoulder width attributes. As the state of these values (and other modifiers to the avatar's skeleton) cannot be determined programmatically, it is necessary to provide an additional parameter.
The battery description field is used to provide the offset for translating the battery's Z coordinate (from the Spine attachment point) into a comfortable position relative to the Chest-mounted controller. The default value for the battery description field is -0.334, which is the offset required for typical female avatars constructed at typical human scale.
To push the battery in further, make this value slightly more negative. The default -0.334 value means that the battery will be pushed in by 33.4 cm from its default position, which is about 13" in US customary and Imperial units. Increasing this position by 1 (i.e., setting it to 0.666) would result in moving the battery a whole meter behind your current position, or more than three feet. Typically, only very small adjustments are necessary to correct misalignments. Most customers find that values in the range -0.35 to -0.37 are adequate to meet their needs. For a basis of comparison, note that batteries are typically 5 to 8 cm in length.
To pull the battery out, make the value slightly more positive. This is typically required for extremely small avatars. We recommend starting with -0.27.
To test your changes, type @device probe after editing the battery's description while it is inserted. The controller will immediately search for devices again, and upon finding the battery, its position will be updated to reflect your changes.
To save your changes permanently, it is necessary to place the battery on the ground before making the description changes. This is because attachments cannot update their names or descriptions except for child prims.
This is a bug in XSU-specific auto-positioning code which will be fixed in Companion 8.5. Adjustments to the controller's vertical (Y) position are incorrectly interpreted as horizontal (X) changes. Consequently, we recommend not adjusting the XSU's vertical placement. If doing so is unavoidably necessary, consult the section below.
As the auto-positioning mechanism is intended for the particular combination of Chest-mounted controllers and Spine-mounted batteries, any other attachment point setup will disable it. If you have difficulties with the auto-positioning system, we recommend switching the attachment points used by these two components, so that the battery is attached to the Chest and the controller is attached to the Spine. Manual re-positioning and re-orientation will be required afterwards.
This solution is also strongly recommended when using a front-mounted controller arrangement, as is popularly done with the NS-115 Scout controller. Generation 3 batteries will insert in the direction their prongs face, so any orientation should be valid once the components are correctly placed.
With our third-generation batteries, released in January 2017, the battery firmware was updated to include a new auto-positioning feature, introduced during Companion 8.3. This mechanism is designed to simplify the lives of those who use multiple controllers. When the battery is inserted, the controller will tell it the correct X/Y/Z offsets to use in order to line up properly with the battery socket.
Troubles with auto-positioning
By the time auto-positioning was introduced to the public, the company was already aware of the attachment point overloading problem, in which multiple attachments on the same point greatly increased the odds that, during region crossing or inter-region teleportation, one or more attachments would be dropped during the limited time window afforded to the simulators in which to transfer avatar data. As a result, the theoretically trivial task of setting the coordinates of the battery and socket equal to one another was not directly possible, as it became standard convention to attach the battery to the Spine attachment point and the controller to the Chest attachment point.
The Spine and Chest have different coordinate systems; specifically, the Chest is rotated 180° around the horizontal axis. Additionally, the attachment points are not rooted at the same location, or even a constant distance from one another: instead, the Spine and Chest have a distance along the Z (depth) axis which is a function of the avatar's shape, particularly the gender, body thickness, and shoulder width attributes. As the state of these values (and other modifiers to the avatar's skeleton) cannot be determined programmatically, it is necessary to provide an additional parameter.
The battery description field
The battery description field is used to provide the offset for translating the battery's Z coordinate (from the Spine attachment point) into a comfortable position relative to the Chest-mounted controller. The default value for the battery description field is -0.334, which is the offset required for typical female avatars constructed at typical human scale.
Vertical offset
This is a bug in XSU-specific auto-positioning code which will be fixed in Companion 8.5. Adjustments to the controller's vertical (Y) position are incorrectly interpreted as horizontal (X) changes. Consequently, we recommend not adjusting the XSU's vertical placement. If doing so is unavoidably necessary, consult the section below.
Disabling auto-positioning
As the auto-positioning mechanism is intended for the particular combination of Chest-mounted controllers and Spine-mounted batteries, any other attachment point setup will disable it. If you have difficulties with the auto-positioning system, we recommend switching the attachment points used by these two components, so that the battery is attached to the Chest and the controller is attached to the Spine. Manual re-positioning and re-orientation will be required afterwards.
This solution is also strongly recommended when using a front-mounted controller arrangement, as is popularly done with the NS-115 Scout controller. Generation 3 batteries will insert in the direction their prongs face, so any orientation should be valid once the components are correctly placed.