Animesh User Guide RC DRAFT

Welcome to Animesh! Animesh is a new Second Life feature to allow independent objects to use rigged mesh and animations, just as you can today with mesh avatars. This means that you can now have wild animals, pets, vehicles, scenery features and other objects that play animations.
== Where it works ==
Animesh is currently being developed. Today it works only with a supported project viewer, in some regions of Aditi and on Agni in the Bluesteel RC channel. Eventually it will become a generally supported feature that works with the default viewer, actively maintained third party viewers, and everywhere on the main grid. The test regions are Animesh1, Animesh2, Animesh3and Animesh4, which are set to moderate maturity, and Animesh Adult, which is intended for adult content. All the regions are publicly accessible. Items left in the regions will be automatically returned to you after 24 hours, and may be manually returned at any time if we need to make changes to the test areas.
On the test grid, Aditi, there are corresponding test regions with the same names and same access settings: [secondlife://secondlife/Animesh1/128/128/23 Animesh1], [secondlife://Aditi/secondlife/Animesh2/128/128/23 Animesh2], [secondlife://Aditi/secondlife/Animesh3/128/128/23 Animesh3]and [secondlife://Aditi/secondlife/Animesh4/128/128/23 Animesh4], 
[secondlife://Aditi/secondlife/Animesh%20Adult/128/128/23 Animesh Adult]
== How to install the Animesh Project Viewer ==
You can get the Animesh Project Viewer from the alternate viewers download page at http://wiki.secondlife.com/wiki/Linden_Lab_Official:Alternate_Viewers.
== Getting started ==
Visit one of the Animesh regions listed above and look around. Hopefully you will see some interesting animated objects! Free sample animesh items are available in all the test regions; just click on the big gift box in the middle of any region.
The sample animesh objects are a velociraptor, a human, and a teddy bear. All of them can play their own animations and wander around the region using pathfinding. The teddy bear is also designed to be used as an attachment if you want to pick it up.
The corresponding source files for upload can be found at BUG-139234
== What's new with animesh ==
=== Making and unmaking animesh objects ===
The animesh viewer adds one new feature to the UI for editing an in-world object. If you right click on an object and choose edit, you will see a dialog for editing the object. In the features tab, there is a new checkbox labelled “Animated Mesh”. If the object is a rigged mesh, you can use the checkbox to turn it into an animesh object with its own skeleton. There are some restrictions: the object must be one you have permissions to modify, it must not exceed the maximum triangle count limit for animesh objects, and you must be in an animesh-enabled region. If any of these condition are not met then the checkbox will not be enabled.
=== Animating animesh objects ===
When an object becomes animesh, it won’t do anything right away. You still have to run animations on it. The way you do this is to add one or more animations to the object’s inventory (using the Content tab) and then run a script that plays those animations.
Here you can see the animesh object contains one animation, and has a script that can run it.
Animesh adds three new LSL methods that can be used to run or stop animations, or check which animations are currently running. The commands are:
* llStartObjectAnimation
* llStopObjectAnimation
* llGetObjectAnimationNames
Details and examples on how to use the methods are given at those wiki pages.
=== Animesh position and orientation ===
A conventional static mesh object has a position defined when it’s rezzed, and an orientation defined when it’s created. An animesh object still has an object position defined “under the hood”, but the displayed mesh is shown at a location determined by its underlying skeleton and currently playing animations. Because of this, the visual location of an animesh object playing an animation may be at some displacement from its "real" position for physics and scripting purposes. The skeleton is positioned relative to the original object as follows:
* The object position is used as the location for the skeleton root joint.
* The object orientation matches the skeleton root orientation.
* Playing animations can alter the visual position and orientation further by animating the pelvis joint.
One result is that animesh objects will be oriented with their local X-axis as the forward direction. Static mesh objects are not necessarily created in this orientation, so there may be a change in orientation when an object becomes animesh.
An animesh object’s real position and orientation can be edited using the standard editing controls (right click the object and pick edit). Scale changes can also be made but have no effect on the skeleton, and so are not reflected in the displayed mesh.
=== Animesh building suggestions ===
Animesh objects do not have attachments the way avatars do. To combine multiple meshes in a single animesh, you would link them together into a single linkset. If you link together multiple meshes, the original source meshes and any corresponding physics representations can be scattered around multiple locations. The meshes will all still display rigged to a single skeleton, with orientation as noted above. This means that there is currently no process that keeps the original source meshes and their physics representations lined up with the animesh skeleton. The recommended practice for now is to have a root prim that’s not a rigged mesh, and associate any physics representation with that root prim. The rigged meshes would then be non-physical children of this root.
Also note that like rigged meshes on avatars, the rigged meshes in animesh objects are non-physical. The animation process only affects how things display on the viewer, so if you want to have a physics shape that lines up with your animesh object, you will need to manage the positioning and animations accordingly.
=== Animesh attachments ===
Animesh objects can also be attachments on your avatar. Like a conventional static attachment, an animesh attachment will move with the selected attachment point on your avatar, such as your right shoulder or left hand. Animesh attachments can then run animations, which can change their apparent position relative to their attachment point (for example, if the pelvis joint is part of the animation).
Like static attachments, animesh attachments can be repositioned using the editing controls. Changing position or rotation will move the attachment relative to its attachment point.
Currently you can have at most one animesh attachment at a time.
=== Animesh Skeleton State and Customization ===
Avatars support extensive customization via sliders. The bones in an avatar skeleton are positioned and scaled based on these customization settings, which are stored mostly in the avatar's shape wearable. Animesh objects do not currently support this type of customization; they do not have shape wearables, so there is no way to do the same kind of skeleton customization for them. The bone positions and scales for an animesh object are simply initialized from the default bone settings (defined in some configuration files that are part of the viewer installation - avatar_skeleton.xml and avatar_lad.xml). These default bone positions and scales can be overridden in the uploaded meshes, using values defined when the meshes were created. This is the same joint position mechanism that rigged meshes can also use to customize avatar positioning.
We know there is a lot of interest in supporting more extensive customization of animeshes, and are hoping to tackle this in a later project.
=== New and updated displays ===
Some additional displays are available to help you see the state of animesh objects. It is likely the details of these displays will change before the feature is in its final release form:
* In the Advanced menu, the option Performance tools->Show avatar complexity information lets you see the computed complexity cost for avatars. This display has some additional information added to it, and now works for animesh objects as well.
Here you can see the updated display, applied to an animesh object. VisTris is the number of currently displayed triangles associated with the object, based on the currently displayed LODs (levels of detail) for its component primitives. EstMaxTris is an estimated triangle count for the most complex LODs of the object; this is the number used to determine whether an object exceeds the triangle count complexity limit for animesh objects. The complexity display only works for avatars and independent animesh objects. Attached animesh objects have their complexity added to the avatar they are attached to, so they are not shown with a complexity display of their own.
* Another updated display is Develop->Render Metadata->Collision skeleton. This will show the collision volumes for animesh objects as well as avatars, with the animesh objects shown a different color:
Here the avatar has a blue skeleton, and the animesh has a red one.
* Develop->Render Metadata->Joints will show the regular bones in the skeleton of both avatars and animesh objects.
Both of the Render Metadata displays have a significant performance impact, so you will probably not want to enable them most of the time.
== Known issues and bugs ==
Please be aware that there are some known issues with the animesh project viewer, and perhaps others that will be discovered during testing. The Release Notes for your version of the project viewer gives more details about currently known issues. The goal of the project viewer is to enable testing by content creators to help us iron out animesh features and identify bugs, so many of the things that look rough around the edges today will be fixed before animesh is officially released. Some things to be aware of:
* Handling of LODs and bounding boxes is still being worked on. Animesh attachments in particular are known to have problems that may affect how they are displayed. Animesh objects may change displayed LODs at incorrect distances - currently the behavior is similar to avatars, where it should be more in line with other in-world objects.
* Animesh shadows do not take alpha into account. This is a general graphical issue with how we display rigged meshes, so it’s the same as what you would see if the same meshes were attached to your own avatar. This is an issue that we are aware of and hope to fix at some point, but it’s not part of the Animesh project.
* Animesh object animation state may not update correctly if an animation is removed from the object while playing, or if they are stopped or started while the object is selected.
* Animesh object displayed position or rotation can lag behind object motion.
== Warnings ==
Animesh is still very much under development. Things may change during this test period. It’s possible that animesh objects created during testing will behave differently or will need to be modified to continue working. We hope to avoid breaking existing animesh content but cannot guarantee it.
Objects you place in the test regions may be deleted or returned at any time. Please keep a copy of all your work in progress.
== FAQ ==
==== What happens if I have an unsupported viewer? ====
If you visit an animesh-enabled region with a non-animesh viewer, you will see animesh objects as non-animated static mesh objects, and animesh attachments as rigged meshes on the host avatar.
====What happens if I visit unsupported regions and try to use animesh content?====
Animesh objects will not work correctly in such regions. Scripts that try to use the new animesh LSL functions will give an error message if run in a non-animesh region. Once you return to an animesh region you may need to reset the script to get it working again. Note that this will not be an issue when animesh is released, since at that point the new LSL methods will be enabled in all regions.
====How can report a bug or request new features?====
Please report the bug using the standard JIRA process, and include [ANIMESH] in the title.
====How can I engage with other users of animesh?====
* Visit the content creation forum area for animesh: https://community.secondlife.com/forums/forum/354-animesh/. Linden Lab will monitor this area while animesh is under development, and we will try to respond to questions of general interest.
* Attend the Content Creation User Group meeting, which is held most weeks on Thursday. All are welcome. See https://wiki.secondlife.com/wiki/Content_Creation_User_Group for location and schedule information.
====Will any pre-animesh content change?====
No. Animesh is a new setting for mesh objects. Any content created without that setting should continue to work the same as before. If you see any change in the behavior of non-animesh objects in animesh-enabled regions or with the Project viewer, please report it as a bug.
====What’s the difference between an animesh attachment and a regular rigged mesh attachment? When should I use one or the other?====
Animesh attachments have a complete skeleton of their own, so they can move completely independently from your avatar. For example, an animesh fairy could flap its own wings separately from the wings on your avatar. An animesh attachment can also become an independent object if it is detached. Regular mesh attachments use your avatar’s skeleton, so if they want to animate any part of your avatar they have to cooperate with other attachments. There are some cases where you could use either an animated attachment or a rigged mesh: if the object uses joints that are not being used for anything else, for example, it animates the wing bones of an avatar that does not have wings, then this could be implemented using either a regular rigged mesh attachment or an animesh attachment.
====Are there any restrictions on animesh content?====
The current limits are intended to help manage the performance costs associated with animesh objects:
* There is a limit to how many animesh objects can be attached to an avatar at one time. Currently this is a maximum of one.
* Animesh objects in-world (ie, not attached to an avatar) will have a land impact that counts against the limits for the region they are in. Currently being animesh adds an additional 15 to the land impact of an object. There is an additional land impact cost of 1.5 per 1,000 charged triangles in the model. All triangles in the highest LOD are charged, but only triangles exceeding a limit are charged in the coarser LODs; there is no LI penalty for LODs as long as each does not exceed half the complexity of the next highest level - for example, if the highest LOD has 10,000 triangles, you could make LODs with no penalty up to 5,000 triangles in the medium LOD, 2,500 in the low LOD, and 1,250 in the lowest LOD. LODs that exceed those limits will be counted against the LI only for any excess above those limits.
* Animesh objects have a complexity limit based on triangle count. Currently an animesh object can have at most 100,000 triangles in its most detailed LOD.
* Attached animesh objects, like other attachments, do not count against land impact. However, they do affect the Avatar Rendering Cost calculations for the avatar they are attached to. The ARC for animesh objects, like the ARC for avatars, incorporates the effects of graphics properties of the mesh objects, and is scaled to be roughly proportional to the land impact - for example, if an animesh object has 50% higher land impact than the corresponding static mesh, then the ARC for that animesh should also be roughly 50% higher.
== Additional resources ==
Here are a few links to resources related to animesh:
* Second Life Blog: Join the Project Animesh Beta - New Support for Animating Mesh Objects
* Content Creation User Group
* Content creation forum area for animesh
* Alternate Viewer Downloads