Animesh User Guide

Category:Mesh
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 supported in all regions of the main grid and on the test grid. Currently Animesh works with the default viewer. If you need a place to test animesh content, there are some dedicated test regions at Animesh1, Animesh2, Animesh3and Animesh4, which are set to moderate maturity, and Animesh Adult, which is intended for adult content. These regions also have a gift box which will give you some test/example animesh objects. 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.
== 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 root object orientation. If the root object is a mesh, the bind shape matrix will be used.
* Playing animations can alter the visual position and orientation further by animating the pelvis joint.
One result is that animesh objects will normally 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. However, if the root object of an animesh linkset is a mesh, the bind shape matrix will also be used. This means that if you want your object to be oriented relative to the static mesh representation, you can use an animesh root mesh. If you want your object to have standard X-forward skeleton orientation, you can use a non-mesh root object (for example, a simple invisible prim) and then align your mesh child objects relative to that.
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.
Position and Scale Constraints
There are some constraints on the scale and positioning of animesh objects. These are intended to maintain consistency with limits on other types of in-world objects (such as conventional prims), and to make the behavior more predictable.
* There is a 64m scale limit for animesh objects. Objects exceeding this size threshold will be scaled down so their computed bounding box does not exceed 64m.
* There is a 3m offset limit for animesh objects. Offset is the distance between the "official" location of the static object and the bounding box of the animesh object as displayed. The display location of animesh objects will be constrained to not exceed this limit.
These constraints are based on a real-time bounding box maintained for rigged meshes, so they may be triggered at some times and not others depending on the animations being played. For performance reasons the box does not update every frame, so the constraints can lag behind the current appearance slightly.
=== 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. 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:
* 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 ==
* 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.
* Some types of editing in the build floater do not work correctly with animesh objects.
== Warnings ==
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?====
This situation should not come up now that animesh support is enabled on the main grid. If you do run into a region, perhaps on the test grid, that lacks animesh support, then animesh objects will not work correctly. 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.
====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, 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 (this also means that animations between animesh objects and your own avatar may not be completely in sync, since they are animated independently). 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, two for premium subscribers.
* 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. This 100,000 limit is based on estimated triangle count, so the actual number of triangles can often be a bit higher.
* 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: Animesh is Here!
* Content Creation User Group
* Content creation forum area for animesh